@ttoss/http-server-mcp 0.35.0 → 0.37.0

package/README.md

@@ -357,7 +357,7 @@ createMcpRouter(mcpServer, {
 });
 ```
 
-The `resource` field in the metadata document is automatically set to `resourceServerUrl + path` (e.g. `https://mcp.example.com/mcp` for the default path). This means MCP clients that follow `resource` to connect will land on the actual MCP endpoint rather than the bare origin.
+The `resource` field in the metadata document is automatically set to `resourceServerUrl + path` (e.g. `https://mcp.example.com/mcp` for the default path). This means MCP clients that follow `resource` to connect will land on the actual MCP endpoint rather than the bare origin. Add `scopesSupported` to advertise the scopes this server accepts as `scopes_supported`, so clients request only what they need; unlike `requiredScopes`, it enforces nothing.
 
 **With your own auth middleware** — use `createProtectedResourceMetadataMiddleware` as a standalone middleware, mounted _before_ your auth layer so discovery stays unauthenticated:
 
@@ -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",
@@ -1592,7 +1616,8 @@ var createMcpRouter = (server, options = {}) => {
     const metadata = resourceUrl !== void 0 && auth.authorizationServerUrl !== void 0 ? {
       document: (0, _ttoss_auth_core.protectedResourceMetadataDocument)({
         resource: resourceUrl,
-        authorizationServers: [auth.authorizationServerUrl]
+        authorizationServers: [auth.authorizationServerUrl],
+        scopesSupported: auth.scopesSupported
       }),
       paths: (0, _ttoss_auth_core.protectedResourceMetadataPaths)({
         resource: resourceUrl
@@ -1689,6 +1714,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.
@@ -1500,6 +1518,12 @@ interface McpAuthOptions {
   resourceServerUrl?: string;
   /** URL of the OAuth Authorization Server that issues tokens for this resource. */
   authorizationServerUrl?: string;
+  /**
+   * Scopes this MCP server accepts, advertised as `scopes_supported` in the
+   * Protected Resource Metadata document so clients request only what they
+   * need. Unlike `requiredScopes`, nothing is enforced from it.
+   */
+  scopesSupported?: string[];
   /**
    * Expected audience — the resource indicator (RFC 8707) this MCP server
    * identifies as. When set, the verified token's `aud` claim must include at
@@ -1829,4 +1853,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.
@@ -1501,6 +1519,12 @@ interface McpAuthOptions {
   resourceServerUrl?: string;
   /** URL of the OAuth Authorization Server that issues tokens for this resource. */
   authorizationServerUrl?: string;
+  /**
+   * Scopes this MCP server accepts, advertised as `scopes_supported` in the
+   * Protected Resource Metadata document so clients request only what they
+   * need. Unlike `requiredScopes`, nothing is enforced from it.
+   */
+  scopesSupported?: string[];
   /**
    * Expected audience — the resource indicator (RFC 8707) this MCP server
    * identifies as. When set, the verified token's `aud` claim must include at
@@ -1830,4 +1854,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",
@@ -1589,7 +1613,8 @@ var createMcpRouter = (server, options = {}) => {
     const metadata = resourceUrl !== void 0 && auth.authorizationServerUrl !== void 0 ? {
       document: protectedResourceMetadataDocument({
         resource: resourceUrl,
-        authorizationServers: [auth.authorizationServerUrl]
+        authorizationServers: [auth.authorizationServerUrl],
+        scopesSupported: auth.scopesSupported
       }),
       paths: protectedResourceMetadataPaths({
         resource: resourceUrl
@@ -1686,4 +1711,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.37.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.2",
-    "@ttoss/http-server": "^0.13.0",
+    "@ttoss/http-server-auth": "^0.9.0",
     "@ttoss/i18n-core": "^0.8.1",
-    "@ttoss/http-server-auth": "^0.8.5"
+    "@ttoss/auth-core": "^0.18.0",
+    "@ttoss/http-server": "^0.13.1"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.0.0",