@ttoss/http-server-mcp 0.34.4 → 0.35.0

package/README.md

@@ -1130,6 +1130,33 @@ Either way the authorization flow works. Driving the official MCP client SDK aga
 
 **Whether the handshake should be public at all is a separate question.** `publicMethods: []` closes both eras, and the authorization flow still works — RFC 9728 discovery is driven by the challenge itself, so a client authenticates from its very first request instead of one step later.
 
+### Holding the surface to a budget
+
+Every tool's name, description and input schema, and the server's instructions, are loaded into every session before the first call. `checkMcpSurface` compares them with a budget and answers the limits they exceed, so a test fails naming the tool that grew:
+
+```typescript
+import {
+  checkMcpSurface,
+  findUnknownToolMentions,
+} from '@ttoss/http-server-mcp';
+
+test('the surface stays inside its budget', () => {
+  expect(
+    checkMcpSurface({
+      tools, // { name, description?, inputSchema? }[], e.g. from openApiToToolDefinitions
+      instructions,
+      budget: { total: 70_000, perTool: 10_000 },
+    })
+  ).toEqual([]);
+});
+
+test('every tool the instructions name exists', () => {
+  expect(findUnknownToolMentions({ instructions, tools })).toEqual([]);
+});
+```
+
+Sizes are characters of `JSON.stringify({ name, description, inputSchema })`; `measureMcpSurface` answers them without judging. `total` and `perTool` have no default — they are the product's choice — while `instructions` defaults to `2048`, about what Claude Code keeps before cutting the rest silently. `findUnknownToolMentions` reads backticked names with a `-` or `_` (`` `get-next` ``); pass `pattern` when the instructions name tools another way.
+
 ## AWS Lambda Deployment
 
 The default **stateless** mode (see [Stateless vs stateful mode](#stateless-vs-stateful-mode)) is built for serverless: a fresh transport is created per request, nothing is kept in memory between invocations, and responses are plain JSON (no SSE) — exactly the request/response shape API Gateway and Lambda Function URLs expect.

package/dist/index.cjs

@@ -212,6 +212,124 @@ var createMcpRequestServer = ({
   };
 };
 
+//#endregion
+//#region src/mcpSurface.ts
+/**
+* Claude Code keeps about this many characters of a server's instructions and
+* drops the rest without telling anyone, so a rule past it never reaches an
+* agent.
+*/
+var DEFAULT_INSTRUCTIONS_LIMIT = 2048;
+var sizeOf = tool => {
+  return JSON.stringify({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema
+  }).length;
+};
+/**
+* Measures what an MCP server costs every session that connects to it: each
+* tool's name, description and input schema, and the instructions.
+*
+* It does not judge; {@link checkMcpSurface} compares the same numbers with a
+* budget.
+*/
+var measureMcpSurface = ({
+  tools,
+  instructions
+}) => {
+  const sizes = tools.map(tool => {
+    return {
+      name: tool.name,
+      size: sizeOf(tool)
+    };
+  }).sort((a, b) => {
+    return b.size - a.size;
+  });
+  return {
+    total: sizes.reduce((sum, entry) => {
+      return sum + entry.size;
+    }, 0),
+    tools: sizes,
+    instructions: instructions?.length ?? 0
+  };
+};
+/**
+* Every limit an MCP surface exceeds, or `[]` when it fits.
+*
+* Returns rather than throws, so a test's `expect(...).toEqual([])` prints
+* which tool went over and by how much. Meant for a test, not for boot: a
+* server refusing to start over a few hundred bytes is worse than a red test.
+*
+* @example
+* ```typescript
+* expect(
+*   checkMcpSurface({
+*     tools,
+*     instructions,
+*     budget: { total: 70_000, perTool: 10_000 },
+*   })
+* ).toEqual([]);
+* ```
+*/
+var checkMcpSurface = ({
+  tools,
+  instructions,
+  budget = {}
+}) => {
+  const report = measureMcpSurface({
+    tools,
+    instructions
+  });
+  const violations = [];
+  if (budget.total !== void 0 && report.total > budget.total) violations.push({
+    kind: "total",
+    size: report.total,
+    limit: budget.total
+  });
+  if (budget.perTool !== void 0) {
+    for (const {
+      name,
+      size
+    } of report.tools) if (size > budget.perTool) violations.push({
+      kind: "per_tool",
+      name,
+      size,
+      limit: budget.perTool
+    });
+  }
+  const instructionsLimit = budget.instructions ?? 2048;
+  if (report.instructions > instructionsLimit) violations.push({
+    kind: "instructions",
+    size: report.instructions,
+    limit: instructionsLimit
+  });
+  return violations;
+};
+var TOOL_MENTION = /`([a-z][a-z0-9]*(?:[-_][a-z0-9]+)+)`/g;
+/**
+* The tool names the instructions mention that the surface does not have.
+*
+* Instructions are read once, at connect: a renamed tool they still name is
+* one every connected agent is taught to call and then told is "not found".
+* Pass `pattern` (a global RegExp whose first group is the name) when the
+* instructions name tools some other way.
+*/
+var findUnknownToolMentions = ({
+  instructions,
+  tools,
+  pattern = TOOL_MENTION
+}) => {
+  const known = new Set(tools.map(tool => {
+    return tool.name;
+  }));
+  return [...new Set([...instructions.matchAll(pattern)].map(([, name]) => {
+    return name;
+  }))].filter(name => {
+    return !known.has(name);
+  });
+};
+
 //#endregion
 //#region src/registerAppResource.ts
 /**
@@ -1571,6 +1689,7 @@ var createMcpRouter = (server, options = {}) => {
 };
 
 //#endregion
+exports.DEFAULT_INSTRUCTIONS_LIMIT = DEFAULT_INSTRUCTIONS_LIMIT;
 Object.defineProperty(exports, 'InMemoryServerEventBus', {
   enumerable: true,
   get: function () {
@@ -1586,14 +1705,17 @@ Object.defineProperty(exports, 'McpServer', {
 exports.UI_EXTENSION_ID = UI_EXTENSION_ID;
 exports.UI_RESOURCE_MIME_TYPE = UI_RESOURCE_MIME_TYPE;
 exports.apiCall = apiCall;
+exports.checkMcpSurface = checkMcpSurface;
 exports.checkScopes = checkScopes;
 exports.createMcpRouter = createMcpRouter;
 exports.createToolGate = createToolGate;
 exports.defineTool = defineTool;
 exports.errorBodyMessage = errorBodyMessage;
+exports.findUnknownToolMentions = findUnknownToolMentions;
 exports.getApiHeaders = getApiHeaders;
 exports.getIdentity = getIdentity;
 exports.getRequestLocale = getRequestLocale;
+exports.measureMcpSurface = measureMcpSurface;
 exports.rankTools = rankTools;
 exports.registerAppResource = registerAppResource;
 exports.registerTools = registerTools;

package/dist/index.d.cts

@@ -886,6 +886,124 @@ interface DeferToolsOptions {
   }) => boolean;
 }
 //#endregion
+//#region src/mcpSurface.d.ts
+/**
+ * What a client loads for one tool before the first call: the three fields a
+ * `tools/list` answers. `openApiToToolDefinitions` returns this shape, and so
+ * does a `tools/list` result.
+ */
+interface McpSurfaceTool {
+  name: string;
+  description?: string;
+  inputSchema?: unknown;
+}
+/** The size of each part of an MCP surface, in characters of JSON. */
+interface McpSurfaceReport {
+  /** Sum of every tool's size. Instructions are not included. */
+  total: number;
+  /** One entry per tool, largest first. */
+  tools: Array<{
+    name: string;
+    size: number;
+  }>;
+  /** Length of the server instructions, or `0` when there are none. */
+  instructions: number;
+}
+/**
+ * The limits a surface is checked against. Only `instructions` has a default:
+ * the others are a product's own choice, not a property of any client.
+ */
+interface McpSurfaceBudget {
+  /** Ceiling on the sum of every tool's size. */
+  total?: number;
+  /** Ceiling on any one tool's size. */
+  perTool?: number;
+  /**
+   * Ceiling on the instructions' length.
+   * @default 2048
+   */
+  instructions?: number;
+}
+/** One limit a surface exceeds. */
+type McpSurfaceViolation = {
+  kind: 'total';
+  size: number;
+  limit: number;
+} | {
+  kind: 'per_tool';
+  name: string;
+  size: number;
+  limit: number;
+} | {
+  kind: 'instructions';
+  size: number;
+  limit: number;
+};
+/**
+ * Claude Code keeps about this many characters of a server's instructions and
+ * drops the rest without telling anyone, so a rule past it never reaches an
+ * agent.
+ */
+declare const DEFAULT_INSTRUCTIONS_LIMIT = 2048;
+/**
+ * Measures what an MCP server costs every session that connects to it: each
+ * tool's name, description and input schema, and the instructions.
+ *
+ * It does not judge; {@link checkMcpSurface} compares the same numbers with a
+ * budget.
+ */
+declare const measureMcpSurface: ({
+  tools,
+  instructions
+}: {
+  tools: McpSurfaceTool[];
+  instructions?: string;
+}) => McpSurfaceReport;
+/**
+ * Every limit an MCP surface exceeds, or `[]` when it fits.
+ *
+ * Returns rather than throws, so a test's `expect(...).toEqual([])` prints
+ * which tool went over and by how much. Meant for a test, not for boot: a
+ * server refusing to start over a few hundred bytes is worse than a red test.
+ *
+ * @example
+ * ```typescript
+ * expect(
+ *   checkMcpSurface({
+ *     tools,
+ *     instructions,
+ *     budget: { total: 70_000, perTool: 10_000 },
+ *   })
+ * ).toEqual([]);
+ * ```
+ */
+declare const checkMcpSurface: ({
+  tools,
+  instructions,
+  budget
+}: {
+  tools: McpSurfaceTool[];
+  instructions?: string;
+  budget?: McpSurfaceBudget;
+}) => McpSurfaceViolation[];
+/**
+ * The tool names the instructions mention that the surface does not have.
+ *
+ * Instructions are read once, at connect: a renamed tool they still name is
+ * one every connected agent is taught to call and then told is "not found".
+ * Pass `pattern` (a global RegExp whose first group is the name) when the
+ * instructions name tools some other way.
+ */
+declare const findUnknownToolMentions: ({
+  instructions,
+  tools,
+  pattern
+}: {
+  instructions: string;
+  tools: Array<Pick<McpSurfaceTool, "name">>;
+  pattern?: RegExp;
+}) => string[];
+//#endregion
 //#region src/registerAppResource.d.ts
 /**
  * Identifier of the MCP Apps extension (`io.modelcontextprotocol/ui`), used as
@@ -1711,4 +1829,4 @@ interface McpRouterOptions {
  */
 declare const createMcpRouter: (server: McpServer$1, options?: McpRouterOptions) => McpRouter;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, type CreateToolGateOptions, type DeferToolsOptions, type DefineToolParams, type GateToolParams, InMemoryServerEventBus, type JsonObjectSchema, McpAuthOptions, McpRouter, McpRouterOptions, McpServer, type RegisterAppResourceParams, type RegisterToolsParams, type RegisteredAppResource, type ServerEvent, type ServerEventBus, type ServerNotifier, type Tool, type ToolCallContext, type ToolCallGate, type ToolGate, type ToolIdentity, type ToolMetaParams, type ToolSchema, type ToolSearchArgs, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkScopes, createMcpRouter, createToolGate, defineTool, errorBodyMessage, getApiHeaders, getIdentity, getRequestLocale, rankTools, registerAppResource, registerTools, z };
+export { ApiCallOptions, CognitoUserPoolConfig, type CreateToolGateOptions, DEFAULT_INSTRUCTIONS_LIMIT, type DeferToolsOptions, type DefineToolParams, type GateToolParams, InMemoryServerEventBus, type JsonObjectSchema, McpAuthOptions, McpRouter, McpRouterOptions, McpServer, type McpSurfaceBudget, type McpSurfaceReport, type McpSurfaceTool, type McpSurfaceViolation, type RegisterAppResourceParams, type RegisterToolsParams, type RegisteredAppResource, type ServerEvent, type ServerEventBus, type ServerNotifier, type Tool, type ToolCallContext, type ToolCallGate, type ToolGate, type ToolIdentity, type ToolMetaParams, type ToolSchema, type ToolSearchArgs, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkMcpSurface, checkScopes, createMcpRouter, createToolGate, defineTool, errorBodyMessage, findUnknownToolMentions, getApiHeaders, getIdentity, getRequestLocale, measureMcpSurface, rankTools, registerAppResource, registerTools, z };

package/dist/index.d.mts

@@ -887,6 +887,124 @@ interface DeferToolsOptions {
   }) => boolean;
 }
 //#endregion
