docs(core): align validator examples with bundled-shim surface

After PR #2088, end users can no longer import or construct
AjvJsonSchemaValidator / CfWorkerJsonSchemaValidator — client/server
bundle them via the runtime shim and expose only the jsonSchemaValidator
interface as the public extension point.

- Strip impossible `new AjvJsonSchemaValidator()` / `new CfWorkerJsonSchemaValidator()`
  snippets from JSDoc on the validation module, ajvProvider, cfWorkerProvider,
  and fromJsonSchema; mark the provider classes @internal.
- fromJsonSchema example now declares `validator: jsonSchemaValidator` and
  notes that consumers importing from server/client omit the second arg.
- Drop the type-only re-exports of AjvJsonSchemaValidator,
  CfWorkerJsonSchemaValidator, and CfWorkerSchemaDraft from core/public —
  with the runtime classes unreachable, a type-only handle is dead surface.
- Reword the migration docs to describe backends by name (AJV /
  @cfworker/json-schema) instead of the now-internal class names.

Author: mattzcarey

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

@@ -9,3 +9,5 @@ Make validator backends symmetrical in core and bundle automatic defaults in cli
 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.
+
+`AjvJsonSchemaValidator` and `CfWorkerJsonSchemaValidator` are now `@internal` and no longer surface from `@modelcontextprotocol/core/public` (not even as types). The `jsonSchemaValidator` interface remains the public extension point for custom validators. Example JSDoc snippets no longer demonstrate direct validator instantiation.

docs/migration-SKILL.md

@@ -500,8 +500,8 @@ Type changes in handler context:
 
 The SDK now auto-selects the appropriate JSON Schema validator based on runtime:
 
-- Node.js → `AjvJsonSchemaValidator` (no change from v1)
-- Cloudflare Workers (workerd) → `CfWorkerJsonSchemaValidator` (previously required manual config)
+- Node.js → AJV (no change from v1)
+- Cloudflare Workers (workerd) → `@cfworker/json-schema` (previously required manual config)
 
 **No action required** for most users. Cloudflare Workers users can remove explicit `jsonSchemaValidator` configuration:
 

docs/migration.md

