@aiwerk/mcp-bridge 1.4.0 → 1.6.0

package/README.md

@@ -14,9 +14,12 @@ Most AI agents connect to MCP servers one-by-one. With 10+ servers, that's 10+ c
 
 **MCP Bridge** solves this:
 - **Router mode**: all servers behind one `mcp` meta-tool (~99% token reduction)
+- **Intent routing**: say what you need in plain language, the bridge finds the right tool
+- **Schema compression**: tool descriptions compressed ~57%, full schema on demand
+- **Security layer**: trust levels, tool deny/allow lists, result size limits
 - **Direct mode**: all tools registered individually with automatic prefixing
 - **3 transports**: stdio, SSE, streamable-http
-- **Built-in catalog**: install popular servers with one command
+- **Built-in catalog**: 14 pre-configured servers, install with one command
 - **Zero config secrets in files**: `${ENV_VAR}` resolution from `.env`
 
 ## Install
@@ -147,6 +150,131 @@ mcp(server="todoist", action="schema", tool="find-tasks")
 
 Set `"enabled": false` to disable compression and return full descriptions.
 
+### Intent Routing
+
+Instead of specifying the exact server and tool, describe what you need:
+
+```
+mcp(action="intent", intent="find my tasks for today")
+```
+
+The bridge uses vector embeddings to match your intent to the right server and tool automatically. Returns the best match with a confidence score and alternatives.
+
+**Embedding providers** (configured via `intentRouting.embedding`):
+
+| Provider | Config | Requires |
+|----------|--------|----------|
+| `gemini` (default for auto) | `GEMINI_API_KEY` in `.env` | Free tier available |
+| `openai` | `OPENAI_API_KEY` in `.env` | Paid API |
+| `ollama` | Local Ollama running | No API key |
+| `keyword` | Nothing | Offline fallback, less accurate |
+
+```json
+"intentRouting": {
+  "embedding": "auto",
+  "minScore": 0.3
+}
+```
+
+- `auto` (default): tries gemini, openai, ollama, then keyword - in order of availability
+- `minScore`: minimum confidence to return a match (0-1, default: 0.3)
+- Index is built lazily on first `action=intent` call
+
+### Security
+
+Three layers of protection for tool results:
+
+#### Trust Levels
+
+Per-server control over how results are passed to the agent:
+
+```json
+"servers": {
+  "my-trusted-server": {
+    "trust": "trusted"
+  },
+  "unknown-server": {
+    "trust": "untrusted"
+  },
+  "sketchy-server": {
+    "trust": "sanitize"
+  }
+}
+```
+
+| Level | Behavior |
+|-------|----------|
+| `trusted` (default) | Results pass through as-is |
+| `untrusted` | Results tagged with `_trust: "untrusted"` metadata |
+| `sanitize` | HTML tags stripped, prompt injection patterns removed |
+
+#### Tool Filter
+
+Control which tools are visible and callable per server:
+
+```json
+"servers": {
+  "github": {
+    "toolFilter": {
+      "deny": ["delete_repository"],
+      "allow": ["list_repos", "create_issue", "search_code"]
+    }
+  }
+}
+```
+
+- `deny`: block specific dangerous tools
+- `allow`: whitelist mode - only these tools are visible
+- If both: allowed tools minus denied ones
+- Applied in both tool listing and execution (defense in depth)
+
+### Adaptive Promotion
+
+Frequently used tools can be automatically "promoted" to standalone tools alongside the `mcp` meta-tool. The promotion system tracks usage and reports which tools qualify — the host environment (e.g., OpenClaw plugin) decides how to register them.
+
+```json
+"adaptivePromotion": {
+  "enabled": true,
+  "maxPromoted": 10,
+  "minCalls": 3,
+  "windowMs": 86400000,
+  "decayMs": 172800000
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `enabled` | `false` | Opt-in: must be explicitly enabled |
+| `maxPromoted` | `10` | Maximum number of tools to promote |
+| `minCalls` | `3` | Minimum calls within window to qualify |
+| `windowMs` | `86400000` (24h) | Time window for counting calls |
+| `decayMs` | `172800000` (48h) | Demote tools with no calls in this period |
+
+Use `action="promotions"` to check current promotion state:
+```
+mcp(action="promotions")
+```
+
+Returns promoted tools (sorted by frequency) and full usage stats. All tracking is in-memory — promotion rebuilds naturally from usage after restart.
+
+#### Max Result Size
+
+Prevent oversized responses from consuming your context:
+
+```json
+{
+  "maxResultChars": 50000,
+  "servers": {
+    "verbose-server": {
+      "maxResultChars": 10000
+    }
+  }
+}
+```
+
+- Global default + per-server override
+- Truncated results include `_truncated: true` and `_originalLength`
+
 ### Modes
 
 | Mode | Tools exposed | Best for |
@@ -248,17 +376,18 @@ const result = await router.dispatch("todoist", "call", "find-tasks", { query: "
 ## Architecture
 
 ```
-┌─────────────────┐     ┌──────────────────────────────────────┐
-│  Claude Desktop  │     │  MCP Bridge                          │
-│  Cursor          │◄───►│                                      │
-│  Windsurf        │stdio│  ┌─────────┐  ┌──────────────────┐  │
-│  OpenClaw        │     │  │ Router / │  │ Backend servers:  │  │
-│  Any MCP client  │     │  │ Direct   │──│ • todoist (stdio) │  │
-└─────────────────┘     │  │ mode     │  │ • github (stdio)  │  │
-                        │  └─────────┘  │ • notion (stdio)  │  │
-                        │               │ • stripe (sse)    │  │
-                        │               └──────────────────┘  │
-                        └──────────────────────────────────────┘
+┌─────────────────┐     ┌──────────────────────────────────────────────┐
+│  Claude Desktop  │     │  MCP Bridge                                  │
+│  Cursor          │◄───►│                                              │
+│  Windsurf        │stdio│  ┌──────────┐  ┌────────┐  ┌────────────┐  │
+│  OpenClaw        │ SSE │  │  Router   │  │Security│  │  Backend   │  │
+│  Any MCP client  │ HTTP│  │  Intent   │─►│ Trust  │─►│  servers:  │  │
+└─────────────────┘     │  │  Schema   │  │ Filter │  │  • todoist │  │
+                        │  │  Compress │  │ Limit  │  │  • github  │  │
+                        │  └──────────┘  └────────┘  │  • notion  │  │
+                        │                            │  • stripe  │  │
+                        │                            └────────────┘  │
+                        └──────────────────────────────────────────────┘
 ```
 
 ## Related

package/dist/src/adaptive-promotion.d.ts

@@ -0,0 +1,33 @@
+import type { Logger } from "./types.js";
+export interface PromotionConfig {
+    enabled?: boolean;
+    maxPromoted?: number;
+    windowMs?: number;
+    minCalls?: number;
+    decayMs?: number;
+}
+export declare class AdaptivePromotion {
+    private readonly enabled;
+    private readonly maxPromoted;
+    private readonly windowMs;
+    private readonly minCalls;
+    private readonly decayMs;
+    private readonly logger;
+    private readonly usage;
+    constructor(config: PromotionConfig, logger: Logger);
+    private key;
+    recordCall(server: string, tool: string): void;
+    getPromotedTools(): Array<{
+        server: string;
+        tool: string;
+        callCount: number;
+    }>;
+    isPromoted(server: string, tool: string): boolean;
+    getStats(): Array<{
+        server: string;
+        tool: string;
+        callCount: number;
+        lastCall: number;
+    }>;
+    private cleanup;
+}

package/dist/src/adaptive-promotion.js

@@ -0,0 +1,95 @@
+const DEFAULT_WINDOW_MS = 86_400_000; // 24h
+const DEFAULT_DECAY_MS = 172_800_000; // 48h
+const DEFAULT_MAX_PROMOTED = 10;
+const DEFAULT_MIN_CALLS = 3;
+export class AdaptivePromotion {
+    enabled;
+    maxPromoted;
+    windowMs;
+    minCalls;
+    decayMs;
+    logger;
+    usage = new Map();
+    constructor(config, logger) {
+        this.enabled = config.enabled ?? false;
+        this.maxPromoted = config.maxPromoted ?? DEFAULT_MAX_PROMOTED;
+        this.windowMs = config.windowMs ?? DEFAULT_WINDOW_MS;
+        this.minCalls = config.minCalls ?? DEFAULT_MIN_CALLS;
+        this.decayMs = config.decayMs ?? DEFAULT_DECAY_MS;
+        this.logger = logger;
+    }
+    key(server, tool) {
+        return `${server}::${tool}`;
+    }
+    recordCall(server, tool) {
+        if (!this.enabled)
+            return;
+        const k = this.key(server, tool);
+        let entry = this.usage.get(k);
+        if (!entry) {
+            entry = { server, tool, callTimestamps: [] };
+            this.usage.set(k, entry);
+        }
+        entry.callTimestamps.push(Date.now());
+        this.cleanup();
+    }
+    getPromotedTools() {
+        if (!this.enabled)
+            return [];
+        const now = Date.now();
+        const cutoff = now - this.windowMs;
+        const candidates = [];
+        for (const entry of this.usage.values()) {
+            const recentCalls = entry.callTimestamps.filter(t => t > cutoff);
+            if (recentCalls.length >= this.minCalls) {
+                candidates.push({
+                    server: entry.server,
+                    tool: entry.tool,
+                    callCount: recentCalls.length
+                });
+            }
+        }
+        candidates.sort((a, b) => b.callCount - a.callCount);
+        return candidates.slice(0, this.maxPromoted);
+    }
+    isPromoted(server, tool) {
+        if (!this.enabled)
+            return false;
+        return this.getPromotedTools().some(p => p.server === server && p.tool === tool);
+    }
+    getStats() {
+        if (!this.enabled)
+            return [];
+        const now = Date.now();
+        const cutoff = now - this.windowMs;
+        const stats = [];
+        for (const entry of this.usage.values()) {
+            const recentCalls = entry.callTimestamps.filter(t => t > cutoff);
+            if (recentCalls.length > 0) {
+                stats.push({
+                    server: entry.server,
+                    tool: entry.tool,
+                    callCount: recentCalls.length,
+                    lastCall: Math.max(...entry.callTimestamps)
+                });
+            }
+        }
+        return stats;
+    }
+    cleanup() {
+        const now = Date.now();
+        const windowCutoff = now - this.windowMs;
+        const decayCutoff = now - this.decayMs;
+        for (const [k, entry] of this.usage.entries()) {
+            // Remove timestamps older than the window
+            entry.callTimestamps = entry.callTimestamps.filter(t => t > windowCutoff);
+            // Remove entire entry if no calls within decay period
+            const lastCall = entry.callTimestamps.length > 0
+                ? Math.max(...entry.callTimestamps)
+                : 0;
+            if (lastCall === 0 || lastCall < decayCutoff) {
+                this.usage.delete(k);
+            }
+        }
+    }
+}

package/dist/src/mcp-router.d.ts

@@ -35,6 +35,19 @@ export type RouterDispatchResponse = {
 } | {
     action: "status";
     servers: RouterServerStatus[];
+} | {
+    action: "promotions";
+    promoted: Array<{
+        server: string;
+        tool: string;
+        callCount: number;
+    }>;
+    stats: Array<{
+        server: string;
+        tool: string;
+        callCount: number;
+        lastCall: string;
+    }>;
 } | {
     action: "intent";
     intent: string;
@@ -68,12 +81,20 @@ export declare class McpRouter {
     private readonly maxConcurrent;
     private readonly states;
     private intentRouter;
+    private readonly promotion;
     constructor(servers: Record<string, McpServerConfig>, clientConfig: McpClientConfig, logger: Logger, transportRefs?: Partial<RouterTransportRefs>);
     static generateDescription(servers: Record<string, McpServerConfig>): string;
     dispatch(server?: string, action?: string, tool?: string, params?: any): Promise<RouterDispatchResponse>;
     getToolList(server: string): Promise<RouterToolHint[]>;
     private resolveIntent;
     private getStatus;
+    getPromotedTools(): Array<{
+        server: string;
+        tool: string;
+        toolHint: RouterToolHint;
+        inputSchema: any;
+    }>;
+    private getPromotionStats;
     disconnectAll(): Promise<void>;
     private ensureConnected;
     private enforceMaxConcurrent;

package/dist/src/mcp-router.js

@@ -5,6 +5,8 @@ import { fetchToolsList, initializeProtocol, PACKAGE_VERSION } from "./protocol.
 import { compressDescription } from "./schema-compression.js";
 import { IntentRouter } from "./intent-router.js";
 import { createEmbeddingProvider } from "./embeddings.js";
+import { isToolAllowed, processResult } from "./security.js";
+import { AdaptivePromotion } from "./adaptive-promotion.js";
 const DEFAULT_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
 const DEFAULT_MAX_CONCURRENT = 5;
 export class McpRouter {
@@ -16,6 +18,7 @@ export class McpRouter {
     maxConcurrent;
     states = new Map();
     intentRouter = null;
+    promotion = null;
     constructor(servers, clientConfig, logger, transportRefs) {
         this.servers = servers;
         this.clientConfig = clientConfig;
@@ -27,6 +30,9 @@ export class McpRouter {
         };
         this.idleTimeoutMs = clientConfig.routerIdleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
         this.maxConcurrent = clientConfig.routerMaxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+        if (clientConfig.adaptivePromotion?.enabled) {
+            this.promotion = new AdaptivePromotion(clientConfig.adaptivePromotion, logger);
+        }
     }
     static generateDescription(servers) {
         const serverNames = Object.keys(servers);
@@ -48,6 +54,10 @@ export class McpRouter {
             if (normalizedAction === "status") {
                 return this.getStatus();
             }
+            // Promotions action: return promotion stats
+            if (normalizedAction === "promotions") {
+                return this.getPromotionStats();
+            }
             // Intent action: find server+tool from natural language
             if (normalizedAction === "intent") {
                 const intent = params?.intent || tool;
@@ -121,6 +131,11 @@ export class McpRouter {
             if (!state.toolNames.includes(tool)) {
                 return this.error("unknown_tool", `Tool '${tool}' not found on server '${server}'`, state.toolNames);
             }
+            // Defense in depth: double-check tool filter
+            const serverConfig = this.servers[server];
+            if (!isToolAllowed(tool, serverConfig)) {
+                return this.error("unknown_tool", `Tool '${tool}' is not allowed on server '${server}'`, state.toolNames);
+            }
             this.markUsed(server);
             const response = await state.transport.sendRequest({
                 jsonrpc: "2.0",
@@ -133,7 +148,13 @@ export class McpRouter {
             if (response.error) {
                 return this.error("mcp_error", response.error.message, undefined, response.error.code);
             }
-            return { server, action: "call", tool, result: response.result };
+            // Record usage for adaptive promotion
+            if (this.promotion) {
+                this.promotion.recordCall(server, tool);
+            }
+            // Security pipeline: truncate → sanitize → trust-tag
+            const result = processResult(response.result, server, serverConfig, this.clientConfig);
+            return { server, action: "call", tool, result };
         }
         catch (error) {
             return this.error("mcp_error", error instanceof Error ? error.message : String(error));
@@ -148,7 +169,9 @@ export class McpRouter {
             this.markUsed(server);
             return state.toolsCache;
         }
-        const tools = await fetchToolsList(state.transport);
+        const allTools = await fetchToolsList(state.transport);
+        const serverConfig = this.servers[server];
+        const tools = allTools.filter((tool) => isToolAllowed(tool.name, serverConfig));
         state.toolNames = tools.map((tool) => tool.name);
         // Store full tool metadata for action=schema
         state.fullToolsMap = new Map(tools.map((tool) => [tool.name, { description: tool.description || "", inputSchema: tool.inputSchema }]));
@@ -227,6 +250,37 @@ export class McpRouter {
         });
         return { action: "status", servers: serverStatuses };
     }
+    getPromotedTools() {
+        if (!this.promotion)
+            return [];
+        const promoted = this.promotion.getPromotedTools();
+        const result = [];
+        for (const p of promoted) {
+            const state = this.states.get(p.server);
+            const fullTool = state?.fullToolsMap?.get(p.tool);
+            const hint = state?.toolsCache?.find(t => t.name === p.tool);
+            if (fullTool && hint) {
+                result.push({
+                    server: p.server,
+                    tool: p.tool,
+                    toolHint: hint,
+                    inputSchema: fullTool.inputSchema
+                });
+            }
+        }
+        return result;
+    }
+    getPromotionStats() {
+        if (!this.promotion) {
+            return { action: "promotions", promoted: [], stats: [] };
+        }
+        const promoted = this.promotion.getPromotedTools();
+        const stats = this.promotion.getStats().map(s => ({
+            ...s,
+            lastCall: new Date(s.lastCall).toISOString()
+        }));
+        return { action: "promotions", promoted, stats };
+    }
     async disconnectAll() {
         for (const serverName of Object.keys(this.servers)) {
             await this.disconnectServer(serverName);

package/dist/src/security.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Security processing for MCP tool results.
+ *
+ * Pipeline order: truncate → sanitize → trust-tag
+ */
+import type { McpServerConfig, McpClientConfig } from "./types.js";
+/**
+ * Sanitize a tool result by stripping HTML and prompt injection patterns.
+ */
+export declare function sanitizeResult(result: any): any;
+/**
+ * Check if a tool is allowed by the server's toolFilter config.
+ * Returns true if the tool should be visible/callable.
+ */
+export declare function isToolAllowed(toolName: string, serverConfig: McpServerConfig): boolean;
+/**
+ * Apply max result size truncation.
+ * Returns the result as-is or a truncation wrapper.
+ */
+export declare function applyMaxResultSize(result: any, serverConfig: McpServerConfig, clientConfig: McpClientConfig): any;
+/**
+ * Apply trust level wrapping/sanitization.
+ */
+export declare function applyTrustLevel(result: any, serverName: string, serverConfig: McpServerConfig): any;
+/**
+ * Full security pipeline: truncate → sanitize → trust-tag
+ */
+export declare function processResult(result: any, serverName: string, serverConfig: McpServerConfig, clientConfig: McpClientConfig): any;

package/dist/src/security.js

@@ -0,0 +1,127 @@
+/**
+ * Security processing for MCP tool results.
+ *
+ * Pipeline order: truncate → sanitize → trust-tag
+ */
+// Prompt injection patterns to strip (case-insensitive)
+const INJECTION_PATTERNS = [
+    /ignore\s+(all\s+)?previous\s+instructions/gi,
+    /ignore\s+(all\s+)?prior\s+instructions/gi,
+    /disregard\s+(all\s+)?previous\s+instructions/gi,
+    /you\s+are\s+now\b/gi,
+    /^system\s*:/gim,
+    /\bact\s+as\s+(a|an)\s+/gi,
+    /pretend\s+you\s+are\b/gi,
+    /from\s+now\s+on\s+you\s+are\b/gi,
+    /new\s+instructions\s*:/gi,
+    /override\s+(all\s+)?instructions/gi,
+];
+function stripHtmlTags(text) {
+    return text.replace(/<[^>]*>/g, "");
+}
+function stripInjectionPatterns(text) {
+    let result = text;
+    for (const pattern of INJECTION_PATTERNS) {
+        // Reset lastIndex for global regexes
+        pattern.lastIndex = 0;
+        result = result.replace(pattern, "");
+    }
+    return result;
+}
+function sanitizeString(text) {
+    return stripInjectionPatterns(stripHtmlTags(text));
+}
+/**
+ * Sanitize a tool result by stripping HTML and prompt injection patterns.
+ */
+export function sanitizeResult(result) {
+    if (typeof result === "string") {
+        return sanitizeString(result);
+    }
+    if (Array.isArray(result)) {
+        return result.map((item) => sanitizeResult(item));
+    }
+    if (result !== null && typeof result === "object") {
+        // MCP standard content array
+        if (Array.isArray(result.content)) {
+            return {
+                ...result,
+                content: result.content.map((item) => {
+                    if (item.type === "text" && typeof item.text === "string") {
+                        return { ...item, text: sanitizeString(item.text) };
+                    }
+                    return item;
+                }),
+            };
+        }
+        // Recursively sanitize object values
+        const sanitized = {};
+        for (const [key, value] of Object.entries(result)) {
+            sanitized[key] = sanitizeResult(value);
+        }
+        return sanitized;
+    }
+    return result;
+}
+/**
+ * Check if a tool is allowed by the server's toolFilter config.
+ * Returns true if the tool should be visible/callable.
+ */
+export function isToolAllowed(toolName, serverConfig) {
+    const filter = serverConfig.toolFilter;
+    if (!filter)
+        return true;
+    const { allow, deny } = filter;
+    if (allow && allow.length > 0) {
+        // Whitelist mode: only allowed tools, minus denied
+        if (!allow.includes(toolName))
+            return false;
+    }
+    if (deny && deny.length > 0) {
+        if (deny.includes(toolName))
+            return false;
+    }
+    return true;
+}
+/**
+ * Apply max result size truncation.
+ * Returns the result as-is or a truncation wrapper.
+ */
+export function applyMaxResultSize(result, serverConfig, clientConfig) {
+    const limit = serverConfig.maxResultChars ?? clientConfig.maxResultChars;
+    if (limit === undefined)
+        return result;
+    const serialized = JSON.stringify(result);
+    if (serialized.length <= limit)
+        return result;
+    return {
+        _truncated: true,
+        _originalLength: serialized.length,
+        result: serialized.slice(0, limit),
+    };
+}
+/**
+ * Apply trust level wrapping/sanitization.
+ */
+export function applyTrustLevel(result, serverName, serverConfig) {
+    const trust = serverConfig.trust ?? "trusted";
+    switch (trust) {
+        case "trusted":
+            return result;
+        case "untrusted":
+            return { _trust: "untrusted", _server: serverName, result };
+        case "sanitize":
+            return sanitizeResult(result);
+        default:
+            return result;
+    }
+}
+/**
+ * Full security pipeline: truncate → sanitize → trust-tag
+ */
+export function processResult(result, serverName, serverConfig, clientConfig) {
+    let processed = applyMaxResultSize(result, serverConfig, clientConfig);
+    // Sanitize step (only for trust=sanitize, handled inside applyTrustLevel)
+    processed = applyTrustLevel(processed, serverName, serverConfig);
+    return processed;
+}

package/dist/src/types.d.ts

@@ -14,6 +14,12 @@ export interface McpServerConfig {
     args?: string[];
     env?: Record<string, string>;
     framing?: "auto" | "lsp" | "newline";
+    trust?: "trusted" | "untrusted" | "sanitize";
+    toolFilter?: {
+        deny?: string[];
+        allow?: string[];
+    };
+    maxResultChars?: number;
 }
 export interface McpClientConfig {
     servers: Record<string, McpServerConfig>;
@@ -33,6 +39,14 @@ export interface McpClientConfig {
         model?: string;
         minScore?: number;
     };
+    maxResultChars?: number;
+    adaptivePromotion?: {
+        enabled?: boolean;
+        maxPromoted?: number;
+        windowMs?: number;
+        minCalls?: number;
+        decayMs?: number;
+    };
 }
 export interface McpTool {
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwerk/mcp-bridge",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Standalone MCP server that multiplexes multiple MCP servers into one interface",
   "type": "module",
   "main": "./dist/src/index.js",