Merge branch 'dr-extend-upstream-mcp-description-filter' into 'main'

feat: add tool_description_length_policy to upstream MCP provider config

See merge request ai-adoption/mcp/mcp4openapi!10

Author: Růžička, David

src/generated-schemas.ts

@@ -360,6 +360,7 @@ export const upstreamMcpServerConfigSchema = z.object({
     tools: upstreamMcpToolPolicySchema.optional(),
     timeout_ms: z.number().optional(),
     html_description_policy: z.enum(['allow', 'strip', 'drop']).optional(),
+    tool_description_length_policy: z.enum(['drop', 'truncate', 'allow']).optional(),
     validation_endpoint: z.string().optional(),
     validation_method: z.union([z.literal("HEAD"), z.literal("GET")]).optional(),
     validation_timeout_ms: z.number().optional()

src/mcp/mcp-server.ts

@@ -1906,7 +1906,7 @@ export class MCPServer {
         );
       }
       const rawTools = result.tools;
-      const sanitized = sanitizeToolList(rawTools, this.logger, provider.html_description_policy ?? 'drop');
+      const sanitized = sanitizeToolList(rawTools, this.logger, provider.html_description_policy ?? 'drop', provider.tool_description_length_policy ?? 'drop');
       const policyFiltered = applyProviderToolPolicy(sanitized.tools, provider.tools);
       // Cache sanitized+policy-filtered tool names for tools/call gate enforcement.
       // Tools dropped here (bad description/inputSchema) must not be callable via tools/call.

src/types/profile.ts

@@ -104,6 +104,14 @@ export interface UpstreamMcpServerConfig {
    */
   html_description_policy?: 'allow' | 'strip' | 'drop';
 
+  /**
+   * Controls how upstream tools with descriptions exceeding the internal length limit are handled.
+   * - drop (default): tools with overlong descriptions are dropped
+   * - truncate: description is truncated to the limit; tool is kept
+   * - allow: description length check is skipped; tool passes through unchanged
+   */
+  tool_description_length_policy?: 'drop' | 'truncate' | 'allow';
+
   /** Optional endpoint to validate upstream credentials at session init (fail-fast). */
   validation_endpoint?: string;
   /** HTTP method for validation probe. Default: 'HEAD'. */

src/upstream/upstream-tool-sanitizer.test.ts

@@ -5,6 +5,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import type { Logger } from '../core/logger.js';
 import { sanitizeToolList, applyProviderToolPolicy, isToolAllowedByProviderPolicy, isValidUpstreamToolName } from './upstream-tool-sanitizer.js';
+import type { ToolDescriptionLengthPolicy } from './upstream-tool-sanitizer.js';
 import type { Tool } from '@modelcontextprotocol/sdk/types.js';
 
 function makeTool(name: string, description?: string): Tool {
@@ -503,6 +504,125 @@ describe('sanitizeToolList — html_description_policy', () => {
   });
 });
 
+describe('sanitizeToolList — tool_description_length_policy', () => {
+  const LONG_DESC = 'a'.repeat(2049);
+  const EXACT_DESC = 'a'.repeat(2048);
+  let logger: Logger;
+
+  beforeEach(() => {
+    logger = { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+  });
+
+  describe('drop (default)', () => {
+    it('drops tool with description > 2048 chars', () => {
+      const tool = makeTool('t', LONG_DESC);
+      const result = sanitizeToolList([tool], logger, 'drop', 'drop');
+      expect(result.tools).toHaveLength(0);
+      expect(result.dropped[0].reason).toBe('tool description too long');
+    });
+
+    it('passes tool with description exactly 2048 chars', () => {
+      const tool = makeTool('t', EXACT_DESC);
+      const result = sanitizeToolList([tool], logger, 'drop', 'drop');
+      expect(result.tools).toHaveLength(1);
+      expect(result.dropped).toHaveLength(0);
+    });
+  });
+
+  describe('truncate', () => {
+    it('keeps tool and truncates description to 2048 chars', () => {
+      const tool = makeTool('t', LONG_DESC);
+      const result = sanitizeToolList([tool], logger, 'drop', 'truncate');
+      expect(result.tools).toHaveLength(1);
+      expect(result.tools[0].description).toHaveLength(2048);
+      expect(result.tools[0].description).toBe(LONG_DESC.slice(0, 2048));
+      expect(result.dropped).toHaveLength(0);
+      expect(logger.warn).not.toHaveBeenCalled();
+    });
+
+    it('does not mutate original tool object', () => {
+      const tool = makeTool('t', LONG_DESC);
+      sanitizeToolList([tool], logger, 'drop', 'truncate');
+      expect(tool.description).toBe(LONG_DESC);
+    });
+
+    it('passes tool with description exactly 2048 chars unchanged', () => {
+      const tool = makeTool('t', EXACT_DESC);
+      const result = sanitizeToolList([tool], logger, 'drop', 'truncate');
+      expect(result.tools).toHaveLength(1);
+      expect(result.tools[0].description).toHaveLength(2048);
+    });
+
+    it('still drops tool with invalid name regardless of truncate policy', () => {
+      const tool = makeTool('bad name!', LONG_DESC);
+      const result = sanitizeToolList([tool], logger, 'drop', 'truncate');
+      expect(result.tools).toHaveLength(0);
+      expect(result.dropped[0].reason).toBe('invalid characters in tool name');
+    });
+
+    it('still drops tool with malformed inputSchema regardless of truncate policy', () => {
+      const tool = { name: 'valid', description: LONG_DESC, inputSchema: null } as unknown as Tool;
+      const result = sanitizeToolList([tool], logger, 'drop', 'truncate');
+      expect(result.tools).toHaveLength(0);
+      expect(result.dropped[0].reason).toBe('malformed tool definition: inputSchema is not an object');
+    });
+  });
+
+  describe('allow', () => {
+    it('passes tool with overlong description through unchanged', () => {
+      const tool = makeTool('t', LONG_DESC);
+      const result = sanitizeToolList([tool], logger, 'drop', 'allow');
+      expect(result.tools).toHaveLength(1);
+      expect(result.tools[0].description).toBe(LONG_DESC);
+      expect(result.dropped).toHaveLength(0);
+      expect(logger.warn).not.toHaveBeenCalled();
+    });
+
+    it('still drops tool with invalid name regardless of allow policy', () => {
+      const tool = makeTool('bad name!', LONG_DESC);
+      const result = sanitizeToolList([tool], logger, 'drop', 'allow');
+      expect(result.tools).toHaveLength(0);
+      expect(result.dropped[0].reason).toBe('invalid characters in tool name');
+    });
+
+    it('still drops tool with malformed inputSchema regardless of allow policy', () => {
+      const tool = { name: 'valid', description: LONG_DESC, inputSchema: null } as unknown as Tool;
+      const result = sanitizeToolList([tool], logger, 'drop', 'allow');
+      expect(result.tools).toHaveLength(0);
+      expect(result.dropped[0].reason).toBe('malformed tool definition: inputSchema is not an object');
+    });
+  });
+
+  describe('interactions with html_description_policy', () => {
+    it('truncate length + strip html: truncates first then strips HTML from truncated string', () => {
+      // desc = '<b>' + 'a' * 2049 + '</b>' = 2056 chars
+      // truncate to 2048: '<b>' + 'a' * 2045 (first 2048 chars)
+      // then strip HTML: 'a' * 2045
+      const desc = '<b>' + 'a'.repeat(2049) + '</b>';
+      const tool = makeTool('t', desc);
+      const result = sanitizeToolList([tool], logger, 'strip', 'truncate');
+      expect(result.tools).toHaveLength(1);
+      expect(result.tools[0].description).toBe('a'.repeat(2045));
+      expect(result.dropped).toHaveLength(0);
+    });
+
+    it('allow length + drop html: still drops tool with HTML chars in description', () => {
+      const tool = makeTool('t', '<b>' + 'a'.repeat(2049) + '</b>');
+      const result = sanitizeToolList([tool], logger, 'drop', 'allow');
+      expect(result.tools).toHaveLength(0);
+      expect(result.dropped[0].reason).toBe('forbidden characters in description');
+    });
+
+    it('allow length + allow html: passes overlong HTML description through unchanged', () => {
+      const desc = '<b>' + 'a'.repeat(2049) + '</b>';
+      const tool = makeTool('t', desc);
+      const result = sanitizeToolList([tool], logger, 'allow', 'allow');
+      expect(result.tools).toHaveLength(1);
+      expect(result.tools[0].description).toBe(desc);
+    });
+  });
+});
+
 describe('applyProviderToolPolicy', () => {
   const tools = [makeTool('alpha'), makeTool('beta'), makeTool('gamma')];
 

src/upstream/upstream-tool-sanitizer.ts

@@ -19,6 +19,7 @@ import type { Logger } from '../core/logger.js';
 import type { UpstreamMcpToolPolicy } from '../types/profile.js';
 
 export type HtmlDescriptionPolicy = 'allow' | 'strip' | 'drop';
+export type ToolDescriptionLengthPolicy = 'drop' | 'truncate' | 'allow';
 
 export interface SanitizationResult {
   tools: Tool[];
@@ -97,15 +98,23 @@ const truncateName = (name: string): string =>
  * Each tool is checked in order:
  *   1. Name length <= 255
  *   2. Name matches [a-zA-Z0-9_-]
- *   3. Description length <= 2048 (if present)
+ *   3. Description length policy (tool_description_length_policy):
+ *      - drop (default): tools with description > 2048 chars are dropped
+ *      - truncate: description is truncated to 2048 chars; tool is kept
+ *      - allow: description length check is skipped; tool passes through unchanged
  *   4. HTML policy (html_description_policy):
  *      - drop (default): tools with <, >, or backtick in description/inputSchema are dropped
  *      - strip: HTML tags stripped from description and inputSchema string values; tool kept
  *      - allow: HTML checks skipped entirely; tool passes through as-is
  *
  * Offending tools are dropped and logged. Safe tools pass through unchanged.
  */
-export function sanitizeToolList(tools: Tool[], logger?: Logger, htmlPolicy: HtmlDescriptionPolicy = 'drop'): SanitizationResult {
+export function sanitizeToolList(
+  tools: Tool[],
+  logger?: Logger,
+  htmlPolicy: HtmlDescriptionPolicy = 'drop',
+  lengthPolicy: ToolDescriptionLengthPolicy = 'drop',
+): SanitizationResult {
   const safe: Tool[] = [];
   const dropped: { name: string; reason: string }[] = [];
 
@@ -131,28 +140,41 @@ export function sanitizeToolList(tools: Tool[], logger?: Logger, htmlPolicy: Htm
       reason = 'invalid characters in tool name';
     } else if (tool.description !== undefined && typeof tool.description !== 'string') {
       reason = 'malformed tool definition: description is not a string';
-    } else if (tool.description && tool.description.length > MAX_DESCRIPTION_LENGTH) {
-      reason = 'tool description too long';
-    } else if (tool.inputSchema !== undefined && (typeof tool.inputSchema !== 'object' || tool.inputSchema === null || Array.isArray(tool.inputSchema))) {
-      reason = 'malformed tool definition: inputSchema is not an object';
-    } else if (htmlPolicy === 'drop') {
-      if (tool.description && DESCRIPTION_FORBIDDEN_CHARS.test(tool.description)) {
-        reason = 'forbidden characters in description';
-        excerpt = firstForbiddenExcerpt(tool.description);
-      } else if (tool.inputSchema && schemaContainsForbiddenChars(tool.inputSchema)) {
-        reason = 'forbidden characters in input schema';
-        const schemaStr = JSON.stringify(tool.inputSchema);
-        excerpt = firstForbiddenExcerpt(schemaStr);
-      }
-    } else if (htmlPolicy === 'strip') {
-      if (tool.description) {
-        tool = { ...tool, description: stripHtmlTags(tool.description) };
+    } else {
+      // Description length policy: applies only to description length, not to other checks.
+      // Evaluated independently so that 'allow'/'truncate' can still fall through to HTML checks.
+      if (tool.description && tool.description.length > MAX_DESCRIPTION_LENGTH) {
+        if (lengthPolicy === 'drop') {
+          reason = 'tool description too long';
+        } else if (lengthPolicy === 'truncate') {
+          tool = { ...tool, description: tool.description.slice(0, MAX_DESCRIPTION_LENGTH) };
+        }
+        // lengthPolicy === 'allow': skip length check, continue to other checks unchanged
       }
-      if (tool.inputSchema) {
-        tool = { ...tool, inputSchema: stripHtmlFromSchema(tool.inputSchema) as Tool['inputSchema'] };
+
+      if (reason === undefined) {
+        if (tool.inputSchema !== undefined && (typeof tool.inputSchema !== 'object' || tool.inputSchema === null || Array.isArray(tool.inputSchema))) {
+          reason = 'malformed tool definition: inputSchema is not an object';
+        } else if (htmlPolicy === 'drop') {
+          if (tool.description && DESCRIPTION_FORBIDDEN_CHARS.test(tool.description)) {
+            reason = 'forbidden characters in description';
+            excerpt = firstForbiddenExcerpt(tool.description);
+          } else if (tool.inputSchema && schemaContainsForbiddenChars(tool.inputSchema)) {
+            reason = 'forbidden characters in input schema';
+            const schemaStr = JSON.stringify(tool.inputSchema);
+            excerpt = firstForbiddenExcerpt(schemaStr);
+          }
+        } else if (htmlPolicy === 'strip') {
+          if (tool.description) {
+            tool = { ...tool, description: stripHtmlTags(tool.description) };
+          }
+          if (tool.inputSchema) {
+            tool = { ...tool, inputSchema: stripHtmlFromSchema(tool.inputSchema) as Tool['inputSchema'] };
+          }
+        }
+        // htmlPolicy === 'allow': skip all HTML checks, pass tool through unchanged
       }
     }
-    // htmlPolicy === 'allow': skip all HTML checks, pass tool through unchanged
 
     if (reason !== undefined) {
       // Coerce non-string names to string for safe logging