Skip to content

fix(server): leave tools with an untyped outputSchema unchecked - #3204

Closed
mattzcarey wants to merge 1 commit into
mainfrom
fix/tool-output-typing-untyped-schemas
Closed

mattzcarey wants to merge 1 commit into
mainfrom
fix/tool-output-typing-untyped-schemas

Conversation

@mattzcarey

Copy link
Copy Markdown
Member

registerTool no longer type-checks the callback result when the tool's outputSchema has an unknown output type, such as an untyped fromJsonSchema(...). Those tools take any CallToolResult again, as they did before #2449. Typed schemas are checked exactly as before.

#2449 made structuredContent a required key for every tool with an outputSchema. For an untyped schema that check adds nothing, and it rejects correct code:

// 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
);
  • TypeScript drops the undefined from an optional outputSchema when inferring, so the callback was checked as if a schema were always present.
  • The only way out was a cast on the callback.

#2449 is not released yet, so this edits its changeset in place. Runtime validation is unchanged. Tests ran, including a compile test for the proxy case that fails without the fix.

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

changeset-bot Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 2a62bf6

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

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

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@pkg-pr-new

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

Copy link
Copy Markdown

Open in StackBlitz

@modelcontextprotocol/client

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

@modelcontextprotocol/codemod

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

@modelcontextprotocol/core

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

@modelcontextprotocol/server

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

@modelcontextprotocol/server-legacy

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

@modelcontextprotocol/express

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

@modelcontextprotocol/fastify

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

@modelcontextprotocol/hono

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

@modelcontextprotocol/node

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

commit: 2a62bf6

@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
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 fix/tool-output-typing-untyped-schemas branch from f7a36af to 2a62bf6 Compare November 18, 2026 16:09

@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 updated push and found no bugs. Because it loosens a compile-time check on the exported ToolResultFor type, in code owned by the SDK team, a human look is still worthwhile.

What was reviewed:

  • ToolResultFor in packages/server/src/server/mcp.ts: the new unknown extends ToolStructuredContent<Output> branch fires for an untyped fromJsonSchema(...), z.unknown() and any-typed outputs, and not for typed schemas or raw shapes, whose content type is never unknown.
  • The proxy case: the optional outputSchema infers as StandardSchemaWithJSON<unknown, unknown>, falls through the raw-shape overload gate, and accepts a plain CallToolResult.
  • The changeset, docs/servers/tools.md, the upgrade skill reference and the JSDoc all describe the unknown-output exemption as the type now behaves; the latest push rewords the JSDoc and shortens the test comment I commented on earlier.
  • I did not run the typecheck. The tests in this file are type-level, so that run is what enforces them.
Extended reasoning...

The change is one conditional branch in the ToolResultFor type in packages/server/src/server/mcp.ts, plus matching JSDoc, an edited unreleased changeset, two doc files and the type-level test file. It touches no security-sensitive surface: runtime output validation is unchanged and only compile-time typing is relaxed for schemas with an unknown output type. Reading found the type behaviour, tests and documentation consistent, and the bug hunt reported nothing. I deferred rather than approved because .github/CODEOWNERS assigns every path to the SDK team and the change is a public-API typing decision that relaxes a check. The type-level tests were read, not run.

@mattzcarey mattzcarey closed this Nov 18, 2026
@claude claude Bot added the v2 Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes label Nov 19, 2026
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.

1 participant