mcp: circular-safe schema deref, quiet child stderr, prefer structuredContent

Merged
H3
2mo ago
+158-4

Summary

Lands #33 by @itsbrex (cherry-picked with authorship preserved) together with the review follow-ups, so it can ship in the next release alongside the matching python-utcp change.

From #33

  • Schema dereferencing passes { dereference: { circular: 'ignore' } }. With the default, a recursive schema becomes a live object cycle that blows up later at JSON.stringify; with 'ignore' the refs on the cycle stay $ref strings and everything else is still inlined.
  • Stdio children's stderr defaults to 'ignore'; UTCP_MCP_CHILD_STDERR=inherit restores it for debugging. Not 'pipe', which would deadlock a chatty child with no reader attached.
  • structuredContent is no longer lost when content is empty.

Follow-ups in this PR

  • _processMcpToolResult prefers structuredContent whenever the server sent it, not only when content is empty. Spec-compliant servers mirror it as a serialized text block for older clients, and re-parsing that text is lossy. This matches the Python SDK. A FastMCP-style single-key { result: value } wrapper is unwrapped; an object that merely has a result key among others passes through untouched.
  • Removed the structured_output branch, which is not an MCP field and never matched.
  • When a stdio server fails to connect while its stderr is suppressed, the error log points at UTCP_MCP_CHILD_STDERR=inherit.
  • Tests for result processing and for schema dereferencing (a circular schema stays JSON-serializable with its $defs intact; acyclic refs still inline).
  • README section on child process stderr.

Test plan

  • bun test packages/mcp: 40 pass (33 existing + 7 new)
  • bun run build in packages/mcp succeeds including DTS

Supersedes #33. Companion: universal-tool-calling-protocol/python-utcp#101.

🤖 Generated with Claude Code


Summary by cubic

Hardens @utcp/mcp so recursive schemas no longer crash tool discovery, chatty stdio children no longer inherit the host's stderr, and tool results keep their structured payload instead of re-parsing mirrored text.

  • Schema dereferencing now uses { dereference: { circular: 'ignore' } }, leaving cycle refs as $ref strings instead of a live object cycle that breaks JSON.stringify.
  • Child stderr defaults to 'ignore'; set UTCP_MCP_CHILD_STDERR=inherit to see it while debugging. Deliberately not 'pipe', which would deadlock a verbose child with no reader attached.
  • Tool results now prefer structuredContent whenever present, matching the Python SDK; a FastMCP-style { result: value } wrapper is unwrapped only when the inner value is not a plain object, so genuine single-key object returns keep their shape.
  • Failed stdio connections log a hint pointing at UTCP_MCP_CHILD_STDERR=inherit when stderr was suppressed, unless the failure raced with a shutdown.
  • Added tests for result processing and circular schema dereferencing, plus a README section on child stderr.