Skip to content

fix pdf-server outputSchema draft-07 dialect rejection - #766

Open
bonallure wants to merge 1 commit into
modelcontextprotocol:mainfrom
bonallure:fix/output-schema-draft07-dialect
Open

fix pdf-server outputSchema draft-07 dialect rejection#766
bonallure wants to merge 1 commit into
modelcontextprotocol:mainfrom
bonallure:fix/output-schema-draft07-dialect

Conversation

@bonallure

Copy link
Copy Markdown

Fixes #765

Motivation

display_pdf and interact in examples/pdf-server fail client-side on any client with a strict JSON Schema 2020-12-only output-schema validator (Claude Desktop, Claude Code), before the tool call ever reaches the server:

Tool 'display_pdf' has an invalid outputSchema: JSON Schema declares an unsupported dialect
("$schema": "http://json-schema.org/draft-07/schema#"). The default validator supports
JSON Schema 2020-12 only, pass a pre-configured Ajv instance to AjvJs

Root cause is in the pinned @modelcontextprotocol/sdk (^1.29.0, still present in latest 1.30.0): the tools/list handler always emits "$schema": "http://json-schema.org/draft-07/schema#" on Zod-derived inputSchema/outputSchema, with no registerTool/registerAppTool option to configure it (zod-json-schema-compat.js's mapMiniTarget() falls back to 'draft-7' since mcp.js never passes a target). This is an already-filed, still-open upstream bug: modelcontextprotocol/typescript-sdk#2721 — there is no released SDK version that fixes it, so this can't be resolved by a version bump.

What changed

  • src/server/index.ts: new exported fixOutputSchemaDialect(server). Wraps the low-level Server.setRequestHandler to intercept the handler McpServer registers for ListToolsRequestSchema, rewriting "$schema": "http://json-schema.org/draft-07/schema#" to "https://json-schema.org/draft/2020-12/schema" on every tool's inputSchema/outputSchema before the response goes out. Must be called immediately after constructing McpServer, before any tool registration (documented in the JSDoc, with an @example).
  • src/server/index.examples.ts: companion fixOutputSchemaDialect_basicUsage region for the JSDoc example.
  • src/server/index.test.ts: unit tests covering the rewrite and the pass-through case for other request schemas.
  • examples/pdf-server/server.ts: calls fixOutputSchemaDialect(server) right after new McpServer(...), before list_pdfs registers.

How it was verified

  • npm test — 376 pass, 1 pre-existing skip, 0 fail.
  • npm run build — clean, no type errors.
  • End-to-end: built createServer() from examples/pdf-server, connected via InMemoryTransport + a real SDK Client, called listTools(). Confirmed display_pdf/read_pdf_bytes/save_pdf's outputSchema.$schema (and every tool's inputSchema.$schema) is now 2020-12, list_pdfs/interact unaffected, and a real tool call (list_pdfs) still round-trips correctly — the fix only touches tools/list schema metadata, not tool invocation.
  • Confirmed the ordering constraint is real: calling fixOutputSchemaDialect after the first tool registration (instead of before) leaves the dialect at draft-07, since McpServer only installs its real tools/list handler once, lazily, on first registration.

Scope note: other examples (budget-allocator-server, cohort-heatmap-server, system-monitor-server, etc.) declare outputSchema and hit the same bug but aren't touched here — kept this PR focused on the reported pdf-server failure; noted them as follow-up in #765.

"Allow edits by maintainers" is checked.

@modelcontextprotocol/sdk always reports "$schema": draft-07 on Zod-derived
tool schemas with no way to configure it, which strict 2020-12-only client
validators reject before a tool call ever reaches the server. Adds
fixOutputSchemaDialect() to rewrite the dialect and wires it into
pdf-server, whose display_pdf/read_pdf_bytes/save_pdf tools hit this.

Upstream bug: modelcontextprotocol/typescript-sdk#2721
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

pdf-server: display_pdf/interact rejected client-side by strict 2020-12 output-schema validators

1 participant