Add JSDoc @example tags with companion .examples.ts files (#1524)

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

packages/middleware/node/src/streamableHttp.examples.ts

@@ -0,0 +1,56 @@
+/**
+ * Type-checked examples for `streamableHttp.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 { randomUUID } from 'node:crypto';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+import { McpServer } from '@modelcontextprotocol/server';
+
+import { NodeStreamableHTTPServerTransport } from './streamableHttp.js';
+
+/**
+ * Example: Stateful Streamable HTTP transport (Node.js).
+ */
+async function NodeStreamableHTTPServerTransport_stateful() {
+    //#region NodeStreamableHTTPServerTransport_stateful
+    const server = new McpServer({ name: 'my-server', version: '1.0.0' });
+
+    const transport = new NodeStreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID()
+    });
+
+    await server.connect(transport);
+    //#endregion NodeStreamableHTTPServerTransport_stateful
+}
+
+/**
+ * Example: Stateless Streamable HTTP transport (Node.js).
+ */
+async function NodeStreamableHTTPServerTransport_stateless() {
+    //#region NodeStreamableHTTPServerTransport_stateless
+    const transport = new NodeStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined
+    });
+    //#endregion NodeStreamableHTTPServerTransport_stateless
+    return transport;
+}
+
+// Stubs for Express-style app
+declare const app: { post(path: string, handler: (req: IncomingMessage & { body?: unknown }, res: ServerResponse) => void): void };
+
+/**
+ * Example: Using with a pre-parsed request body (e.g. Express).
+ */
+function NodeStreamableHTTPServerTransport_express(transport: NodeStreamableHTTPServerTransport) {
+    //#region NodeStreamableHTTPServerTransport_express
+    app.post('/mcp', (req, res) => {
+        transport.handleRequest(req, res, req.body);
+    });
+    //#endregion NodeStreamableHTTPServerTransport_express
+}

packages/middleware/node/src/streamableHttp.ts

@@ -28,25 +28,6 @@ export type StreamableHTTPServerTransportOptions = WebStandardStreamableHTTPServ
  * This is a wrapper around {@linkcode WebStandardStreamableHTTPServerTransport} that provides Node.js HTTP compatibility.
  * It uses the `@hono/node-server` library to convert between Node.js HTTP and Web Standard APIs.
  *
- * Usage example:
- *
- * ```typescript
- * // Stateful mode - server sets the session ID
- * const statefulTransport = new StreamableHTTPServerTransport({
- *   sessionIdGenerator: () => randomUUID(),
- * });
- *
- * // Stateless mode - explicitly set session ID to undefined
- * const statelessTransport = new StreamableHTTPServerTransport({
- *   sessionIdGenerator: undefined,
- * });
- *
- * // Using with pre-parsed request body
- * app.post('/mcp', (req, res) => {
- *   transport.handleRequest(req, res, req.body);
- * });
- * ```
- *
  * In stateful mode:
  * - Session ID is generated and included in response headers
  * - Session ID is always included in initialization responses
@@ -57,6 +38,31 @@ export type StreamableHTTPServerTransportOptions = WebStandardStreamableHTTPServ
  * In stateless mode:
  * - No Session ID is included in any responses
  * - No session validation is performed
+ *
+ * @example Stateful setup
+ * ```ts source="./streamableHttp.examples.ts#NodeStreamableHTTPServerTransport_stateful"
+ * const server = new McpServer({ name: 'my-server', version: '1.0.0' });
+ *
+ * const transport = new NodeStreamableHTTPServerTransport({
+ *     sessionIdGenerator: () => randomUUID()
+ * });
+ *
+ * await server.connect(transport);
+ * ```
+ *
+ * @example Stateless setup
+ * ```ts source="./streamableHttp.examples.ts#NodeStreamableHTTPServerTransport_stateless"
+ * const transport = new NodeStreamableHTTPServerTransport({
+ *     sessionIdGenerator: undefined
+ * });
+ * ```
+ *
+ * @example Using with a pre-parsed request body (e.g. Express)
+ * ```ts source="./streamableHttp.examples.ts#NodeStreamableHTTPServerTransport_express"
+ * app.post('/mcp', (req, res) => {
+ *     transport.handleRequest(req, res, req.body);
+ * });
+ * ```
  */
 export class NodeStreamableHTTPServerTransport implements Transport {
     private _webStandardTransport: WebStandardStreamableHTTPServerTransport;