Merge origin/main into jerome/publish-examples

Resolve conflicts by:
- Keep server-utils.ts next to server.ts (not in src/)
- Simplify server-utils.ts to stateless HTTP only (no SSE)
- Keep main() with explicit --stdio handling in server.ts
- Add integration-server from main for E2E testing
- Add npm start alias from main

Author: ochafik

README.md

@@ -57,7 +57,7 @@ To run all examples together:
 
 ```bash
 npm install
-npm run examples:start
+npm start
 ```
 
 Then open http://localhost:8080/.

examples/basic-server-react/server-utils.ts

@@ -1,112 +1,47 @@
 /**
- * Shared utilities for running MCP servers with HTTP transports.
- *
- * Supports:
- * - Streamable HTTP transport (/mcp) - stateful sessions
- * - Legacy SSE transport (/sse, /messages) - backwards compatibility
+ * Shared utilities for running MCP servers with Streamable HTTP transport.
  */
 
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
-import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import cors from "cors";
-import { randomUUID } from "node:crypto";
 import type { Request, Response } from "express";
 
 export interface ServerOptions {
-  /** Port to listen on (required). */
   port: number;
-  /** Server name for logging. */
   name?: string;
 }
 
-type Transport = StreamableHTTPServerTransport | SSEServerTransport;
-
-/** Session state: transport + its dedicated server instance */
-interface Session {
-  transport: Transport;
-  server: McpServer;
-}
-
 /**
- * Starts an MCP server with HTTP transports.
+ * Starts an MCP server with Streamable HTTP transport in stateless mode.
  *
- * Provides:
- * - /mcp (GET/POST/DELETE): Streamable HTTP with stateful sessions
- * - /sse (GET) + /messages (POST): Legacy SSE for older clients
- *
- * @param createServer - Factory function that creates a new McpServer instance per session.
- *                       Each session needs its own server because McpServer only supports
- *                       one transport at a time.
+ * @param createServer - Factory function that creates a new McpServer instance per request.
+ * @param options - Server configuration options.
  */
 export async function startServer(
   createServer: () => McpServer,
   options: ServerOptions,
 ): Promise<void> {
   const { port, name = "MCP Server" } = options;
 
-  // Session store: each session has its own transport AND server instance
-  const sessions = new Map<string, Session>();
-
-  // Express app - bind to all interfaces for development/testing
   const app = createMcpExpressApp({ host: "0.0.0.0" });
-  app.use(
-    cors({
-      exposedHeaders: ["mcp-session-id"],
-    }),
-  );
+  app.use(cors());
 
-  // Streamable HTTP (stateful)
   app.all("/mcp", async (req: Request, res: Response) => {
-    try {
-      const sessionId = req.headers["mcp-session-id"] as string | undefined;
-      let session = sessionId ? sessions.get(sessionId) : undefined;
-
-      // Session exists but wrong transport type
-      if (
-        session &&
-        !(session.transport instanceof StreamableHTTPServerTransport)
-      ) {
-        return res.status(400).json({
-          jsonrpc: "2.0",
-          error: { code: -32000, message: "Session uses different transport" },
-          id: null,
-        });
-      }
-
-      // New session requires initialize request
-      if (!session) {
-        if (req.method !== "POST" || !isInitializeRequest(req.body)) {
-          return res.status(400).json({
-            jsonrpc: "2.0",
-            error: { code: -32000, message: "Bad request: not initialized" },
-            id: null,
-          });
-        }
-
-        // Create new server instance for this session (McpServer supports only one transport)
-        const serverInstance = createServer();
+    const server = createServer();
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+    });
 
-        const transport = new StreamableHTTPServerTransport({
-          sessionIdGenerator: () => randomUUID(),
-          onsessioninitialized: (id) => {
-            sessions.set(id, { transport, server: serverInstance });
-          },
-        });
-        transport.onclose = () => {
-          if (transport.sessionId) sessions.delete(transport.sessionId);
-        };
-        await serverInstance.connect(transport);
-        session = { transport, server: serverInstance };
-      }
+    res.on("close", () => {
+      transport.close().catch(() => {});
+      server.close().catch(() => {});
+    });
 
-      await (session.transport as StreamableHTTPServerTransport).handleRequest(
-        req,
-        res,
-        req.body,
-      );
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
     } catch (error) {
       console.error("MCP error:", error);
       if (!res.headersSent) {
@@ -119,63 +54,15 @@ export async function startServer(
     }
   });
 
-  // Legacy SSE
-  app.get("/sse", async (_req: Request, res: Response) => {
-    try {
-      // Create new server instance for this session (McpServer supports only one transport)
-      const serverInstance = createServer();
-      const transport = new SSEServerTransport("/messages", res);
-      sessions.set(transport.sessionId, { transport, server: serverInstance });
-      res.on("close", () => sessions.delete(transport.sessionId));
-      await serverInstance.connect(transport);
-    } catch (error) {
-      console.error("SSE error:", error);
-      if (!res.headersSent) res.status(500).end();
-    }
-  });
-
-  app.post("/messages", async (req: Request, res: Response) => {
-    try {
-      const session = sessions.get(req.query.sessionId as string);
-      if (!session || !(session.transport instanceof SSEServerTransport)) {
-        return res.status(404).json({
-          jsonrpc: "2.0",
-          error: { code: -32001, message: "Session not found" },
-          id: null,
-        });
-      }
-      await session.transport.handlePostMessage(req, res, req.body);
-    } catch (error) {
-      console.error("Message error:", error);
-      if (!res.headersSent) {
-        res.status(500).json({
-          jsonrpc: "2.0",
-          error: { code: -32603, message: "Internal server error" },
-          id: null,
-        });
-      }
-    }
+  const httpServer = app.listen(port, () => {
+    console.log(`${name} listening on http://localhost:${port}/mcp`);
   });
 
-  return new Promise<void>((resolve, reject) => {
-    const httpServer = app.listen(port);
+  const shutdown = () => {
+    console.log("\nShutting down...");
+    httpServer.close(() => process.exit(0));
+  };
 
-    httpServer.on("listening", () => {
-      console.log(`${name} listening on http://localhost:${port}/mcp`);
-      resolve();
-    });
-
-    httpServer.on("error", (err: Error) => {
-      reject(err);
-    });
-
-    const shutdown = () => {
-      console.log("\nShutting down...");
-      sessions.forEach((session) => session.transport.close().catch(() => {}));
-      httpServer.close(() => process.exit(0));
-    };
-
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
-  });
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
 }

examples/basic-server-react/server.ts

@@ -7,50 +7,39 @@ import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE, RESOURCE_URI_
 import { startServer } from "./server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
-const RESOURCE_URI = "ui://get-time/mcp-app.html";
 
 /**
  * Creates a new MCP server instance with tools and resources registered.
- * Each HTTP session needs its own server instance because McpServer only supports one transport.
  */
 export function createServer(): McpServer {
   const server = new McpServer({
-    name: "Basic MCP App Server (React-based)",
+    name: "Basic MCP App Server (React)",
     version: "1.0.0",
   });
 
-  // MCP Apps require two-part registration: a tool (what the LLM calls) and a
-  // resource (the UI it renders). The `_meta` field on the tool links to the
-  // resource URI, telling hosts which UI to display when the tool executes.
+  const resourceUri = "ui://get-time/mcp-app.html";
+
   registerAppTool(server,
     "get-time",
     {
       title: "Get Time",
-      description: "Returns the current server time as an ISO 8601 string.",
+      description: "Returns the current server time.",
       inputSchema: {},
-      _meta: { [RESOURCE_URI_META_KEY]: RESOURCE_URI },
+      _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
     },
     async (): Promise<CallToolResult> => {
-      const time = new Date().toISOString();
-      return {
-        content: [{ type: "text", text: JSON.stringify({ time }) }],
-      };
+      return { content: [{ type: "text", text: new Date().toISOString() }] };
     },
   );
 
   registerAppResource(server,
-    RESOURCE_URI,
-    RESOURCE_URI,
+    resourceUri,
+    resourceUri,
     { mimeType: RESOURCE_MIME_TYPE },
     async (): Promise<ReadResourceResult> => {
       const html = await fs.readFile(path.join(DIST_DIR, "mcp-app.html"), "utf-8");
-
       return {
-        contents: [
-          // Per the MCP App specification, "text/html;profile=mcp-app" signals
-          // to the Host that this resource is indeed for an MCP App UI.
-          { uri: RESOURCE_URI, mimeType: RESOURCE_MIME_TYPE, text: html },
-        ],
+        contents: [{ uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html }],
       };
     },
   );
@@ -62,8 +51,8 @@ async function main() {
   if (process.argv.includes("--stdio")) {
     await createServer().connect(new StdioServerTransport());
   } else {
-    const port = parseInt(process.env.PORT ?? "3101", 10);
-    await startServer(createServer, { port, name: "Basic MCP App Server (React-based)" });
+    const port = parseInt(process.env.PORT ?? "3001", 10);
+    await startServer(createServer, { port, name: "Basic MCP App Server (React)" });
   }
 }
 

examples/basic-server-react/src/mcp-app.tsx

@@ -20,12 +20,8 @@ const log = {
 
 
 function extractTime(callToolResult: CallToolResult): string {
-  const text = callToolResult.content!
-    .filter((c): c is { type: "text"; text: string } => c.type === "text")
-    .map((c) => c.text)
-    .join("");
-  const { time } = JSON.parse(text) as { time: string };
-  return time;
+  const { text } = callToolResult.content?.find((c) => c.type === "text")!;
+  return text;
 }
 
 
@@ -37,8 +33,6 @@ function GetTimeApp() {
     onAppCreated: (app) => {
       app.onteardown = async () => {
         log.info("App is being torn down");
-        await new Promise((resolve) => setTimeout(resolve, 500)); // Simulate cleanup work
-        log.info("App teardown complete");
         return {};
       };
       app.ontoolinput = async (input) => {
@@ -120,7 +114,7 @@ function GetTimeAppInner({ app, toolResult }: GetTimeAppInnerProps) {
 
       <div className={styles.action}>
         <p>
-          <strong>Server Time:</strong> <code>{serverTime}</code>
+          <strong>Server Time:</strong> <code id="server-time">{serverTime}</code>
         </p>
         <button onClick={handleGetTime}>Get Server Time</button>
       </div>