feat(client,server): bundle default validators, expose customisation via subpaths

[mattzcarey]

What this PR does

Makes the default JSON Schema validator a zero-install, zero-config experience that adapts to your runtime, and gives customisation users a single-import escape hatch with no package.json changes required.

Default usage — just import McpServer

import { McpServer } from '@modelcontextprotocol/server';

const server = new McpServer({ name: 'my-server', version: '1.0.0' }, { capabilities: { tools: {} } });

That's it. No installs, no config, no validator imports.

The package's _shims conditional export picks the right runtime shim for you, and the shim has the right validator backend bundled into it:

Runtime	Resolved shim	Bundled validator
Node (Express, Next.js server, plain node script.js, etc.)	dist/shimsNode.mjs	AJV + ajv-formats
Cloudflare Workers / wrangler dev	dist/shimsWorkerd.mjs	@cfworker/json-schema
Browser / Vite / esbuild --platform=browser	dist/shimsWorkerd.mjs	@cfworker/json-schema
Deno deploy (workerd condition)	dist/shimsWorkerd.mjs	@cfworker/json-schema

If you move the same code from Node to a Worker, the bundle just picks the right backend — your code doesn't change, your package.json doesn't change.

Customising the bundled validator

Want to add custom AJV formats, change the draft, pre-register schemas by $id? Import from the subpath. The subpath re-exports Ajv and addFormats from the SDK's vendored copy, so you don't need ajv or ajv-formats in your package.json:

import { Ajv, addFormats, AjvJsonSchemaValidator } from '@modelcontextprotocol/server/validators/ajv';

const ajv = new Ajv({ strict: true, allErrors: true });
addFormats(ajv);

new McpServer(info, {
    capabilities: { tools: {} },
    jsonSchemaValidator: new AjvJsonSchemaValidator(ajv),
});

Same idea for the workerd validator (its customisation surface is a plain options object — no third-party constructor to expose):

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

new McpServer(info, {
    capabilities: { tools: {} },
    jsonSchemaValidator: new CfWorkerJsonSchemaValidator({ draft: '2020-12', shortcircuit: false }),
});

The same paths exist on @modelcontextprotocol/client/validators/{ajv,cf-worker}.

Important: importing from one of these subpaths pins your code to that backend. The default McpServer import would have picked the validator per runtime; the subpath explicitly chooses AJV (or cfworker) regardless of where you deploy. Use the subpath when you actually want that, not as a habit.

Replacing validation wholesale

Bring your own object implementing the jsonSchemaValidator interface:

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

Why the named classes are subpath-only, not on the root barrel

Re-exporting AjvJsonSchemaValidator or CfWorkerJsonSchemaValidator from @modelcontextprotocol/server (root) would pull the corresponding backend's code into every consumer's root index chunk, including the 95% of users who never customise. Subpaths keep the default code path validator-overhead-free and let bundlers tree-shake cleanly. The structural type used for the AJV constructor parameter (AjvLike declared inside ajvProvider.ts) similarly removes the bare import { Ajv } from "ajv" from the chunk transitively reached by the root entry, so TS consumers don't hit TS2307 either.

Codemod (v1 → v2)

The v1-to-v2 codemod (@modelcontextprotocol/codemod) rewrites v1 validator imports to the new v2 subpaths automatically, picking client vs server per file based on sibling imports + the consumer's package.json:

v1	v2
@modelcontextprotocol/sdk/validation/{ajv,ajv-provider}[.js]	@modelcontextprotocol/{client,server}/validators/ajv
@modelcontextprotocol/sdk/validation/{cfworker,cfworker-provider}[.js]	@modelcontextprotocol/{client,server}/validators/cf-worker
@modelcontextprotocol/sdk/validation/{index,types}.js	@modelcontextprotocol/{client,server} (type-only barrel)

Verified end-to-end against a real-world v1 caller this PR is unblocking.

Known limitations

The SDK's bundled AJV does not tree-shake away if the user passes their own. Server's constructor falls back to new DefaultJsonSchemaValidator() via a static ?? expression, so the bundler keeps the default validator's chunk reachable even when every call site at runtime supplies a custom jsonSchemaValidator. A user who imports Ajv directly from 'ajv' (instead of from our subpath) and passes their own instance ends up with two copies of AJV in their bundle — ours (vendored into the shim) + theirs (from their node_modules). ~30 KB gzipped overhead.

Workarounds for that user:

• Import Ajv from our subpath (import { Ajv } from '@modelcontextprotocol/server/validators/ajv') so both the validator class and the AJV constructor come from the SDK's single vendored copy.
• Use a bundler dedup pass (esbuild's dedupe, pnpm's dedupe, Webpack resolve.alias) if their AJV version matches the SDK's pin.

