@aiwerk/mcp-bridge 1.5.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

@@ -6,6 +6,7 @@ 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 {
@@ -17,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;
@@ -28,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);
@@ -49,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;
@@ -139,6 +148,10 @@ export class McpRouter {
             if (response.error) {
                 return this.error("mcp_error", response.error.message, undefined, response.error.code);
             }
+            // 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 };
@@ -237,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/types.d.ts

@@ -40,6 +40,13 @@ export interface McpClientConfig {
         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.5.0",
+  "version": "1.6.0",
   "description": "Standalone MCP server that multiplexes multiple MCP servers into one interface",
   "type": "module",
   "main": "./dist/src/index.js",