feat(mcp): stdio MCP server exposing the four companion tools

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-01 21:45:42 +10:00
parent c7a94f26d1
commit 1c03d6c277
5 changed files with 499 additions and 0 deletions
--- a/lib/mcp/companion-stdio.js
+++ b/lib/mcp/companion-stdio.js
@@ -0,0 +1,110 @@
+/**
+ * companion-stdio.js
+ *
+ * Exposes the four Void companion tools through the MCP stdio protocol.
+ * The `claude` CLI spawns this file as a subprocess and communicates
+ * over stdin/stdout using JSON-RPC.
+ *
+ * Usage (via claude MCP config):
+ *   VOID_AGENT_JSON='...' VOID_SPACE_ID='...' node lib/mcp/companion-stdio.js
+ *
+ * Exported helpers (transport-free — safe to import in tests):
+ *   listMcpTools()          → array of {name, description, input_schema}
+ *   callMcpTool(name, args, ctx) → raw handler result object
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema
+} from '@modelcontextprotocol/sdk/types.js';
+import { companionRegistry } from '../ai/agent/tools/index.js';
+import { buildCtxFromEnv } from './context.js';
+
+// ---------------------------------------------------------------------------
+// Transport-free helpers (exported for testing)
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the list of MCP tool descriptors (no handler) from the companion registry.
+ * @returns {{ name: string, description: string, input_schema: object }[]}
+ */
+export function listMcpTools() {
+  return companionRegistry.listTools().map(({ name, description, input_schema }) => ({
+    name,
+    description,
+    input_schema
+  }));
+}
+
+/**
+ * Calls a tool handler directly (same code path as the MCP server), bypassing transport.
+ * @param {string} name
+ * @param {object} args
+ * @param {object} ctx  – tool context {agent, space_id, view, actor}
+ * @returns {Promise<object>} raw handler result
+ */
+export async function callMcpTool(name, args, ctx) {
+  const tool = companionRegistry.getTool(name);
+  if (!tool) {
+    throw new Error(`Unknown tool: ${name}`);
+  }
+  return tool.handler(args, ctx);
+}
+
+// ---------------------------------------------------------------------------
+// MCP server factory (used when running as a script)
+// ---------------------------------------------------------------------------
+
+function createServer() {
+  const server = new Server(
+    { name: 'void-companion', version: '1.0.0' },
+    { capabilities: { tools: {} } }
+  );
+
+  // tools/list — return all companion tools with their raw JSON schemas
+  server.setRequestHandler(ListToolsRequestSchema, () => ({
+    tools: listMcpTools().map(({ name, description, input_schema }) => ({
+      name,
+      description,
+      inputSchema: input_schema   // MCP protocol field name is inputSchema
+    }))
+  }));
+
+  // tools/call — delegate to the registry handler, wrap result as text content
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    const ctx = buildCtxFromEnv();
+    try {
+      const result = await callMcpTool(name, args, ctx);
+      const text = JSON.stringify(result);
+      return {
+        content: [{ type: 'text', text }],
+        structuredContent: result
+      };
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: err.message ?? String(err) }],
+        isError: true
+      };
+    }
+  });
+
+  return server;
+}
+
+// ---------------------------------------------------------------------------
+// Entry point — only connect stdio transport when run as a script
+// ---------------------------------------------------------------------------
+
+const isMain =
+  typeof process !== 'undefined' &&
+  process.argv[1] &&
+  import.meta.url === new URL(process.argv[1], 'file://').href;
+
+if (isMain) {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
--- a/lib/mcp/context.js
+++ b/lib/mcp/context.js
@@ -0,0 +1,18 @@
+/**
+ * Builds the tool ctx object from environment variables.
+ * Used by companion-stdio.js when a tool call arrives, so each call reads
+ * fresh env values (useful if the process restarts or env is injected at launch).
+ *
+ * Environment variables:
+ *   VOID_AGENT_JSON  – JSON-serialised agent actor object (required for most tools)
+ *   VOID_SPACE_ID    – UUID of the active space
+ *   VOID_VIEW_JSON   – JSON-serialised view object (optional)
+ */
+export function buildCtxFromEnv(env = process.env) {
+  return {
+    agent: env.VOID_AGENT_JSON ? JSON.parse(env.VOID_AGENT_JSON) : null,
+    space_id: env.VOID_SPACE_ID || null,
+    view: env.VOID_VIEW_JSON ? JSON.parse(env.VOID_VIEW_JSON) : null,
+    actor: { kind: 'user', id: null }
+  };
+}
--- a/package-lock.json
+++ b/package-lock.json
@@ -9,6 +9,7 @@
      "version": "2.0.0-alpha.5",
      "dependencies": {
        "@anthropic-ai/sdk": "^0.40.1",
+        "@modelcontextprotocol/sdk": "^1.29.0",
        "@mozilla/readability": "^0.6.0",
        "bcrypt": "^6.0.0",
        "dompurify": "^3.4.7",
@@ -364,6 +365,18 @@
        }
      }
    },
