Repository navigation
feat(server): send structuredContent as JSON text when a tool omits content - #3153
Conversation
🦋 Changeset detectedLatest commit: d8b4793 The changes in this PR will be included in the next version bump. This PR includes changesets to release 6 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
@modelcontextprotocol/client
@modelcontextprotocol/codemod
@modelcontextprotocol/core
@modelcontextprotocol/server
@modelcontextprotocol/server-legacy
@modelcontextprotocol/express
@modelcontextprotocol/fastify
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
There was a problem hiding this comment.
Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.
Beyond the inline findings, I also checked how the new withStructuredContentText step interacts with the existing SEP-2106 projection in projectCallToolResult.
- Array and primitive
structuredContentdoes not get a second text block:appendTextFallbackForNonObjectskips results that already carry atextblock, and the helper runs first. - On the 2025 era the mirrored text holds the unwrapped value while
structuredContentis wrapped as{ result: ... }for non-object-root schemas. That is the same shape the existing auto-append already produces, so I did not treat it as a regression.
Extended reasoning...
The change adds a small helper to the McpServer tools/call path in packages/server/src/server/mcp.ts and makes content optional on ToolResultWithStructuredContent, with docs, a changeset, conformance fixtures and an e2e requirement alongside. It touches no auth, crypto or permission code, but it changes wire output for every tool result that has structuredContent and no content. I did not approve because the inline findings include a behaviour change in how mixed-family results are rejected and a public typing gap on RegisteredTool.update, and every changed path is covered by the repo-wide CODEOWNERS entry.
820f72a to
04976f4
Compare
04976f4 to
1d33298
Compare
1d33298 to
b637489
Compare
b637489 to
d8b4793
Compare
…ontent
A McpServer tool result that carries structuredContent but no content
now gets a single text block holding the serialized JSON of
structuredContent, as the tools spec recommends ("a tool that returns
structured content SHOULD also return the serialized JSON in a
TextContent block"). Previously such a result went out with
content: []. A result that supplies content, even an empty array, is
handled as before, and a content-less result carrying another result
family's keys (task, inputRequests, requestState) is still rejected.
To match, successful results of a tool with an outputSchema may omit
content in TypeScript, in registerTool and in
RegisteredTool.update({ callback }).
Covered by an e2e requirement on every transport and both eras, and by
fixtures in the conformance everything-server for the planned
tools-call-structured-content scenario.
registerTool's output typing (#2449) made structuredContent a required key even when the schema's output type is unknown, such as an untyped fromJsonSchema(). The type check adds nothing there, and it rejected correct code: a proxy that mirrors an upstream tool returns a plain CallToolResult, with no structuredContent when the upstream tool has no outputSchema. ToolResultFor now resolves to CallToolResult when the schema output is unknown, as before #2449. Typed schemas are checked as before, and runtime validation is unchanged.
d8b4793 to
51d1781
Compare
There was a problem hiding this comment.
I reviewed the current head and found no bugs, and the points from my earlier inline comments are addressed in the code as it stands. A maintainer look is still worthwhile, because this changes what every McpServer tool result with structuredContent and no content puts on the wire and loosens the public registerTool types.
What was reviewed:
withStructuredContentTextinpackages/server/src/server/mcp.ts: it runs after output validation and the input-required return, skips results carryingtask,inputRequestsorrequestState(so they still fail with -32602), and array values do not get a second text block fromappendTextFallbackForNonObject.- The type changes:
ToolResultForfalls back toCallToolResultforunknownoutputs, andRegisteredTool.update({ callback })accepts the content-less typed result. - The changesets,
docs/servers/tools.md, both upgrade-skill references and the new e2e requirement were read against the helper and now describe the ungated fill and the typed-schema condition. - This was by reading only: I did not run the typecheck or the tests, so the
@ ts-expect-errorcases are not confirmed by a run.
Extended reasoning...
The change is 10 files (+213/-53) centred on packages/server/src/server/mcp.ts, adding a JSON text block to content-less tool results and changing the exported types ToolResultFor, ToolResultWithStructuredContent and the RegisteredTool.update callback. It touches no auth, crypto or permission code; the only guard-like surface is the foreign-result-family check, which the helper preserves and a unit test pins. Approval is not appropriate because every changed path falls under the repo-wide CODEOWNERS entry, the change alters default wire output and public typing (a design choice the maintainers should confirm, including that the fill is not gated on outputSchema or isError), and an earlier third-party review was dismissed with contents I cannot see. The latest push was a rebase plus a small wording fix that addressed the last open nit.
A
McpServertool result that hasstructuredContentbut nocontentnow gets one text block holding the serialized JSON ofstructuredContent. It used to go out withcontent: []. To match, successful results of a tool with a typedoutputSchemamay omitcontentin TypeScript, inregisterTooland inRegisteredTool.update({ callback }). This also fixes a compile regression from #2449 for tools with an untypedoutputSchema.Why the text block:
contentstill see the result.content: []gave them nothing.structuredContent(SEP-2106); object results were the gap.outputSchemaorisError: any tool result withstructuredContentand nocontentgets it.What stays the same:
content, even an empty array, is handled as before.task,inputRequests,requestState) is still rejected with-32602.The #2449 regression: it made
structuredContenta required key for every tool with anoutputSchema, including one whose output type isunknown, such as an untypedfromJsonSchema(...). That rejected correct code, with a cast as the only way out:Those tools take any
CallToolResultagain; typed schemas are checked as before. #2449 is not released, so its changeset is edited in place.Covered by a new e2e requirement on every transport and both eras, unit tests for the guard and
update(), and a compile test for the proxy case. The conformance everything-server gains fixtures for a plannedtools-call-structured-contentscenario; that scenario is not in a conformance release yet, so CI does not exercise them.