fix(mcp): circular-ref-safe schema deref, quiet child stderr, structuredContent fallback

Closed
IT
2mo ago
+20-2

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=inherit restores 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 tsup dts step currently fails on a clean checkout of main too (an @types/node resolution 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'; set UTCP_MCP_CHILD_STDERR=inherit to debug. Not 'pipe' to avoid deadlocks.
    • Tool results: when content is empty and structuredContent exists, return structuredContent so payloads aren’t lost.