@ttoss/http-server-mcp 0.28.0 → 0.28.1

package/MIGRATIONS.md

@@ -1,5 +1,40 @@
 # Migrations
 
+## The `2026-07-28` revision needs `createMcpServer`
+
+That revision is served only when `createMcpRouter` is given a
+`createMcpServer` factory.
+
+```diff
++const buildServer = () => {
++  const mcpServer = new McpServer({ name: 'my-server', version: '1.0.0' });
++  registerEverything(mcpServer);
++  return mcpServer;
++};
++
+-createMcpRouter(mcpServer, {
++createMcpRouter(buildServer(), {
++  createMcpServer: buildServer,
+   auth: { ... },
+ });
+```
+
+**Why it cannot default to the server you already pass.** The negotiated
+revision is instance state: serving one `2026-07-28` request marks that
+`McpServer` modern for good, and it then validates every later message against
+that revision. One instance serving both eras is pinned by the first client to
+speak the newer one, after which every 2025-era request is answered
+`-32602 Request is missing the required _meta envelope for protocol revision
+2026-07-28` at **HTTP 200** for the life of the process — a status and body a
+client reads as "no tools" rather than as a fault. The SDK's own serving
+entries take a factory and call it once per request for this reason.
+
+**What you will observe if you miss this.** A client speaking `2026-07-28` gets
+`400` with `-32022 Unsupported protocol version` and `data.supported` listing
+the 2025-era revisions, which it can renegotiate from. Only deployments
+actually receiving that traffic are affected; every client without the
+per-request envelope is served exactly as before.
+
 ## `tools/list` is no longer public by default
 
 `auth.publicMethods` now defaults to `['initialize']` instead of

package/README.md

@@ -906,7 +906,27 @@ app.listen(3000);
 
 This package implements the [Model Context Protocol](https://spec.modelcontextprotocol.io/) over HTTP using JSON responses (no SSE streaming), and serves each request over the protocol revision it actually speaks.
 
-Requests are classified once at the boundary. Traffic from today's MCP clients is served over `NodeStreamableHTTPServerTransport` with `enableJsonResponse: true`, adapting Koa's context-based middleware to the SDK's Node.js request/response expectations. Requests carrying the `2026-07-28` revision's per-request envelope are served by that revision's stateless core (`createMcpHandler`) instead. Both paths are served from the same `McpServer` instance and the same registered tools, so supporting the newer revision requires no configuration.
+Requests are classified once at the boundary, and the classifier's answer is three-way. Traffic from today's MCP clients is served over `NodeStreamableHTTPServerTransport` with `enableJsonResponse: true`, adapting Koa's context-based middleware to the SDK's Node.js request/response expectations. Requests carrying the `2026-07-28` revision's per-request envelope are served by that revision's stateless core (`createMcpHandler`). Requests the classifier refuses outright are answered with its own rejection — the status, code, message and data it chose — rather than passed to either era's handler.
+
+### Serving the `2026-07-28` revision
+
+Set `createMcpServer` to a factory returning an `McpServer` with the same tools registered:
+
+```typescript
+const buildServer = () => {
+  const mcpServer = new McpServer({ name: 'my-server', version: '1.0.0' });
+  registerEverything(mcpServer);
+  return mcpServer;
+};
+
+const mcpRouter = createMcpRouter(buildServer(), {
+  createMcpServer: buildServer,
+});
+```
+
+It has to be a factory, and cannot default to the server the router was given, because the negotiated revision is instance state: serving one `2026-07-28` request marks that `McpServer` modern for good, and it then validates every later message against that revision. One instance serving both eras is pinned by the first client to speak the newer one, after which every 2025-era request is answered `-32602 Request is missing the required _meta envelope…` at HTTP 200 for the life of the process. The SDK's own serving entries take a factory and call it once per request for the same reason.
+
+Without `createMcpServer`, `2026-07-28` requests get the unsupported-protocol-version error listing the revisions this endpoint does serve, so that client renegotiates and no other client is affected.
 
 **Supported HTTP methods:**
 

package/dist/index.cjs

@@ -36,41 +36,88 @@ var header = (ctx, name) => {
   const value = ctx.get(name);
   return value === "" ? void 0 : value;
 };
+/** The id to echo in an error answer, by the SDK's own rule. */
+var echoableRequestId = body => {
+  if (body === null || typeof body !== "object" || Array.isArray(body)) return null;
+  const {
+    id,
+    method
+  } = body;
+  if (typeof method !== "string") return null;
+  return typeof id === "string" || typeof id === "number" ? id : null;
+};
+/**
+* Writes a JSON-RPC error straight to the Node response: `createMcpRouter` sets
+* `ctx.respond = false` after serving, so Koa never writes `ctx.body`.
+*/
+var emitJsonRpcError = (ctx, answer, body) => {
+  ctx.res.writeHead(answer.httpStatus, {
+    "content-type": "application/json"
+  });
+  ctx.res.end(JSON.stringify({
+    jsonrpc: "2.0",
+    error: {
+      code: answer.code,
+      message: answer.message,
+      ...(answer.data !== void 0 && {
+        data: answer.data
+      })
+    },
+    id: echoableRequestId(body)
+  }));
+};
+/** The SDK's own ladder rejection, emitted with the status the SDK chose. */
+var rejectionAnswer = rejection => {
+  return {
+    httpStatus: rejection.httpStatus,
+    code: rejection.code,
+    message: rejection.message,
+    ...(rejection.data !== void 0 && {
+      data: rejection.data
+    })
+  };
+};
+/**
+* The answer to `2026-07-28` traffic without `createMcpServer`. `data.supported`
+* is what lets the client renegotiate onto a revision this endpoint serves.
+*/
+var REVISION_NOT_SERVED_ANSWER = {
+  httpStatus: 400,
+  code: _modelcontextprotocol_server.ProtocolErrorCode.UnsupportedProtocolVersion,
+  message: "Unsupported protocol version: this endpoint serves the 2025-era MCP revisions only. Pass createMcpServer to createMcpRouter to serve protocol revision 2026-07-28.",
+  data: {
+    supported: [..._modelcontextprotocol_server.SUPPORTED_PROTOCOL_VERSIONS]
+  }
+};
 /**
 * Builds the per-request serving function used by `createMcpRouter`, routing
-* each request to the protocol revision it actually speaks.
-*
-* Requests are classified once at the boundary with the SDK's own
-* `classifyInboundRequest`:
-*
-* - **2025-era traffic** (everything without a `2026-07-28` per-request
-*   envelope — which is all traffic from today's MCP clients) is served over
-*   `NodeStreamableHTTPServerTransport` with `enableJsonResponse: true`, the
-*   same wiring and the same plain-JSON responses this package has always
-*   produced.
-* - **`2026-07-28` traffic** is served by `createMcpHandler` with
-*   `legacy: 'reject'`, so the modern revision is handled by the SDK's
-*   stateless core rather than the transport above. Malformed requests are
-*   routed here too, so the SDK emits its own spec-defined rejection instead of
-*   this package inventing one.
-*
-* Splitting on the classifier — instead of letting `createMcpHandler` serve
-* both eras through its built-in legacy fallback — is what keeps 2025-era
-* responses byte-compatible. That fallback constructs its transport with only
-* `sessionIdGenerator: undefined` and no way to pass `enableJsonResponse`, so
-* every response it produces is SSE-framed (`text/event-stream`) regardless of
-* the handler's `responseMode`. Owning the legacy branch keeps `application/json`.
+* each request by the SDK's three-way `classifyInboundRequest` outcome.
+*
+* **Why the modern era needs `createMcpServer` rather than the `server` above.**
+* The negotiated revision is *instance* state: the SDK marks an instance modern
+* when it serves one modern request, and it then validates every later message
+* against `2026-07-28` — there is no per-request era consult. One instance
+* serving both eras is therefore pinned by the first client to speak the newer
+* revision, after which every 2025-era request is answered `-32602 Request is
+* missing the required _meta envelope…` at HTTP 200 for the life of the
+* process. The SDK's own entries take a factory and call it per request for
+* this reason (they also `close()` the instance, which a shared one cannot
+* survive). Without the factory, `2026-07-28` traffic gets
+* {@link REVISION_NOT_SERVED_ANSWER} and no other client is affected.
+*
+* **Why not `createMcpHandler`'s built-in legacy fallback.** It constructs its
+* transport with no way to pass `enableJsonResponse`, so every response it
+* produces is SSE-framed. Owning the legacy branch keeps `application/json`.
 */
 var createMcpRequestServer = ({
+  createMcpServer,
   server,
   sessionIdGenerator
 }) => {
   const isStateful = sessionIdGenerator !== void 0;
-  const modernHandler = (0, _modelcontextprotocol_node.toNodeHandler)((0, _modelcontextprotocol_server.createMcpHandler)(() => {
-    return server;
-  }, {
+  const modernHandler = createMcpServer ? (0, _modelcontextprotocol_node.toNodeHandler)((0, _modelcontextprotocol_server.createMcpHandler)(createMcpServer, {
     legacy: "reject"
-  }));
+  })) : void 0;
   let sharedTransport;
   if (isStateful) {
     sharedTransport = new _modelcontextprotocol_node.NodeStreamableHTTPServerTransport({
@@ -87,17 +134,23 @@ var createMcpRequestServer = ({
     statelessQueue = result.catch(() => {});
     return result;
   };
-  const isLegacy = (ctx, body) => {
-    return (0, _modelcontextprotocol_server.classifyInboundRequest)({
+  return async (ctx, body) => {
+    const outcome = (0, _modelcontextprotocol_server.classifyInboundRequest)({
       httpMethod: ctx.method,
       protocolVersionHeader: header(ctx, "mcp-protocol-version"),
       mcpMethodHeader: header(ctx, "mcp-method"),
       mcpNameHeader: header(ctx, "mcp-name"),
       body
-    }).kind === "legacy";
-  };
-  return async (ctx, body) => {
-    if (!isLegacy(ctx, body)) {
+    });
+    if (outcome.kind === "reject") {
+      emitJsonRpcError(ctx, rejectionAnswer(outcome), body);
+      return;
+    }
+    if (outcome.kind === "modern") {
+      if (modernHandler === void 0) {
+        emitJsonRpcError(ctx, REVISION_NOT_SERVED_ANSWER, body);
+        return;
+      }
       await modernHandler(ctx.req, ctx.res, body);
       return;
     }
@@ -692,6 +745,7 @@ var createMcpRouter = (server, options = {}) => {
     path = "/mcp",
     aliases = [],
     sessionIdGenerator,
+    createMcpServer,
     apiBaseUrl,
     getApiHeaders,
     auth
@@ -699,7 +753,8 @@ var createMcpRouter = (server, options = {}) => {
   const needsContext = apiBaseUrl !== void 0 || getApiHeaders !== void 0 || auth !== void 0;
   const serveRequest = createMcpRequestServer({
     server,
-    sessionIdGenerator
+    sessionIdGenerator,
+    createMcpServer
   });
   const router = new _ttoss_http_server.Router();
   let authCheck;

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 
 /// <reference types="node" />
-import { CallToolResult, McpServer, McpServer as McpServer$1, RegisteredResource } from "@modelcontextprotocol/server";
+import { CallToolResult, McpServer, McpServer as McpServer$1, McpServerFactory, RegisteredResource } from "@modelcontextprotocol/server";
 import { Router } from "@ttoss/http-server";
 import accepts from "accepts";
 import { AsyncLocalStorage } from "async_hooks";
@@ -1310,6 +1310,31 @@ interface McpRouterOptions {
    * served statelessly regardless of this option.
    */
   sessionIdGenerator?: () => string;
+  /**
+   * Per-request factory for the `McpServer` serving one `2026-07-28` request.
+   * Set it to serve that revision; without it, requests carrying its
+   * per-request envelope get the unsupported-protocol-version error naming the
+   * 2025-era revisions this endpoint does serve. Register the same tools here
+   * as on `server`, so the two eras cannot drift apart.
+   *
+   * It cannot default to `server`: the negotiated revision is instance state,
+   * so one instance serving both eras is pinned to `2026-07-28` by the first
+   * client to speak it, and every 2025-era request after that is answered
+   * `-32602 … missing the required _meta envelope` at HTTP 200. The SDK's own
+   * serving entries take a factory and call it once per request.
+   *
+   * @example
+   * ```typescript
+   * const buildServer = () => {
+   *   const mcpServer = new McpServer({ name: 'my-server', version: '1.0.0' });
+   *   registerEverything(mcpServer);
+   *   return mcpServer;
+   * };
+   *
+   * createMcpRouter(buildServer(), { createMcpServer: buildServer });
+   * ```
+   */
+  createMcpServer?: McpServerFactory;
   /**
    * Base URL prepended to relative paths passed to `apiCall` (paths starting
    * with `/`). Tool handlers can then call `apiCall('GET', '/resource')` without

package/dist/index.d.mts

@@ -2,7 +2,7 @@
 /// <reference types="node" />
 import { Router } from "@ttoss/http-server";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { CallToolResult, McpServer, McpServer as McpServer$1, RegisteredResource } from "@modelcontextprotocol/server";
+import { CallToolResult, McpServer, McpServer as McpServer$1, McpServerFactory, RegisteredResource } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import accepts from "accepts";
 import { AsyncLocalStorage as AsyncLocalStorage$1 } from "async_hooks";
@@ -1311,6 +1311,31 @@ interface McpRouterOptions {
    * served statelessly regardless of this option.
    */
   sessionIdGenerator?: () => string;
+  /**
+   * Per-request factory for the `McpServer` serving one `2026-07-28` request.
+   * Set it to serve that revision; without it, requests carrying its
+   * per-request envelope get the unsupported-protocol-version error naming the
+   * 2025-era revisions this endpoint does serve. Register the same tools here
+   * as on `server`, so the two eras cannot drift apart.
+   *
+   * It cannot default to `server`: the negotiated revision is instance state,
+   * so one instance serving both eras is pinned to `2026-07-28` by the first
+   * client to speak it, and every 2025-era request after that is answered
+   * `-32602 … missing the required _meta envelope` at HTTP 200. The SDK's own
+   * serving entries take a factory and call it once per request.
+   *
+   * @example
+   * ```typescript
+   * const buildServer = () => {
+   *   const mcpServer = new McpServer({ name: 'my-server', version: '1.0.0' });
+   *   registerEverything(mcpServer);
+   *   return mcpServer;
+   * };
+   *
+   * createMcpRouter(buildServer(), { createMcpServer: buildServer });
+   * ```
+   */
+  createMcpServer?: McpServerFactory;
   /**
    * Base URL prepended to relative paths passed to `apiCall` (paths starting
    * with `/`). Tool handlers can then call `apiCall('GET', '/resource')` without

package/dist/index.mjs

@@ -5,7 +5,7 @@ import { Router } from "@ttoss/http-server";
 import { authMiddleware } from "@ttoss/http-server-auth";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { NodeStreamableHTTPServerTransport, toNodeHandler } from "@modelcontextprotocol/node";
-import { McpServer, classifyInboundRequest, createMcpHandler, fromJsonSchema } from "@modelcontextprotocol/server";
+import { McpServer, ProtocolErrorCode, SUPPORTED_PROTOCOL_VERSIONS, classifyInboundRequest, createMcpHandler, fromJsonSchema } from "@modelcontextprotocol/server";
 import { z } from "zod";
 
 //#region src/context.ts
@@ -33,41 +33,88 @@ var header = (ctx, name) => {
   const value = ctx.get(name);
   return value === "" ? void 0 : value;
 };
+/** The id to echo in an error answer, by the SDK's own rule. */
+var echoableRequestId = body => {
+  if (body === null || typeof body !== "object" || Array.isArray(body)) return null;
+  const {
+    id,
+    method
+  } = body;
+  if (typeof method !== "string") return null;
+  return typeof id === "string" || typeof id === "number" ? id : null;
+};
+/**
+* Writes a JSON-RPC error straight to the Node response: `createMcpRouter` sets
+* `ctx.respond = false` after serving, so Koa never writes `ctx.body`.
+*/
+var emitJsonRpcError = (ctx, answer, body) => {
+  ctx.res.writeHead(answer.httpStatus, {
+    "content-type": "application/json"
+  });
+  ctx.res.end(JSON.stringify({
+    jsonrpc: "2.0",
+    error: {
+      code: answer.code,
+      message: answer.message,
+      ...(answer.data !== void 0 && {
+        data: answer.data
+      })
+    },
+    id: echoableRequestId(body)
+  }));
+};
+/** The SDK's own ladder rejection, emitted with the status the SDK chose. */
+var rejectionAnswer = rejection => {
+  return {
+    httpStatus: rejection.httpStatus,
+    code: rejection.code,
+    message: rejection.message,
+    ...(rejection.data !== void 0 && {
+      data: rejection.data
+    })
+  };
+};
+/**
+* The answer to `2026-07-28` traffic without `createMcpServer`. `data.supported`
+* is what lets the client renegotiate onto a revision this endpoint serves.
+*/
+var REVISION_NOT_SERVED_ANSWER = {
+  httpStatus: 400,
+  code: ProtocolErrorCode.UnsupportedProtocolVersion,
+  message: "Unsupported protocol version: this endpoint serves the 2025-era MCP revisions only. Pass createMcpServer to createMcpRouter to serve protocol revision 2026-07-28.",
+  data: {
+    supported: [...SUPPORTED_PROTOCOL_VERSIONS]
+  }
+};
 /**
 * Builds the per-request serving function used by `createMcpRouter`, routing
-* each request to the protocol revision it actually speaks.
-*
-* Requests are classified once at the boundary with the SDK's own
-* `classifyInboundRequest`:
-*
-* - **2025-era traffic** (everything without a `2026-07-28` per-request
-*   envelope — which is all traffic from today's MCP clients) is served over
-*   `NodeStreamableHTTPServerTransport` with `enableJsonResponse: true`, the
-*   same wiring and the same plain-JSON responses this package has always
-*   produced.
-* - **`2026-07-28` traffic** is served by `createMcpHandler` with
-*   `legacy: 'reject'`, so the modern revision is handled by the SDK's
-*   stateless core rather than the transport above. Malformed requests are
-*   routed here too, so the SDK emits its own spec-defined rejection instead of
-*   this package inventing one.
-*
-* Splitting on the classifier — instead of letting `createMcpHandler` serve
-* both eras through its built-in legacy fallback — is what keeps 2025-era
-* responses byte-compatible. That fallback constructs its transport with only
-* `sessionIdGenerator: undefined` and no way to pass `enableJsonResponse`, so
-* every response it produces is SSE-framed (`text/event-stream`) regardless of
-* the handler's `responseMode`. Owning the legacy branch keeps `application/json`.
+* each request by the SDK's three-way `classifyInboundRequest` outcome.
+*
+* **Why the modern era needs `createMcpServer` rather than the `server` above.**
+* The negotiated revision is *instance* state: the SDK marks an instance modern
+* when it serves one modern request, and it then validates every later message
+* against `2026-07-28` — there is no per-request era consult. One instance
+* serving both eras is therefore pinned by the first client to speak the newer
+* revision, after which every 2025-era request is answered `-32602 Request is
+* missing the required _meta envelope…` at HTTP 200 for the life of the
+* process. The SDK's own entries take a factory and call it per request for
+* this reason (they also `close()` the instance, which a shared one cannot
+* survive). Without the factory, `2026-07-28` traffic gets
+* {@link REVISION_NOT_SERVED_ANSWER} and no other client is affected.
+*
+* **Why not `createMcpHandler`'s built-in legacy fallback.** It constructs its
+* transport with no way to pass `enableJsonResponse`, so every response it
+* produces is SSE-framed. Owning the legacy branch keeps `application/json`.
 */
 var createMcpRequestServer = ({
+  createMcpServer,
   server,
   sessionIdGenerator
 }) => {
   const isStateful = sessionIdGenerator !== void 0;
-  const modernHandler = toNodeHandler(createMcpHandler(() => {
-    return server;
-  }, {
+  const modernHandler = createMcpServer ? toNodeHandler(createMcpHandler(createMcpServer, {
     legacy: "reject"
-  }));
+  })) : void 0;
   let sharedTransport;
   if (isStateful) {
     sharedTransport = new NodeStreamableHTTPServerTransport({
@@ -84,17 +131,23 @@ var createMcpRequestServer = ({
     statelessQueue = result.catch(() => {});
     return result;
   };
-  const isLegacy = (ctx, body) => {
-    return classifyInboundRequest({
+  return async (ctx, body) => {
+    const outcome = classifyInboundRequest({
       httpMethod: ctx.method,
       protocolVersionHeader: header(ctx, "mcp-protocol-version"),
       mcpMethodHeader: header(ctx, "mcp-method"),
       mcpNameHeader: header(ctx, "mcp-name"),
       body
-    }).kind === "legacy";
-  };
-  return async (ctx, body) => {
-    if (!isLegacy(ctx, body)) {
+    });
+    if (outcome.kind === "reject") {
+      emitJsonRpcError(ctx, rejectionAnswer(outcome), body);
+      return;
+    }
+    if (outcome.kind === "modern") {
+      if (modernHandler === void 0) {
+        emitJsonRpcError(ctx, REVISION_NOT_SERVED_ANSWER, body);
+        return;
+      }
       await modernHandler(ctx.req, ctx.res, body);
       return;
     }
@@ -689,6 +742,7 @@ var createMcpRouter = (server, options = {}) => {
     path = "/mcp",
     aliases = [],
     sessionIdGenerator,
+    createMcpServer,
     apiBaseUrl,
     getApiHeaders,
     auth
@@ -696,7 +750,8 @@ var createMcpRouter = (server, options = {}) => {
   const needsContext = apiBaseUrl !== void 0 || getApiHeaders !== void 0 || auth !== void 0;
   const serveRequest = createMcpRequestServer({
     server,
-    sessionIdGenerator
+    sessionIdGenerator,
+    createMcpServer
   });
   const router = new Router();
   let authCheck;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",