Skip to content
ZincGitHubDownload

Phase 3: plugin MCP tools (report)

View as Markdown

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: added import mcp; and export mcp-handler;.
  • New world plugin-mcp { include plugin-library; import mcp; export mcp-handler; }.
  • The plugin-minimal comment 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

  1. plugin-host/test/pkg/units.test.ts line ~134: expect(KNOWN_CAPABILITIES.length).toBe(36) becomes 37 (the schema list gained mcp.expose; the test will fail until then).
  2. plugin-host/src/manifest.ts: add "plugin-mcp" to the PluginWorld union (type only).
  3. plugin-host/src/package/json-schema.ts ignores if/then/contains, so the schema rule “mcp.tools needs mcp.expose” is not enforced at install. Either add those keywords, or a rule in package/validate.ts. The bridge is safe meanwhile (it never lists a plugin without the grant).
  4. 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 (older plugin world).
  5. Done (2026-11-19): the skills (.claude/skills/zinc-plugin-*) cover plugin-mcp, defineTool, mcp::Tool and the mcp.expose permission (SKILL.md, choose-and-manifest.md, the JS and Rust recipes, the port skill’s rules), and scaffold.ts --with mcp writes a working tool in JS or Rust. They are published as zips: agent-skills.md.

What is left / notes

  • No notifications/tools/list_changed over HTTP: stateless and POST-only, so impossible without sessions and a GET stream. Long-lived connections (in-memory, a future SSE) get it via provider.onChange (tested).
  • The settings row is not covered by a screenshot test (no window); bun check and 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 _requestHandlers map 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 passes scope: { 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 mcp feature but has no end-to-end test.
  • One test run of samples/test.ts showed 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 editing sdk/js/src/ui.ts and defaults.ts at the time).
  • Housekeeping: early on I ran an edit with the wrong working directory against the MAIN checkout’s core/src/mcp/server.ts and reverted it at once with git apply -R (content identical to HEAD; git status there still lists the file as stat-modified because of line endings). No other file in the main checkout was touched.