The default case — just McpServer with no custom validator — is unaffected: one copy of AJV (or @cfworker/json-schema), exactly the one the runtime needs. The duplication only shows up for the customisation path with a third-party AJV install.

Properly fixing the tree-shake would require an API change (e.g. dynamic import() of the default, which propagates async into validation; or making the default opt-in, which removes the zero-config story). Left as a future follow-up if real complaints come in.

Migration

For users who never customised the validator: nothing to do.

For users who customised it manually:

- import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/cfworker-provider.js';
+ import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/server/validators/cf-worker';

For AJV specifically, the new subpath now serves Ajv and addFormats too, so you can drop ajv / ajv-formats from package.json:

- import { Ajv } from 'ajv';
- import addFormats from 'ajv-formats';
- import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv-provider.js';
+ import { Ajv, addFormats, AjvJsonSchemaValidator } from '@modelcontextprotocol/server/validators/ajv';

The codemod handles the path rewrite. Folding the ajv / ajv-formats imports into the new subpath, and removing them from package.json, is a follow-up.

[changeset-bot]

🦋 Changeset detected

Latest commit: 99cf12f

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

This PR includes changesets to release 3 packages

Name	Type
@modelcontextprotocol/server	Patch
@modelcontextprotocol/client	Patch
@modelcontextprotocol/core	Minor

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/typescript-sdk/@modelcontextprotocol/client@2088

@modelcontextprotocol/codemod

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/codemod@2088

@modelcontextprotocol/server

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

@modelcontextprotocol/express

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

@modelcontextprotocol/fastify

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

@modelcontextprotocol/hono

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

@modelcontextprotocol/node

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

commit: 99cf12f

[mattzcarey]

@claude review pls

[claude]

Thanks for the follow-up commits — the mockPaths transform now appends subpathSuffix (with test coverage), the validator subpaths are re-exposed on client/server, and the CF Workers integration test no longer pre-installs @cfworker/json-schema, which together address my earlier findings, and I found no new issues in this revision. That said, this PR reshapes the public validator API surface (new subpath exports, bundling/dts config, codemod mappings, migration docs), so it still warrants a maintainer's design-level sign-off rather than auto-approval.

Extended reasoning...

Overview

This revision (head 99cf12f) of PR #2088 spans 46 files: it bundles the default JSON Schema validator backends (AJV for Node, @cfworker/json-schema for workerd/browser) into the client/server runtime shims via noExternal, exposes customisation through new ./validators/{ajv,cf-worker} subpath exports that re-export the vendored Ajv/addFormats, demotes the validator classes to type-only on the core barrels, adds codemod mappings (subpathSuffix) for the v1 validation/* paths, and rewrites the migration docs, changesets, tests, and tsconfig path maps accordingly.

Changes since my last review

The latest commits respond directly to prior review threads: mockPaths.ts now appends mapping.subpathSuffix in its RESOLVE_BY_CONTEXT branch (mirroring importPaths.ts) and mockPaths.test.ts adds vi.mock / vi.doMock / jest.mock / dynamic-import coverage for the validator specifiers; the ./validators/ajv and ./validators/cf-worker subpaths exist on both published packages with matching exports/typesVersions/tsdown entries; and cloudflareWorkers.test.ts no longer pre-installs @cfworker/json-schema, so it now genuinely guards the bundling invariant. The bug-hunting pass on this revision surfaced no new findings.

Security risks

No security-sensitive surface is touched — no auth, crypto, or transport-session logic changes. The main risks are supply-chain/bundling-shaped (vendoring ajv/ajv-formats/@cfworker/json-schema into published dist chunks) and API-compatibility-shaped (root barrels now export the validator classes type-only), neither of which is a vulnerability per se.

Level of scrutiny

This is exactly the kind of PR the repo's review conventions reserve for human judgment: it adds new public subpath exports, changes what the root barrels export, alters the published bundle contents, and ships a migration story (docs + codemod) whose prose has already gone through several correction rounds (one previously-flagged docs/changeset thread about the peer-dep wording was resolved by a maintainer and I have not re-raised it). Minimalism and API-surface trade-offs here are maintainer calls, not something to shadow-approve.

Other factors

Test coverage for the new behavior is reasonable: barrel-cleanliness regression tests for the shims, validator-override tests on client and server, codemod transform tests for both import and mock paths, and the workerd end-to-end test. The maintainer is actively engaged on the PR, so this defer is primarily a confirmation that the latest round of fixes checks out from my side.