Repository navigation
feat: render MCP config into each target's MCP dialect - #37
Merged
Merged
Conversation
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).
steve-calvert-glean
force-pushed
the
feat/mcp-dialects
branch
from
October 2, 2026 22:28
875874e to
a82431a
Compare
steve-calvert-glean
added a commit
that referenced
this pull request
Oct 19, 2026
Fixes from a self-review of the #37 + #38 stack. - F3: validate parsed SKILL.md frontmatter with gray-matter's default engines, so a ---js block ran through eval(). A shared parseMatter() helper now refuses the js and javascript engines, for every target. - F13: build could emit a plugin.json that validate rejects (a bad extension namespace, extra author fields). placeClientFields now runs the same manifest checks and fails the build. - F6: native dialects kept an Agent Plugins "./server" cwd as a bare relative path, which clients resolve against the user's project. It now becomes ${<root>}/server, like a ./ command. - F8: the agent-plugins target dropped scripts/ by default while still emitting MCP commands that point into it. scripts is now a default component, as it is for codex. - F1: validate re-rendered mcp.json and kept only render errors, so a server without "type" or with "http" passed. It now reports any server that is not already in normalized Agent Plugins form. - F15: add a test for default-format codex output with hooks/. - F9, F17, F18, F21: README upgrade note covers the MCP build errors, the MCP rules list is complete, install-snippet docs name agent-plugins, and CLAUDE.md agrees with CONFORMANCE.md on schemas.
steve-calvert-glean
added a commit
that referenced
this pull request
Oct 19, 2026
Fixes from a self-review of the #37 + #38 stack. - F3: validate parsed SKILL.md frontmatter with gray-matter's default engines, so a ---js block ran through eval(). A shared parseMatter() helper now refuses the js and javascript engines, for every target. - F13: build could emit a plugin.json that validate rejects (a bad extension namespace, extra author fields). placeClientFields now runs the same manifest checks and fails the build. - F6: native dialects kept an Agent Plugins "./server" cwd as a bare relative path, which clients resolve against the user's project. It now becomes ${<root>}/server, like a ./ command. - F8: the agent-plugins target dropped scripts/ by default while still emitting MCP commands that point into it. scripts is now a default component, as it is for codex. - F1: validate re-rendered mcp.json and kept only render errors, so a server without "type" or with "http" passed. It now reports any server that is not already in normalized Agent Plugins form. - F15: add a test for default-format codex output with hooks/. - F9, F17, F18, F21: README upgrade note covers the MCP build errors, the MCP rules list is complete, install-snippet docs name agent-plugins, and CLAUDE.md agrees with CONFORMANCE.md on schemas.
steve-calvert-glean
added a commit
that referenced
this pull request
Oct 20, 2026
…s target (#38) * feat!: emit Agent Plugins packages from codex and add an agent-plugins target Agent Plugins 1.0 standardizes the plugin package: a closed root plugin.json, skills/, mcp.json, and reverse-domain extension namespaces. OpenAI now prefers it for Codex and ChatGPT and keeps .codex-plugin/plugin.json only as a fallback. - src/agent-plugins.ts: the package module. It builds the portable manifest, moves client fields under extensions[<namespace>], and validates a package against the spec (closed manifest, plugin name, mcp.json, and skill names per the Agent Skills spec). - codex: emits a package by default (root plugin.json with OpenAI settings under extensions.com.openai, plus mcp.json) and keeps .agents/plugins/marketplace.json. format: "legacy" keeps the .codex-plugin layout; validate detects the layout per plugin. - agent-plugins: a new standalone target that writes portable packages only, with no marketplace and no client profile. Client-only content kinds are a config error; non-portable manifest fields are a build error. - Targets can now choose a definition per config (forConfig) and post- process the merged manifest (finalizeManifest). - Vendors the official 1.0.0 schemas (with provenance) as the conformance oracle for codex and agent-plugins. BREAKING CHANGE: the codex target's default output layout changes from .codex-plugin/plugin.json + .mcp.json to an Agent Plugins package (plugin.json + mcp.json). Set `format: "legacy"` on the codex target to keep the previous layout. MCP config and skill names that Agent Plugins clients would skip now fail build or validate. * fix: address self-review findings Fixes from a self-review of the #37 + #38 stack. - F3: validate parsed SKILL.md frontmatter with gray-matter's default engines, so a ---js block ran through eval(). A shared parseMatter() helper now refuses the js and javascript engines, for every target. - F13: build could emit a plugin.json that validate rejects (a bad extension namespace, extra author fields). placeClientFields now runs the same manifest checks and fails the build. - F6: native dialects kept an Agent Plugins "./server" cwd as a bare relative path, which clients resolve against the user's project. It now becomes ${<root>}/server, like a ./ command. - F8: the agent-plugins target dropped scripts/ by default while still emitting MCP commands that point into it. scripts is now a default component, as it is for codex. - F1: validate re-rendered mcp.json and kept only render errors, so a server without "type" or with "http" passed. It now reports any server that is not already in normalized Agent Plugins form. - F15: add a test for default-format codex output with hooks/. - F9, F17, F18, F21: README upgrade note covers the MCP build errors, the MCP rules list is complete, install-snippet docs name agent-plugins, and CLAUDE.md agrees with CONFORMANCE.md on schemas. * fix: report broken and deep Agent Plugins packages in validate Resolves the self-review findings that needed a decision. - F2: findPackages stopped at depth 4, so validate missed a package at a valid deeper plugin path. The depth cap is gone; the walk still stops at each package and skips node_modules and dot-directories. - F7: a plugin.json that failed to parse or declared another $schema was not treated as a package. Codex then blamed a missing .codex-plugin/plugin.json, and the agent-plugins target skipped the plugin. Both now validate the root plugin.json and report it. - F10: the README now says Cursor output drops "type" from stdio and HTTP servers, instead of claiming native config is always unchanged.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 forkedmcp/config.jsonper target.gleanwork/agent-pluginskeepsoverrides/codex/glean/mcp/config.jsonfor exactly this. Agent Plugins output needs$schema, an explicittype, 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.mcpDialect; the engine renders through the module.claude${CLAUDE_PLUGIN_ROOT}/${CLAUDE_PLUGIN_DATA}streamable-http→httpcursor${CURSOR_PLUGIN_ROOT}/ none (build error)typedropped for stdio/HTTP (Cursor infers it)copilot${PLUGIN_ROOT}/ as authoredstreamable-http→httpverbatimagent-plugins${PLUGIN_ROOT}/${PLUGIN_DATA}+$schematype; spec §7.2 / §9 enforcedThe
agent-pluginsdialect turns anything a conforming client would silently skip into a build error: a shell string ascommand,${API_TOKEN}inenv(left unexpanded), plain http to a remote host, reserved env names, or acwdthat escapes the plugin. No target uses this dialect yet; the next PR switchescodexto it.Also adds
CONTEXT.md(glossary) anddocs/adr/0001(codex emits Agent Plugins packages by default, with no dual layout).Behavior change
${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../bin/servercommand becomes${<root variable>}/bin/server.Verification
npm run checkpasses (239 tests; 40 new intests/mcp.test.ts, plus one build-level wiring test).gleanwork/agent-pluginswith released 0.11.0 and with this branch (temp copies): all 191 output files are byte-identical, including the claude, cursor, and codex.mcp.jsonfiles.agent-pluginsdialect gives valid Agent Pluginsmcp.json. The current codex override is rejected because itscwd: "."isn't a valid Agent Plugins path.Next
codexformatoption (defaultagent-plugins), a standaloneagent-pluginstarget, and pinned 1.0.0 schemas. Release as 0.12.0.agent-plugins: delete the codex MCP override, convert the shared config, and regeneratecodex-plugins.