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

[itsbrex]

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.

^{Written for commit 7df273b. Summary will update on new commits.}

[Copilot]

Pull request overview

This PR improves the robustness of the MCP integration by making schema dereferencing resilient to recursive JSON Schemas, reducing terminal noise from stdio MCP child processes, and preserving tool-call payloads that are returned via MCP’s structuredContent field.

Changes:

• Make JSON Schema dereferencing tolerant of circular $ref graphs by setting $RefParser.dereference(..., { dereference: { circular: 'ignore' } }).
• Default stdio MCP child stderr to 'ignore', with UTCP_MCP_CHILD_STDERR=inherit to opt back into inherited stderr for debugging.
• Add a fallback in _processMcpToolResult to return structuredContent when content is empty.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cubic-dev-ai]

No issues found across 1 file

_{Re-trigger cubic}