collabmd 0.1.48 → 0.1.51

package/src/domain/agent-tool-definitions.js

@@ -0,0 +1,872 @@
+function objectSchema(properties = {}, required = Object.keys(properties)) {
+  return { additionalProperties: false, properties, required, type: 'object' };
+}
+
+const REVISION_SCHEMA = {
+  description: 'Lowercase SHA-256 revision returned by read_document.',
+  pattern: '^[a-f0-9]{64}$',
+  type: 'string',
+};
+
+const WORKSPACE_ENTRY_SCHEMA = objectSchema({
+  agentEditable: { type: 'boolean' },
+  embeddable: { type: 'boolean' },
+  kind: { type: ['string', 'null'] },
+  mtimeMs: { minimum: 0, type: 'number' },
+  nodeType: { enum: ['directory', 'file'], type: 'string' },
+  path: { type: 'string' },
+  readable: { type: 'boolean' },
+  size: { minimum: 0, type: 'number' },
+});
+
+const DOCUMENT_REFERENCE_SCHEMA = objectSchema({
+  exists: { type: 'boolean' },
+  kind: { type: ['string', 'null'] },
+  line: { minimum: 1, type: 'integer' },
+  rawTarget: { type: 'string' },
+  resolvedPath: { type: ['string', 'null'] },
+  targetPath: { type: 'string' },
+});
+
+const VIDEO_REFERENCE_SCHEMA = objectSchema({
+  kind: { type: ['string', 'null'] },
+  line: { minimum: 1, type: 'integer' },
+  mimeType: { type: ['string', 'null'] },
+  source: { type: 'string' },
+  supported: { type: 'boolean' },
+  url: { type: ['string', 'null'] },
+});
+
+const BACKLINK_SCHEMA = objectSchema({
+  contexts: { items: { type: 'string' }, type: 'array' },
+  file: { type: 'string' },
+});
+
+const VALIDATION_ISSUE_SCHEMA = objectSchema({
+  code: { type: 'string' },
+  line: { minimum: 1, type: 'integer' },
+  message: { type: 'string' },
+  target: { type: 'string' },
+});
+
+const DIAGRAM_RENDER_OUTPUT_PROPERTIES = {
+  endLine: { minimum: 1, type: 'integer' },
+  format: { enum: ['png', 'svg'], type: 'string' },
+  kind: { enum: ['mermaid', 'plantuml'], type: 'string' },
+  mimeType: { enum: ['image/png', 'image/svg+xml'], type: 'string' },
+  path: { type: 'string' },
+  renderer: { type: 'string' },
+  revision: REVISION_SCHEMA,
+  startLine: { minimum: 1, type: 'integer' },
+  warnings: { items: { type: 'string' }, type: 'array' },
+};
+
+const SEARCH_SNIPPET_SCHEMA = objectSchema({
+  column: { minimum: 1, type: 'integer' },
+  line: { minimum: 1, type: 'integer' },
+  matchEnd: { minimum: 0, type: 'integer' },
+  matchStart: { minimum: 0, type: 'integer' },
+  text: { type: 'string' },
+});
+
+const SEARCH_FILE_SCHEMA = objectSchema({
+  file: { type: 'string' },
+  kind: { type: 'string' },
+  matchCount: { minimum: 0, type: 'integer' },
+  snippets: { items: SEARCH_SNIPPET_SCHEMA, type: 'array' },
+  truncated: { type: 'boolean' },
+});
+
+const SYNTAX_GUIDE_SCHEMA = objectSchema({
+  examples: { items: { type: 'string' }, type: 'array' },
+  extensions: { items: { type: 'string' }, type: 'array' },
+  guide: { type: 'string' },
+  kind: { type: 'string' },
+});
+
+const CAPABILITY_SCHEMA = objectSchema({
+  agentCreatable: { type: 'boolean' },
+  agentEditable: { type: 'boolean' },
+  commentsSupported: { type: 'boolean' },
+  editable: { type: 'boolean' },
+  examples: { items: { type: 'string' }, type: 'array' },
+  extensions: { items: { type: 'string' }, type: 'array' },
+  guide: { type: 'string' },
+  kind: { type: 'string' },
+  readable: { type: 'boolean' },
+  searchable: { type: 'boolean' },
+});
+
+const EXCALIDRAW_ELEMENT_TYPES = ['arrow', 'diamond', 'ellipse', 'freedraw', 'line', 'rectangle', 'text'];
+const EXCALIDRAW_POINT_SCHEMA = {
+  items: { type: 'number' },
+  maxItems: 2,
+  minItems: 2,
+  type: 'array',
+};
+const EXCALIDRAW_ELEMENT_INPUT_SCHEMA = {
+  additionalProperties: false,
+  properties: {
+    autoResize: { type: 'boolean' },
+    afterElementId: {
+      description: 'Place this new element immediately after an existing or concurrently created element.',
+      maxLength: 128,
+      minLength: 1,
+      type: 'string',
+    },
+    backgroundColor: { type: 'string' },
+    endArrowhead: { type: ['string', 'null'] },
+    beforeElementId: {
+      description: 'Place this new element immediately before an existing or concurrently created element.',
+      maxLength: 128,
+      minLength: 1,
+      type: 'string',
+    },
+    containerId: { maxLength: 128, minLength: 1, type: ['string', 'null'] },
+    endElementId: { maxLength: 128, minLength: 1, type: 'string' },
+    fillStyle: { enum: ['cross-hatch', 'hachure', 'solid', 'zigzag'], type: 'string' },
+    fontFamily: { minimum: 1, type: 'integer' },
+    fontSize: { exclusiveMinimum: 0, type: 'number' },
+    lineHeight: { exclusiveMinimum: 0, type: 'number' },
+    groupIds: {
+      items: { maxLength: 128, minLength: 1, type: 'string' },
+      maxItems: 20,
+      type: 'array',
+      uniqueItems: true,
+    },
+    height: { minimum: 0, type: 'number' },
+    id: { maxLength: 128, minLength: 1, type: 'string' },
+    opacity: { maximum: 100, minimum: 0, type: 'number' },
+    points: { items: EXCALIDRAW_POINT_SCHEMA, maxItems: 1000, minItems: 2, type: 'array' },
+    roughness: { maximum: 2, minimum: 0, type: 'number' },
+    startArrowhead: { type: ['string', 'null'] },
+    startElementId: { maxLength: 128, minLength: 1, type: 'string' },
+    strokeColor: { type: 'string' },
+    strokeStyle: { enum: ['dashed', 'dotted', 'solid'], type: 'string' },
+    strokeWidth: { exclusiveMinimum: 0, type: 'number' },
+    text: { maxLength: 20000, type: 'string' },
+    type: { enum: EXCALIDRAW_ELEMENT_TYPES, type: 'string' },
+    width: { minimum: 0, type: 'number' },
+    x: { type: 'number' },
+    y: { type: 'number' },
+  },
+  required: ['id', 'type', 'x', 'y'],
+  type: 'object',
+};
+const EXCALIDRAW_UPDATE_SCHEMA = objectSchema({
+  id: { maxLength: 128, minLength: 1, type: 'string' },
+  set: {
+    additionalProperties: true,
+    description: 'Excalidraw element fields to shallow-merge. id, type, and version cannot change.',
+    type: 'object',
+  },
+});
+const EXCALIDRAW_REPLACEMENT_ELEMENT_INPUT_SCHEMA = {
+  ...EXCALIDRAW_ELEMENT_INPUT_SCHEMA,
+  required: ['type', 'x', 'y'],
+};
+const EXCALIDRAW_REPLACE_SCHEMA = objectSchema({
+  element: EXCALIDRAW_REPLACEMENT_ELEMENT_INPUT_SCHEMA,
+  id: { maxLength: 128, minLength: 1, type: 'string' },
+}, ['element', 'id']);
+const EXCALIDRAW_REORDER_SCHEMA = objectSchema({
+  action: { enum: ['bringToFront', 'sendToBack'], type: 'string' },
+  afterElementId: { maxLength: 128, minLength: 1, type: 'string' },
+  beforeElementId: { maxLength: 128, minLength: 1, type: 'string' },
+  id: { maxLength: 128, minLength: 1, type: 'string' },
+}, ['id']);
+const EXCALIDRAW_TRANSLATE_SCHEMA = objectSchema({
+  dx: { type: 'number' },
+  dy: { type: 'number' },
+  ids: {
+    description: 'Requested targets. Bound text, its container, and all members of referenced groups move atomically.',
+    items: { maxLength: 128, minLength: 1, type: 'string' },
+    maxItems: 200,
+    minItems: 1,
+    type: 'array',
+    uniqueItems: true,
+  },
+});
+const EXCALIDRAW_BOUNDS_SCHEMA = objectSchema({
+  height: { minimum: 0, type: 'number' },
+  width: { minimum: 0, type: 'number' },
+  x: { type: 'number' },
+  y: { type: 'number' },
+});
+const EXCALIDRAW_SUMMARY_ELEMENT_SCHEMA = {
+  additionalProperties: false,
+  properties: {
+    behind: {
+      description: 'ID of the immediately higher element that paints in front of this element.',
+      type: 'string',
+    },
+    endElementId: { type: 'string' },
+    containerId: { type: 'string' },
+    fontFamily: {
+      description: 'Excalidraw font-family identifier. Standard Excalifont is 5; legacy Virgil is 1.',
+      minimum: 1,
+      type: 'integer',
+    },
+    fontName: { type: 'string' },
+    fontSize: { exclusiveMinimum: 0, type: 'number' },
+    height: { minimum: 0, type: 'number' },
+    id: { type: 'string' },
+    inFrontOf: {
+      description: 'ID of the immediately lower element that this element paints in front of.',
+      type: 'string',
+    },
+    paintOrder: {
+      description: 'Zero-based back-to-front paint position.',
+      minimum: 0,
+      type: 'integer',
+    },
+    lineHeight: { exclusiveMinimum: 0, type: 'number' },
+    startElementId: { type: 'string' },
+    text: { type: 'string' },
+    textAlign: { type: 'string' },
+    type: { type: 'string' },
+    verticalAlign: { type: 'string' },
+    width: { minimum: 0, type: 'number' },
+    x: { type: 'number' },
+    y: { type: 'number' },
+  },
+  required: ['height', 'id', 'paintOrder', 'type', 'width', 'x', 'y'],
+  type: 'object',
+};
+const EXCALIDRAW_WARNING_SCHEMA = objectSchema({
+  code: { type: 'string' },
+  elementIds: { items: { type: 'string' }, type: 'array' },
+  message: { type: 'string' },
+});
+const EXCALIDRAW_INSPECTION_PROPERTIES = {
+  bounds: EXCALIDRAW_BOUNDS_SCHEMA,
+  elementCount: { minimum: 0, type: 'integer' },
+  elements: { items: EXCALIDRAW_SUMMARY_ELEMENT_SCHEMA, type: 'array' },
+  layout: objectSchema({
+    boundText: objectSchema({
+      misaligned: { minimum: 0, type: 'integer' },
+      outsideContainer: { minimum: 0, type: 'integer' },
+      staleHeight: { minimum: 0, type: 'integer' },
+      total: { minimum: 0, type: 'integer' },
+    }),
+  }),
+  truncated: { type: 'boolean' },
+  valid: { type: 'boolean' },
+  warnings: { items: EXCALIDRAW_WARNING_SCHEMA, type: 'array' },
+};
+const EXCALIDRAW_INSPECTION_SCHEMA = objectSchema(EXCALIDRAW_INSPECTION_PROPERTIES);
+const EXCALIDRAW_INSPECTION_OUTPUT_SCHEMA = objectSchema({
+  ...EXCALIDRAW_INSPECTION_PROPERTIES,
+  path: { type: 'string' },
+  revision: REVISION_SCHEMA,
+});
+const EXCALIDRAW_RENDER_RESULT_PROPERTIES = {
+  elementCount: { minimum: 0, type: 'integer' },
+  format: { enum: ['png', 'svg'], type: 'string' },
+  height: { minimum: 1, type: 'integer' },
+  mimeType: { enum: ['image/png', 'image/svg+xml'], type: 'string' },
+  renderer: { type: 'string' },
+  rendererVersion: { type: 'string' },
+  scale: { exclusiveMinimum: 0, type: 'number' },
+  warnings: { items: { type: 'string' }, type: 'array' },
+  width: { minimum: 1, type: 'integer' },
+};
+const EXCALIDRAW_RENDER_INPUT_PROPERTIES = {
+  format: {
+    description: 'Image format. PNG is most widely supported by MCP clients.',
+    enum: ['png', 'svg'],
+    type: 'string',
+  },
+  padding: {
+    description: 'Scene padding in diagram units.',
+    maximum: 100,
+    minimum: 0,
+    type: 'number',
+  },
+  path: {
+    description: 'Vault-relative .excalidraw path.',
+    maxLength: 1024,
+    minLength: 1,
+    type: 'string',
+  },
+  render: {
+    description: 'Return an image render. Set false for a compact structural and layout verification response.',
+    type: 'boolean',
+  },
+  scale: {
+    description: 'Requested output scale; automatically reduced when needed to stay within 4096 pixels.',
+    maximum: 4,
+    minimum: 0.25,
+    type: 'number',
+  },
+};
+const EXCALIDRAW_INLINE_VERIFY_INPUT_SCHEMA = objectSchema({
+  format: EXCALIDRAW_RENDER_INPUT_PROPERTIES.format,
+  inspectOcclusion: {
+    description: 'Inspect fully occluded elements. Defaults to true.',
+    type: 'boolean',
+  },
+  padding: EXCALIDRAW_RENDER_INPUT_PROPERTIES.padding,
+  render: {
+    description: 'Also return an image rendered from the exact created or edited revision.',
+    type: 'boolean',
+  },
+  scale: EXCALIDRAW_RENDER_INPUT_PROPERTIES.scale,
+}, []);
+const EXCALIDRAW_INLINE_VERIFICATION_SCHEMA = objectSchema({
+  inspection: EXCALIDRAW_INSPECTION_SCHEMA,
+  ...EXCALIDRAW_RENDER_RESULT_PROPERTIES,
+}, ['inspection']);
+const EXCALIDRAW_COMPACT_VERIFICATION_PROPERTIES = {
+  elementCount: { minimum: 0, type: 'integer' },
+  format: { enum: ['png', 'svg'], type: 'string' },
+  inspection: EXCALIDRAW_INSPECTION_SCHEMA,
+  layout: EXCALIDRAW_INSPECTION_PROPERTIES.layout,
+  path: { type: 'string' },
+  revision: REVISION_SCHEMA,
+  valid: { type: 'boolean' },
+};
+const EXCALIDRAW_VERIFY_OUTPUT_SCHEMA = {
+  oneOf: [
+    objectSchema(EXCALIDRAW_COMPACT_VERIFICATION_PROPERTIES),
+    objectSchema({
+      ...EXCALIDRAW_COMPACT_VERIFICATION_PROPERTIES,
+      ...EXCALIDRAW_RENDER_RESULT_PROPERTIES,
+    }),
+  ],
+};
+
+export const AGENT_TOOL_DEFINITIONS = Object.freeze([
+  {
+    annotations: { idempotentHint: true, readOnlyHint: true },
+    description: 'List current Vault files and directories, including binary metadata and agent capability flags.',
+    inputSchema: objectSchema({
+      cursor: {
+        description: 'Path from the previous nextCursor; omit for the first page.',
+        type: 'string',
+      },
+      kinds: {
+        description: 'Optional CollabMD content kinds to include.',
+        items: { type: 'string' },
+        type: 'array',
+        uniqueItems: true,
+      },
+      limit: {
+        description: 'Maximum entries to return.',
+        maximum: 200,
+        minimum: 1,
+        type: 'integer',
+      },
+      prefix: {
+        description: 'Optional Vault directory or path prefix.',
+        type: 'string',
+      },
+      pathQuery: {
+        description: 'Optional case-insensitive substring to match anywhere in an entry path.',
+        maxLength: 500,
+        minLength: 1,
+        type: 'string',
+      },
+    }, []),
+    method: 'listWorkspaceEntries',
+    name: 'list_workspace_entries',
+    outputSchema: objectSchema({
+      entries: { items: WORKSPACE_ENTRY_SCHEMA, type: 'array' },
+      nextCursor: { type: ['string', 'null'] },
+      truncated: { type: 'boolean' },
+    }),
+    scope: 'vault:read',
+    untrustedContentHint: true,
+    webMcp: true,
+  },
+
+  {
+    annotations: { idempotentHint: true, readOnlyHint: true },
+    description: 'Search current Vault text with one fixed case-insensitive term. Returns path and line evidence.',
+    inputSchema: objectSchema({
+      limit: {
+        description: 'Maximum matching documents to return.',
+        maximum: 50,
+        minimum: 1,
+        type: 'integer',
+      },
+      maxSnippetsPerFile: {
+        description: 'Maximum matching snippets returned per document.',
+        maximum: 10,
+        minimum: 1,
+        type: 'integer',
+      },
+      kinds: {
+        description: 'Optional CollabMD content kinds to include.',
+        items: { type: 'string' },
+        type: 'array',
+        uniqueItems: true,
+      },
+      prefix: {
+        description: 'Optional Vault directory or path prefix.',
+        type: 'string',
+      },
+      query: {
+        description: 'Literal case-insensitive text to find; regular expressions are not supported.',
+        maxLength: 500,
+        minLength: 2,
+        type: 'string',
+      },
+      wholeWord: {
+        description: 'Match only when the literal query is bounded by non-word characters.',
+        type: 'boolean',
+      },
+    }, ['query']),
+    method: 'searchVault',
+    name: 'search_vault',
+    outputSchema: objectSchema({
+      backend: { type: 'string' },
+      files: { items: SEARCH_FILE_SCHEMA, type: 'array' },
+      matchCount: { minimum: 0, type: 'integer' },
+      ok: { type: 'boolean' },
+      query: { type: 'string' },
+      search: {
+        additionalProperties: false,
+        properties: {
+          available: { type: 'boolean' },
+          backend: { type: 'string' },
+          minQueryLength: { minimum: 1, type: 'integer' },
+          unavailableReason: { type: 'string' },
+          version: { type: 'string' },
+        },
+        required: ['available', 'backend', 'minQueryLength', 'unavailableReason', 'version'],
+        type: 'object',
+      },
+      truncated: { type: 'boolean' },
+    }),
+    scope: 'vault:read',
+    untrustedContentHint: true,
+    webMcp: true,
+  },
+  {
+    annotations: { idempotentHint: true, readOnlyHint: true },
+    description: 'Read a current CollabMD document range and return full-document revision for citations and edits.',
+    inputSchema: objectSchema({
+      lineCount: {
+        description: 'Maximum number of lines to return.',
+        maximum: 500,
+        minimum: 1,
+        type: 'integer',
+      },
+      path: {
+        description: 'Vault-relative document path.',
+        maxLength: 1024,
+        minLength: 1,
+        type: 'string',
+      },
+      startLine: {
+        description: 'One-based first line to return.',
+        minimum: 1,
+        type: 'integer',
+      },
+    }, ['path']),
+    method: 'readDocument',
+    name: 'read_document',
+    outputSchema: objectSchema({
+      content: { type: 'string' },
+      endLine: { minimum: 1, type: 'integer' },
+      kind: { type: 'string' },
+      path: { type: 'string' },
+      revision: REVISION_SCHEMA,
+      startLine: { minimum: 1, type: 'integer' },
+      totalLines: { minimum: 1, type: 'integer' },
+      truncated: { type: 'boolean' },
+    }),
+    scope: 'vault:read',
+    untrustedContentHint: true,
+    webMcp: true,
+  },
+  {
+    annotations: { idempotentHint: true, readOnlyHint: true },
+    description: 'Inspect resolved and missing wiki-links, embeds, public video embeds, and backlinks for one Markdown document.',
+    inputSchema: objectSchema({
+      path: {
+        description: 'Vault-relative Markdown path.',
+        maxLength: 1024,
+        minLength: 1,
+        type: 'string',
+      },
+    }, ['path']),
+    method: 'inspectDocumentReferences',
+    name: 'inspect_document_references',
+    outputSchema: objectSchema({
+      backlinks: { items: BACKLINK_SCHEMA, type: 'array' },
+      embeds: { items: DOCUMENT_REFERENCE_SCHEMA, type: 'array' },
+      path: { type: 'string' },
+      revision: REVISION_SCHEMA,
+      videos: { items: VIDEO_REFERENCE_SCHEMA, type: 'array' },
+      wikiLinks: { items: DOCUMENT_REFERENCE_SCHEMA, type: 'array' },
+    }),
+    scope: 'vault:read',
+    untrustedContentHint: true,
+    webMcp: true,
+  },
+  {
+    annotations: { idempotentHint: true, readOnlyHint: true },
+    description: 'Validate one Markdown document for missing wiki-link/embed targets and unsupported public video embeds.',
+    inputSchema: objectSchema({
+      path: {
+        description: 'Vault-relative Markdown path.',
+        maxLength: 1024,
+        minLength: 1,
+        type: 'string',
+      },
+    }, ['path']),
+    method: 'validateDocument',
+    name: 'validate_document',
+    outputSchema: objectSchema({
+      issues: { items: VALIDATION_ISSUE_SCHEMA, type: 'array' },
+      path: { type: 'string' },
+      revision: REVISION_SCHEMA,
+      valid: { type: 'boolean' },
+    }),
+    scope: 'vault:read',
+    untrustedContentHint: true,
+    webMcp: true,
+  },
+  {
+    annotations: { idempotentHint: true, readOnlyHint: true },
+    description: 'Run a Base query and return filtered rows so you can verify filters and expected output.',
+    inputSchema: objectSchema({
+      limit: {
+        description: 'Maximum rows to return.',
+        maximum: 200,
+        minimum: 1,
+        type: 'integer',
+      },
+      path: {
+        description: 'Vault-relative .base path.',
+        maxLength: 1024,
+        minLength: 1,
+        type: 'string',
+      },
+      search: {
+        description: 'Optional case-insensitive row search across visible columns.',
+        maxLength: 500,
+        type: 'string',
+      },
+      view: {
+        description: 'Optional Base view name.',
+        maxLength: 200,
+        type: 'string',
+      },
+    }, ['path']),
+    method: 'queryBase',
+    name: 'query_base',
+    outputSchema: objectSchema({
+      columns: {
+        items: objectSchema({
+          id: { type: 'string' },
+          label: { type: 'string' },
+        }),
+        type: 'array',
+      },
+      path: { type: 'string' },
+      rows: {
+        items: objectSchema({
+          cells: {
+            additionalProperties: { type: 'string' },
+            type: 'object',
+          },
+          path: { type: 'string' },
+        }),
+        type: 'array',
+      },
+      totalRows: { minimum: 0, type: 'integer' },
+      truncated: { type: 'boolean' },
+      view: objectSchema({
+        name: { type: 'string' },
+        type: { type: 'string' },
+      }),
+    }),
+    scope: 'vault:read',
+    untrustedContentHint: true,
+    webMcp: true,
+  },
+  {
+    annotations: { idempotentHint: true, readOnlyHint: true },
+    description: 'Render one standalone or fenced Mermaid/PlantUML diagram. Markdown with multiple diagrams requires the opening fence startLine. Mermaid rendering requires WebMCP.',
+    inputSchema: objectSchema({
+      format: {
+        description: 'Image format. PNG is most widely supported by MCP clients.',
+        enum: ['png', 'svg'],
+        type: 'string',
+      },
+      path: {
+        description: 'Vault-relative Markdown, Mermaid, or PlantUML path.',
+        maxLength: 1024,
+        minLength: 1,
+        type: 'string',
+      },
+      startLine: {
+        description: 'Opening fence line for a diagram embedded in Markdown.',
+        minimum: 1,
+        type: 'integer',
+      },
+    }, ['path']),
+    method: 'renderDiagram',
+    name: 'render_diagram',
+    outputSchema: objectSchema(DIAGRAM_RENDER_OUTPUT_PROPERTIES),
+    resultKind: 'image',
+    scope: 'vault:read',
+    untrustedContentHint: true,
+    webMcp: true,
+  },
+
+  {
+    annotations: { idempotentHint: true, readOnlyHint: true },
+    description: 'Inspect an Excalidraw scene structurally. Returns paint order, geometry, text style, bindings, bounds, layout diagnostics, occlusion, clipping, and validity warnings.',
+    inputSchema: objectSchema({
+      path: {
+        description: 'Vault-relative .excalidraw path.',
+        maxLength: 1024,
+        minLength: 1,
+        type: 'string',
+      },
+    }, ['path']),
+    method: 'inspectExcalidraw',
+    name: 'inspect_excalidraw',
+    outputSchema: EXCALIDRAW_INSPECTION_OUTPUT_SCHEMA,
+    scope: 'vault:read',
+    untrustedContentHint: true,
+    webMcp: true,
+  },
+  {
+    annotations: { idempotentHint: true, readOnlyHint: true },
+    description: 'Verify one Excalidraw revision with compact structural and layout diagnostics; render is optional.',
+    inputSchema: objectSchema({
+      ...EXCALIDRAW_RENDER_INPUT_PROPERTIES,
+      inspectOcclusion: {
+        description: 'Inspect fully occluded elements. Defaults to true.',
+        type: 'boolean',
+      },
+    }, ['path']),
+    method: 'verifyExcalidraw',
+    name: 'verify_excalidraw',
+    outputSchema: EXCALIDRAW_VERIFY_OUTPUT_SCHEMA,
+    resultKind: 'optional-image',
+    scope: 'vault:read',
+    untrustedContentHint: true,
+    webMcp: true,
+  },
+  {
+    annotations: { idempotentHint: true, readOnlyHint: true },
+    description: 'Describe CollabMD-supported content kinds, extensions, syntax, and agent write support.',
+    inputSchema: objectSchema({
+      kind: {
+        description: 'Optional content kind. Omit to list all capabilities.',
+        type: 'string',
+      },
+    }, []),
+    method: 'getSyntax',
+    name: 'get_collabmd_syntax',
+    outputSchema: {
+      oneOf: [
+        objectSchema({ capabilities: { items: CAPABILITY_SCHEMA, type: 'array' } }),
+        SYNTAX_GUIDE_SCHEMA,
+      ],
+    },
+    scope: 'vault:read',
+    webMcp: true,
+  },
+  {
+    annotations: { destructiveHint: false, idempotentHint: true, readOnlyHint: false },
+    description: 'Create a valid editable .excalidraw scene from basic Excalidraw elements, with optional same-revision verification.',
+    inputSchema: objectSchema({
+      elements: {
+        description: 'One to 200 basic Excalidraw elements in back-to-front order. Text may bind to a container with containerId; groupIds define atomic movement groups. Arrows may bind with startElementId and endElementId. beforeElementId or afterElementId sets explicit placement.',
+        items: EXCALIDRAW_ELEMENT_INPUT_SCHEMA,
+        maxItems: 200,
+        minItems: 1,
+        type: 'array',
+      },
+      path: {
+        description: 'New Vault-relative path ending in .excalidraw.',
+        maxLength: 1024,
+        minLength: 1,
+        type: 'string',
+      },
+      verify: EXCALIDRAW_INLINE_VERIFY_INPUT_SCHEMA,
+    }, ['path', 'elements']),
+    method: 'createExcalidraw',
+    name: 'create_excalidraw',
+    outputSchema: objectSchema({
+      elementCount: { minimum: 1, type: 'integer' },
+      path: { type: 'string' },
+      revision: REVISION_SCHEMA,
+      verification: EXCALIDRAW_INLINE_VERIFICATION_SCHEMA,
+    }, ['elementCount', 'path', 'revision']),
+    resultKind: 'optional-image',
+    scope: 'vault:edit',
+    webMcp: true,
+  },
+  {
+    annotations: { destructiveHint: false, idempotentHint: false, readOnlyHint: false },
+    description: 'Create, update, replace, translate, reorder, or delete elements in an existing .excalidraw scene when its revision still matches. Bound text whose font, size, line height, or content changes reflows automatically.',
+    inputSchema: objectSchema({
+      create: {
+        items: EXCALIDRAW_ELEMENT_INPUT_SCHEMA,
+        maxItems: 200,
+        type: 'array',
+      },
+      delete: {
+        description: 'Element IDs to tombstone.',
+        items: { maxLength: 128, minLength: 1, type: 'string' },
+        maxItems: 200,
+        type: 'array',
+        uniqueItems: true,
+      },
+      normalizeTextPlacement: {
+        description: 'Normalize every bound text label to its container center and current line-height metrics. This can be the only edit operation.',
+        enum: [true],
+        type: 'boolean',
+      },
+      path: {
+        description: 'Vault-relative .excalidraw path returned by read_document.',
+        maxLength: 1024,
+        minLength: 1,
+        type: 'string',
+      },
+      revision: REVISION_SCHEMA,
+      reorder: {
+        description: 'Layer changes applied in array order. Each entry uses exactly one action, beforeElementId, or afterElementId directive.',
+        items: EXCALIDRAW_REORDER_SCHEMA,
+        maxItems: 200,
+        type: 'array',
+      },
+      replace: {
+        description: 'Atomic same-ID element replacement. Layer position is preserved by default.',
+        items: EXCALIDRAW_REPLACE_SCHEMA,
+        maxItems: 200,
+        type: 'array',
+      },
+      update: {
+        items: EXCALIDRAW_UPDATE_SCHEMA,
+        maxItems: 200,
+        type: 'array',
+      },
+      translate: EXCALIDRAW_TRANSLATE_SCHEMA,
+      verify: EXCALIDRAW_INLINE_VERIFY_INPUT_SCHEMA,
+    }, ['path', 'revision']),
+    method: 'editExcalidraw',
+    name: 'edit_excalidraw',
+    outputSchema: objectSchema({
+      created: { minimum: 0, type: 'integer' },
+      deleted: { minimum: 0, type: 'integer' },
+      elementCount: { minimum: 0, type: 'integer' },
+      path: { type: 'string' },
+      reordered: { minimum: 0, type: 'integer' },
+      reflowed: {
+        description: 'Number of bound text labels whose position or height was normalized.',
+        minimum: 0,
+        type: 'integer',
+      },
+      replaced: { minimum: 0, type: 'integer' },
+      revision: REVISION_SCHEMA,
+      translated: {
+        description: 'Number of explicitly requested translation targets; related bound or grouped elements may also move.',
+        minimum: 0,
+        type: 'integer',
+      },
+      updated: { minimum: 0, type: 'integer' },
+      verification: EXCALIDRAW_INLINE_VERIFICATION_SCHEMA,
+    }, ['created', 'deleted', 'elementCount', 'path', 'reordered', 'reflowed', 'replaced', 'revision', 'translated', 'updated']),
+    resultKind: 'optional-image',
+    scope: 'vault:edit',
+    webMcp: true,
+  },
+  {
+    annotations: { destructiveHint: false, idempotentHint: false, readOnlyHint: false },
+    description: 'Apply bounded exact replacements to a document only when its revision still matches.',
+    inputSchema: objectSchema({
+      path: {
+        description: 'Vault-relative path returned by read_document.',
+        maxLength: 1024,
+        minLength: 1,
+        type: 'string',
+      },
+      replacements: {
+        description: 'One to 20 exact text replacements; each oldText must resolve unambiguously.',
+        items: {
+          additionalProperties: false,
+          properties: {
+            newText: {
+              description: 'Replacement text, normalized to LF line endings.',
+              type: 'string',
+            },
+            oldText: {
+              description: 'Exact current text to replace.',
+              minLength: 1,
+              type: 'string',
+            },
+          },
+          required: ['oldText', 'newText'],
+          type: 'object',
+        },
+        maxItems: 20,
+        minItems: 1,
+        type: 'array',
+      },
+      revision: REVISION_SCHEMA,
+    }, ['path', 'revision', 'replacements']),
+    method: 'applyTextEdits',
+    name: 'apply_text_edits',
+    outputSchema: objectSchema({
+      path: { type: 'string' },
+      replacementCount: { minimum: 1, type: 'integer' },
+      revision: REVISION_SCHEMA,
+    }),
+    scope: 'vault:edit',
+    webMcp: true,
+  },
+  {
+    annotations: { destructiveHint: false, idempotentHint: true, readOnlyHint: false },
+    description: 'Create a new supported CollabMD text document. An identical retry succeeds; different content at an existing path fails.',
+    inputSchema: objectSchema({
+      content: {
+        description: 'Initial document text, normalized to LF line endings.',
+        maxLength: 200000,
+        type: 'string',
+      },
+      path: {
+        description: 'New Vault-relative path with a supported text extension.',
+        maxLength: 1024,
+        minLength: 1,
+        type: 'string',
+      },
+    }, ['path', 'content']),
+    method: 'createDocument',
+    name: 'create_document',
+    outputSchema: objectSchema({
+      kind: { type: 'string' },
+      path: { type: 'string' },
+      revision: REVISION_SCHEMA,
+    }),
+    scope: 'vault:edit',
+    webMcp: true,
+  },
+]);
+
+const DEFINITIONS_BY_NAME = new Map(AGENT_TOOL_DEFINITIONS.map((definition) => [definition.name, definition]));
+
+export function getAgentToolDefinition(name) {
+  return DEFINITIONS_BY_NAME.get(name) ?? null;
+}
+
+export function listAgentToolDefinitions(scopes = []) {
+  const allowed = new Set(scopes);
+  return AGENT_TOOL_DEFINITIONS.filter(({ scope }) => allowed.has(scope));
+}
+
+export function listWebMcpToolDefinitions() {
+  return AGENT_TOOL_DEFINITIONS.filter(({ webMcp }) => webMcp);
+}
+
+export function toWebMcpToolName(name) {
+  return `collabmd_${name}`;
+}