@@ -900,8 +900,8 @@ server.setRequestHandler('tools/call', async (request, ctx) => {
 
 The SDK now automatically selects the appropriate JSON Schema validator based on your runtime environment:
 
-- **Node.js**: Uses `AjvJsonSchemaValidator` (same as v1 default)
-- **Cloudflare Workers**: Uses `CfWorkerJsonSchemaValidator` (previously required manual configuration)
+- **Node.js**: Uses AJV (same as v1 default)
+- **Cloudflare Workers**: Uses `@cfworker/json-schema` (previously required manual configuration)
 
 This means Cloudflare Workers users no longer need to explicitly pass the validator:
 

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

@@ -141,8 +141,9 @@ export { InMemoryTaskMessageQueue, InMemoryTaskStore } from '../../experimental/
 export type { SpecTypeName, SpecTypes } from '../../types/specTypeSchema.js';
 export { isSpecType, specTypeSchemas } from '../../types/specTypeSchema.js';
 export type { StandardSchemaV1, StandardSchemaWithJSON } from '../../util/standardSchema.js';
-export type { AjvJsonSchemaValidator } from '../../validators/ajvProvider.js';
-export type { CfWorkerJsonSchemaValidator, CfWorkerSchemaDraft } from '../../validators/cfWorkerProvider.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.
 // 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';

packages/core/src/index.examples.ts

@@ -29,28 +29,14 @@ export * from './validators/fromJsonSchema.js';
 /**
  * JSON Schema validation
  *
- * This module provides configurable JSON Schema validation for the MCP SDK.
- * Choose a validator based on your runtime environment:
+ * Client and server packages automatically select a JSON Schema validator backend based on the
+ * runtime: AJV-backed on Node.js, `@cfworker/json-schema`-backed on browser/workerd. Both backends
+ * are bundled into the corresponding shim, so consumers do not need to install or import validator
+ * packages for the default behaviour.
  *
- * - `AjvJsonSchemaValidator`: Best for Node.js (default, fastest)
- *   Used automatically by client/server Node shims.
- *
- * - `CfWorkerJsonSchemaValidator`: Best for edge runtimes
- *   Used automatically by client/server browser/workerd shims.
- *
- * Client and server packages bundle their runtime default validator backends, so most users should
- * rely on automatic runtime selection. Advanced users can pass their own validator implementation
- * through client/server options.
- *
- * @example For Node.js with AJV
- * ```ts source="./index.examples.ts#validation_ajv"
- * const validator = new AjvJsonSchemaValidator();
- * ```
- *
- * @example For Cloudflare Workers
- * ```ts source="./index.examples.ts#validation_cfWorker"
- * const validator = new CfWorkerJsonSchemaValidator();
- * ```
+ * To override validation, pass an object implementing the {@link jsonSchemaValidator} interface as
+ * `jsonSchemaValidator` on the client/server options. See `validators/types.ts` for the contract
+ * and a sample implementation.
  *
  * @module validation
  */

packages/core/src/index.ts

@@ -22,18 +22,13 @@ function createDefaultAjvInstance(): Ajv {
 }
 
 /**
- * @example Use with default AJV instance (recommended)
- * ```ts source="./ajvProvider.examples.ts#AjvJsonSchemaValidator_default"
- * const validator = new AjvJsonSchemaValidator();
- * ```
+ * AJV-backed validator used as the default in Node shims.
  *
- * @example Use with custom AJV instance
- * ```ts source="./ajvProvider.examples.ts#AjvJsonSchemaValidator_customInstance"
- * const ajv = new Ajv({ strict: true, allErrors: true });
- * const validator = new AjvJsonSchemaValidator(ajv);
- * ```
+ * Not part of the public surface: end users get this automatically via the runtime shim and
+ * cannot import it from `@modelcontextprotocol/client` or `@modelcontextprotocol/server`.
+ * To override validation, implement the {@link jsonSchemaValidator} interface.
  *
- * @see `CfWorkerJsonSchemaValidator` for the edge-runtime-compatible validator selected automatically by client/server browser/workerd shims.
+ * @internal
  */
 export class AjvJsonSchemaValidator implements jsonSchemaValidator {
     private _ajv: Ajv;
@@ -42,18 +37,6 @@ export class AjvJsonSchemaValidator implements jsonSchemaValidator {
      * Create an AJV validator
      *
      * @param ajv - Optional pre-configured AJV instance. If not provided, a default instance will be created.
-     *
-     * @example Use default configuration (recommended for most cases)
-     * ```ts source="./ajvProvider.examples.ts#AjvJsonSchemaValidator_default"
-     * const validator = new AjvJsonSchemaValidator();
-     * ```
-     *
-     * @example Provide custom AJV instance for advanced configuration
-     * ```ts source="./ajvProvider.examples.ts#AjvJsonSchemaValidator_constructor_withFormats"
-     * const ajv = new Ajv({ validateFormats: true });
-     * addFormats(ajv);
-     * const validator = new AjvJsonSchemaValidator(ajv);
-     * ```
      */
     constructor(ajv?: Ajv) {
         this._ajv = ajv ?? createDefaultAjvInstance();

packages/core/src/validators/ajvProvider.examples.ts

@@ -14,23 +14,19 @@ import type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSche
 
 /**
  * JSON Schema draft version supported by @cfworker/json-schema
+ *
+ * @internal
  */
 export type CfWorkerSchemaDraft = '4' | '7' | '2019-09' | '2020-12';
 
 /**
+ * `@cfworker/json-schema`-backed validator used as the default in browser/workerd shims.
  *
- * @example Use with default configuration (2020-12, shortcircuit)
- * ```ts source="./cfWorkerProvider.examples.ts#CfWorkerJsonSchemaValidator_default"
- * const validator = new CfWorkerJsonSchemaValidator();
- * ```
+ * Not part of the public surface: end users get this automatically via the runtime shim and
+ * cannot import it from `@modelcontextprotocol/client` or `@modelcontextprotocol/server`.
+ * To override validation, implement the {@link jsonSchemaValidator} interface.
  *
- * @example Use with custom configuration
- * ```ts source="./cfWorkerProvider.examples.ts#CfWorkerJsonSchemaValidator_customConfig"
- * const validator = new CfWorkerJsonSchemaValidator({
- *     draft: '2020-12',
- *     shortcircuit: false // Report all errors
- * });
- * ```
+ * @internal
  */
 export class CfWorkerJsonSchemaValidator implements jsonSchemaValidator {
     private shortcircuit: boolean;