+    "node_modules/@hono/node-server": {
+      "version": "1.19.14",
+      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.14.tgz",
+      "integrity": "sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.14.1"
+      },
+      "peerDependencies": {
+        "hono": "^4"
+      }
+    },
    "node_modules/@jridgewell/resolve-uri": {
      "version": "3.1.2",
      "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
@@ -392,6 +405,46 @@
        "@jridgewell/sourcemap-codec": "^1.4.14"
      }
    },
+    "node_modules/@modelcontextprotocol/sdk": {
+      "version": "1.29.0",
+      "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.29.0.tgz",
+      "integrity": "sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@hono/node-server": "^1.19.9",
+        "ajv": "^8.17.1",
+        "ajv-formats": "^3.0.1",
+        "content-type": "^1.0.5",
+        "cors": "^2.8.5",
+        "cross-spawn": "^7.0.5",
+        "eventsource": "^3.0.2",
+        "eventsource-parser": "^3.0.0",
+        "express": "^5.2.1",
+        "express-rate-limit": "^8.2.1",
+        "hono": "^4.11.4",
+        "jose": "^6.1.3",
+        "json-schema-typed": "^8.0.2",
+        "pkce-challenge": "^5.0.0",
+        "raw-body": "^3.0.0",
+        "zod": "^3.25 || ^4.0",
+        "zod-to-json-schema": "^3.25.1"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@cfworker/json-schema": "^4.1.1",
+        "zod": "^3.25 || ^4.0"
+      },
+      "peerDependenciesMeta": {
+        "@cfworker/json-schema": {
+          "optional": true
+        },
+        "zod": {
+          "optional": false
+        }
+      }
+    },
    "node_modules/@mozilla/readability": {
      "version": "0.6.0",
      "resolved": "https://registry.npmjs.org/@mozilla/readability/-/readability-0.6.0.tgz",
@@ -973,6 +1026,39 @@
        "node": ">= 8.0.0"
      }
    },
+    "node_modules/ajv": {
+      "version": "8.20.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
+      "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.3",
+        "fast-uri": "^3.0.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/ajv-formats": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-3.0.1.tgz",
+      "integrity": "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==",
+      "license": "MIT",
+      "dependencies": {
+        "ajv": "^8.0.0"
+      },
+      "peerDependencies": {
+        "ajv": "^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "ajv": {
+          "optional": true
+        }
+      }
+    },
    "node_modules/append-field": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/append-field/-/append-field-1.0.0.tgz",
@@ -1232,6 +1318,23 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/cors": {
+      "version": "2.8.6",
+      "resolved": "https://registry.npmjs.org/cors/-/cors-2.8.6.tgz",
+      "integrity": "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==",
+      "license": "MIT",
+      "dependencies": {
+        "object-assign": "^4",
+        "vary": "^1"
+      },
+      "engines": {
+        "node": ">= 0.10"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
    "node_modules/cron-parser": {
      "version": "4.9.0",
      "resolved": "https://registry.npmjs.org/cron-parser/-/cron-parser-4.9.0.tgz",
@@ -1244,6 +1347,20 @@
        "node": ">=12.0.0"
      }
    },
