Skip to content

feat: render MCP config into each target's MCP dialect - #37

Open
steve-calvert-glean wants to merge 2 commits into
mainfrom
feat/mcp-dialects
Open

steve-calvert-glean wants to merge 2 commits into
mainfrom
feat/mcp-dialects

Conversation

@steve-calvert-glean

Copy link
Copy Markdown
Contributor

First of three PRs adding Agent Plugins support. This one builds the MCP piece and changes no output for configs that already work.

Why

Authored MCP config was copied verbatim into every target. The README said pluginpack "translates the configuration into each target's native MCP layout", but only the file path changed. Each client expects different variable names (${CLAUDE_PLUGIN_ROOT}, ${CURSOR_PLUGIN_ROOT}, ${PLUGIN_ROOT}), so authors forked mcp/config.json per target. gleanwork/agent-plugins keeps overrides/codex/glean/mcp/config.json for exactly this. Agent Plugins output needs $schema, an explicit type, and spec-valid fields, so this has to be fixed before that format can be emitted.

What

  • src/mcp.ts: renderMcpConfig(servers, dialect, context) holds every client's MCP dialect: variable names, transport labels, and the Agent Plugins 1.0 rules.
  • Each target sets one mcpDialect; the engine renders through the module.
Dialect Root / data variables Transport
claude ${CLAUDE_PLUGIN_ROOT} / ${CLAUDE_PLUGIN_DATA} streamable-http → http
cursor ${CURSOR_PLUGIN_ROOT} / none (build error) type dropped for stdio/HTTP (Cursor infers it)
copilot ${PLUGIN_ROOT} / as authored streamable-http → http
verbatim as authored (codex, antigravity for now) as authored
agent-plugins ${PLUGIN_ROOT} / ${PLUGIN_DATA} + $schema explicit type; spec §7.2 / §9 enforced

The agent-plugins dialect turns anything a conforming client would silently skip into a build error: a shell string as command, ${API_TOKEN} in env (left unexpanded), plain http to a remote host, reserved env names, or a cwd that escapes the plugin. No target uses this dialect yet; the next PR switches codex to it.

Also adds CONTEXT.md (glossary) and docs/adr/0001 (codex emits Agent Plugins packages by default, with no dual layout).

Behavior change

  • Cursor: ${PLUGIN_DATA} / ${CLAUDE_PLUGIN_DATA} in MCP config is now a build error. Cursor has no plugin-data variable, so that config never worked there.
  • Claude/Cursor: a ./bin/server command becomes ${<root variable>}/bin/server.
  • Config already in a target's own dialect is emitted unchanged.

Verification

  • npm run check passes (239 tests; 40 new in tests/mcp.test.ts, plus one build-level wiring test).
  • Built gleanwork/agent-plugins with released 0.11.0 and with this branch (temp copies): all 191 output files are byte-identical, including the claude, cursor, and codex .mcp.json files.
  • Rendering Glean's shared config in the agent-plugins dialect gives valid Agent Plugins mcp.json. The current codex override is rejected because its cwd: "." isn't a valid Agent Plugins path.

Next

  • (b) Agent Plugins package module, a codex format option (default agent-plugins), a standalone agent-plugins target, and pinned 1.0.0 schemas. Release as 0.12.0.
  • (c) agent-plugins: delete the codex MCP override, convert the shared config, and regenerate codex-plugins.

Authored MCP config was copied verbatim into every target, so authors
forked mcp/config.json per target just to change a plugin-root variable,
and nothing checked the result.

Add src/mcp.ts, which owns every client's MCP dialect: plugin-root and
plugin-data variable names and transport labels. Each target names one
mcpDialect and the engine renders through the module.

- claude: ${CLAUDE_PLUGIN_ROOT}/${CLAUDE_PLUGIN_DATA}; streamable-http -> http
- cursor: ${CURSOR_PLUGIN_ROOT}; type dropped for stdio/HTTP; plugin-data
  variables are a build error (Cursor has none)
- copilot: ${PLUGIN_ROOT}; streamable-http -> http
- codex, antigravity: verbatim (codex moves to Agent Plugins next)
- agent-plugins: Agent Plugins 1.0 mcp.json with $schema, validated
  against spec 7.2/9 (not yet used by a target)

Config already in a target's dialect is unchanged: building
gleanwork/agent-plugins with 0.11.0 and with this change produces
byte-identical output (191 files).

Also adds CONTEXT.md (glossary) and ADR 0001 (codex emits Agent Plugins
packages by default, with no dual layout).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant