Add sync-snippets script for type-checked examples

JSDoc `@example` code blocks were previously inlined and not
type-checked, meaning they could silently drift from the actual API.
This adds a `scripts/sync-snippets.ts` script (`pnpm sync:snippets`)
that extracts code from co-located `.examples.ts` files — using
`//#region` markers — and syncs them into JSDoc `@example` fences and
markdown files.

The script supports a `--check` mode (wired into `lint:all`) to catch
drift in CI. Code fences use a `source="./file.examples.ts#regionName"`
attribute to reference their source of truth.

Includes `.examples.ts` companion files for:

- `packages/core`: `SdkError`, validation providers
  (`AjvJsonSchemaValidator`, `CfWorkerJsonSchemaValidator`,
  `jsonSchemaValidator`), and module-level validator examples
- `packages/client`: `Client` options, `fetchToken`, auth extensions
  (`createPrivateKeyJwtAuth`, `ClientCredentialsProvider`,
  `PrivateKeyJwtProvider`), client middleware (`applyMiddlewares`,
  `createMiddleware`), and experimental task streaming
- `packages/server`: `hostHeaderValidation` response helper
- `packages/middleware/express`: `createMcpExpressApp` and host header
  validation middleware

Also removes the duplicate `@example` from `Protocol.requestStream()`
(now covered by `ExperimentalClientTasks.requestStream()`), adds ESLint
overrides for `.examples.ts` files (`no-unused-vars`, `no-console`), and
updates `CLAUDE.md` with snippet conventions.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Author: jonathanhefner

CLAUDE.md

@@ -41,6 +41,12 @@ Include what changed, why, and how to migrate. Search for related sections and g
 - **Testing**: Co-locate tests with source files, use descriptive test names
 - **Comments**: JSDoc for public APIs, inline comments for complex logic
 
+### JSDoc `@example` Code Snippets
+
+JSDoc `@example` tags should pull type-checked code from companion `.examples.ts` files (e.g., `client.ts` → `client.examples.ts`). Use `` ```ts source="./file.examples.ts#regionName" `` fences referencing `//#region regionName` blocks; region names follow `exportedName_variant` or `ClassName_methodName_variant` pattern (e.g., `applyMiddlewares_basicUsage`, `Client_connect_basicUsage`). For whole-file inclusion (any file type), omit the `#regionName`.
+
+Run `pnpm sync:snippets` to sync example content into JSDoc comments and markdown files.
+
 ## Architecture Overview
 
 ### Core Layers

common/eslint-config/eslint.config.mjs

@@ -86,6 +86,14 @@ export default defineConfig(
             'unicorn/consistent-function-scoping': 'off'
         }
     },
