gitmost/packages/mcp/src/tool-specs.ts

// 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.
//
// MAINTENANCE RULE: adding, renaming, or removing a spec here (or an inline
// registerTool in index.ts) REQUIRES updating SERVER_INSTRUCTIONS in
// packages/mcp/src/index.ts — the intent-routing guide MCP clients receive on
// initialize. Enforced by test/unit/server-instructions.test.mjs.

// Loose on purpose — see the comment above. The two zod majors expose different
// static type surfaces, so typing this precisely would couple the registry to
// one of them. Each builder uses only the common, stable subset of the API.
type ZodLike = any;

export interface SharedToolSpec {
  /** snake_case tool name passed to McpServer.registerTool. */
  mcpName: string;
  /** camelCase key in the ai-SDK tools object (the in-app layer). */
  inAppKey: string;
  /** Single canonical model-facing description used by both layers. */
  description: string;
  /**
   * Builds the tool's input schema as a plain object of zod fields (a
   * ZodRawShape). Called with the consumer's own zod namespace. Omitted for
   * no-argument tools (the MCP side then registers with no inputSchema and the
   * in-app side uses z.object({})).
   */
  buildShape?: (z: ZodLike) => Record<string, unknown>;
}

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),
    }),
  },

  // --- in-page occurrence search (client-side, over ProseMirror plain text) ---

  searchInPage: {
    mcpName: 'search_in_page',
    inAppKey: 'searchInPage',
    description:
      'Find every occurrence of a string (or regex) INSIDE one page and get ' +
      'WHERE each is — instead of pulling blocks one-by-one with get_node. ' +
      'Searches the plain text of each text block/cell (marks glued, so a match ' +
      'survives bold/italic/link splits; comment anchors do not interfere). ' +
      'Returns { total, truncated, matches:[{ nodeId, blockIndex, type, before, ' +
      'match, after }] }: `nodeId` is the block id (or "#<index>" for ' +
      'table/cell content) — pass it to get_node/patch_node (the "#<index>" ' +
      'form resolves with get_node but NOT patch_node, which only accepts a real ' +
      'block id). To anchor a comment, do NOT pass nodeId to create_comment (it ' +
      'has no nodeId param); build a UNIQUE text selection from before+match+' +
      'after and pass it as create_comment\'s `selection`. `blockIndex` is the ' +
      'get_outline index; `before`/`after` give ~40 chars of context to build ' +
      'that unique selection. `total` counts all ' +
      'hits and `truncated` is true when more than `limit` were found (nothing ' +
      'is silently dropped). Default is a literal, case-INSENSITIVE substring; ' +
      'set regex:true for an RE2 regular expression (linear-time, ReDoS-safe: ' +
      'char classes, word boundaries, anchors and quantifiers work; lookaround ' +
      '(?=…)/(?<=…) and backreferences \\1 are NOT supported) and ' +
      'caseSensitive:true to match case. Ideal for systematic ' +
      'editorial sweeps (unquoted "ё", straight quotes, "т.е.", stray units). An ' +
      'invalid regex or an empty query returns a clear error to fix.',
    buildShape: (z) => ({
      pageId: z.string().min(1).describe('ID of the page to search'),
      query: z
        .string()
        .min(1)
        .describe('The text to find (a literal substring, or a regex when regex:true)'),
      regex: z
        .boolean()
        .optional()
        .describe(
          'Treat query as an RE2 regular expression — linear-time, ReDoS-safe; ' +
            'no lookaround or backreferences (default false).',
        ),
      caseSensitive: z
        .boolean()
        .optional()
        .describe('Case-sensitive matching (default false).'),
      limit: z
        .number()
        .int()
        .min(1)
        .max(200)
        .optional()
        .describe('Max matches to RETURN (default 50, max 200); total is always reported.'),
    }),
  },

  // --- node delete ---

  deleteNode: {
    mcpName: 'delete_node',
    inAppKey: 'deleteNode',
    description:
      'Remove a single block by its attrs.id (from the page outline or ' +
      '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 outline (cheap) ' +
      'or 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 outline or 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),
    }),
  },
} satisfies Record<string, SharedToolSpec>;