Bundle automatic validator defaults in client and server shims

Author: mattzcarey

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

@@ -0,0 +1,11 @@
+---
+'@modelcontextprotocol/core': minor
+'@modelcontextprotocol/client': patch
+'@modelcontextprotocol/server': patch
+---
+
+Make validator backends symmetrical in core and bundle automatic defaults in client/server runtime shims.
+
+Core no longer re-exports concrete validator providers as runtime values from the root/public barrels. AJV/AJV formats and `@cfworker/json-schema` are optional peer backends behind explicit core validator provider subpaths, used internally by client/server shims.
+
+Client/server continue to select defaults automatically: Node shims use AJV, while browser/workerd shims use `@cfworker/json-schema`. Those backends are bundled into the shim chunks that select them, so users do not need to install validator packages or import explicit validators for default behavior. Advanced users can still pass their own `jsonSchemaValidator` implementation.

docs/migration-SKILL.md

@@ -518,11 +518,11 @@ new McpServer(
 new McpServer({ name: 'server', version: '1.0.0' }, {});
 ```
 
-Access validators explicitly:
+Validator behavior:
 
-- Runtime-aware default: `import { DefaultJsonSchemaValidator } from '@modelcontextprotocol/server/_shims';`
-- AJV (Node.js): `import { AjvJsonSchemaValidator } from '@modelcontextprotocol/server';`
-- CF Worker: `import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/server/validators/cf-worker';`
+- 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.
+- Advanced users may pass `jsonSchemaValidator: myCustomValidator` with their own validator implementation.
 
 ## 15. Migration Steps (apply in this order)
 

docs/migration.md

@@ -932,15 +932,18 @@ const server = new McpServer(
 );
 ```
 
-You can still explicitly override the validator if needed:
+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.
 
-```typescript
-// Runtime-aware default (auto-selects AjvJsonSchemaValidator or CfWorkerJsonSchemaValidator)
-import { DefaultJsonSchemaValidator } from '@modelcontextprotocol/server/_shims';
+Advanced users can still override validation by passing an object that implements the SDK's JSON Schema validator interface:
 
-// Specific validators
-import { AjvJsonSchemaValidator } from '@modelcontextprotocol/server';
-import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/server/validators/cf-worker';
+```typescript
+const server = new McpServer(
+    { name: 'my-server', version: '1.0.0' },
+    {
+        capabilities: { tools: {} },
+        jsonSchemaValidator: myCustomValidator
+    }
+);
 ```
 
 ## Unchanged APIs

packages/client/package.json

@@ -28,10 +28,6 @@
             "types": "./dist/stdio.d.mts",
             "import": "./dist/stdio.mjs"
         },
