@ttoss/http-server-mcp 0.40.0 → 0.42.0

package/README.md

@@ -484,13 +484,14 @@ registerTools({ server: fullServer, tools });
 registerTools({ server: deferredServer, tools, defer: true });
 ```
 
-A schema enters the model's context only for the tools it is about to use. `call` enforces the tool's schema as a direct call would, and its errors help the model recover: an unknown name answers suggestions (close typos first, then near-misses and tools sharing the name's words, by how much they share), and invalid arguments, a tool's own error result, or a thrown error carry the input schema, so a `call` made without `describe` corrects itself in one retry.
+A schema enters the model's context only for the tools it is about to use. `call` enforces the tool's schema as a direct call would, and its errors help the model recover: an unknown name answers suggestions (close typos first, then near-misses and tools sharing the name's words, by how much they share), and invalid arguments carry the input schema, so a `call` made without `describe` corrects itself in one retry.
 
 Pass options instead of `true` to tune it:
 
 - `except` — tools kept standalone, not deferred; they stay reachable through `search` too. Defaults to those linked to an [MCP Apps](#mcp-apps-interactive-uis) view, since a host finds a view through the tool's own `tools/list` entry.
 - `visible` — runs on every `search`, `describe` and `call`; a tool it rejects is absent from all three. Standalone tools stay listed.
 - `search` — replaces the default ranking, `rankTools`, e.g. with embeddings.
+- `schemaOnError` (default `'invalidArguments'`) — which failed calls carry the input schema. By default only arguments that fail it do: a tool's own error result or a thrown error is usually a refusal of the operation (a 404, a 409), and a large schema on every refusal costs more context than deferring saved. `'always'` attaches it to those too, for tools that do not validate their arguments and whose errors may be argument errors only the API detects.
 - `searchLimit` (default `10`), `searchMaxLimit` — the largest `limit` accepted (default `50`, or `searchLimit` when higher) — and `names` (default `search` / `describe` / `call`).
 
 A gate (below) sees each call with the tool's own name and arguments, so authorization stays per tool when deferred.
@@ -676,6 +677,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)
@@ -1052,6 +1054,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
@@ -951,6 +997,7 @@ var deferredToolsOf = ({
     tools,
     searchLimit,
     searchMaxLimit: options.searchMaxLimit ?? Math.max(DEFAULT_SEARCH_MAX_LIMIT, searchLimit),
+    schemaOnError: options.schemaOnError ?? "invalidArguments",
     searchTools: options.search ?? rankTools,
     visibleTools: () => {
       return tools.filter(isVisible);
@@ -1094,7 +1141,8 @@ var describeToolOf = ({
 /** Runs one tool the way a direct call would, with errors that help a retry. */
 var runTool = async ({
   tool,
-  args
+  args,
+  schemaOnError
 }) => {
   const schemas = resolveToolSchemas(tool);
   const validated = await schemas.input["~standard"].validate(args);
@@ -1106,24 +1154,24 @@ var runTool = async ({
     },
     isError: true
   });
-  const schemaHint = {
+  const schemaHint = schemaOnError === "always" ? [{
     type: "text",
     text: JSON.stringify({
       inputSchema: schemas.inputJson
     })
-  };
+  }] : [];
   try {
     const result = await tool.handler(validated.value);
     return result.isError ? {
       ...result,
-      content: [...result.content, schemaHint]
+      content: [...result.content, ...schemaHint]
     } : result;
   } catch (error) {
     return {
       content: [{
         type: "text",
         text: errorMessageOf(error)
-      }, schemaHint],
+      }, ...schemaHint],
       isError: true
     };
   }
@@ -1131,7 +1179,8 @@ var runTool = async ({
 var callToolOf = ({
   names,
   find,
-  visibleTools
+  visibleTools,
+  schemaOnError
 }) => {
   return {
     name: names.call,
@@ -1166,7 +1215,8 @@ var callToolOf = ({
       });
       return runTool({
         tool,
-        args: args.arguments ?? {}
+        args: args.arguments ?? {},
+        schemaOnError
       });
     }
   };
@@ -1644,6 +1694,7 @@ var createMcpRouter = (server, options = {}) => {
     createMcpServer,
     bus,
     keepAliveMs,
+    streaming,
     apiBaseUrl,
     getApiHeaders,
     auth
@@ -1654,7 +1705,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

@@ -861,6 +861,20 @@ interface DeferToolsOptions {
    * @default 50, or `searchLimit` when that is higher
    */
   searchMaxLimit?: number;
+  /**
+   * Which failed `call`s carry the tool's input schema.
+   *
+   * - `'invalidArguments'` — only arguments that fail the tool's schema, so a
+   *   `call` made without `describe` corrects itself in one retry. A tool's
+   *   own error result or a thrown error is usually a refusal of the
+   *   operation (a 404, a 409), and a large schema on every refusal costs
+   *   more context than deferring saved.
+   * - `'always'` — those carry it too. For tools that do not validate their
+   *   arguments, whose errors may be argument errors only the API detects.
+   *
+   * @default 'invalidArguments'
+   */
+  schemaOnError?: 'always' | 'invalidArguments';
   /**
    * Runs on every `search`, `describe` and `call`. A tool it rejects is
    * absent from all three; `call` answers it as an unknown name. Tools
@@ -1707,6 +1721,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

@@ -862,6 +862,20 @@ interface DeferToolsOptions {
    * @default 50, or `searchLimit` when that is higher
    */
   searchMaxLimit?: number;
+  /**
+   * Which failed `call`s carry the tool's input schema.
+   *
+   * - `'invalidArguments'` — only arguments that fail the tool's schema, so a
+   *   `call` made without `describe` corrects itself in one retry. A tool's
+   *   own error result or a thrown error is usually a refusal of the
+   *   operation (a 404, a 409), and a large schema on every refusal costs
+   *   more context than deferring saved.
+   * - `'always'` — those carry it too. For tools that do not validate their
+   *   arguments, whose errors may be argument errors only the API detects.
+   *
+   * @default 'invalidArguments'
+   */
+  schemaOnError?: 'always' | 'invalidArguments';
   /**
    * Runs on every `search`, `describe` and `call`. A tool it rejects is
    * absent from all three; `call` answers it as an unknown name. Tools
@@ -1708,6 +1722,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
@@ -948,6 +994,7 @@ var deferredToolsOf = ({
     tools,
     searchLimit,
     searchMaxLimit: options.searchMaxLimit ?? Math.max(DEFAULT_SEARCH_MAX_LIMIT, searchLimit),
+    schemaOnError: options.schemaOnError ?? "invalidArguments",
     searchTools: options.search ?? rankTools,
     visibleTools: () => {
       return tools.filter(isVisible);
@@ -1091,7 +1138,8 @@ var describeToolOf = ({
 /** Runs one tool the way a direct call would, with errors that help a retry. */
 var runTool = async ({
   tool,
-  args
+  args,
+  schemaOnError
 }) => {
   const schemas = resolveToolSchemas(tool);
   const validated = await schemas.input["~standard"].validate(args);
@@ -1103,24 +1151,24 @@ var runTool = async ({
     },
     isError: true
   });
-  const schemaHint = {
+  const schemaHint = schemaOnError === "always" ? [{
     type: "text",
     text: JSON.stringify({
       inputSchema: schemas.inputJson
     })
-  };
+  }] : [];
   try {
     const result = await tool.handler(validated.value);
     return result.isError ? {
       ...result,
-      content: [...result.content, schemaHint]
+      content: [...result.content, ...schemaHint]
     } : result;
   } catch (error) {
     return {
       content: [{
         type: "text",
         text: errorMessageOf(error)
-      }, schemaHint],
+      }, ...schemaHint],
       isError: true
     };
   }
@@ -1128,7 +1176,8 @@ var runTool = async ({
 var callToolOf = ({
   names,
   find,
-  visibleTools
+  visibleTools,
+  schemaOnError
 }) => {
   return {
     name: names.call,
@@ -1163,7 +1212,8 @@ var callToolOf = ({
       });
       return runTool({
         tool,
-        args: args.arguments ?? {}
+        args: args.arguments ?? {},
+        schemaOnError
       });
     }
   };
@@ -1641,6 +1691,7 @@ var createMcpRouter = (server, options = {}) => {
     createMcpServer,
     bus,
     keepAliveMs,
+    streaming,
     apiBaseUrl,
     getApiHeaders,
     auth
@@ -1651,7 +1702,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.40.0",
+  "version": "0.42.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -38,9 +38,9 @@
     "@modelcontextprotocol/server": "^2.3.1",
     "zod": "^4.6.7",
     "@ttoss/auth-core": "^0.20.1",
-    "@ttoss/http-server": "^0.14.2",
     "@ttoss/http-server-auth": "^0.10.2",
-    "@ttoss/i18n-core": "^0.9.2"
+    "@ttoss/i18n-core": "^0.9.2",
+    "@ttoss/http-server": "^0.14.2"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.3.1",