@mcp-layer/test-server 1.0.1 → 1.0.3

package/README.md

@@ -49,7 +49,10 @@ npx mcp-test-server-http --port 3333
 
 This exposes:
 - Streamable HTTP on `/mcp`
-- SSE compatibility on `/sse` and `/sse/messages`
+- SSE compatibility on `/sse` (GET stream + POST messages with `?sessionId=...`)
+
+SSE is kept for legacy MCP clients. Streamable HTTP clients should use only `/mcp`.
+The HTTP fixture issues Streamable HTTP session IDs so a single transport can safely handle multiple requests with the current MCP SDK.
 
 ## What it provides
 
@@ -129,6 +132,22 @@ const client = new Client({ name: 'demo', version: '0.0.0' });
 await client.connect(transport);
 ```
 
+Use this programmatic helper when you need a mounted localhost HTTP endpoint in tests:
+
+```js
+import { startHttpServer } from '@mcp-layer/test-server/http';
+
+const server = await startHttpServer({ port: 0 });
+const url = `http://127.0.0.1:${server.port}`;
+
+// streamable HTTP endpoint
+const mcp = `${url}/mcp`;
+// legacy SSE endpoint
+const sse = `${url}/sse`;
+
+await server.close();
+```
+
 ## Testing
 
 ```bash
@@ -262,6 +281,28 @@ await assert.rejects(pending);
 
 </details>
 
+<a id="error-141392"></a>
+### Invalid --port value "{value}".
+
+Thrown from: `port`
+
+This happens when `mcp-test-server-http` is started with a non-integer or out-of-range `--port` argument. The HTTP fixture only accepts numeric TCP ports in the `0-65535` range.
+
+Step-by-step resolution:
+1. Pass `--port` as a base-10 integer (`--port 3333`).
+2. Avoid host:port strings (`127.0.0.1:3333`) and non-numeric values.
+3. If you use environment variables, ensure the value is present and parseable.
+4. In tests, reserve an ephemeral port first and pass that numeric value.
+
+<details>
+<summary>Fix Example: start HTTP fixture with a valid port</summary>
+
+```bash
+npx mcp-test-server-http --port 3333
+```
+
+</details>
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-layer/test-server",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Feature-rich MCP server for integration testing and local development.",
   "repository": {
     "type": "git",
@@ -24,6 +24,10 @@
       "import": "./src/index.js",
       "default": "./src/index.js"
     },
