Clean up examples (#182)

* Centralize example server transport logic in shared utils

Move stdio/HTTP transport handling into `server-utils.ts` so example
servers only need to call `startServer(createServer)`. Switch HTTP
transport to stateless mode and remove legacy SSE endpoints.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Make example servers self-contained with local server-utils

Copy `server-utils.ts` into each example's `src/` directory so examples
can be used standalone without the shared directory. Updates imports
from `"../shared/server-utils.js"` to `"./src/server-utils.js"`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Add `integration-server` example for E2E testing

Add dedicated `integration-server` example (duplicated from
`basic-server-react`) to preserve E2E testing capabilities while
allowing `basic-server-react` to be simplified as a minimal example.

Changes:
- Add `examples/integration-server` exercising SDK communication APIs
- Update E2E tests to use `integration-server` instead of
  `basic-server-react` and `basic-server-vanillajs`
- Use server name labels instead of indices for more robust test
  selection
- Remove `basic-react.png` and `basic-vanillajs.png` golden snapshots

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Simplify `basic-server-*` examples

- Clarify comments
- Return plain text from `get-time` tool instead of JSON
- Remove simulated cleanup delay from `onteardown`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

examples/basic-server-react/server.ts

@@ -1,55 +1,52 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "@modelcontextprotocol/ext-apps/server";
-import { startServer } from "../shared/server-utils.js";
+import { startServer } from "./src/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.
  */
 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.
+  // Two-part registration: tool + resource, tied together by the resource URI.
+  const resourceUri = "ui://get-time/mcp-app.html";
+
+  // Register a tool with UI metadata. When the host calls this tool, it reads
+  // `_meta[RESOURCE_URI_META_KEY]` to know which resource to fetch and render
+  // as an interactive UI.
   registerAppTool(server,
     "get-time",
     {
       title: "Get Time",
       description: "Returns the current server time as an ISO 8601 string.",
       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: time }] };
     },
   );
 
+  // Register the resource, which returns the bundled HTML/JavaScript for the UI.
   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 },
+          { uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html },
         ],
       };
     },
@@ -58,16 +55,4 @@ function createServer(): McpServer {
   return server;
 }
 
-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)" });
-  }
-}
-
-main().catch((e) => {
-  console.error(e);
-  process.exit(1);
-});
+startServer(createServer);

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>

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

@@ -0,0 +1,110 @@
+/**
+ * Shared utilities for running MCP servers with various transports.
+ */
+
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import cors from "cors";
+import type { Request, Response } from "express";
+
+/**
+ * Starts an MCP server using the appropriate transport based on command-line arguments.
+ *
+ * If `--stdio` is passed, uses stdio transport. Otherwise, uses Streamable HTTP transport.
+ *
+ * @param createServer - Factory function that creates a new McpServer instance.
+ */
+export async function startServer(
+  createServer: () => McpServer,
+): Promise<void> {
+  try {
+    if (process.argv.includes("--stdio")) {
+      await startStdioServer(createServer);
+    } else {
+      await startStreamableHttpServer(createServer);
+    }
+  } catch (e) {
+    console.error(e);
+    process.exit(1);
+  }
+}
+
+/**
+ * Starts an MCP server with stdio transport.
+ *
+ * @param createServer - Factory function that creates a new McpServer instance.
+ */
+export async function startStdioServer(
+  createServer: () => McpServer,
+): Promise<void> {
+  await createServer().connect(new StdioServerTransport());
+}
+
+/**
+ * Starts an MCP server with Streamable HTTP transport in stateless mode.
+ *
+ * Each request creates a fresh server and transport instance, which are
+ * closed when the response ends (no session tracking).
+ *
+ * The server listens on the port specified by the PORT environment variable,
+ * defaulting to 3001 if not set.
+ *
+ * @param createServer - Factory function that creates a new McpServer instance per request.
+ */
+export async function startStreamableHttpServer(
+  createServer: () => McpServer,
+): Promise<void> {
+  const port = parseInt(process.env.PORT ?? "3001", 10);
+
+  // Express app - bind to all interfaces for development/testing
+  const expressApp = createMcpExpressApp({ host: "0.0.0.0" });
+  expressApp.use(cors());
+
+  expressApp.all("/mcp", async (req: Request, res: Response) => {
+    // Create fresh server and transport for each request (stateless mode)
+    const server = createServer();
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+    });
+
+    // Clean up when response ends
+    res.on("close", () => {
+      transport.close().catch(() => {});
+      server.close().catch(() => {});
+    });
+
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+    } catch (error) {
+      console.error("MCP error:", error);
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: "2.0",
+          error: { code: -32603, message: "Internal server error" },
+          id: null,
+        });
+      }
+    }
+  });
+
+  const { promise, resolve, reject } = Promise.withResolvers<void>();
+
+  const httpServer = expressApp.listen(port, (err?: Error) => {
+    if (err) return reject(err);
+    console.log(`Server listening on http://localhost:${port}/mcp`);
+    resolve();
+  });
+
+  const shutdown = () => {
+    console.log("\nShutting down...");
+    httpServer.close(() => process.exit(0));
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  return promise;
+}