@ttoss/http-server-mcp 0.35.0 → 0.36.0

package/README.md

@@ -1155,7 +1155,7 @@ test('every tool the instructions name exists', () => {
 });
 ```
 
-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.
+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
 

package/dist/index.cjs

@@ -215,11 +215,17 @@ 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.
+* 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,
@@ -254,6 +260,20 @@ var measureMcpSurface = ({
     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.
 *
@@ -298,6 +318,10 @@ var checkMcpSurface = ({
       limit: budget.perTool
     });
   }
+  violations.push(...checkDescriptions({
+    tools,
+    limit: budget.description ?? 2048
+  }));
   const instructionsLimit = budget.instructions ?? 2048;
   if (report.instructions > instructionsLimit) violations.push({
     kind: "instructions",
@@ -1689,6 +1713,7 @@ 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,

package/dist/index.d.cts

@@ -910,14 +910,21 @@ interface McpSurfaceReport {
   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.
+ * 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
@@ -934,17 +941,28 @@ type McpSurfaceViolation = {
   name: string;
   size: number;
   limit: number;
+} | {
+  kind: 'description';
+  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.
+ * 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.
@@ -1829,4 +1847,4 @@ interface McpRouterOptions {
  */
 declare const createMcpRouter: (server: McpServer$1, options?: McpRouterOptions) => McpRouter;
 //#endregion
-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 };
+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

@@ -911,14 +911,21 @@ interface McpSurfaceReport {
   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.
+ * 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
@@ -935,17 +942,28 @@ type McpSurfaceViolation = {
   name: string;
   size: number;
   limit: number;
+} | {
+  kind: 'description';
+  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.
+ * 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.
@@ -1830,4 +1848,4 @@ interface McpRouterOptions {
  */
 declare const createMcpRouter: (server: McpServer$1, options?: McpRouterOptions) => McpRouter;
 //#endregion
-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 };
+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

@@ -212,11 +212,17 @@ 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.
+* 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,
@@ -251,6 +257,20 @@ var measureMcpSurface = ({
     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.
 *
@@ -295,6 +315,10 @@ var checkMcpSurface = ({
       limit: budget.perTool
     });
   }
+  violations.push(...checkDescriptions({
+    tools,
+    limit: budget.description ?? 2048
+  }));
   const instructionsLimit = budget.instructions ?? 2048;
   if (report.instructions > instructionsLimit) violations.push({
     kind: "instructions",
@@ -1686,4 +1710,4 @@ var createMcpRouter = (server, options = {}) => {
 };
 
 //#endregion
-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 };
+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.35.0",
+  "version": "0.36.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -38,8 +38,8 @@
     "@modelcontextprotocol/server": "^2.0.0",
     "zod": "^4.4.3",
     "@ttoss/auth-core": "^0.17.2",
-    "@ttoss/http-server": "^0.13.0",
     "@ttoss/i18n-core": "^0.8.1",
+    "@ttoss/http-server": "^0.13.0",
     "@ttoss/http-server-auth": "^0.8.5"
   },
   "devDependencies": {