+    "./http": {
+      "import": "./src/transport/http.js",
+      "default": "./src/transport/http.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -35,6 +39,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.20.2",
+    "argh": "^1.0.0",
     "express": "^5.0.1",
     "zod": "^3.25.76",
     "@mcp-layer/error": "0.2.0"

package/src/http.js

@@ -1,6 +1,46 @@
 import { startHttpServer } from './transport/http.js';
+import { LayerError } from '@mcp-layer/error';
+import argh from 'argh';
 
-startHttpServer().catch(error => {
+/**
+ * Parse CLI arguments for the HTTP test-server binary.
+ * @returns {{ port?: unknown }}
+ */
+function args() {
+  return argh(process.argv.slice(2));
+}
+
+/**
+ * Parse the optional CLI port value.
+ * @param {{ port?: unknown }} parsed - Parsed CLI argument map.
+ * @returns {number | undefined}
+ */
+function port(parsed) {
+  const value = parsed.port;
+  if (value === undefined) return undefined;
+
+  const number = typeof value === 'number' ? value : Number(value);
+  if (!Number.isInteger(number) || number < 0 || number > 65535) {
+    throw new LayerError({
+      name: 'test-server',
+      method: 'port',
+      message: 'Invalid --port value "{value}".',
+      vars: { value }
+    });
+  }
+
+  return number;
+}
+
+/**
+ * Start the HTTP test server process.
+ * @returns {Promise<void>}
+ */
+async function main() {
+  await startHttpServer({ port: port(args()) });
+}
+
+main().catch(function handle(error) {
   console.error(error);
   process.exitCode = 1;
 });

package/src/transport/http.js

@@ -1,75 +1,134 @@
 import express from 'express';
+import { randomUUID } from 'node:crypto';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { build } from '../index.js';
 
+/**
+ * Extract a single header/query string value.
+ * @param {unknown} value - Raw input value.
+ * @returns {string | undefined}
+ */
+function one(value) {
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value) && typeof value[0] === 'string') return value[0];
+  return undefined;
+}
+
+/**
+ * Generate session ids for streamable HTTP sessions.
+ * @returns {string}
+ */
+function sessionid() {
+  return randomUUID();
+}
+
+/**
+ * Close one tracked SSE session.
+ * @param {Record<string, { transport: { close: () => Promise<void> }, server: { close: () => Promise<void> } }>} sessions - Session map.
+ * @param {string} id - Session id to close.
+ * @returns {Promise<void>}
+ */
+async function closesession(sessions, id) {
+  const session = sessions[id];
+  if (!session) return;
+  delete sessions[id];
+  try {
+    await session.transport.close();
+  } finally {
+    await session.server.close();
+  }
+}
+
+/**
+ * Close and remove every open session in a map.
+ * @param {Record<string, { transport: { close: () => Promise<void> }, server: { close: () => Promise<void> } }>} sessions - Session map to drain.
+ * @returns {Promise<void>}
+ */
+async function drain(sessions) {
+  for (const id of Object.keys(sessions))
+    await closesession(sessions, id);
+}
+
 /**
  * Start an HTTP server that exposes Streamable HTTP and SSE transports.
  * @param {{ port?: number }} [opts] - Optional port override for the HTTP server.
- * @returns {Promise<{ close: () => Promise<void> }>}
+ * @returns {Promise<{ port: number, close: () => Promise<void> }>}
  */
 export async function startHttpServer(opts = {}) {
   const port = opts.port ?? Number(process.env.PORT ?? 3000);
   const app = express();
   app.use(express.json({ limit: '1mb' }));
 
-  /** @type {Record<string, { transport: StreamableHTTPServerTransport, server: import('@modelcontextprotocol/sdk/server/mcp.js').McpServer }>} */
-  const httpSessions = {};
+  const streamServer = build();
+  const streamTransport = new StreamableHTTPServerTransport({
+    // SDK 1.26+ requires a transport per request in stateless mode; use sessions instead.
+    sessionIdGenerator: sessionid,
+    enableJsonResponse: true
+  });
+  await streamServer.connect(streamTransport);
+
   /** @type {Record<string, { transport: SSEServerTransport, server: import('@modelcontextprotocol/sdk/server/mcp.js').McpServer }>} */
   const sseSessions = {};
 
-  function newSession() {
-    const transport = new StreamableHTTPServerTransport({
-      enableJsonResponse: true
-    });
-    const server = build();
-    return { transport, server };
-  }
-
-  app.post('/mcp', async (req, res) => {
-    const sessionId = req.headers['mcp-session-id'];
-    let session = sessionId ? httpSessions[sessionId] : undefined;
-
-    if (!session) {
-      session = newSession();
-      httpSessions[session.transport.sessionId] = session;
-      res.setHeader('Mcp-Session-Id', session.transport.sessionId);
-      res.on('close', () => {
-        void session.transport.close();
-        delete httpSessions[session.transport.sessionId];
-      });
-      await session.server.connect(session.transport);
-    }
-
-    await session.transport.handleRequest(req, res, req.body);
-  });
-
-  app.get('/sse', async (req, res) => {
-    const transport = new SSEServerTransport('/sse/messages', res);
+  /**
+   * Handle legacy SSE session bootstrap.
+   * @param {import('express').Request} req - Express request.
+   * @param {import('express').Response} res - Express response.
+   * @returns {Promise<void>}
+   */
+  async function sse(req, res) {
+    // The SDK emits this endpoint back to the client; we keep GET+POST on one path to reduce routing surface.
+    const transport = new SSEServerTransport('/sse', res);
     const server = build();
     sseSessions[transport.sessionId] = { transport, server };
-    res.on('close', () => {
-      void transport.close();
-      delete sseSessions[transport.sessionId];
+    res.on('close', function onclose() {
+      void closesession(sseSessions, transport.sessionId);
     });
     await server.connect(transport);
-  });
+  }
 
-  app.post('/sse/messages', async (req, res) => {
-    const sessionId = req.query.sessionId;
-    const session = typeof sessionId === 'string' ? sseSessions[sessionId] : undefined;
+  /**
+   * Handle legacy SSE postback messages.
+   * @param {import('express').Request} req - Express request.
+   * @param {import('express').Response} res - Express response.
+   * @returns {Promise<void>}
+   */
+  async function ssemessage(req, res) {
+    const sessionId = one(req.query.sessionId);
+    const session = sessionId ? sseSessions[sessionId] : undefined;
     if (!session) {
       res.status(400).send('No SSE session found');
       return;
     }
+
     await session.transport.handlePostMessage(req, res, req.body);
+  }
+
+  app.all('/mcp', function mcpHandler(req, res, next) {
+    void streamTransport.handleRequest(req, res, req.body).catch(next);
+  });
+
+  app.get('/sse', function sseHandler(req, res, next) {
+    void sse(req, res).catch(next);
+  });
+  app.post('/sse', function sseMessageHandler(req, res, next) {
+    void ssemessage(req, res).catch(next);
   });
 
-  return new Promise(resolve => {
-    const listener = app.listen(port, () => {
+  return new Promise(function start(resolve) {
+    const listener = app.listen(port, function listen() {
+      const address = listener.address();
+      const activePort = address && typeof address !== 'string' ? address.port : port;
       resolve({
+        port: activePort,
         async close() {
-          await new Promise(r => listener.close(r));
+          await streamTransport.close();
+          await streamServer.close();
+          await drain(sseSessions);
+          await new Promise(function stop(done) {
+            listener.close(done);
+          });
         }
       });
     });