+//#region src/mcpSurface.d.ts
+/**
+ * What a client loads for one tool before the first call: the three fields a
+ * `tools/list` answers. `openApiToToolDefinitions` returns this shape, and so
+ * does a `tools/list` result.
+ */
+interface McpSurfaceTool {
+  name: string;
+  description?: string;
+  inputSchema?: unknown;
+}
+/** The size of each part of an MCP surface, in characters of JSON. */
+interface McpSurfaceReport {
+  /** Sum of every tool's size. Instructions are not included. */
+  total: number;
+  /** One entry per tool, largest first. */
+  tools: Array<{
+    name: string;
+    size: number;
+  }>;
+  /** Length of the server instructions, or `0` when there are none. */
+  instructions: number;
+}
+/**
+ * The limits a surface is checked against. Only `instructions` has a default:
+ * the others are a product's own choice, not a property of any client.
+ */
+interface McpSurfaceBudget {
+  /** Ceiling on the sum of every tool's size. */
+  total?: number;
+  /** Ceiling on any one tool's size. */
+  perTool?: number;
+  /**
+   * Ceiling on the instructions' length.
+   * @default 2048
+   */
+  instructions?: number;
+}
+/** One limit a surface exceeds. */
+type McpSurfaceViolation = {
+  kind: 'total';
+  size: number;
+  limit: number;
+} | {
+  kind: 'per_tool';
+  name: string;
+  size: number;
+  limit: number;
+} | {
+  kind: 'instructions';
+  size: number;
+  limit: number;
+};
+/**
+ * Claude Code keeps about this many characters of a server's instructions and
+ * drops the rest without telling anyone, so a rule past it never reaches an
+ * agent.
+ */
+declare const DEFAULT_INSTRUCTIONS_LIMIT = 2048;
+/**
+ * Measures what an MCP server costs every session that connects to it: each
+ * tool's name, description and input schema, and the instructions.
+ *
+ * It does not judge; {@link checkMcpSurface} compares the same numbers with a
+ * budget.
+ */
+declare const measureMcpSurface: ({
+  tools,
+  instructions
+}: {
+  tools: McpSurfaceTool[];
+  instructions?: string;
+}) => McpSurfaceReport;
+/**
+ * Every limit an MCP surface exceeds, or `[]` when it fits.
+ *
+ * Returns rather than throws, so a test's `expect(...).toEqual([])` prints
+ * which tool went over and by how much. Meant for a test, not for boot: a
+ * server refusing to start over a few hundred bytes is worse than a red test.
+ *
+ * @example
+ * ```typescript
+ * expect(
+ *   checkMcpSurface({
+ *     tools,
+ *     instructions,
+ *     budget: { total: 70_000, perTool: 10_000 },
+ *   })
+ * ).toEqual([]);
+ * ```
+ */
+declare const checkMcpSurface: ({
+  tools,
+  instructions,
+  budget
+}: {
+  tools: McpSurfaceTool[];
+  instructions?: string;
+  budget?: McpSurfaceBudget;
+}) => McpSurfaceViolation[];
+/**
+ * The tool names the instructions mention that the surface does not have.
+ *
+ * Instructions are read once, at connect: a renamed tool they still name is
+ * one every connected agent is taught to call and then told is "not found".
+ * Pass `pattern` (a global RegExp whose first group is the name) when the
+ * instructions name tools some other way.
+ */
+declare const findUnknownToolMentions: ({
+  instructions,
+  tools,
+  pattern
+}: {
+  instructions: string;
+  tools: Array<Pick<McpSurfaceTool, "name">>;
+  pattern?: RegExp;
+}) => string[];
+//#endregion
 //#region src/registerAppResource.d.ts
 /**
  * Identifier of the MCP Apps extension (`io.modelcontextprotocol/ui`), used as
@@ -1712,4 +1830,4 @@ interface McpRouterOptions {
  */
 declare const createMcpRouter: (server: McpServer$1, options?: McpRouterOptions) => McpRouter;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, type CreateToolGateOptions, type DeferToolsOptions, type DefineToolParams, type GateToolParams, InMemoryServerEventBus, type JsonObjectSchema, McpAuthOptions, McpRouter, McpRouterOptions, McpServer, type RegisterAppResourceParams, type RegisterToolsParams, type RegisteredAppResource, type ServerEvent, type ServerEventBus, type ServerNotifier, type Tool, type ToolCallContext, type ToolCallGate, type ToolGate, type ToolIdentity, type ToolMetaParams, type ToolSchema, type ToolSearchArgs, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkScopes, createMcpRouter, createToolGate, defineTool, errorBodyMessage, getApiHeaders, getIdentity, getRequestLocale, rankTools, registerAppResource, registerTools, z };
