Add sync-snippets script for type-checked examples (#1487)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

packages/middleware/express/src/express.examples.ts

@@ -0,0 +1,41 @@
+/**
+ * Type-checked examples for `express.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 { createMcpExpressApp } from './express.js';
+
+/**
+ * Example: Basic usage with default DNS rebinding protection.
+ */
+function createMcpExpressApp_default() {
+    //#region createMcpExpressApp_default
+    const app = createMcpExpressApp();
+    //#endregion createMcpExpressApp_default
+    return app;
+}
+
+/**
+ * Example: Custom host binding with and without DNS rebinding protection.
+ */
+function createMcpExpressApp_customHost() {
+    //#region createMcpExpressApp_customHost
+    const appOpen = createMcpExpressApp({ host: '0.0.0.0' }); // No automatic DNS rebinding protection
+    const appLocal = createMcpExpressApp({ host: 'localhost' }); // DNS rebinding protection enabled
+    //#endregion createMcpExpressApp_customHost
+    return { appOpen, appLocal };
+}
+
+/**
+ * Example: Custom allowed hosts for non-localhost binding.
+ */
+function createMcpExpressApp_allowedHosts() {
+    //#region createMcpExpressApp_allowedHosts
+    const app = createMcpExpressApp({ host: '0.0.0.0', allowedHosts: ['myapp.local', 'localhost'] });
+    //#endregion createMcpExpressApp_allowedHosts
+    return app;
+}

packages/middleware/express/src/express.ts

@@ -34,16 +34,19 @@ export interface CreateMcpExpressAppOptions {
  * @param options - Configuration options
  * @returns A configured Express application
  *
- * @example
- * ```typescript
- * // Basic usage - defaults to 127.0.0.1 with DNS rebinding protection
+ * @example Basic usage - defaults to 127.0.0.1 with DNS rebinding protection
+ * ```ts source="./express.examples.ts#createMcpExpressApp_default"
  * const app = createMcpExpressApp();
+ * ```
  *
- * // Custom host - DNS rebinding protection only applied for localhost hosts
- * const app = createMcpExpressApp({ host: '0.0.0.0' }); // No automatic DNS rebinding protection
- * const app = createMcpExpressApp({ host: 'localhost' }); // DNS rebinding protection enabled
+ * @example Custom host - DNS rebinding protection only applied for localhost hosts
+ * ```ts source="./express.examples.ts#createMcpExpressApp_customHost"
+ * const appOpen = createMcpExpressApp({ host: '0.0.0.0' }); // No automatic DNS rebinding protection
+ * const appLocal = createMcpExpressApp({ host: 'localhost' }); // DNS rebinding protection enabled
+ * ```
  *
- * // Custom allowed hosts for non-localhost binding
+ * @example Custom allowed hosts for non-localhost binding
+ * ```ts source="./express.examples.ts#createMcpExpressApp_allowedHosts"
  * const app = createMcpExpressApp({ host: '0.0.0.0', allowedHosts: ['myapp.local', 'localhost'] });
  * ```
  */

packages/middleware/express/src/middleware/hostHeaderValidation.examples.ts

@@ -0,0 +1,31 @@
+/**
+ * Type-checked examples for `hostHeaderValidation.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 { Express } from 'express';
+
+import { hostHeaderValidation, localhostHostValidation } from './hostHeaderValidation.js';
+
+/**
+ * Example: Using hostHeaderValidation middleware with custom allowed hosts.
+ */
+function hostHeaderValidation_basicUsage(app: Express) {
+    //#region hostHeaderValidation_basicUsage
+    const middleware = hostHeaderValidation(['localhost', '127.0.0.1', '[::1]']);
+    app.use(middleware);
+    //#endregion hostHeaderValidation_basicUsage
+}
+
+/**
+ * Example: Using localhostHostValidation convenience middleware.
+ */
+function localhostHostValidation_basicUsage(app: Express) {
+    //#region localhostHostValidation_basicUsage
+    app.use(localhostHostValidation());
+    //#endregion localhostHostValidation_basicUsage
+}

packages/middleware/express/src/middleware/hostHeaderValidation.ts

@@ -15,7 +15,7 @@ import type { NextFunction, Request, RequestHandler, Response } from 'express';
  * @returns Express middleware function
  *
  * @example
- * ```typescript
+ * ```ts source="./hostHeaderValidation.examples.ts#hostHeaderValidation_basicUsage"
  * const middleware = hostHeaderValidation(['localhost', '127.0.0.1', '[::1]']);
  * app.use(middleware);
  * ```
@@ -43,7 +43,7 @@ export function hostHeaderValidation(allowedHostnames: string[]): RequestHandler
  * Allows only `localhost`, `127.0.0.1`, and `[::1]` (IPv6 localhost) hostnames.
  *
  * @example
- * ```typescript
+ * ```ts source="./hostHeaderValidation.examples.ts#localhostHostValidation_basicUsage"
  * app.use(localhostHostValidation());
  * ```
  */