agent_coder
f720151c63
The same tool metadata (zod schema + model-facing description) was hand-duplicated between the standalone MCP server and the in-app AI-chat agent, so every tweak had to land in two places and copies drifted (a materialized parity bug). The shared transport-agnostic registry (packages/mcp/src/tool-specs.ts) already de-duplicates 14 tools; this migrates two more genuinely-identical ones — patch_node/patchNode and insert_node/insertNode. The canonical description is a strict SUPERSET of both originals (keeps MCP's "without resending the whole document" + table-structure/anchor guidance AND the in-app "reversible via page history" / "exactly one of anchorNodeId or anchorText" framing — no model-facing guidance dropped); the schema is identical (the in-app side just gains MCP's .min(1) on ids, a safe tightening). Each transport keeps its own execute/auth wrapper, and the in-app parseNodeArg node-arg normalization is unchanged. The three table tools are intentionally NOT merged (a real param-name divergence: table vs tableRef) — documented on both sides. Other per-transport divergences (search/share/create_comment/transform/list_pages) are left separate with a short comment explaining why (the issue asked to flag these as intentional). DocmostClientLike stays a hand-mirror (the ESM/CJS boundary blocks a compile-time type import; a runtime drift-guard already pins it). Also fixes a latent contract-spec bug: derive `required` from `instanceof z.ZodOptional` (matches the emitted JSON schema) instead of `isOptional()`, which wrongly reported z.any() fields as optional. Partially addresses #294. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
316 lines
16 KiB
JavaScript
316 lines
16 KiB
JavaScript
// Zod-agnostic shared tool-spec registry consumed by BOTH the zod-v3 MCP server
|
|
// (packages/mcp/src/index.ts) and the zod-v4 in-app AI-SDK service
|
|
// (apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts). Intentionally
|
|
// imports NO zod: each consumer passes its OWN zod namespace into buildShape,
|
|
// because the two packages are on different zod majors (v3 here, v4 in the
|
|
// server) and a zod schema object built with one major cannot be reused by the
|
|
// other. The builders below only touch z.string()/.min()/.optional()/.describe(),
|
|
// z.array() and z.object() — API identical across v3 and v4 — so a single
|
|
// builder works with either namespace.
|
|
//
|
|
// Only tools whose snake_case/camelCase name, input schema AND model-facing
|
|
// description are genuinely identical across both layers live here. Tools that
|
|
// diverge on purpose (security guardrails, tuned UX, "Reversible" framing on
|
|
// some write tools, different limits, hybrid-RRF search, etc.) stay defined
|
|
// per-layer and are NOT represented here.
|
|
export const SHARED_TOOL_SPECS = {
|
|
// --- no-argument read tools ---
|
|
getWorkspace: {
|
|
mcpName: 'get_workspace',
|
|
inAppKey: 'getWorkspace',
|
|
description: 'Fetch metadata about the current workspace (name, settings).',
|
|
},
|
|
listSpaces: {
|
|
mcpName: 'list_spaces',
|
|
inAppKey: 'listSpaces',
|
|
description: 'List the spaces the current user can access. Returns the array of ' +
|
|
'spaces (id, name, slug, ...).',
|
|
},
|
|
listShares: {
|
|
mcpName: 'list_shares',
|
|
inAppKey: 'listShares',
|
|
description: 'List all public shares in the workspace with page titles and public URLs.',
|
|
},
|
|
// --- single-pageId read tools ---
|
|
getPageJson: {
|
|
mcpName: 'get_page_json',
|
|
inAppKey: 'getPageJson',
|
|
description: 'Get page details with the raw ProseMirror JSON content (lossless: ' +
|
|
'includes block ids, callouts, tables, link/image attributes) plus the ' +
|
|
'slugId used in URLs. Use the block ids it returns to make precise ' +
|
|
'structural edits or surgical text edits without resending the page.',
|
|
buildShape: (z) => ({
|
|
pageId: z.string().min(1),
|
|
}),
|
|
},
|
|
getOutline: {
|
|
mcpName: 'get_outline',
|
|
inAppKey: 'getOutline',
|
|
description: "Return a COMPACT outline of a page's top-level blocks ({index, type, " +
|
|
'id, level, firstText}; tables add rows/cols/header; lists add item ' +
|
|
'count) WITHOUT the full document body. Use it to locate sections/tables ' +
|
|
'and grab block ids cheaply before fetching, patching or inserting ' +
|
|
'individual blocks.',
|
|
buildShape: (z) => ({
|
|
pageId: z.string().min(1),
|
|
}),
|
|
},
|
|
// --- two-id read tool ---
|
|
getNode: {
|
|
mcpName: 'get_node',
|
|
inAppKey: 'getNode',
|
|
description: "Fetch a single node's full ProseMirror subtree (lossless) without " +
|
|
'pulling the whole document. `nodeId` is a block id from the page ' +
|
|
'outline or page-JSON view (works for headings/paragraphs/callouts/images), OR ' +
|
|
'`#<index>` to fetch a top-level block by its outline index — use the ' +
|
|
'`#<index>` form for tables/rows/cells, which carry no id.',
|
|
buildShape: (z) => ({
|
|
pageId: z.string().min(1),
|
|
nodeId: z.string().min(1),
|
|
}),
|
|
},
|
|
// --- node delete ---
|
|
deleteNode: {
|
|
mcpName: 'delete_node',
|
|
inAppKey: 'deleteNode',
|
|
description: 'Remove a single block by its attrs.id (from the page-JSON view) WITHOUT ' +
|
|
'resending the whole document.',
|
|
buildShape: (z) => ({
|
|
pageId: z.string().min(1),
|
|
nodeId: z.string().min(1),
|
|
}),
|
|
},
|
|
// --- single-block structural write (patch / insert) ---
|
|
//
|
|
// CANONICAL description merges both layers: the MCP copy's "WITHOUT resending
|
|
// the whole document" + "cheaper/safer than a full-document replace" guidance
|
|
// AND the in-app copy's "keeps the same node id" + "Reversible via page
|
|
// history" framing — nothing either side conveyed is dropped. Sibling tools are
|
|
// named in transport-neutral prose ("the page-JSON view", "a full-document
|
|
// replace") to match the rest of the registry, since the two layers expose
|
|
// those siblings under different (snake_case vs camelCase) identifiers.
|
|
patchNode: {
|
|
mcpName: 'patch_node',
|
|
inAppKey: 'patchNode',
|
|
description: 'Replace a single content block identified by its attrs.id with a new ' +
|
|
'ProseMirror node, WITHOUT resending the whole document; the replacement ' +
|
|
'keeps the same node id. Get the block id from the page-JSON view, then ' +
|
|
'pass a ProseMirror node to put in its place. Example node: a paragraph ' +
|
|
'{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
|
|
'heading {"type":"heading","attrs":{"level":2},"content":' +
|
|
'[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
|
|
'{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
|
|
'JSON object or a JSON string (both accepted). Cheaper and safer than ' +
|
|
'replacing the whole document for one-block structural edits. Reversible: ' +
|
|
'the previous version is kept in page history.',
|
|
buildShape: (z) => ({
|
|
pageId: z.string().min(1).describe('ID of the page containing the block'),
|
|
nodeId: z
|
|
.string()
|
|
.min(1)
|
|
.describe('attrs.id of the block to replace (from the page outline or ' +
|
|
'page-JSON view)'),
|
|
node: z
|
|
.any()
|
|
.describe('ProseMirror node to put in place of the node with this id, e.g. ' +
|
|
'{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
|
|
'JSON object or JSON string both accepted.'),
|
|
}),
|
|
},
|
|
insertNode: {
|
|
mcpName: 'insert_node',
|
|
inAppKey: 'insertNode',
|
|
description: 'Insert a block before/after another block (by attrs.id or anchor text) ' +
|
|
'or append it at the end (top level). For before/after you MUST provide ' +
|
|
'EXACTLY ONE of anchorNodeId or anchorText. Get anchor block ids from the ' +
|
|
'page-JSON view. Avoids resending the whole document. Can also insert ' +
|
|
'table structure: to add a tableRow, pass a tableRow node with position ' +
|
|
'before/after and anchor INSIDE the target table — anchorNodeId of any ' +
|
|
'block/cell in it, or anchorText matching the table; to add a ' +
|
|
'tableCell/tableHeader, use anchorNodeId of a block inside the target row ' +
|
|
'(anchorText only resolves top-level blocks, so it cannot target a row). ' +
|
|
"`anchorText` is matched against the block's literal rendered plain text " +
|
|
'(no markdown); markdown/emoji are tolerated as a fallback; prefer plain ' +
|
|
'text or anchorNodeId. Note: append is top-level only and rejects ' +
|
|
'structural table nodes. Example node: a paragraph ' +
|
|
'{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
|
|
'heading {"type":"heading","attrs":{"level":2},"content":' +
|
|
'[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
|
|
'{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
|
|
'JSON object or a JSON string (both accepted). Reversible via page history.',
|
|
buildShape: (z) => ({
|
|
pageId: z.string().min(1),
|
|
node: z
|
|
.any()
|
|
.describe('ProseMirror node to insert, e.g. ' +
|
|
'{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
|
|
'JSON object or JSON string both accepted.'),
|
|
position: z
|
|
.enum(['before', 'after', 'append'])
|
|
.describe('Where to insert relative to the anchor.'),
|
|
anchorNodeId: z
|
|
.string()
|
|
.optional()
|
|
.describe('Anchor block id (for before/after).'),
|
|
anchorText: z
|
|
.string()
|
|
.optional()
|
|
.describe("Anchor text fragment (for before/after), matched against the " +
|
|
"block's literal rendered plain text (no markdown). Markdown/emoji " +
|
|
'are tolerated as a fallback; prefer plain text or anchorNodeId.'),
|
|
}),
|
|
},
|
|
// --- share management ---
|
|
unsharePage: {
|
|
mcpName: 'unshare_page',
|
|
inAppKey: 'unsharePage',
|
|
description: 'Remove the public share of a page (revokes the public URL).',
|
|
buildShape: (z) => ({
|
|
pageId: z.string().min(1).describe('ID of the page to unshare'),
|
|
}),
|
|
},
|
|
// --- version history ---
|
|
diffPageVersions: {
|
|
mcpName: 'diff_page_versions',
|
|
inAppKey: 'diffPageVersions',
|
|
description: 'Diff two versions of a page and return a Docmost-equivalent change set ' +
|
|
'(inserted/deleted text, integrity counts for images/links/tables/' +
|
|
'callouts/footnote markers, and a human-readable markdown summary). ' +
|
|
"`from`/`to` each accept a historyId, or null/'current' for the page's " +
|
|
'current content (defaults: from=current, to=current — pass a historyId ' +
|
|
'from the page-history list to compare against the live page).',
|
|
buildShape: (z) => ({
|
|
pageId: z.string().min(1),
|
|
from: z
|
|
.string()
|
|
.optional()
|
|
.describe("historyId, or 'current'/omit for current content"),
|
|
to: z
|
|
.string()
|
|
.optional()
|
|
.describe("historyId, or 'current'/omit for current content"),
|
|
}),
|
|
},
|
|
listPageHistory: {
|
|
mcpName: 'list_page_history',
|
|
inAppKey: 'listPageHistory',
|
|
description: "List a page's saved versions (Docmost auto-snapshots on every save), " +
|
|
'newest first, cursor-paginated. Returns { items, nextCursor }; each ' +
|
|
"item's id is the historyId to pass to the page diff or restore tools.",
|
|
buildShape: (z) => ({
|
|
pageId: z.string().min(1),
|
|
cursor: z
|
|
.string()
|
|
.optional()
|
|
.describe('Pagination cursor from a previous nextCursor'),
|
|
}),
|
|
},
|
|
restorePageVersion: {
|
|
mcpName: 'restore_page_version',
|
|
inAppKey: 'restorePageVersion',
|
|
description: 'Restore a page to a saved version: writes that version\'s content back ' +
|
|
'as the page\'s current content (Docmost has no restore endpoint, so ' +
|
|
'this creates a NEW history snapshot — the restore is itself revertible). ' +
|
|
'Get the historyId from the page-history list.',
|
|
buildShape: (z) => ({
|
|
historyId: z.string().min(1),
|
|
}),
|
|
},
|
|
// --- markdown round-trip ---
|
|
importPageMarkdown: {
|
|
mcpName: 'import_page_markdown',
|
|
inAppKey: 'importPageMarkdown',
|
|
description: "Replace a page's content from a self-contained Docmost-flavoured " +
|
|
'Markdown file produced by the page-Markdown export tool. Restores comment ' +
|
|
'highlight anchors and diagrams from their inline HTML. NOTE: comment ' +
|
|
'thread records are NOT created/updated/deleted on the server by this ' +
|
|
'tool — only the page body + inline comment marks are written; manage ' +
|
|
'comment threads via the comment tools/UI.',
|
|
buildShape: (z) => ({
|
|
pageId: z.string().min(1),
|
|
markdown: z.string().min(1),
|
|
}),
|
|
},
|
|
// --- server-side content copy ---
|
|
copyPageContent: {
|
|
mcpName: 'copy_page_content',
|
|
inAppKey: 'copyPageContent',
|
|
description: "Replace targetPageId's content with a copy of sourcePageId's content, " +
|
|
'entirely server-side — the document is NOT sent through the model. The ' +
|
|
'target keeps its own title and slug; only its body is replaced. Ideal ' +
|
|
"for 'make page A's content equal to B' or 'replace A with B but keep A's URL'.",
|
|
buildShape: (z) => ({
|
|
sourcePageId: z.string().min(1).describe('Page to copy content FROM'),
|
|
targetPageId: z
|
|
.string()
|
|
.min(1)
|
|
.describe('Page whose content is REPLACED (title/slug kept)'),
|
|
}),
|
|
},
|
|
// --- surgical text edit (folds in the documented drift-bug fix) ---
|
|
//
|
|
// CANONICAL description is the CORRECTED in-app wording: a formatting-only
|
|
// change is REFUSED into failed[] (not silently stripped-and-retried). The
|
|
// stale MCP claim that "Markdown wrappers are tolerated via a strip-and-retry
|
|
// fallback" is intentionally absent here.
|
|
editPageText: {
|
|
mcpName: 'edit_page_text',
|
|
inAppKey: 'editPageText',
|
|
description: "Surgical find/replace inside a page's text, preserving all block " +
|
|
'ids and marks. A find MAY cross bold/italic/link boundaries; the ' +
|
|
'replacement inherits marks from the unchanged common prefix/suffix ' +
|
|
'(so editing plain text next to a bold word keeps it bold, and ' +
|
|
'editing inside a bold word keeps the new text bold). Each find must ' +
|
|
'match exactly once unless replaceAll is set. The batch applies what ' +
|
|
'it can and returns applied[] + failed[] plus a verify change-report ' +
|
|
'(the text/marks/structure that ACTUALLY changed — read it to confirm ' +
|
|
'your edit landed; do not assume success); a fully-unmatched batch ' +
|
|
'writes nothing and errors. find and replace are LITERAL text, not ' +
|
|
'markdown. This tool edits plain text ONLY and CANNOT add or remove ' +
|
|
'formatting marks: a formatting change — find/replace that differ only ' +
|
|
'in markdown markers (e.g. find:"~~x~~", replace:"x"), or a replace ' +
|
|
'containing **bold**/~~strike~~/`code` wrappers — is REFUSED into ' +
|
|
'failed[]. To change bold/italic/strike/code/link, read the block as ' +
|
|
'page JSON and use a structural node patch/update to set its marks. ' +
|
|
'Examples: edits:[{find:"teh",replace:"the"}]; edits:[{find:"Hello ' +
|
|
'world",replace:"Hello there"}] (crosses a bold boundary).',
|
|
buildShape: (z) => ({
|
|
pageId: z.string().describe('ID of the page to edit'),
|
|
edits: z
|
|
.array(z.object({
|
|
find: z.string().describe('Exact text to find'),
|
|
replace: z.string().describe('Replacement text (may be empty)'),
|
|
replaceAll: z
|
|
.boolean()
|
|
.optional()
|
|
.describe('Replace every occurrence (default: must match once)'),
|
|
}))
|
|
.min(1)
|
|
.describe('List of find/replace operations, applied in order'),
|
|
}),
|
|
},
|
|
// --- hand a large page to an external consumer without bloating context ---
|
|
stashPage: {
|
|
mcpName: 'stash_page',
|
|
inAppKey: 'stashPage',
|
|
description: 'Serialize a whole page (the full ProseMirror JSON, as get_page_json ' +
|
|
'returns) into an ephemeral in-memory blob and return ONLY a short ' +
|
|
'anonymous URL to it — the body NEVER enters the model context, so this ' +
|
|
'is the way to hand a large page (or its images) to an external consumer ' +
|
|
'without truncation. Every internal file/image attachment is mirrored ' +
|
|
'into the same sandbox and its src rewritten to a sandbox URL, so the ' +
|
|
'consumer can fetch the images anonymously too; external http(s) images ' +
|
|
'are left untouched. Returns { uri, size, sha256, images:{mirrored, ' +
|
|
'failed} }. Integrity: the blob is served with ETag = its sha256, so a ' +
|
|
'truncated/corrupted fetch is detectable. Blobs are RAM-only: they expire ' +
|
|
'after a short TTL (~1h) and are cleared on restart — consume the URL ' +
|
|
'within the TTL and one uptime, or re-stash. A blob is bound to the ' +
|
|
'server instance that created it: in a multi-replica deployment without ' +
|
|
'sticky sessions a blob stored on one instance is not retrievable via the ' +
|
|
'sandbox URL on another (it 404s like an expired one).',
|
|
buildShape: (z) => ({
|
|
pageId: z.string().min(1),
|
|
}),
|
|
},
|
|
};
|