mcp: circular-safe schema deref, quiet child stderr, prefer structuredContent
Merged
H3
2mo ago+158+158+012345678901234567890123456789-4-4-0123456789
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 atJSON.stringify; with'ignore'the refs on the cycle stay$refstrings and everything else is still inlined. - Stdio children's stderr defaults to
'ignore';UTCP_MCP_CHILD_STDERR=inheritrestores it for debugging. Not'pipe', which would deadlock a chatty child with no reader attached. structuredContentis no longer lost whencontentis empty.
Follow-ups in this PR
_processMcpToolResultprefersstructuredContentwhenever the server sent it, not only whencontentis 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 aresultkey among others passes through untouched.- Removed the
structured_outputbranch, 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
$defsintact; acyclic refs still inline). - README section on child process stderr.
Test plan
-
bun test packages/mcp: 40 pass (33 existing + 7 new) -
bun run buildin 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$refstrings instead of a live object cycle that breaksJSON.stringify. - Child stderr defaults to
'ignore'; setUTCP_MCP_CHILD_STDERR=inheritto see it while debugging. Deliberately not'pipe', which would deadlock a verbose child with no reader attached. - Tool results now prefer
structuredContentwhenever 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=inheritwhen 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.