+    {
+        // Example files contain intentionally unused functions (one per region)
+        files: ['**/*.examples.ts'],
+        rules: {
+            '@typescript-eslint/no-unused-vars': 'off',
+            'no-console': 'off'
+        }
+    },
     {
         // Ignore generated protocol types everywhere
         ignores: ['**/spec.types.ts']

package.json

@@ -23,14 +23,15 @@
     ],
     "scripts": {
         "fetch:spec-types": "tsx scripts/fetch-spec-types.ts",
+        "sync:snippets": "tsx scripts/sync-snippets.ts",
         "examples:simple-server:w": "pnpm --filter @modelcontextprotocol/examples-server exec tsx --watch src/simpleStreamableHttp.ts --oauth",
         "docs": "typedoc",
         "docs:check": "typedoc --emit none",
         "typecheck:all": "pnpm -r typecheck",
         "build:all": "pnpm -r build",
         "prepack:all": "pnpm -r prepack",
-        "lint:all": "pnpm -r lint",
-        "lint:fix:all": "pnpm -r lint:fix",
+        "lint:all": "pnpm sync:snippets --check && pnpm -r lint",
+        "lint:fix:all": "pnpm sync:snippets && pnpm -r lint:fix",
         "check:all": "pnpm -r typecheck && pnpm -r lint",
         "test:all": "pnpm -r test",
         "test:conformance:client": "pnpm --filter @modelcontextprotocol/test-conformance run test:conformance:client",

packages/client/src/client/auth.examples.ts

@@ -0,0 +1,63 @@
+/**
+ * Type-checked examples for {@linkcode fetchToken} in {@link ./auth.ts `auth.ts`}.
+ *
+ * These examples are synced into JSDoc comments via the sync-snippets script.
+ * Each function's region markers define the code snippet that appears in the docs.
+ *
+ * @module
+ */
+
+import type { AuthorizationServerMetadata } from '@modelcontextprotocol/core';
+
+import type { OAuthClientProvider } from './auth.js';
+import { fetchToken } from './auth.js';
+
+/**
+ * Base class providing no-op implementations of required OAuthClientProvider methods.
+ * Used as a base for concise examples that focus on specific methods.
+ */
+abstract class MyProviderBase implements OAuthClientProvider {
+    get redirectUrl(): URL | undefined {
+        return;
+    }
+    get clientMetadata() {
+        return { redirect_uris: [] as string[] };
+    }
+    clientInformation(): undefined {
+        return;
+    }
+    tokens(): undefined {
+        return;
+    }
+    saveTokens() {
+        return Promise.resolve();
+    }
+    redirectToAuthorization() {
+        return Promise.resolve();
+    }
+    saveCodeVerifier() {
+        return Promise.resolve();
+    }
+    codeVerifier() {
+        return Promise.resolve('');
+    }
+}
+
+/**
+ * Example: Using fetchToken with a client_credentials provider.
+ */
+async function fetchToken_clientCredentials(authServerUrl: URL, metadata: AuthorizationServerMetadata) {
+    //#region fetchToken_clientCredentials
+    // Provider for client_credentials:
+    class MyProvider extends MyProviderBase implements OAuthClientProvider {
+        prepareTokenRequest(scope?: string) {
+            const params = new URLSearchParams({ grant_type: 'client_credentials' });
+            if (scope) params.set('scope', scope);
+            return params;
+        }
+    }
+
+    const tokens = await fetchToken(new MyProvider(), authServerUrl, { metadata });
+    //#endregion fetchToken_clientCredentials
+    return tokens;
+}

packages/client/src/client/auth.ts

@@ -1210,18 +1210,17 @@ export async function refreshAuthorization(
  * @throws {Error} When provider doesn't implement prepareTokenRequest or token fetch fails
  *
  * @example
- * ```typescript
+ * ```ts source="./auth.examples.ts#fetchToken_clientCredentials"
  * // Provider for client_credentials:
- * class MyProvider implements OAuthClientProvider {
- *   prepareTokenRequest(scope) {
- *     const params = new URLSearchParams({ grant_type: 'client_credentials' });
- *     if (scope) params.set('scope', scope);
- *     return params;
- *   }
- *   // ... other methods
+ * class MyProvider extends MyProviderBase implements OAuthClientProvider {
+ *     prepareTokenRequest(scope?: string) {
+ *         const params = new URLSearchParams({ grant_type: 'client_credentials' });
+ *         if (scope) params.set('scope', scope);
+ *         return params;
+ *     }
  * }
  *
- * const tokens = await fetchToken(provider, authServerUrl, { metadata });
+ * const tokens = await fetchToken(new MyProvider(), authServerUrl, { metadata });
  * ```
  */
 export async function fetchToken(

packages/client/src/client/authExtensions.examples.ts

@@ -0,0 +1,62 @@
+/**
+ * Type-checked examples for auth extensions in {@link ./authExtensions.ts `authExtensions.ts`}.
+ *
+ * These examples are synced into JSDoc comments via the sync-snippets script.
+ * Each function's region markers define the code snippet that appears in the docs.
+ *
+ * @module
+ */
+
+import { ClientCredentialsProvider, createPrivateKeyJwtAuth, PrivateKeyJwtProvider } from './authExtensions.js';
+import { StreamableHTTPClientTransport } from './streamableHttp.js';
+
+/**
+ * Example: Creating a private key JWT authentication function.
+ */
+function createPrivateKeyJwtAuth_basicUsage(pemEncodedPrivateKey: string) {
+    //#region createPrivateKeyJwtAuth_basicUsage
+    const addClientAuth = createPrivateKeyJwtAuth({
+        issuer: 'my-client',
+        subject: 'my-client',
+        privateKey: pemEncodedPrivateKey,
+        alg: 'RS256'
+    });
+    // pass addClientAuth as provider.addClientAuthentication implementation
+    //#endregion createPrivateKeyJwtAuth_basicUsage
+    return addClientAuth;
+}
+
+/**
+ * Example: Using ClientCredentialsProvider for OAuth client credentials flow.
+ */
+function ClientCredentialsProvider_basicUsage(serverUrl: URL) {
+    //#region ClientCredentialsProvider_basicUsage
+    const provider = new ClientCredentialsProvider({
+        clientId: 'my-client',
+        clientSecret: 'my-secret'
+    });
+
+    const transport = new StreamableHTTPClientTransport(serverUrl, {
+        authProvider: provider
+    });
+    //#endregion ClientCredentialsProvider_basicUsage
+    return transport;
+}
+
+/**
+ * Example: Using PrivateKeyJwtProvider for OAuth with private key JWT.
+ */
+function PrivateKeyJwtProvider_basicUsage(pemEncodedPrivateKey: string, serverUrl: URL) {
+    //#region PrivateKeyJwtProvider_basicUsage
+    const provider = new PrivateKeyJwtProvider({
+        clientId: 'my-client',
+        privateKey: pemEncodedPrivateKey,
+        algorithm: 'RS256'
+    });
+
+    const transport = new StreamableHTTPClientTransport(serverUrl, {
+        authProvider: provider
+    });
+    //#endregion PrivateKeyJwtProvider_basicUsage
+    return transport;
+}

packages/client/src/client/authExtensions.ts

@@ -14,8 +14,13 @@ import type { AddClientAuthentication, OAuthClientProvider } from './auth.js';
  * Helper to produce a private_key_jwt client authentication function.
  *
  * @example
- * ```typescript
- * const addClientAuth = createPrivateKeyJwtAuth({ issuer, subject, privateKey, alg, audience? });
+ * ```ts source="./authExtensions.examples.ts#createPrivateKeyJwtAuth_basicUsage"
+ * const addClientAuth = createPrivateKeyJwtAuth({
+ *     issuer: 'my-client',
+ *     subject: 'my-client',
+ *     privateKey: pemEncodedPrivateKey,
+ *     alg: 'RS256'
+ * });
  * // pass addClientAuth as provider.addClientAuthentication implementation
  * ```
  */
@@ -116,14 +121,14 @@ export interface ClientCredentialsProviderOptions {
  * the client authenticates using a client_id and client_secret.
  *
  * @example
- * ```typescript
+ * ```ts source="./authExtensions.examples.ts#ClientCredentialsProvider_basicUsage"
  * const provider = new ClientCredentialsProvider({
- *   clientId: 'my-client',
- *   clientSecret: 'my-secret'
+ *     clientId: 'my-client',
+ *     clientSecret: 'my-secret'
  * });
  *
  * const transport = new StreamableHTTPClientTransport(serverUrl, {
- *   authProvider: provider
+ *     authProvider: provider
  * });
  * ```
  */
@@ -227,15 +232,15 @@ export interface PrivateKeyJwtProviderOptions {
  * ({@link https://datatracker.ietf.org/doc/html/rfc7523#section-2.2 | RFC 7523 Section 2.2}).
  *
  * @example
- * ```typescript
+ * ```ts source="./authExtensions.examples.ts#PrivateKeyJwtProvider_basicUsage"
  * const provider = new PrivateKeyJwtProvider({
- *   clientId: 'my-client',
- *   privateKey: pemEncodedPrivateKey,
- *   algorithm: 'RS256'
+ *     clientId: 'my-client',
+ *     privateKey: pemEncodedPrivateKey,
+ *     algorithm: 'RS256'
  * });
  *
  * const transport = new StreamableHTTPClientTransport(serverUrl, {
- *   authProvider: provider
+ *     authProvider: provider
  * });
  * ```
  */

packages/client/src/client/client.examples.ts

@@ -0,0 +1,38 @@
+/**
+ * Type-checked examples for {@linkcode Client} in {@link ./client.ts `client.ts`}.
+ *
+ * These examples are synced into JSDoc comments via the sync-snippets script.
+ * Each function's region markers define the code snippet that appears in the docs.
+ *
+ * @module
+ */
+
+import { Client } from './client.js';
+
+/**
+ * Example: Using listChanged to automatically track tool and prompt updates.
+ */
+function ClientOptions_listChanged() {
+    //#region ClientOptions_listChanged
+    const client = new Client(
+        { name: 'my-client', version: '1.0.0' },
+        {
+            listChanged: {
+                tools: {
+                    onChanged: (error, tools) => {
+                        if (error) {
+                            console.error('Failed to refresh tools:', error);
+                            return;
+                        }
+                        console.log('Tools updated:', tools);
+                    }
+                },
+                prompts: {
+                    onChanged: (error, prompts) => console.log('Prompts updated:', prompts)
+                }
+            }
+        }
+    );
+    //#endregion ClientOptions_listChanged
+    return client;
+}

packages/client/src/client/client.ts

@@ -161,25 +161,25 @@ export type ClientOptions = ProtocolOptions & {
      * Configure handlers for list changed notifications (tools, prompts, resources).
      *
      * @example
-     * ```typescript
+     * ```ts source="./client.examples.ts#ClientOptions_listChanged"
      * const client = new Client(
-     *   { name: 'my-client', version: '1.0.0' },
-     *   {
-     *     listChanged: {
-     *       tools: {
-     *         onChanged: (error, tools) => {
-     *           if (error) {
-     *             console.error('Failed to refresh tools:', error);
-     *             return;
-     *           }
-     *           console.log('Tools updated:', tools);
+     *     { name: 'my-client', version: '1.0.0' },
+     *     {
+     *         listChanged: {
+     *             tools: {
+     *                 onChanged: (error, tools) => {
+     *                     if (error) {
+     *                         console.error('Failed to refresh tools:', error);
+     *                         return;
+     *                     }
+     *                     console.log('Tools updated:', tools);
+     *                 }
+     *             },
+     *             prompts: {
+     *                 onChanged: (error, prompts) => console.log('Prompts updated:', prompts)
+     *             }
      *         }
-     *       },
-     *       prompts: {
-     *         onChanged: (error, prompts) => console.log('Prompts updated:', prompts)
-     *       }
      *     }
-     *   }
      * );
      * ```
      */