feat(config): add mcpServers canonical object format with headers support#1037
Conversation
esengine
left a comment
There was a problem hiding this comment.
Thanks @ADX15xs — the normalization layer and the call-site fan-out look right, and the 27-test matrix is exactly what I wanted on this surface. Headers plumb cleanly through both SSE and Streamable HTTP.
One thing I need fixed before merge: the three as unknown as McpServerSpec / as McpServerSpec casts —
src/cli/commands/mcp-inspect.ts:147src/cli/commands/mcp-runtime.ts:202src/mcp/reconnect.ts:531
CLAUDE.md bans as escape hatches without a biome-ignore + reason, and these aren't really needed — McpSpec is a discriminated union on transport, so switching on parsed.transport and building the overlaid spec per branch gives you a typed McpServerSpec without any cast.
Comment-style nits in src/config.ts and the test body I'll clean up in a follow-up — no need for you to spin on those. Just the casts and this is in.
… server declarations Introduces a robust configuration system for MCP servers that supports both legacy string-based specs and a new canonical `mcpServers` object format. This allows for advanced configurations including custom HTTP headers for SSE and Streamable HTTP transports. - Adds `mcpServers` to `ReasonixConfig` to support structured server definitions. - Implements `normalizeMcpConfig` to merge legacy `mcp` strings with the new object format, ensuring `mcpServers` takes precedence. - Enhances `buildTransportFromSpec` to support passing `headers` for non-stdio transports. - Updates CLI commands (`acp`, `mcp-inspect`, `mcp-runtime`, `run`) and internal resolution logic to use normalized configurations. - Adds `specToRaw` for serializing normalized specs back to legacy string formats. - Updates documentation to reflect the new configuration schema and examples. - Adds unit tests for configuration normalization logic.
Implements transport-specific property assignment when merging parsed MCP specifications with normalized configuration. This ensures that environment variables are only applied to `stdio` transports, while HTTP headers are correctly scoped to `sse` and `streamable-http` transports, preventing invalid configuration leakage between types. - Update `mcp-inspect` and `mcp-runtime` to use conditional spec building based on transport type. - Refactor `reconnectMcpServer` to decouple transport-specific properties from the base specification. - Improve type safety by explicitly typing the constructed `McpServerSpec`.
5a07a4f to
f64a477
Compare
Extracts the complex conditional logic for merging parsed MCP specifications with configuration into a dedicated utility function. This simplifies the command implementations in `mcp-inspect` and `mcp-runtime` and cleans up the reconnection logic. - Add `overlayMatchedSpec` to `src/mcp/spec.ts` to handle transport-specific property merging. - Replace inline switch statements in `mcp-inspect.ts` and `mcp-runtime.ts` with the new utility. - Simplify `reconnectMcpServer` in `src/mcp/reconnect.ts` by removing redundant spec reconstruction.
|
This is exactly the shape I wanted out of #1032 — single Round-tripping via Will pull locally, run |
…port (esengine#1037) * refactor(mcp): implement configuration normalization and object-based server declarations Introduces a robust configuration system for MCP servers that supports both legacy string-based specs and a new canonical `mcpServers` object format. This allows for advanced configurations including custom HTTP headers for SSE and Streamable HTTP transports. - Adds `mcpServers` to `ReasonixConfig` to support structured server definitions. - Implements `normalizeMcpConfig` to merge legacy `mcp` strings with the new object format, ensuring `mcpServers` takes precedence. - Enhances `buildTransportFromSpec` to support passing `headers` for non-stdio transports. - Updates CLI commands (`acp`, `mcp-inspect`, `mcp-runtime`, `run`) and internal resolution logic to use normalized configurations. - Adds `specToRaw` for serializing normalized specs back to legacy string formats. - Updates documentation to reflect the new configuration schema and examples. - Adds unit tests for configuration normalization logic. * feat(mcp): refine spec construction logic for different transport types Implements transport-specific property assignment when merging parsed MCP specifications with normalized configuration. This ensures that environment variables are only applied to `stdio` transports, while HTTP headers are correctly scoped to `sse` and `streamable-http` transports, preventing invalid configuration leakage between types. - Update `mcp-inspect` and `mcp-runtime` to use conditional spec building based on transport type. - Refactor `reconnectMcpServer` to decouple transport-specific properties from the base specification. - Improve type safety by explicitly typing the constructed `McpServerSpec`. * refactor(mcp): centralize spec overlay logic into `overlayMatchedSpec` Extracts the complex conditional logic for merging parsed MCP specifications with configuration into a dedicated utility function. This simplifies the command implementations in `mcp-inspect` and `mcp-runtime` and cleans up the reconnection logic. - Add `overlayMatchedSpec` to `src/mcp/spec.ts` to handle transport-specific property merging. - Replace inline switch statements in `mcp-inspect.ts` and `mcp-runtime.ts` with the new utility. - Simplify `reconnectMcpServer` in `src/mcp/reconnect.ts` by removing redundant spec reconstruction.
What
Introduces
mcpServers: Record<string, McpServerConfig>as the canonical way to declare MCP servers, alongside a singlenormalizeMcpConfig()normalization layer that merges the new object format with legacymcp[]/mcpEnv/mcpDisabledfields. Headers are plumbed throughbuildTransportFromSpecintoSseTransportandStreamableHttpTransport, enabling HTTP auth for SSE and Streamable HTTP transports.Why
The legacy
mcp: string[]format cannot express HTTP headers (e.g.Authorization,X-API-Key) needed for authenticated SSE / Streamable HTTP MCP servers. The newmcpServersobject format fills this gap while remaining fully backward-compatible.How to verify
npm run verify— lint, typecheck, and all 3125 tests pass (203 test files).tests/mcp-normalize-config.test.ts(27 tests) cover legacy-only, object-only, merge conflicts, disabled flags, env/headers, and transport round-trips.mcp-env-config,mcp-spec,mcp-integration,mcp-reconnect,acp-mcp,chat-mcp-startup-summary,resolve.Checklist
npm run verifypasses locally (lint + typecheck + tests + comment-policy gate)Co-Authored-By: Claudetrailer in commitsCHANGELOG.md— release notes are maintainer-written at release timeCloses #1032