Phase 3: plugin MCP tools (report)
Design and how-to: mcp.md. User side: docs/user-guide/mcp.md (“Tools from plugins”). Core side: core/MCP.md (“Plugin tools”).
Test results
| What | Result |
|---|---|
core: bun test test/mcp (new plugin-tools.test.ts: fake provider, listing, naming, schema validation, errors, timeout, annotations, disabled/empty/throwing provider, output schema, list_changed, HTTP with the global provider) |
31 pass (14 new) |
gpui-ui: bun test src/wasmplugins/mcp (handler, provider gating, bridge install and HTTP) |
10 pass |
plugin-api/sdk/js: bun test test |
20 pass (6 new) |
bun check in core/, gpui-ui/, plugin-api/sdk/js/, plugin-host/ |
clean |
jco types for all 9 worlds (plugin, plugin-minimal, plugin-core, plugin-library, plugin-extend, plugin-ui, plugin-reader, plugin-dialogs, plugin-mcp) |
all ok |
cargo build --target wasm32-wasip2 in plugin-api/sdk/rust with --features full, mcp, library |
all build (the stable toolchain has the target; cargo is not on this shell’s PATH) |
bun plugin-api/samples/test.ts (word-count, quick-tags, mcp-tools, highlight-export) |
PASS, 77 checks (mcp-tools section: 29) |
The mcp-tools section is end to end through the real chain: a throwaway core (a fresh fixture library in %TEMP%, started with startServer on a free port), the real MCP endpoint, the gpui-ui bridge, the real supervisor
and the real library host handlers talking to that core. It checks: switch off lists nothing and a call fails; switch on lists the manifest tool and the run-time tool with prefixed names, description prefix,
annotations and schemas; count_tagged returns structuredContent from the real library; invalid arguments are tool errors before the plugin runs; add_tag really writes the tag in the throwaway database;
a plugin not-found is a tool error with its message; switch off again; stop lists nothing; restart brings both tools back; revoking mcp.expose removes them.
The supervisor worked in this run.
Files
New: plugin-api/wit/mcp.wit; core/src/mcp/plugin-tools.ts, plugin-tools-server.ts; core/test/mcp/plugin-tools.test.ts; gpui-ui/src/wasmplugins/mcp/{tools,handler,provider,exposure}.ts, mcp.test.ts;
plugin-api/sdk/js/src/mcp.ts; plugin-api/sdk/rust/src/mcp.rs; plugin-api/samples/mcp-tools/{manifest.json,README.md,src/main.js}; docs/developer-guide/wasm-plugins/mcp.md, this report.
Edited: plugin-api/wit/world.wit; plugin-api/manifest.schema.json; the fixture copy gpui-ui/src/wasmplugins/ui/test/fixture-ui-js/wit/deps/zinc-plugin/{mcp,world}.wit;
core/src/mcp/{server,http}.ts (createMcpServer(db, { pluginTools }); http passes the global provider), core/MCP.md, docs/user-guide/mcp.md;
gpui-ui/src/wasmplugins/{index,register}.ts, extend/settings.tsx (per-plugin switch row); plugin-api/sdk/js/{src/plugin.ts,src/index.ts,scripts/build.ts,template/src/main.js,test/sdk.test.ts};
plugin-api/sdk/rust/{Cargo.toml,src/lib.rs,src/plugin.rs}; plugin-api/samples/test.ts.
WIT changes in full
plugin-api/wit/mcp.wit (new):
interface mcp { use types.{json, error}; record tool-annotations { read-only: bool, destructive: bool, idempotent: bool } record tool-def { name: string, // 1-48 of [A-Za-z0-9_.-] description: string, // up to 4000 input-schema: json, // object schema, up to 64 KiB output-schema: option<json>, annotations: tool-annotations, } register-tool: func(tool: tool-def) -> result<_, error>; // replaces a same-named tool; max 64 per plugin unregister-tool: func(name: string) -> result<_, error>; // not-found if absent; also removes a manifest tool until restart list-tools: func() -> list<tool-def>; // manifest tools, then run-time ones}interface mcp-handler { use types.{json, error}; on-mcp-call: func(tool: string, args: json) -> result<json, error>;}(Doc comments in the file carry the full rules.) world.wit:
world plugin: addedimport mcp;andexport mcp-handler;.- New
world plugin-mcp { include plugin-library; import mcp; export mcp-handler; }. - The
plugin-minimalcomment lists the new interfaces; no other world changed.
Default mcp-handler so that nothing built against plugin has to opt in: the JS SDK (definePlugin fallback and build.ts, which appends a default mcpHandler export to a plugin or plugin-mcp bundle that
lacks one) and the Rust SDK (Plugin::on_mcp_call default, implemented by Glue whenever the world has mcp-handler) list no tools and answer calls with not-found. Verified: the three existing samples build and pass unchanged.
Manifest schema: capability mcp.expose (examples and x-risk.medium, 37 ids), top-level mcp.tools ($defs.mcpTool: name, description, input_schema, output_schema, annotations.read_only/destructive/idempotent),
world enum gains plugin-mcp, and an if/then that mcp.tools requires mcp.expose.
Needs from other areas
plugin-host/test/pkg/units.test.tsline ~134:expect(KNOWN_CAPABILITIES.length).toBe(36)becomes37(the schema list gainedmcp.expose; the test will fail until then).plugin-host/src/manifest.ts: add"plugin-mcp"to thePluginWorldunion (type only).plugin-host/src/package/json-schema.tsignoresif/then/contains, so the schema rule “mcp.tools needs mcp.expose” is not enforced at install. Either add those keywords, or a rule inpackage/validate.ts. The bridge is safe meanwhile (it never lists a plugin without the grant).- The other WIT copies (
plugin-host/test/fixtures/*/wit,plugin-host/test/pkg/fixtures/e2e-js/wit,gpui-ui/test/wasm-extend-fixture/wit) were not touched; refresh them when their owners next sync the WIT. They still build (olderpluginworld). - Done (2026-11-19): the skills (
.claude/skills/zinc-plugin-*) coverplugin-mcp,defineTool,mcp::Tooland themcp.exposepermission (SKILL.md,choose-and-manifest.md, the JS and Rust recipes, the port skill’s rules), andscaffold.ts --with mcpwrites a working tool in JS or Rust. They are published as zips: agent-skills.md.
What is left / notes
- No
notifications/tools/list_changedover HTTP: stateless and POST-only, so impossible without sessions and a GET stream. Long-lived connections (in-memory, a future SSE) get it viaprovider.onChange(tested). - The settings row is not covered by a screenshot test (no window);
bun checkand the toggle’s store (exposure.ts) are exercised through the provider tests. Static tools only are counted in the row’s description. - Core wraps the MCP SDK’s private
_requestHandlersmap to add JSON-Schema tools (McpServer only accepts zod). A test fails first if an SDK upgrade moves it. fill()in the JS SDK does not default variant fields (item-query.scope): the sample passesscope: { tag: "all" }. A trap in the guest was the symptom.- A Rust version of the sample was not written; the Rust SDK compiles with the
mcpfeature but has no end-to-end test. - One test run of
samples/test.tsshowed a transient field-order mismatch in quick-tags ({kind,name}vs{name,kind}); it passed in the next runs. It is outside this change (another agent was editingsdk/js/src/ui.tsanddefaults.tsat the time). - Housekeeping: early on I ran an edit with the wrong working directory against the MAIN checkout’s
core/src/mcp/server.tsand reverted it at once withgit apply -R(content identical to HEAD;git statusthere still lists the file as stat-modified because of line endings). No other file in the main checkout was touched.