+export { ApiCallOptions, CognitoUserPoolConfig, type CreateToolGateOptions, DEFAULT_INSTRUCTIONS_LIMIT, type DeferToolsOptions, type DefineToolParams, type GateToolParams, InMemoryServerEventBus, type JsonObjectSchema, McpAuthOptions, McpRouter, McpRouterOptions, McpServer, type McpSurfaceBudget, type McpSurfaceReport, type McpSurfaceTool, type McpSurfaceViolation, type RegisterAppResourceParams, type RegisterToolsParams, type RegisteredAppResource, type ServerEvent, type ServerEventBus, type ServerNotifier, type Tool, type ToolCallContext, type ToolCallGate, type ToolGate, type ToolIdentity, type ToolMetaParams, type ToolSchema, type ToolSearchArgs, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkMcpSurface, checkScopes, createMcpRouter, createToolGate, defineTool, errorBodyMessage, findUnknownToolMentions, getApiHeaders, getIdentity, getRequestLocale, measureMcpSurface, rankTools, registerAppResource, registerTools, z };

package/dist/index.mjs

@@ -209,6 +209,124 @@ var createMcpRequestServer = ({
   };
 };
 
+//#endregion
+//#region src/mcpSurface.ts
+/**
+* Claude Code keeps about this many characters of a server's instructions and
+* drops the rest without telling anyone, so a rule past it never reaches an
+* agent.
+*/
+var DEFAULT_INSTRUCTIONS_LIMIT = 2048;
+var sizeOf = tool => {
+  return JSON.stringify({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema
+  }).length;
+};
+/**
+* Measures what an MCP server costs every session that connects to it: each
+* tool's name, description and input schema, and the instructions.
+*
+* It does not judge; {@link checkMcpSurface} compares the same numbers with a
+* budget.
+*/
+var measureMcpSurface = ({
+  tools,
+  instructions
+}) => {
+  const sizes = tools.map(tool => {
+    return {
+      name: tool.name,
+      size: sizeOf(tool)
+    };
+  }).sort((a, b) => {
+    return b.size - a.size;
+  });
+  return {
+    total: sizes.reduce((sum, entry) => {
+      return sum + entry.size;
+    }, 0),
+    tools: sizes,
+    instructions: instructions?.length ?? 0
+  };
+};
+/**
+* Every limit an MCP surface exceeds, or `[]` when it fits.
+*
+* Returns rather than throws, so a test's `expect(...).toEqual([])` prints
+* which tool went over and by how much. Meant for a test, not for boot: a
+* server refusing to start over a few hundred bytes is worse than a red test.
+*
+* @example
+* ```typescript
+* expect(
+*   checkMcpSurface({
+*     tools,
+*     instructions,
+*     budget: { total: 70_000, perTool: 10_000 },
+*   })
+* ).toEqual([]);
+* ```
+*/
+var checkMcpSurface = ({
+  tools,
+  instructions,
+  budget = {}
+}) => {
+  const report = measureMcpSurface({
+    tools,
+    instructions
+  });
+  const violations = [];
+  if (budget.total !== void 0 && report.total > budget.total) violations.push({
+    kind: "total",
+    size: report.total,
+    limit: budget.total
+  });
+  if (budget.perTool !== void 0) {
+    for (const {
+      name,
+      size
+    } of report.tools) if (size > budget.perTool) violations.push({
+      kind: "per_tool",
+      name,
+      size,
+      limit: budget.perTool
+    });
+  }
+  const instructionsLimit = budget.instructions ?? 2048;
+  if (report.instructions > instructionsLimit) violations.push({
+    kind: "instructions",
+    size: report.instructions,
+    limit: instructionsLimit
+  });
+  return violations;
+};
+var TOOL_MENTION = /`([a-z][a-z0-9]*(?:[-_][a-z0-9]+)+)`/g;
+/**
+* The tool names the instructions mention that the surface does not have.
+*
+* Instructions are read once, at connect: a renamed tool they still name is
+* one every connected agent is taught to call and then told is "not found".
+* Pass `pattern` (a global RegExp whose first group is the name) when the
+* instructions name tools some other way.
+*/
+var findUnknownToolMentions = ({
+  instructions,
+  tools,
+  pattern = TOOL_MENTION
+}) => {
+  const known = new Set(tools.map(tool => {
+    return tool.name;
+  }));
+  return [...new Set([...instructions.matchAll(pattern)].map(([, name]) => {
+    return name;
+  }))].filter(name => {
+    return !known.has(name);
+  });
+};
+
 //#endregion
 //#region src/registerAppResource.ts
 /**
@@ -1568,4 +1686,4 @@ var createMcpRouter = (server, options = {}) => {
 };
 
 //#endregion
-export { InMemoryServerEventBus, McpServer, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, apiCall, checkScopes, createMcpRouter, createToolGate, defineTool, errorBodyMessage, getApiHeaders, getIdentity, getRequestLocale, rankTools, registerAppResource, registerTools, z };
+export { DEFAULT_INSTRUCTIONS_LIMIT, InMemoryServerEventBus, McpServer, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, apiCall, checkMcpSurface, checkScopes, createMcpRouter, createToolGate, defineTool, errorBodyMessage, findUnknownToolMentions, getApiHeaders, getIdentity, getRequestLocale, measureMcpSurface, rankTools, registerAppResource, registerTools, z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.34.4",
+  "version": "0.35.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -37,10 +37,10 @@
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "zod": "^4.4.3",
-    "@ttoss/auth-core": "^0.17.1",
-    "@ttoss/http-server": "^0.12.1",
-    "@ttoss/i18n-core": "^0.8.0",
-    "@ttoss/http-server-auth": "^0.8.3"
+    "@ttoss/auth-core": "^0.17.2",
+    "@ttoss/http-server": "^0.13.0",
+    "@ttoss/i18n-core": "^0.8.1",
+    "@ttoss/http-server-auth": "^0.8.5"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.0.0",