@ttoss/http-server-mcp 0.39.1 → 0.41.0

package/README.md

@@ -676,6 +676,7 @@ Creates a Koa router configured to handle MCP protocol requests.
   - `createMcpServer` (`McpServerFactory`) — Per-request factory serving the `2026-07-28` revision; see [Serving the `2026-07-28` revision](#serving-the-2026-07-28-revision)
   - `bus` (`ServerEventBus`) — Change-event bus `subscriptions/listen` streams subscribe to (default: in-process); see [Change notifications and shutdown](#change-notifications-and-shutdown)
   - `keepAliveMs` (`number`) — SSE keepalive interval for `2026-07-28` streams (default: `15000`)
+  - `streaming` (`boolean`) — `false` on a host that buffers the response (AWS Lambda behind API Gateway): no change notifications are advertised, so `subscriptions/listen` completes at once (default: `true`); see [Hosting without streaming](#hosting-without-streaming-aws-lambda)
   - `apiBaseUrl` (`string`) — Base URL prepended to relative paths in `apiCall`
   - `getApiHeaders` (`(ctx: Context) => Record<string, string>`) — Return headers to inject into every `apiCall` for this request
   - `auth` (`McpAuthOptions`) — OAuth/JWT authentication; see [Authentication](#authentication)
@@ -781,6 +782,8 @@ Registers `Tool`s on an MCP server. See [Tools](#tools).
 
 By default, a JSON Schema `inputSchema` is **advertised but not enforced**: it round-trips verbatim over `tools/list` so clients know what to send, while arguments reach your handler unchecked. Set `validateArguments: true` to reject mismatched calls before the handler runs.
 
+A schema with `additionalProperties: false` refuses every argument it does not declare, and names each one (`prefix: is not an argument of this tool`), so a misspelled argument is an error the caller can fix rather than one dropped unseen.
+
 Enable it once you're confident `inputSchema` describes every value the tool genuinely accepts. Schemas derived from an OpenAPI document are a common source of _incomplete_ ones — a field a client may send as `null` to clear it, or one that accepts several shapes, is easily emitted as a bare `{ type: 'string' }`. Validating against a schema like that rejects calls the underlying API would have accepted. To describe those cases accurately, use `{ type: ['string', 'null'] }` for a nullable field and forward `oneOf`/`anyOf` verbatim rather than collapsing to one type.
 
 ### `defineTool(params)`
@@ -1050,6 +1053,19 @@ process.on('SIGTERM', async () => {
 
 The default bus is in-process, so `notify` reaches the streams this process holds. Behind several replicas, pass a `bus` implementing `ServerEventBus` over a shared pub/sub. Keep `keepAliveMs` below the idle timeout of anything in front of the server, or a quiet stream is cut there. 2025-era traffic is served statelessly, so it holds no stream to notify.
 
+### Hosting without streaming (AWS Lambda)
+
+A host that buffers the whole response — AWS Lambda behind API Gateway, or any runtime without response streaming — never delivers a stream that stays open: the invocation dies at its timeout, and the client reopens the stream at once. Pass `streaming: false` there:
+
+```typescript
+const mcpRouter = createMcpRouter(buildServer(), {
+  createMcpServer: buildServer,
+  streaming: false,
+});
+```
+
+The router then stops every server instance it serves from advertising change notifications: `listChanged` for tools, prompts and resources, and `resources.subscribe`. `McpServer` turns them on by default for each kind you register, which is what makes the SDK hold a `subscriptions/listen` open; with nothing advertised, a listen is acknowledged and completed in the same response. A kind you register nothing for stays unadvertised. Nothing is lost on such a host: no process outlives the request to send a notification, so `notify` and `close()` reach no client.
+
 **Supported HTTP methods:**
 
 - `POST /mcp` - Send JSON-RPC requests/notifications

package/dist/index.cjs

@@ -55,6 +55,49 @@ var NO_NOTIFIER = {
   resourceUpdated: () => {}
 };
 /**
+* Stops the server advertising change notifications for the tools, prompts
+* and resources it serves, keeping every other capability as registered.
+*
+* `McpServer` advertises `listChanged: true` for each kind the moment one is
+* registered, and the SDK then honours a `2026-07-28` `subscriptions/listen`
+* with an SSE stream it never ends. A host that buffers the response until the
+* handler returns — AWS Lambda behind API Gateway — delivers nothing and kills
+* the invocation at its timeout, and the client reopens the stream at once, so
+* each open session keeps one invocation busy for good (measured on a
+* production Lambda in 2026-10: one 30 s timeout per session every ~30 s).
+* With nothing advertised the SDK acknowledges the
+* listen and completes it in the same response. A kind with nothing
+* registered stays unadvertised, since advertising it would answer its `list`
+* call with "method not found".
+*/
+var withoutChangeNotifications = product => {
+  const server = product instanceof _modelcontextprotocol_server.McpServer ? product.server : product;
+  const {
+    tools,
+    prompts,
+    resources
+  } = server.getCapabilities();
+  const off = {};
+  if (tools) off.tools = {
+    listChanged: false
+  };
+  if (prompts) off.prompts = {
+    listChanged: false
+  };
+  if (resources) off.resources = {
+    listChanged: false,
+    subscribe: false
+  };
+  server.registerCapabilities(off);
+  return product;
+};
+/** `factory`, with each instance it builds passed through {@link withoutChangeNotifications}. */
+var servingNoChangeNotifications = factory => {
+  return factory && (async ctx => {
+    return withoutChangeNotifications(await factory(ctx));
+  });
+};
+/**
 * Reads a header as `string | undefined`. Koa's `ctx.get` returns `''` for a
 * missing header, which the classifier would read as "header present but
 * empty" rather than absent.
@@ -141,10 +184,13 @@ var createMcpRequestServer = ({
   server,
   sessionIdGenerator,
   bus,
-  keepAliveMs
+  keepAliveMs,
+  streaming = true
 }) => {
   const isStateful = sessionIdGenerator !== void 0;
-  const modern = createMcpServer ? (0, _modelcontextprotocol_server.createMcpHandler)(createMcpServer, {
+  if (!streaming) withoutChangeNotifications(server);
+  const factory = streaming ? createMcpServer : servingNoChangeNotifications(createMcpServer);
+  const modern = factory ? (0, _modelcontextprotocol_server.createMcpHandler)(factory, {
     legacy: "reject",
     bus,
     keepAliveMs
@@ -520,6 +566,50 @@ var isStandardSchema = schema => {
   return "~standard" in schema;
 };
 /**
+* Enforces a closed schema while naming each undeclared argument. The SDK's
+* own `additionalProperties: false` issue carries no path, so the argument to
+* drop goes unnamed; the rest of the schema is checked with it left open.
+*/
+var namingUndeclared = ({
+  schema,
+  standard
+}) => {
+  const {
+    additionalProperties: _closed,
+    ...openSchema
+  } = schema;
+  const open = (0, _modelcontextprotocol_server.fromJsonSchema)(openSchema);
+  const declared = new Set(Object.keys(schema.properties ?? {}));
+  const withUndeclared = ({
+    value,
+    result
+  }) => {
+    const undeclared = Object.keys(Object(value)).filter(key => {
+      return !declared.has(key);
+    });
+    if (undeclared.length === 0) return result;
+    return {
+      issues: [...undeclared.map(key => {
+        return {
+          message: "is not an argument of this tool",
+          path: [key]
+        };
+      }), ...(result.issues ?? [])]
+    };
+  };
+  return {
+    "~standard": {
+      ...standard["~standard"],
+      validate: async value => {
+        return withUndeclared({
+          value,
+          result: await open["~standard"].validate(value)
+        });
+      }
+    }
+  };
+};
+/**
 * Converts a JSON Schema into the Standard Schema `registerTool` accepts.
 *
 * A Standard Schema keeps advertisement and enforcement in separate fields:
@@ -532,6 +622,10 @@ var fromJsonObjectSchema = ({
   validate
 }) => {
   const standard = (0, _modelcontextprotocol_server.fromJsonSchema)(schema);
+  if (validate && schema.additionalProperties === false) return namingUndeclared({
+    schema,
+    standard
+  });
   if (validate) return standard;
   return {
     "~standard": {
@@ -1596,6 +1690,7 @@ var createMcpRouter = (server, options = {}) => {
     createMcpServer,
     bus,
     keepAliveMs,
+    streaming,
     apiBaseUrl,
     getApiHeaders,
     auth
@@ -1606,7 +1701,8 @@ var createMcpRouter = (server, options = {}) => {
     sessionIdGenerator,
     createMcpServer,
     bus,
-    keepAliveMs
+    keepAliveMs,
+    streaming
   });
   const router = new _ttoss_http_server.Router();
   let authCheck;

package/dist/index.d.cts

@@ -1707,6 +1707,18 @@ export interface McpRouterOptions {
    * @default 15000
    */
   keepAliveMs?: number;
+  /**
+   * Whether the host delivers a response while the handler is still writing
+   * it. Set `false` on a host that buffers the whole response — AWS Lambda
+   * behind API Gateway, or any serverless runtime without response streaming.
+   * The router then stops every instance it serves from advertising change
+   * notifications (`listChanged` for tools, prompts and resources, and
+   * `resources.subscribe`), so a `2026-07-28` `subscriptions/listen` is
+   * acknowledged and completed at once instead of being held until the
+   * platform's timeout. `notify` then reaches no client.
+   * @default true
+   */
+  streaming?: boolean;
   /**
    * 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

@@ -1708,6 +1708,18 @@ export interface McpRouterOptions {
    * @default 15000
    */
   keepAliveMs?: number;
+  /**
+   * Whether the host delivers a response while the handler is still writing
+   * it. Set `false` on a host that buffers the whole response — AWS Lambda
+   * behind API Gateway, or any serverless runtime without response streaming.
+   * The router then stops every instance it serves from advertising change
+   * notifications (`listChanged` for tools, prompts and resources, and
+   * `resources.subscribe`), so a `2026-07-28` `subscriptions/listen` is
+   * acknowledged and completed at once instead of being held until the
+   * platform's timeout. `notify` then reaches no client.
+   * @default true
+   */
+  streaming?: boolean;
   /**
    * 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 { InMemoryServerEventBus, McpServer, ProtocolErrorCode, SUPPORTED_PROTOCOL_VERSIONS, classifyInboundRequest, createMcpHandler, fromJsonSchema } from "@modelcontextprotocol/server";
+import { InMemoryServerEventBus, McpServer, McpServer as McpServer$1, ProtocolErrorCode, SUPPORTED_PROTOCOL_VERSIONS, classifyInboundRequest, createMcpHandler, fromJsonSchema } from "@modelcontextprotocol/server";
 import { z } from "zod";
 
 //#region src/context.ts
@@ -52,6 +52,49 @@ var NO_NOTIFIER = {
   resourceUpdated: () => {}
 };
 /**
+* Stops the server advertising change notifications for the tools, prompts
+* and resources it serves, keeping every other capability as registered.
+*
+* `McpServer` advertises `listChanged: true` for each kind the moment one is
+* registered, and the SDK then honours a `2026-07-28` `subscriptions/listen`
+* with an SSE stream it never ends. A host that buffers the response until the
+* handler returns — AWS Lambda behind API Gateway — delivers nothing and kills
+* the invocation at its timeout, and the client reopens the stream at once, so
+* each open session keeps one invocation busy for good (measured on a
+* production Lambda in 2026-10: one 30 s timeout per session every ~30 s).
+* With nothing advertised the SDK acknowledges the
+* listen and completes it in the same response. A kind with nothing
+* registered stays unadvertised, since advertising it would answer its `list`
+* call with "method not found".
+*/
+var withoutChangeNotifications = product => {
+  const server = product instanceof McpServer$1 ? product.server : product;
+  const {
+    tools,
+    prompts,
+    resources
+  } = server.getCapabilities();
+  const off = {};
+  if (tools) off.tools = {
+    listChanged: false
+  };
+  if (prompts) off.prompts = {
+    listChanged: false
+  };
+  if (resources) off.resources = {
+    listChanged: false,
+    subscribe: false
+  };
+  server.registerCapabilities(off);
+  return product;
+};
+/** `factory`, with each instance it builds passed through {@link withoutChangeNotifications}. */
+var servingNoChangeNotifications = factory => {
+  return factory && (async ctx => {
+    return withoutChangeNotifications(await factory(ctx));
+  });
+};
+/**
 * Reads a header as `string | undefined`. Koa's `ctx.get` returns `''` for a
 * missing header, which the classifier would read as "header present but
 * empty" rather than absent.
@@ -138,10 +181,13 @@ var createMcpRequestServer = ({
   server,
   sessionIdGenerator,
   bus,
-  keepAliveMs
+  keepAliveMs,
+  streaming = true
 }) => {
   const isStateful = sessionIdGenerator !== void 0;
-  const modern = createMcpServer ? createMcpHandler(createMcpServer, {
+  if (!streaming) withoutChangeNotifications(server);
+  const factory = streaming ? createMcpServer : servingNoChangeNotifications(createMcpServer);
+  const modern = factory ? createMcpHandler(factory, {
     legacy: "reject",
     bus,
     keepAliveMs
@@ -517,6 +563,50 @@ var isStandardSchema = schema => {
   return "~standard" in schema;
 };
 /**
+* Enforces a closed schema while naming each undeclared argument. The SDK's
+* own `additionalProperties: false` issue carries no path, so the argument to
+* drop goes unnamed; the rest of the schema is checked with it left open.
+*/
+var namingUndeclared = ({
+  schema,
+  standard
+}) => {
+  const {
+    additionalProperties: _closed,
+    ...openSchema
+  } = schema;
+  const open = fromJsonSchema(openSchema);
+  const declared = new Set(Object.keys(schema.properties ?? {}));
+  const withUndeclared = ({
+    value,
+    result
+  }) => {
+    const undeclared = Object.keys(Object(value)).filter(key => {
+      return !declared.has(key);
+    });
+    if (undeclared.length === 0) return result;
+    return {
+      issues: [...undeclared.map(key => {
+        return {
+          message: "is not an argument of this tool",
+          path: [key]
+        };
+      }), ...(result.issues ?? [])]
+    };
+  };
+  return {
+    "~standard": {
+      ...standard["~standard"],
+      validate: async value => {
+        return withUndeclared({
+          value,
+          result: await open["~standard"].validate(value)
+        });
+      }
+    }
+  };
+};
+/**
 * Converts a JSON Schema into the Standard Schema `registerTool` accepts.
 *
 * A Standard Schema keeps advertisement and enforcement in separate fields:
@@ -529,6 +619,10 @@ var fromJsonObjectSchema = ({
   validate
 }) => {
   const standard = fromJsonSchema(schema);
+  if (validate && schema.additionalProperties === false) return namingUndeclared({
+    schema,
+    standard
+  });
   if (validate) return standard;
   return {
     "~standard": {
@@ -1593,6 +1687,7 @@ var createMcpRouter = (server, options = {}) => {
     createMcpServer,
     bus,
     keepAliveMs,
+    streaming,
     apiBaseUrl,
     getApiHeaders,
     auth
@@ -1603,7 +1698,8 @@ var createMcpRouter = (server, options = {}) => {
     sessionIdGenerator,
     createMcpServer,
     bus,
-    keepAliveMs
+    keepAliveMs,
+    streaming
   });
   const router = new Router();
   let authCheck;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.39.1",
+  "version": "0.41.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -37,9 +37,9 @@
     "@modelcontextprotocol/node": "^2.1.1",
     "@modelcontextprotocol/server": "^2.3.1",
     "zod": "^4.6.7",
+    "@ttoss/http-server": "^0.14.2",
     "@ttoss/http-server-auth": "^0.10.2",
     "@ttoss/auth-core": "^0.20.1",
-    "@ttoss/http-server": "^0.14.2",
     "@ttoss/i18n-core": "^0.9.2"
   },
   "devDependencies": {