Add sync-snippets script for type-checked examples

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 `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 `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 `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)
- * }
  * }
- * }
  * );
  * ```
  */

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 `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 `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 `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)
- * }
  * }
- * }
  * );
  * ```
  */

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 `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 `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 `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)
- * }
  * }
- * }
  * );
  * ```
  */

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 `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 `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 `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)
- * }
  * }
- * }
  * );
  * ```
  */

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 `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 `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 `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)
- * }
  * }
- * }
  * );
  * ```
  */

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 `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 `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 `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)
- * }
  * }
- * }
  * );
  * ```
  */

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 `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 `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 `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)
- * }
  * }
- * }
  * );
  * ```
  */

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 `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 `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 `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)
- * }
  * }
- * }
  * );
  * ```
  */