feat(client,server): re-expose validator classes via explicit subpaths

Restore the public entry points for the built-in JSON Schema validator
classes via symmetric subpaths so consumers can customize the bundled
backends without having to reimplement the entire 'jsonSchemaValidator'
interface:

- @modelcontextprotocol/{client,server}/validators/ajv
    exports AjvJsonSchemaValidator (was unreachable since #2088)
- @modelcontextprotocol/{client,server}/validators/cf-worker
    exports CfWorkerJsonSchemaValidator (was reachable on main, removed
    by #2088; restored here)

The named classes are intentionally NOT re-exported from the root barrel
(@modelcontextprotocol/server / @modelcontextprotocol/client). Re-exporting
either as a runtime value would pull the corresponding peer dep ('ajv'
or '@cfworker/json-schema') into every consumer's root index chunk,
defeating the purpose of the runtime shim's pay-only-for-what-you-use
default. Consumers who never customize get the validator transparently
via the shim; consumers who customize import from the subpath and
install the peer dep themselves.

The shim continues to bundle 'ajv' + 'ajv-formats' (Node) and
'@cfworker/json-schema' (workerd/browser) via tsdown noExternal so the
default code path remains zero-install. The barrel-clean regression
tests are tightened to match top-of-line bare imports only, so JSDoc
examples that reference 'from "ajv"' inside vendored chunks do not
trigger false positives.

The migration docs and changesets are rewritten to document the new
customization path.

Author: mattzcarey

.changeset/cfworker-out-of-barrel.md

@@ -3,4 +3,4 @@
 '@modelcontextprotocol/client': patch
 ---
 
-Stop bundling `@cfworker/json-schema` into the main package barrel. Previously `CfWorkerJsonSchemaValidator` was re-exported from the core internal barrel, so tsdown inlined the `@cfworker/json-schema` dev dependency into every consumer's bundle even when it was never used. The validator is now reachable only via the `_shims` conditional (workerd/browser), so consumers that don't opt into it no longer ship that code. The interim `@modelcontextprotocol/{server,client}/validators/cf-worker` subpath this introduced has been removed in a follow-up — the runtime shim is now the only entry point.
+Stop bundling `@cfworker/json-schema` into the main package barrel. Previously `CfWorkerJsonSchemaValidator` was re-exported from the core internal barrel, so tsdown inlined the `@cfworker/json-schema` dependency into every consumer's bundle even when it was never used. The named validator classes are now reachable only via the explicit `@modelcontextprotocol/{client,server}/validators/{ajv,cf-worker}` subpaths and the runtime `_shims` conditional, so consumers that import only from the root entry point no longer ship the validator dep.

.changeset/workerd-shim-vendors-cfworker.md

@@ -6,6 +6,13 @@
 
 Bundle automatic JSON Schema validator defaults in `@modelcontextprotocol/client` and `@modelcontextprotocol/server` runtime shims.
 
-Client/server select defaults automatically based on the runtime: Node shims use AJV, while browser/workerd shims use `@cfworker/json-schema`. Those backends are bundled into the shim chunks that select them, so consumers do not need to install validator packages or import explicit validators for default behavior. Advanced users can still pass their own `jsonSchemaValidator` interface implementation.
+Client and server pick the right validator automatically based on the runtime: the Node shim uses AJV, the browser/workerd shim uses `@cfworker/json-schema`. Both backends are bundled into the shim chunks that select them, so the default code path needs no extra installs — `import { McpServer } from '@modelcontextprotocol/server'` does not pull `ajv` or `@cfworker/json-schema` into the root entry chunk.
 
-The `@modelcontextprotocol/{client,server}/validators/cf-worker` subpath export has been removed — there is no longer any public entry point for the SDK's built-in validator classes. `AjvJsonSchemaValidator` and `CfWorkerJsonSchemaValidator` are now `@internal` and no longer exported from `@modelcontextprotocol/client` or `@modelcontextprotocol/server` (not even as types). The `jsonSchemaValidator` interface remains the public extension point for custom validators, and example JSDoc snippets no longer demonstrate direct validator instantiation.
+The named validator classes remain part of the public surface for consumers who want to customize the built-in backend (pre-register schemas by `$id`, register custom AJV formats, switch dialects, change `@cfworker/json-schema` draft). They are exposed through explicit subpaths so they do not bloat the root index chunk:
+
+- `import { AjvJsonSchemaValidator } from '@modelcontextprotocol/{client,server}/validators/ajv'`
+- `import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/{client,server}/validators/cf-worker'`
+
+Importing from one of these subpaths means the corresponding peer dep (`ajv` + `ajv-formats`, or `@cfworker/json-schema`) must be in your `package.json`. The shim keeps its own vendored copy for the default path, so a project can use the subpath in some files and rely on the default in others.
+
+The `jsonSchemaValidator` interface remains the public extension point for replacing validation entirely with a custom implementation.

docs/migration-SKILL.md

@@ -530,9 +530,9 @@ new McpServer({ name: 'server', version: '1.0.0' }, {});
 Validator behavior:
 
 - Do not add validator imports for normal migrations.
-- Do not install `ajv`, `ajv-formats`, or `@cfworker/json-schema`; client/server bundle the runtime-selected defaults.
-- The SDK's built-in validator classes (`AjvJsonSchemaValidator`, `CfWorkerJsonSchemaValidator`) are not exported from `@modelcontextprotocol/{client,server}` (not even as types). The `@modelcontextprotocol/{client,server}/validators/cf-worker` subpath that existed in v2 pre-releases has been removed.
-- Advanced users may pass `jsonSchemaValidator: myCustomValidator` with their own implementation of the `jsonSchemaValidator` interface.
+- Do not install `ajv`, `ajv-formats`, or `@cfworker/json-schema` for the default path; client/server bundle the runtime-selected defaults and the root entry point does not pull either dep in.
+- To customize the built-in backend (e.g. register custom AJV formats, change `@cfworker/json-schema` draft), import the named class from the package subpath: `@modelcontextprotocol/{client,server}/validators/ajv` for `AjvJsonSchemaValidator`, `@modelcontextprotocol/{client,server}/validators/cf-worker` for `CfWorkerJsonSchemaValidator`. Importing from a subpath means the corresponding peer dep must be in your `package.json`.
+- To replace validation entirely, pass `jsonSchemaValidator: myCustomValidator` with your own implementation of the `jsonSchemaValidator` interface.
 
 ## 15. Migration Steps (apply in this order)
 

docs/migration.md

@@ -933,21 +933,44 @@ const server = new McpServer(
 );
 ```
 
-You do not need to install or import validator packages for the default behavior. The client and server packages bundle the validator backend selected by the runtime shim.
+You do not need to install or import validator packages for the default behavior. The client and server packages bundle the validator backend selected by the runtime shim, so a normal `import { McpServer } from '@modelcontextprotocol/server'` does not pull `ajv` or `@cfworker/json-schema` into your bundle until you choose to customize.
 
-Advanced users can still override validation by passing an object that implements the SDK's JSON Schema validator interface:
+If you want to customize the **built-in** backend (for example, pre-register schemas by `$id`, register custom AJV formats, or change the `@cfworker/json-schema` draft), import the named class from the explicit subpath and pass an instance through `jsonSchemaValidator`:
 
 ```typescript
+import { Ajv } from 'ajv';
+import addFormats from 'ajv-formats';
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/server/validators/ajv';
+
+const ajv = new Ajv({ strict: true, allErrors: true });
+addFormats(ajv);
+
+const server = new McpServer(
+    { name: 'my-server', version: '1.0.0' },
+    {
+        capabilities: { tools: {} },
+        jsonSchemaValidator: new AjvJsonSchemaValidator(ajv)
+    }
+);
+```
+
+```typescript
+import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/server/validators/cf-worker';
+
 const server = new McpServer(
     { name: 'my-server', version: '1.0.0' },
     {
         capabilities: { tools: {} },
-        jsonSchemaValidator: myCustomValidator
+        jsonSchemaValidator: new CfWorkerJsonSchemaValidator({ draft: '2020-12', shortcircuit: false })
     }
 );
 ```
 
-The SDK's built-in validator classes (`AjvJsonSchemaValidator`, `CfWorkerJsonSchemaValidator`) are not part of the public surface — `@modelcontextprotocol/{client,server}` no longer export them as runtime values or types, and the `@modelcontextprotocol/{client,server}/validators/cf-worker` subpath that briefly existed in v2 pre-releases has been removed. To customise validation, implement the `jsonSchemaValidator` interface yourself and pass your implementation through the option above.
+(both subpaths are also available on `@modelcontextprotocol/client/validators/...`)
+
+If you import from one of these subpaths in your own code, the corresponding peer dep (`ajv` + `ajv-formats`, or `@cfworker/json-schema`) needs to be installed in your `package.json`. The runtime shim continues to vendor a copy for the default code path, so you can use the subpath in some files and rely on the default in others.
+
+To replace validation wholesale rather than customizing the built-in classes, implement the `jsonSchemaValidator` interface and pass your own implementation through the option above.
 
 ## Unchanged APIs
 

packages/client/package.json

@@ -28,6 +28,14 @@
             "types": "./dist/stdio.d.mts",
             "import": "./dist/stdio.mjs"
         },
+        "./validators/ajv": {
+            "types": "./dist/validators/ajv.d.mts",
+            "import": "./dist/validators/ajv.mjs"
+        },
+        "./validators/cf-worker": {
+            "types": "./dist/validators/cfWorker.d.mts",
+            "import": "./dist/validators/cfWorker.mjs"
+        },
         "./_shims": {
             "workerd": {
                 "types": "./dist/shimsWorkerd.d.mts",
@@ -50,6 +58,12 @@
     "types": "./dist/index.d.mts",
     "typesVersions": {
         "*": {
+            "validators/ajv": [
+                "dist/validators/ajv.d.mts"
+            ],
+            "validators/cf-worker": [
+                "dist/validators/cfWorker.d.mts"
+            ],
             "stdio": [
                 "dist/stdio.d.mts"
             ]

packages/client/src/validators/ajv.ts

@@ -0,0 +1,14 @@
+/**
+ * Customisation entry point for the AJV validator. Re-exports `Ajv` + `addFormats` from the
+ * SDK's bundled copy, so customising the validator needs no extra installs.
+ *
+ * @example
+ * ```ts
+ * import { Ajv, addFormats, AjvJsonSchemaValidator } from '@modelcontextprotocol/client/validators/ajv';
+ *
+ * const ajv = new Ajv({ strict: true, allErrors: true });
+ * addFormats(ajv);
+ * const validator = new AjvJsonSchemaValidator(ajv);
+ * ```
+ */
+export { addFormats, Ajv, AjvJsonSchemaValidator } from '@modelcontextprotocol/core/validators/ajv';

packages/client/src/validators/cfWorker.ts

@@ -0,0 +1,3 @@
+/** Customisation entry point for the `@cfworker/json-schema` validator. */
+export type { CfWorkerSchemaDraft } from '@modelcontextprotocol/core/validators/cfWorker';
+export { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/core/validators/cfWorker';

packages/client/test/client/barrelClean.test.ts

@@ -8,7 +8,8 @@ import { beforeAll, describe, expect, test } from 'vitest';
 const pkgDir = join(dirname(fileURLToPath(import.meta.url)), '../..');
 const distDir = join(pkgDir, 'dist');
 const NODE_ONLY = /\b(child_process|cross-spawn|node:stream|node:child_process)\b/;
-const VALIDATOR_BACKEND_IMPORT = /from\s+["'](?:ajv|ajv-formats|@cfworker\/json-schema)["']/;
+// Anchored at start-of-line so JSDoc-example `from 'ajv'` strings in vendored chunks don't match.
+const VALIDATOR_BACKEND_IMPORT = /^import[^\n]*?from\s+["'](?:ajv|ajv-formats|@cfworker\/json-schema)["']/m;
 
 function chunkImportsOf(entryPath: string): string[] {
     const visited = new Set<string>();

packages/client/tsdown.config.ts

@@ -2,26 +2,25 @@ import { defineConfig } from 'tsdown';
 
 export default defineConfig({
     failOnWarn: 'ci-only',
-    // 1. Entry Points
-    //    Directly matches package.json include/exclude globs
-    entry: ['src/index.ts', 'src/stdio.ts', 'src/shimsNode.ts', 'src/shimsWorkerd.ts', 'src/shimsBrowser.ts'],
-
-    // 2. Output Configuration
+    entry: [
+        'src/index.ts',
+        'src/stdio.ts',
+        'src/shimsNode.ts',
+        'src/shimsWorkerd.ts',
+        'src/shimsBrowser.ts',
+        'src/validators/ajv.ts',
+        'src/validators/cfWorker.ts'
+    ],
     format: ['esm'],
     outDir: 'dist',
-    clean: true, // Recommended: Cleans 'dist' before building
+    clean: true,
     sourcemap: true,
-
-    // 3. Platform & Target
     target: 'esnext',
     platform: 'node',
-    shims: true, // Polyfills common Node.js shims (__dirname, etc.)
-
-    // 4. Type Definitions
-    //    Bundles d.ts files into a single output
+    shims: true,
     dts: {
         resolver: 'tsc',
-        // override just for DTS generation:
+        resolve: ['ajv', 'ajv-formats'],
         compilerOptions: {
             baseUrl: '.',
             paths: {
@@ -32,15 +31,6 @@ export default defineConfig({
             }
         }
     },
-    // 5. Vendoring Strategy - Bundle this package's core implementation into the output,
-    //    but treat most dependencies as external (require/import).
-    //
-    //    The runtime `_shims` entries choose default JSON Schema validators: AJV on Node and
-    //    @cfworker/json-schema on workerd/browser. Client users should not have to install a
-    //    validator backend just to use the runtime default, so bundle the default backends into
-    //    the shim chunks that select them.
     noExternal: ['@modelcontextprotocol/core', 'ajv', 'ajv-formats', '@cfworker/json-schema'],
-
-    // 6. External packages - keep self-reference imports external for runtime resolution
     external: ['@modelcontextprotocol/client/_shims']
 });

packages/core/src/exports/public/index.ts

@@ -142,9 +142,10 @@ export { InMemoryTaskMessageQueue, InMemoryTaskStore } from '../../experimental/
 export type { SpecTypeName, SpecTypes } from '../../types/specTypeSchema.js';
 export { isSpecType, specTypeSchemas } from '../../types/specTypeSchema.js';
 export type { StandardSchemaV1, StandardSchemaV1Sync, StandardSchemaWithJSON } from '../../util/standardSchema.js';
-// Concrete validator providers (AjvJsonSchemaValidator, CfWorkerJsonSchemaValidator) are
-// intentionally NOT exported: client/server bundle them via the runtime shim and end users
-// cannot reach them. To override validation, implement the `jsonSchemaValidator` interface.
+// Validator providers are type-only here — import the runtime classes from the explicit
+// `@modelcontextprotocol/{client,server}/validators/{ajv,cf-worker}` subpaths to customise.
+export type { AjvJsonSchemaValidator } from '../../validators/ajvProvider.js';
+export type { CfWorkerJsonSchemaValidator, CfWorkerSchemaDraft } from '../../validators/cfWorkerProvider.js';
 // fromJsonSchema is intentionally NOT exported here — the server and client packages
 // provide runtime-aware wrappers that default to the appropriate validator via _shims.
 export type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from '../../validators/types.js';