+    "node_modules/cross-spawn": {
+      "version": "7.0.6",
+      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+      "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+      "license": "MIT",
+      "dependencies": {
+        "path-key": "^3.1.0",
+        "shebang-command": "^2.0.0",
+        "which": "^2.0.1"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
    "node_modules/css-tree": {
      "version": "3.2.1",
      "resolved": "https://registry.npmjs.org/css-tree/-/css-tree-3.2.1.tgz",
@@ -1498,6 +1615,27 @@
        "node": ">=6"
      }
    },
+    "node_modules/eventsource": {
+      "version": "3.0.7",
+      "resolved": "https://registry.npmjs.org/eventsource/-/eventsource-3.0.7.tgz",
+      "integrity": "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==",
+      "license": "MIT",
+      "dependencies": {
+        "eventsource-parser": "^3.0.1"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/eventsource-parser": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/eventsource-parser/-/eventsource-parser-3.1.0.tgz",
+      "integrity": "sha512-kJezFj9YFAMLeORyi7aCLxLbD5/qWMQnoMVlVPyHIll7lgRJCc3JVln9Vgl9nwQi0YkMnhdGTMNn7CkRRAptMg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
    "node_modules/expect-type": {
      "version": "1.3.0",
      "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.3.0.tgz",
@@ -1551,18 +1689,58 @@
        "url": "https://opencollective.com/express"
      }
    },
+    "node_modules/express-rate-limit": {
+      "version": "8.5.2",
+      "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.5.2.tgz",
+      "integrity": "sha512-5Kb34ipNX694DH48vN9irak1Qx30nb0PLYHXfJgw4YEjiC3ZEmZJhwOp+VfiCYwFzvFTdB9QkArYS5kXa2cx2A==",
+      "license": "MIT",
+      "dependencies": {
+        "ip-address": "^10.2.0"
+      },
+      "engines": {
+        "node": ">= 16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/express-rate-limit"
+      },
+      "peerDependencies": {
+        "express": ">= 4.11"
+      }
+    },
    "node_modules/fast-copy": {
      "version": "4.0.3",
      "resolved": "https://registry.npmjs.org/fast-copy/-/fast-copy-4.0.3.tgz",
      "integrity": "sha512-58apWr0GUiDFM8+3afrO6eYwJBn9ZAhDOzG3L+/9llab/haCARS2UIfffmOurYLwbgDRs8n0rfr6qAAPEAuAQw==",
      "license": "MIT"
    },
+    "node_modules/fast-deep-equal": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+      "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+      "license": "MIT"
+    },
    "node_modules/fast-safe-stringify": {
      "version": "2.1.1",
      "resolved": "https://registry.npmjs.org/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz",
      "integrity": "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==",
      "license": "MIT"
    },
+    "node_modules/fast-uri": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.2.tgz",
+      "integrity": "sha512-rVjf7ArG3LTk+FS6Yw81V1DLuZl1bRbNrev6Tmd/9RaroeeRRJhAt7jg/6YFxbvAQXUCavSoZhPPj6oOx+5KjQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "BSD-3-Clause"
+    },
    "node_modules/fdir": {
      "version": "6.5.0",
      "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
@@ -1822,6 +2000,15 @@
      "integrity": "sha512-7xgomUX6ADmcYzFik0HzAxh/73YlKR9bmFzf51CZwR+b6YtzU2m0u49hQCqV6SvlqIqsaxovfwdvbnsw3b/zpg==",
      "license": "MIT"
    },
+    "node_modules/hono": {
+      "version": "4.12.23",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.23.tgz",
+      "integrity": "sha512-eIaZ9qDgu7XV0pxOCrg7/WhnQ6Ivm22UcxhXx/A3dcbqbbYgBEkc6e/J/s7j2tS96zoB0S9VBdLwQNCWwUo4LA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=16.9.0"
+      }
+    },
    "node_modules/html-encoding-sniffer": {
      "version": "6.0.0",
      "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-6.0.0.tgz",
@@ -1892,6 +2079,15 @@
      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
      "license": "ISC"
    },
+    "node_modules/ip-address": {
+      "version": "10.2.0",
+      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.2.0.tgz",
+      "integrity": "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12"
+      }
+    },
    "node_modules/ipaddr.js": {
      "version": "1.9.1",
      "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz",
@@ -1913,6 +2109,12 @@
      "integrity": "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==",
      "license": "MIT"
    },
+    "node_modules/isexe": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
+      "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
+      "license": "ISC"
+    },
    "node_modules/istanbul-lib-coverage": {
      "version": "3.2.2",
      "resolved": "https://registry.npmjs.org/istanbul-lib-coverage/-/istanbul-lib-coverage-3.2.2.tgz",
@@ -1952,6 +2154,15 @@
        "node": ">=8"
      }
    },
+    "node_modules/jose": {
+      "version": "6.2.3",
+      "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.3.tgz",
+      "integrity": "sha512-YYVDInQKFJfR/xa3ojUTl8c2KoTwiL1R5Wg9YCydwH0x0B9grbzlg5HC7mMjCtUJjbQ/YnGEZIhI5tCgfTb4Hw==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/panva"
+      }
+    },
    "node_modules/joycon": {
      "version": "3.1.1",
      "resolved": "https://registry.npmjs.org/joycon/-/joycon-3.1.1.tgz",
@@ -2008,6 +2219,18 @@
        }
      }
    },
+    "node_modules/json-schema-traverse": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+      "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
+      "license": "MIT"
+    },
+    "node_modules/json-schema-typed": {
+      "version": "8.0.2",
+      "resolved": "https://registry.npmjs.org/json-schema-typed/-/json-schema-typed-8.0.2.tgz",
+      "integrity": "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==",
+      "license": "BSD-2-Clause"
+    },
    "node_modules/lightningcss": {
      "version": "1.32.0",
      "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.32.0.tgz",
@@ -2620,6 +2843,15 @@
        "node-gyp-build-test": "build-test.js"
      }
    },
+    "node_modules/object-assign": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
+      "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
    "node_modules/object-inspect": {
      "version": "1.13.4",
      "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz",
@@ -2694,6 +2926,15 @@
        "node": ">= 0.8"
      }
    },
