Bundle automatic validator defaults in client/server shims

[mattzcarey]

Summary

• Bundle both validator backends selected by client/server runtime shims: AJV for Node defaults, @cfworker/json-schema for browser/workerd defaults.
• Remove explicit client/server validators/cf-worker subpath exports. Validator selection is automatic for normal users; advanced users can provide their own jsonSchemaValidator implementation.
• Mark AjvJsonSchemaValidator and CfWorkerJsonSchemaValidator @internal; drop their type-only re-exports from core/public so the runtime classes and their TypeScript type handles are both unreachable from @modelcontextprotocol/client / @modelcontextprotocol/server.
• Rewrite .examples.ts files and JSDoc snippets in packages/core/ so they no longer demonstrate end-user code (new AjvJsonSchemaValidator(), new CfWorkerJsonSchemaValidator()) that the new surface makes impossible. fromJsonSchema's example now uses a declared jsonSchemaValidator and notes that consumers importing from server/client omit the second arg.
• Add regression tests that built client/server shims do not leave bare imports for ajv, ajv-formats, or @cfworker/json-schema for consumers to resolve.
• Update migration docs to say users do not need to install or import validator packages; describe runtime selection by backend name (AJV / @cfworker/json-schema) rather than the now-internal class names.

Why

Client and server choose runtime defaults via conditional _shims:

• Node shim: AJV-backed validator
• Browser/workerd shim: @cfworker/json-schema-backed validator

Because client/server make those default choices, consumers should not need to know about or install validator implementation dependencies. Those backends are now bundled into the shim chunks that select them. The implementation classes are also no longer part of the public surface — neither as runtime constructors nor as TypeScript types — because exposing a handle to a constructor consumers can't reach is purely confusing.

Impact

• Client/server users: no extra validator install or validator import is needed. Node gets the bundled AJV default through the Node shim; browser/workerd gets the bundled cfworker validator through the browser/workerd shim.
• Advanced users: custom validation is still possible by passing jsonSchemaValidator: myCustomValidator with their own implementation of the jsonSchemaValidator interface.
• Published packages: packed client/server tarballs do not depend on @modelcontextprotocol/core, ajv, ajv-formats, or @cfworker/json-schema; those implementations are bundled where client/server need them.
• Public surface: explicit concrete validator subpaths are removed from client/server, the runtime classes are @internal, and core/public no longer re-exports them as types. The supported customisation path is the jsonSchemaValidator interface (still exported from core/public and re-exported by client/server).

Follow-up for codemod reviewers

If this validator packaging change ships, the v1-to-v2 codemod should remove redundant manual SDK validator imports/configuration for the built-in AJV and Cloudflare Workers validators. Those validators are no longer exported from client/server (not even as types), and normal migrations should rely on automatic runtime defaults instead.

Examples the codemod should simplify/remove when they refer to the SDK built-ins:

import { AjvJsonSchemaValidator } from '@modelcontextprotocol/server';
import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/server/validators/cf-worker';

new McpServer(info, {
  jsonSchemaValidator: new CfWorkerJsonSchemaValidator()
});

For custom user validators, the codemod should preserve the override:

new McpServer(info, { jsonSchemaValidator: myCustomValidator });

Reviewer note: this PR intentionally makes built-in validator selection automatic for client/server users; codemod output should not teach users to import SDK concrete validators for the default case.

[changeset-bot]

🦋 Changeset detected

Latest commit: 9739e09

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

This PR includes changesets to release 7 packages

Name	Type
@modelcontextprotocol/server	Patch
@modelcontextprotocol/client	Patch
@modelcontextprotocol/core	Minor
@modelcontextprotocol/express	Patch
@modelcontextprotocol/fastify	Patch
@modelcontextprotocol/hono	Patch
@modelcontextprotocol/node	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]

Open in StackBlitz

@modelcontextprotocol/client

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

@modelcontextprotocol/server

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

@modelcontextprotocol/express

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

@modelcontextprotocol/fastify

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

@modelcontextprotocol/hono

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

@modelcontextprotocol/node

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

commit: 9739e09

[claude]

