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

@@ -0,0 +1,110 @@
+import type { JSONRPCMessage, JsonSchemaType, JsonSchemaValidatorResult, jsonSchemaValidator } from '@modelcontextprotocol/core';
+import { InMemoryTransport, LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/core';
+import { Client } from '../../src/client/client.js';
+import { fromJsonSchema } from '../../src/fromJsonSchema.js';
+
+class RecordingValidator implements jsonSchemaValidator {
+    schemas: JsonSchemaType[] = [];
+    values: unknown[] = [];
+
+    getValidator<T>(schema: JsonSchemaType) {
+        this.schemas.push(schema);
+        return (value: unknown): JsonSchemaValidatorResult<T> => {
+            this.values.push(value);
+            return { valid: true, data: value as T, errorMessage: undefined };
+        };
+    }
+}
+
+async function connectInitializedClient(client: Client) {
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    serverTransport.onmessage = async message => {
+        if ('method' in message && 'id' in message && message.method === 'initialize') {
+            await serverTransport.send({
+                jsonrpc: '2.0',
+                id: message.id,
+                result: {
+                    protocolVersion: LATEST_PROTOCOL_VERSION,
+                    capabilities: { tools: {} },
+                    serverInfo: { name: 'test-server', version: '1.0.0' }
+                }
+            });
+        } else if ('method' in message && 'id' in message && message.method === 'tools/list') {
+            await serverTransport.send({
+                jsonrpc: '2.0',
+                id: message.id,
+                result: {
+                    tools: [
+                        {
+                            name: 'structured-tool',
+                            description: 'A tool with structured output',
+                            inputSchema: { type: 'object' },
+                            outputSchema: {
+                                type: 'object',
+                                properties: { count: { type: 'number' } },
+                                required: ['count']
+                            }
+                        }
+                    ]
+                }
+            } satisfies JSONRPCMessage);
+        }
+    };
+
+    await Promise.all([client.connect(clientTransport), serverTransport.start()]);
+    return { clientTransport, serverTransport };
+}
+
+describe('client JSON Schema validator overrides', () => {
+    test('Client constructor uses a custom validator for tool output schema caching', async () => {
+        const validator = new RecordingValidator();
+        const client = new Client(
+            { name: 'test-client', version: '1.0.0' },
+            {
+                capabilities: {},
+                jsonSchemaValidator: validator
+            }
+        );
+        const { clientTransport, serverTransport } = await connectInitializedClient(client);
+
+        await expect(client.listTools()).resolves.toMatchObject({
+            tools: [
+                {
+                    name: 'structured-tool',
+                    outputSchema: {
+                        type: 'object',
+                        properties: { count: { type: 'number' } },
+                        required: ['count']
+                    }
+                }
+            ]
+        });
+
+        expect(validator.schemas).toEqual([
+            {
+                type: 'object',
+                properties: { count: { type: 'number' } },
+                required: ['count']
+            }
+        ]);
+
+        await client.close();
+        await clientTransport.close();
+        await serverTransport.close();
+    });
+
+    test('fromJsonSchema uses an explicitly supplied custom validator', async () => {
+        const validator = new RecordingValidator();
+        const schema: JsonSchemaType = {
+            type: 'object',
+            properties: { name: { type: 'string' } },
+            required: ['name']
+        };
+
+        const standardSchema = fromJsonSchema<{ name: string }>(schema, validator);
+        expect(standardSchema['~standard'].validate({ name: 123 })).toEqual({ value: { name: 123 } });
+
+        expect(validator.schemas).toEqual([schema]);
+        expect(validator.values).toEqual([{ name: 123 }]);
+    });
+});

packages/client/test/client/jsonSchemaValidatorOverride.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"
             ],