-        "./validators/cf-worker": {
-            "types": "./dist/validators/cfWorker.d.mts",
-            "import": "./dist/validators/cfWorker.mjs"
-        },
         "./_shims": {
             "workerd": {
                 "types": "./dist/shimsWorkerd.d.mts",
@@ -54,9 +50,6 @@
     "types": "./dist/index.d.mts",
     "typesVersions": {
         "*": {
-            "validators/cf-worker": [
-                "dist/validators/cfWorker.d.mts"
-            ],
             "stdio": [
                 "dist/stdio.d.mts"
             ]
@@ -93,6 +86,8 @@
         "@modelcontextprotocol/eslint-config": "workspace:^",
         "@modelcontextprotocol/test-helpers": "workspace:^",
         "@cfworker/json-schema": "catalog:runtimeShared",
+        "ajv": "catalog:runtimeShared",
+        "ajv-formats": "catalog:runtimeShared",
         "@types/content-type": "catalog:devTools",
         "@types/cross-spawn": "catalog:devTools",
         "@types/eventsource": "catalog:devTools",

packages/client/src/client/client.ts

@@ -161,7 +161,7 @@ export type ClientOptions = ProtocolOptions & {
      * The validator is used to validate structured content returned by tools
      * against their declared output schemas.
      *
-     * @default {@linkcode DefaultJsonSchemaValidator} ({@linkcode index.AjvJsonSchemaValidator | AjvJsonSchemaValidator} on Node.js, `CfWorkerJsonSchemaValidator` on Cloudflare Workers)
+     * @default Runtime-selected validator (`AjvJsonSchemaValidator` on Node.js, `CfWorkerJsonSchemaValidator` on browser/workerd runtimes)
      */
     jsonSchemaValidator?: jsonSchemaValidator;
 

packages/client/src/shimsNode.ts

@@ -3,7 +3,7 @@
  *
  * This file is selected via package.json export conditions when running in Node.js.
  */
-export { AjvJsonSchemaValidator as DefaultJsonSchemaValidator } from '@modelcontextprotocol/core';
+export { AjvJsonSchemaValidator as DefaultJsonSchemaValidator } from '@modelcontextprotocol/core/validators/ajv';
 
 /**
  * Whether `fetch()` may throw `TypeError` due to CORS. CORS is a browser-only concept —

packages/client/src/validators/cfWorker.ts

@@ -8,6 +8,7 @@ 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)["']/;
 
 function chunkImportsOf(entryPath: string): string[] {
     const visited = new Set<string>();
@@ -52,4 +53,17 @@ describe('@modelcontextprotocol/client root entry is browser-safe', () => {
         expect(stdio).toMatch(/\bgetDefaultEnvironment\b/);
         expect(stdio).toMatch(/\bDEFAULT_INHERITED_ENV_VARS\b/);
     });
+
+    test('runtime shims vendor default validator backends instead of requiring consumers to install them', () => {
+        for (const shim of ['shimsNode.mjs', 'shimsWorkerd.mjs', 'shimsBrowser.mjs']) {
+            const entry = join(distDir, shim);
+            expect(readFileSync(entry, 'utf8')).not.toMatch(VALIDATOR_BACKEND_IMPORT);
+
+            for (const chunk of chunkImportsOf(entry)) {
+                expect({ chunk, content: readFileSync(chunk, 'utf8') }).not.toEqual(
+                    expect.objectContaining({ content: expect.stringMatching(VALIDATOR_BACKEND_IMPORT) })
+                );
+            }
+        }
+    });
 });

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

@@ -7,6 +7,7 @@
             "*": ["./*"],
             "@modelcontextprotocol/core": ["./node_modules/@modelcontextprotocol/core/src/index.ts"],
             "@modelcontextprotocol/core/public": ["./node_modules/@modelcontextprotocol/core/src/exports/public/index.ts"],
+            "@modelcontextprotocol/core/validators/ajv": ["./node_modules/@modelcontextprotocol/core/src/validators/ajvProvider.ts"],
             "@modelcontextprotocol/core/validators/cfWorker": [
                 "./node_modules/@modelcontextprotocol/core/src/validators/cfWorkerProvider.ts"
             ],

packages/client/tsconfig.json

@@ -4,7 +4,7 @@ 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', 'src/validators/cfWorker.ts'],
+    entry: ['src/index.ts', 'src/stdio.ts', 'src/shimsNode.ts', 'src/shimsWorkerd.ts', 'src/shimsBrowser.ts'],
 
     // 2. Output Configuration
     format: ['esm'],
@@ -27,13 +27,19 @@ export default defineConfig({
             paths: {
                 '@modelcontextprotocol/core': ['../core/src/index.ts'],
                 '@modelcontextprotocol/core/public': ['../core/src/exports/public/index.ts'],
+                '@modelcontextprotocol/core/validators/ajv': ['../core/src/validators/ajvProvider.ts'],
                 '@modelcontextprotocol/core/validators/cfWorker': ['../core/src/validators/cfWorkerProvider.ts']
             }
         }
     },
-    // 5. Vendoring Strategy - Bundle the code for this specific package into the output,
-    //    but treat all other dependencies as external (require/import).
-    noExternal: ['@modelcontextprotocol/core'],
+    // 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']