Conversation
…a instance In the stateless createMcpHandler(() => buildServer()) pattern the app builds a fresh McpServer per request and re-registers its tools, so the per-instance _toolInputSchemaJson memo never hit: every request re-converted every registered tool's schema (once eagerly in registerTool, again per tools/list). standardSchemaToJsonSchema now memoizes successful conversions process-wide in a WeakMap keyed by schema identity and io direction, so an app that hoists its schemas to module scope (the natural pattern in that model) converts each schema once per process instead of once per McpServer instance — 53 hoisted tools on a fresh server: ~14-19 ms -> ~1 ms. Conversion failures are not memoized, entries stay collectible with their schema, and repeat calls return the same (read-only) object. Fixes modelcontextprotocol#2838
🦋 Changeset detectedLatest commit: 0e68e73 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: |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #2838.
standardSchemaToJsonSchemanow memoizes successful Standard Schema → JSON Schema conversions process-wide, keyed by schema identity andiodirection, so the stateless per-request-server pattern stops re-converting every tool schema on every request.Motivation and Context
In the recommended stateless pattern
createMcpHandler(() => buildServer()), a freshMcpServeris built per request and the app re-registers its tools on it.registerToolconverts each zodinputSchemaeagerly and caches the result in_toolInputSchemaJsonon that instance;tools/listconverts again per call. Since the instance is new every request, the cache never hits — every request pays the full conversion for every tool, includinginitialize, which never reads a tool schema. The issue measured ~19 ms/request for 53 hoisted tools (30.8 msinitializevs 1.7 ms for a plain Express route on the same server). Hoisting the zod schemas doesn't help on its own because zod's~standard.jsonSchema.input()rebuilds from scratch on every call and the SDK called it per registration.Root cause: conversion results were memoized only per
McpServerinstance; nothing keyed the conversion to the schema itself.The fix:
standardSchemaToJsonSchema(packages/core-internal/src/util/standardSchema.ts) memoizes successful conversions in a module-levelWeakMap<schema, { input?, output? }>. Every conversion call site —registerTool's eager conversion, the lazytoolInputSchemaJson()path,tools/list(input and output),outputSchemahandling, prompt argument extraction, elicitation — already funnels through this one function, so a single insertion point covers them all.WeakMapkeys keep entries collectible with their schema, so apps that build fresh schemas per request (nothing to reuse) retain nothing new.x-mcp-headerscan, the elicitation wire-grammar walk, and the 2025 codec's legacyoutputSchemawrap each build new objects rather than mutating); the JSDoc now states the read-only contract explicitly.Effect on the issue's repro (53 hoisted tools × 25 fields, fresh
McpServerper build, measured against the built packages): 14–17.5 ms → 1.2–1.3 ms per registration pass, matching the ~0.8 ms the issue reports for explicit memoization.How Has This Been Tested?
New regression coverage:
packages/core-internal/test/util/standardSchema.test.ts— amemoizationblock: at most one conversion per schema instance periodirection (counting Standard Schema double); the memoized value is the post-type:'object'-stamping result; a real hoisted zod schema returns the identical object on repeat calls; conversion failures are not memoized. All four fail onmain, pass with the fix.packages/server/test/server/toolSchemaMemoization.test.ts— the issue scenario end to end: one hoisted schema registered on 25 freshMcpServerinstances, thentools/listagainst each; the converter runs exactly once. Fails onmain(25 conversions), passes with the fix (1).Suites:
core-internal: 1461 passed (69 files);server: 510 passed (46 files);typecheckandeslint+prettierclean for both packages;lint:allclean repo-wide.test:all: every package green except@modelcontextprotocol/test-e2e, which reports 2 unhandledREQUEST_TIMEOUTerrors inscenarios/protocol.test.ts— reproduced identically on unmodifiedmain(same 2641 passed / 147 expected fail / 2 errors), so pre-existing and unrelated to this change.Breaking Changes
None. No public API changes; conversion output is unchanged (the memo returns what the converter already produced). The only behavioral delta: repeat conversions of the same schema instance return the identical object instead of a fresh equal object.
Types of changes
Checklist
standardSchemaToJsonSchemaJSDoc documents the memoization and the read-only contract)Additional context
globalRegistry) is captured at first conversion. The per-instance cache already had this property within one server's lifetime; this extends it to process lifetime for hoisted schemas — exactly the "cost once per process" semantics the issue asks for.client+server(both inline core-internal;server-legacydoes not depend on it).