fix(mcp): circular-ref-safe schema deref, quiet child stderr, structuredContent fallback
Three independent robustness fixes to McpCommunicationProtocol, all battle-tested for several weeks as a patch-package shim over @utcp/mcp 1.1.1→1.1.3 in a code-mode deployment federating 15+ MCP servers / 400+ tools.
1. Circular-reference-safe schema dereferencing
$RefParser.dereference(schema) throws on recursive JSON Schemas (e.g. self-referencing SOQL/SOSL filter grammars returned by Salesforce MCP servers). Because the error propagates before the per-schema try/catch can help every time the same schema is re-encountered, the affected manual's tool discovery degrades. Passing { dereference: { circular: 'ignore' } } keeps the cycle as a live reference and discovery succeeds; acyclic schemas are byte-identical.
2. Child stderr: default 'ignore', opt-in 'inherit'
StdioClientTransport is constructed without a stderr option, so every stdio MCP child inherits the host's stderr and floods the terminal during discovery (banners, telemetry notices, auth chatter — multiplied by N servers).
- Default is now
'ignore'. UTCP_MCP_CHILD_STDERR=inheritrestores the old behavior for debugging.- Deliberately not
'pipe': with no reader attached the OS pipe buffer fills and a chatty child deadlocks.
3. structuredContent fallback in _processMcpToolResult
Some MCP servers return results with an empty content array and the payload only in structuredContent (an MCP spec field). Today that collapses to [] and the payload is silently lost. When content is empty and structuredContent != null, return structuredContent. Results that carry content are untouched, and the existing structured_output branch still wins.
Notes
- One file changed:
packages/mcp/src/mcp_communication_protocol.ts. - The esbuild JS bundle builds clean with these changes. The
tsupdts step currently fails on a clean checkout ofmaintoo (an@types/noderesolution issue under bun's node_modules layout) — pre-existing and unrelated. - Happy to split into three PRs if you prefer smaller reviews.
Summary by cubic
Improve MCP stability by handling circular JSON Schemas, quieting child stderr by default, and preserving results returned via structuredContent. Reduces discovery failures and terminal noise when federating many MCP servers.
- Bug Fixes
- Schema deref: use
$RefParser.dereference(..., { dereference: { circular: 'ignore' } })to safely handle recursive schemas without breaking discovery. - Child stderr: default to
'ignore'; setUTCP_MCP_CHILD_STDERR=inheritto debug. Not'pipe'to avoid deadlocks. - Tool results: when
contentis empty andstructuredContentexists, returnstructuredContentso payloads aren’t lost.
- Schema deref: use