+    "node_modules/path-key": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
+      "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
    "node_modules/path-to-regexp": {
      "version": "8.4.2",
      "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.4.2.tgz",
@@ -2895,6 +3136,15 @@
      "integrity": "sha512-BndPH67/JxGExRgiX1dX0w1FvZck5Wa4aal9198SrRhZjH3GxKQUKIBnYJTdj2HDN3UQAS06HlfcSbQj2OHmaw==",
      "license": "MIT"
    },
+    "node_modules/pkce-challenge": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/pkce-challenge/-/pkce-challenge-5.0.1.tgz",
+      "integrity": "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
    "node_modules/postcss": {
      "version": "8.5.15",
      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz",
@@ -3280,6 +3530,27 @@
      "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==",
      "license": "ISC"
    },
+    "node_modules/shebang-command": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
+      "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
+      "license": "MIT",
+      "dependencies": {
+        "shebang-regex": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/shebang-regex": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
+      "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
    "node_modules/side-channel": {
      "version": "1.1.0",
      "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.0.tgz",
@@ -3933,6 +4204,21 @@
        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
      }
    },
+    "node_modules/which": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
+      "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+      "license": "ISC",
+      "dependencies": {
+        "isexe": "^2.0.0"
+      },
+      "bin": {
+        "node-which": "bin/node-which"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
    "node_modules/why-is-node-running": {
      "version": "2.3.0",
      "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
@@ -3988,6 +4274,15 @@
      "funding": {
        "url": "https://github.com/sponsors/colinhacks"
      }
+    },
+    "node_modules/zod-to-json-schema": {
+      "version": "3.25.2",
+      "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.2.tgz",
+      "integrity": "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==",
+      "license": "ISC",
+      "peerDependencies": {
+        "zod": "^3.25.28 || ^4"
+      }
    }
  }
 }
--- a/package.json
+++ b/package.json
@@ -11,6 +11,7 @@
  },
  "dependencies": {
    "@anthropic-ai/sdk": "^0.40.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
    "@mozilla/readability": "^0.6.0",
    "bcrypt": "^6.0.0",
    "dompurify": "^3.4.7",
--- a/tests/mcp/companion_tools.test.js
+++ b/tests/mcp/companion_tools.test.js
@@ -0,0 +1,75 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { pool } from '../../lib/db/pool.js';
+import { resetDb } from '../helpers/db.js';
+import { migrateUp } from '../../lib/db/migrate.js';
+import { listMcpTools, callMcpTool } from '../../lib/mcp/companion-stdio.js';
+
+let spaceId, agentId;
+
+beforeAll(async () => {
+  await resetDb();
+  await migrateUp();
+  ({ rows: [{ id: spaceId }] } = await pool.query(
+    `INSERT INTO spaces(slug,name) VALUES('mcp-test','MCP Test') RETURNING id`
+  ));
+  ({ rows: [{ id: agentId }] } = await pool.query(
+    `SELECT id FROM agents WHERE slug='companion'`
+  ));
+});
+
+const suggestAgent = (id) => ({
+  kind: 'agent',
+  id,
+  capabilities: { read: true, suggest: true, write: false },
+  scopes: {}
+});
+
+describe('listMcpTools()', () => {
+  it('returns exactly the four companion tools sorted by name', () => {
+    const tools = listMcpTools();
+    expect(tools.map(t => t.name).sort()).toEqual(['context', 'propose_change', 'read', 'search']);
+  });
+
+  it('each tool has name, description, and input_schema', () => {
+    const tools = listMcpTools();
+    for (const t of tools) {
+      expect(t.name).toBeTruthy();
+      expect(t.description).toBeTruthy();
+      expect(t.input_schema).toBeTruthy();
+      expect(t.input_schema.type).toBe('object');
+    }
+  });
+});
+
+describe('callMcpTool()', () => {
+  it('propose_change writes a pending_changes row (pending) and returns applied:false', async () => {
+    const ctx = { agent: suggestAgent(agentId), space_id: spaceId };
+    const result = await callMcpTool(
+      'propose_change',
+      {
+        entity_type: 'task',
+        action: 'create',
+        payload: { space_id: spaceId, title: 'MCP test task' }
+      },
+      ctx
+    );
+
+    expect(result.pending_change_id).toBeTruthy();
+    expect(result.applied).toBe(false);
+
+    // Check DB: the row exists and is pending
+    const { rows } = await pool.query(
+      `SELECT * FROM pending_changes WHERE id=$1`,
+      [result.pending_change_id]
+    );
+    expect(rows).toHaveLength(1);
+    expect(rows[0].status).toBe('pending');
+    expect(rows[0].agent_id).toBe(agentId);
+
+    // The task was NOT created
+    const { rows: tasks } = await pool.query(
+      `SELECT * FROM tasks WHERE title='MCP test task'`
+    );
+    expect(tasks).toHaveLength(0);
+  });
+});