🟡 The migration docs added here say consumers should not install @cfworker/json-schema, but test/integration/test/server/cloudflareWorkers.test.ts:46 — the only end-to-end test that runs the packed server tarball under real workerd — still pre-installs '@cfworker/json-schema': '^4.1.1' in the generated consumer package.json. That dep is now dead weight after this PR adds @cfworker/json-schema to noExternal, and it masks a future re-externalization regression because wrangler would resolve the bare import from the test's pre-installed copy instead of failing. Removing line 46 turns the test into a true regression guard and aligns it with the docs this PR adds.

Extended reasoning...

What the issue is

docs/migration-SKILL.md:524 (and the matching paragraph in docs/migration.md and .changeset/workerd-shim-vendors-cfworker.md) now instructs consumers: "Do not install ajv, ajv-formats, or @cfworker/json-schema; client/server bundle the runtime-selected defaults." But the SDK's own consumer simulation in test/integration/test/server/cloudflareWorkers.test.ts:44-47 still does exactly the thing the docs say not to do — it writes a generated package.json with an explicit dependency:

dependencies: {
    '@modelcontextprotocol/server': `file:./${tarballName}`,
    '@cfworker/json-schema': '^4.1.1'        // <-- now contradicts the docs
},

That file is not in this PR's diff (last touched in #1652), so this is a surviving instance of the pattern the PR replaces.

Why the explicit install used to be needed, and isn't anymore

At the PR base commit, packages/server/tsdown.config.ts had noExternal: ['@modelcontextprotocol/core'] only. The built dist/shimsWorkerd.mjs (and its chunks) therefore left a bare import { Validator } from '@cfworker/json-schema' for the consumer's bundler to resolve. wrangler's esbuild step would fail without it, so the test pre-installed the package.

This PR adds 'ajv', 'ajv-formats', '@cfworker/json-schema' to noExternal in both packages/server/tsdown.config.ts and packages/client/tsdown.config.ts, inlining the cfworker code into the workerd shim chunk. The explicit dep in the test consumer's package.json is now redundant.

Why it matters: the dead dep masks a regression

cloudflareWorkers.test.ts is the only test that exercises the packed tarball under a real workerd runtime via wrangler dev. The new barrelClean.test.ts tests added in this PR only string-match the dist/*.mjs output for bare from 'ajv'|'ajv-formats'|'@cfworker/json-schema' imports — useful but static. If a future tsdown/config change re-externalizes @cfworker/json-schema (e.g. someone removes it from noExternal while refactoring), the static test would catch it — but if that test is also touched, the workerd test should be the safety net. Today it isn't, because the consumer ships its own copy of @cfworker/json-schema, so wrangler's bundler would resolve the bare import from node_modules and the test would keep passing.

Step-by-step proof

1. Test packs @modelcontextprotocol/server to a tarball and writes a consumer package.json listing both file:./<tarball> and '@cfworker/json-schema': '^4.1.1'.
2. npm install puts both in the consumer's node_modules.
3. The test's server.ts constructs new McpServer(...) — the Server constructor eagerly does this._jsonSchemaValidator = options?.jsonSchemaValidator ?? new DefaultJsonSchemaValidator(), so the workerd shim's static @cfworker/json-schema import path is exercised.
4. wrangler dev runs esbuild over server.ts. After this PR, the import resolves to the bundled copy inside dist/shimsWorkerd.mjs — no bare import to satisfy.
5. Hypothetical regression: @cfworker/json-schema is dropped from noExternal. dist/shimsWorkerd.mjs now has from '@cfworker/json-schema'. Without line 46, esbuild fails ("Could not resolve") and the test catches it. With line 46, esbuild resolves it from the test's pre-installed copy, the test passes, and the regression ships.

How to fix

Delete the '@cfworker/json-schema': '^4.1.1' line from the generated consumer package.json at test/integration/test/server/cloudflareWorkers.test.ts:46. This is a one-line change that turns the test into a genuine end-to-end regression guard for the bundling invariant and brings it into agreement with the docs this PR adds.

Filed as a nit: the test isn't directly modified by the PR, the static barrelClean.test.ts already guards the structural invariant, and removing the line is a hygiene improvement rather than a fix for broken behavior.