@ttoss/http-server-mcp 0.34.5 → 0.36.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. `description` (each tool's description alone) and `instructions` default to `2048`, where [Claude Code truncates both](https://code.claude.com/docs/en/mcp) without saying so; a schema is never cut, which is why `perTool` cannot stand in for `description`. `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,148 @@ var createMcpRequestServer = ({
   };
 };
 
+//#endregion
+//#region src/mcpSurface.ts
+/**
+* Claude Code truncates a server's instructions at this many characters
+* without telling anyone, so a rule past it never reaches an agent
+* (https://code.claude.com/docs/en/mcp; a user can change it with
+* `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH`).
+*/
+var DEFAULT_INSTRUCTIONS_LIMIT = 2048;
+/**
+* Claude Code truncates each tool description at the same length as the
+* instructions, from the same documentation, and just as silently.
+*/
+var DEFAULT_DESCRIPTION_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
+  };
+};
+var checkDescriptions = ({
+  tools,
+  limit
+}) => {
+  return tools.flatMap(tool => {
+    const size = tool.description?.length ?? 0;
+    return size > limit ? [{
+      kind: "description",
+      name: tool.name,
+      size,
+      limit
+    }] : [];
+  });
+};
+/**
+* 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
+    });
+  }
+  violations.push(...checkDescriptions({
+    tools,
+    limit: budget.description ?? 2048
+  }));
+  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 +1713,8 @@ var createMcpRouter = (server, options = {}) => {
 };
 
 //#endregion
+exports.DEFAULT_DESCRIPTION_LIMIT = DEFAULT_DESCRIPTION_LIMIT;
+exports.DEFAULT_INSTRUCTIONS_LIMIT = DEFAULT_INSTRUCTIONS_LIMIT;
 Object.defineProperty(exports, 'InMemoryServerEventBus', {
   enumerable: true,
   get: function () {
@@ -1586,14 +1730,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,142 @@ 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. `description` and `instructions`
+ * have defaults, because a client cuts them; `total` and `perTool` 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 any one tool's description length. Unlike `perTool`, it leaves
+   * out the name and input schema, which no client cuts.
+   * @default 2048
+   */
+  description?: 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: 'description';
+  name: string;
+  size: number;
+  limit: number;
+} | {
+  kind: 'instructions';
+  size: number;
+  limit: number;
+};
+/**
+ * Claude Code truncates a server's instructions at this many characters
+ * without telling anyone, so a rule past it never reaches an agent
+ * (https://code.claude.com/docs/en/mcp; a user can change it with
+ * `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH`).
+ */
+declare const DEFAULT_INSTRUCTIONS_LIMIT = 2048;
+/**
+ * Claude Code truncates each tool description at the same length as the
+ * instructions, from the same documentation, and just as silently.
+ */
+declare const DEFAULT_DESCRIPTION_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 +1847,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_DESCRIPTION_LIMIT, 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,142 @@ 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. `description` and `instructions`
+ * have defaults, because a client cuts them; `total` and `perTool` 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 any one tool's description length. Unlike `perTool`, it leaves
+   * out the name and input schema, which no client cuts.
+   * @default 2048
+   */
+  description?: 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: 'description';
+  name: string;
+  size: number;
+  limit: number;
+} | {
+  kind: 'instructions';
+  size: number;
+  limit: number;
+};
+/**
+ * Claude Code truncates a server's instructions at this many characters
+ * without telling anyone, so a rule past it never reaches an agent
+ * (https://code.claude.com/docs/en/mcp; a user can change it with
+ * `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH`).
+ */
+declare const DEFAULT_INSTRUCTIONS_LIMIT = 2048;
+/**
+ * Claude Code truncates each tool description at the same length as the
+ * instructions, from the same documentation, and just as silently.
+ */
+declare const DEFAULT_DESCRIPTION_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 +1848,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_DESCRIPTION_LIMIT, 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,148 @@ var createMcpRequestServer = ({
   };
 };
 
+//#endregion
+//#region src/mcpSurface.ts
+/**
+* Claude Code truncates a server's instructions at this many characters
+* without telling anyone, so a rule past it never reaches an agent
+* (https://code.claude.com/docs/en/mcp; a user can change it with
+* `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH`).
+*/
+var DEFAULT_INSTRUCTIONS_LIMIT = 2048;
+/**
+* Claude Code truncates each tool description at the same length as the
+* instructions, from the same documentation, and just as silently.
+*/
+var DEFAULT_DESCRIPTION_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
+  };
+};
+var checkDescriptions = ({
+  tools,
+  limit
+}) => {
+  return tools.flatMap(tool => {
+    const size = tool.description?.length ?? 0;
+    return size > limit ? [{
+      kind: "description",
+      name: tool.name,
+      size,
+      limit
+    }] : [];
+  });
+};
+/**
+* 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
+    });
+  }
+  violations.push(...checkDescriptions({
+    tools,
+    limit: budget.description ?? 2048
+  }));
+  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 +1710,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_DESCRIPTION_LIMIT, 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.5",
+  "version": "0.36.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -39,8 +39,8 @@
     "zod": "^4.4.3",
     "@ttoss/auth-core": "^0.17.2",
     "@ttoss/i18n-core": "^0.8.1",
-    "@ttoss/http-server": "^0.12.2",
-    "@ttoss/http-server-auth": "^0.8.4"
+    "@ttoss/http-server": "^0.13.0",
+    "@ttoss/http-server-auth": "^0.8.5"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.0.0",