Skip to content

feat(server): send structuredContent as JSON text when a tool omits content - #3153

Merged
mattzcarey merged 4 commits into
mainfrom
feat/tool-structured-content-text
Nov 18, 2026
Merged

mattzcarey merged 4 commits into
mainfrom
feat/tool-structured-content-text

Conversation

@mattzcarey

@mattzcarey mattzcarey commented Nov 5, 2026 •

Copy link
Copy Markdown
Member

A McpServer tool result that has structuredContent but no content now gets one text block holding the serialized JSON of structuredContent. It used to go out with content: []. To match, successful results of a tool with a typed outputSchema may omit content in TypeScript, in registerTool and in RegisteredTool.update({ callback }). This also fixes a compile regression from #2449 for tools with an untyped outputSchema.

server.registerTool('weather', { outputSchema: z.object({ temperature: z.number() }) }, async () => ({
    structuredContent: { temperature: 22.5 }
}));
// → { content: [{ type: 'text', text: '{"temperature":22.5}' }], structuredContent: { temperature: 22.5 } }

Why the text block:

  • The tools spec says "a tool that returns structured content SHOULD also return the serialized JSON in a TextContent block", so clients that only read content still see the result. content: [] gave them nothing.
  • The SDK already appended this block for array and primitive structuredContent (SEP-2106); object results were the gap.
  • The fill is not gated on outputSchema or isError: any tool result with structuredContent and no content gets it.

What stays the same:

  • A result that supplies content, even an empty array, is handled as before.
  • A content-less result that carries another result family's keys (task, inputRequests, requestState) is still rejected with -32602.

The #2449 regression: it made structuredContent a required key for every tool with an outputSchema, including one whose output type is unknown, such as an untyped fromJsonSchema(...). That rejected correct code, with a cast as the only way out:

// A proxy mirroring an upstream tool. Failed to compile after #2449.
server.registerTool(
    tool.name,
    { outputSchema: tool.outputSchema ? fromJsonSchema(tool.outputSchema) : undefined },
    async () => upstream.callTool(...) // CallToolResult; no structuredContent when the upstream tool has no outputSchema
);

Those tools take any CallToolResult again; 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 planned tools-call-structured-content scenario; that scenario is not in a conformance release yet, so CI does not exercise them.

@mattzcarey
mattzcarey requested a review from a team as a code owner November 5, 2026 15:01
@changeset-bot

changeset-bot Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: d8b4793

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages
Name Type
@modelcontextprotocol/server Minor
@modelcontextprotocol/client Minor
@modelcontextprotocol/codemod Minor
@modelcontextprotocol/core Minor
@modelcontextprotocol/server-legacy Minor
@modelcontextprotocol/core-internal Patch

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

@pkg-pr-new

pkg-pr-new Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@3153

@modelcontextprotocol/codemod

npm i https://pkg.pr.new/@modelcontextprotocol/codemod@3153

@modelcontextprotocol/core

npm i https://pkg.pr.new/@modelcontextprotocol/core@3153

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@3153

@modelcontextprotocol/server-legacy

npm i https://pkg.pr.new/@modelcontextprotocol/server-legacy@3153

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@3153

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@3153

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@3153

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@3153

commit: 51d1781

@mattzcarey
mattzcarey added this pull request to stack #3154 November 5, 2026 15:03

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 structuredContent does not get a second text block: appendTextFallbackForNonObject skips results that already carry a text block, and the helper runs first.
  • On the 2025 era the mirrored text holds the unwrapped value while structuredContent is 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.

Comment thread packages/server/src/server/mcp.ts Resolved
Comment thread packages/server/src/server/mcp.ts Resolved
@claude claude Bot added the v2 Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes label Nov 6, 2026
@mattzcarey
mattzcarey force-pushed the feat/tool-structured-content-text branch from 820f72a to 04976f4 Compare November 18, 2026 15:15

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code review found no issues

No high-confidence issues detected in this change.

Still open from earlier reviews (4):

  • Unresolved: 4 minor or pre-existing.

Base automatically changed from fix/sep-2106-output-schema-safety to main November 18, 2026 15:32
@KKonstantinov
KKonstantinov force-pushed the feat/tool-structured-content-text branch from 04976f4 to 1d33298 Compare November 18, 2026 15:32

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code review found no issues

No high-confidence issues detected in this change.

Still open from earlier reviews (4):

  • Unresolved: 4 minor or pre-existing.

KKonstantinov
KKonstantinov previously approved these changes Nov 18, 2026

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No new blocking issues. 1 optional suggestion (a nit or a note on pre-existing code) was found and not posted. Nothing in this review needs a push before merging.

@mattzcarey
mattzcarey force-pushed the feat/tool-structured-content-text branch from b637489 to d8b4793 Compare November 18, 2026 16:46

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

Comment thread packages/server/src/server/mcp.ts Resolved
…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.
@mattzcarey
mattzcarey force-pushed the feat/tool-structured-content-text branch from d8b4793 to 51d1781 Compare November 18, 2026 17:02

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  • withStructuredContentText in packages/server/src/server/mcp.ts: it runs after output validation and the input-required return, skips results carrying task, inputRequests or requestState (so they still fail with -32602), and array values do not get a second text block from appendTextFallbackForNonObject.
  • The type changes: ToolResultFor falls back to CallToolResult for unknown outputs, and RegisteredTool.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-error cases 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.

@mattzcarey
mattzcarey merged commit 5ee54ee into main Nov 18, 2026
20 checks passed
@mattzcarey
mattzcarey deleted the feat/tool-structured-content-text branch November 18, 2026 17:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

v2 Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants