@aiwerk/mcp-bridge 1.0.1 → 1.1.0

package/README.md

@@ -1,6 +1,19 @@
 # @aiwerk/mcp-bridge
 
-Standalone MCP server that multiplexes multiple MCP servers into one interface. Works with Claude Desktop, Cursor, Windsurf, Cline, or any MCP client.
+Multiplex multiple MCP servers into one interface. One config, one connection, all your tools.
+
+Works with **Claude Desktop**, **Cursor**, **Windsurf**, **Cline**, **OpenClaw**, or any MCP client.
+
+## Why?
+
+Most AI agents connect to MCP servers one-by-one. With 10+ servers, that's 10+ connections, 200+ tools in context, and thousands of wasted tokens.
+
+**MCP Bridge** solves this:
+- **Router mode**: all servers behind one `mcp` meta-tool (~99% token reduction)
+- **Direct mode**: all tools registered individually with automatic prefixing
+- **3 transports**: stdio, SSE, streamable-http
+- **Built-in catalog**: install popular servers with one command
+- **Zero config secrets in files**: `${ENV_VAR}` resolution from `.env`
 
 ## Install
 
@@ -11,22 +24,62 @@ npm install -g @aiwerk/mcp-bridge
 ## Quick Start
 
 ```bash
-# Initialize config directory
+# 1. Initialize config
 mcp-bridge init
 
-# Edit your config
-vi ~/.mcp-bridge/config.json
-
-# Install a server from the catalog
+# 2. Install a server from the catalog
 mcp-bridge install todoist
 
-# Start (stdio mode for MCP clients)
+# 3. Add your API key
+echo "TODOIST_API_TOKEN=your-token" >> ~/.mcp-bridge/.env
+
+# 4. Start (stdio mode — connects to any MCP client)
 mcp-bridge
 ```
 
+## Use with Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "bridge": {
+      "command": "mcp-bridge",
+      "args": []
+    }
+  }
+}
+```
+
+## Use with Cursor / Windsurf
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "bridge": {
+      "command": "mcp-bridge",
+      "args": ["--config", "/path/to/config.json"]
+    }
+  }
+}
+```
+
+## Use with OpenClaw
+
+Install as a plugin (handles everything automatically):
+
+```bash
+openclaw plugins install @aiwerk/openclaw-mcp-bridge
+```
+
+See [@aiwerk/openclaw-mcp-bridge](https://github.com/AIWerk/openclaw-mcp-bridge) for details.
+
 ## Configuration
 
-Config location: `~/.mcp-bridge/config.json`
+Config: `~/.mcp-bridge/config.json` | Secrets: `~/.mcp-bridge/.env`
 
 ```json
 {
@@ -36,19 +89,22 @@ Config location: `~/.mcp-bridge/config.json`
       "transport": "stdio",
       "command": "npx",
       "args": ["-y", "@doist/todoist-ai"],
-      "env": {
-        "TODOIST_API_KEY": "${TODOIST_API_TOKEN}"
-      },
+      "env": { "TODOIST_API_KEY": "${TODOIST_API_TOKEN}" },
       "description": "Task management"
     },
     "github": {
       "transport": "stdio",
-      "command": "docker",
-      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
-      "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
-      },
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" },
       "description": "GitHub repos, issues, PRs"
+    },
+    "notion": {
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-notion"],
+      "env": { "NOTION_API_KEY": "${NOTION_TOKEN}" },
+      "description": "Notion pages and databases"
     }
   },
   "toolPrefix": true,
@@ -57,61 +113,123 @@ Config location: `~/.mcp-bridge/config.json`
 }
 ```
 
-Environment variables go in `~/.mcp-bridge/.env`:
+### Modes
+
+| Mode | Tools exposed | Best for |
+|------|--------------|----------|
+| `router` (default) | Single `mcp` meta-tool | 3+ servers, token-conscious agents |
+| `direct` | All tools individually | Few servers, simple agents |
+
+**Router mode** — the agent calls `mcp(server="todoist", action="list")` to discover, then `mcp(server="todoist", tool="find-tasks", params={...})` to execute.
+
+**Direct mode** — tools are registered as `todoist_find_tasks`, `github_list_repos`, etc.
+
+### Transports
+
+| Transport | Config key | Use case |
+|-----------|-----------|----------|
+| `stdio` | `command`, `args` | Local CLI servers (most common) |
+| `sse` | `url`, `headers` | Remote SSE servers |
+| `streamable-http` | `url`, `headers` | Modern HTTP-based servers |
+
+### Environment variables
+
+Secrets go in `~/.mcp-bridge/.env` (chmod 600 on init):
 
 ```
 TODOIST_API_TOKEN=your-token-here
 GITHUB_TOKEN=ghp_xxxxx
+NOTION_TOKEN=ntn_xxxxx
 ```
 
-## Modes
+Use `${VAR_NAME}` in config — resolved from `.env` + system env.
 
-**Router mode** (default) — exposes a single `mcp` meta-tool. The agent calls `mcp(server="todoist", action="list")` to discover tools, then `mcp(server="todoist", tool="get_tasks", params={...})` to call them. ~99% reduction in tool registration tokens.
+## CLI Reference
 
-**Direct mode** — registers all tools from all servers individually (`todoist_get_tasks`, `github_list_repos`, etc.). Better for few servers or simpler agents.
+```bash
+mcp-bridge                        # Start in stdio mode (default)
+mcp-bridge --sse --port 3000      # Start as SSE server
+mcp-bridge --http --port 3000     # Start as HTTP server
+mcp-bridge --verbose              # Info-level logs to stderr
+mcp-bridge --debug                # Full protocol logs to stderr
+mcp-bridge --config ./my.json     # Custom config file
+
+mcp-bridge init                   # Create ~/.mcp-bridge/ with template
+mcp-bridge install <server>       # Install from catalog
+mcp-bridge catalog                # List available servers
+mcp-bridge servers                # List configured servers
+mcp-bridge search <query>         # Search catalog by keyword
+mcp-bridge update [--check]       # Check for / install updates
+mcp-bridge --version              # Print version
+```
 
-## Claude Desktop
+## Server Catalog
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+Built-in catalog with pre-configured servers:
 
-```json
-{
-  "mcpServers": {
-    "mcp-bridge": {
-      "command": "mcp-bridge",
-      "args": []
-    }
-  }
-}
-```
-
-## CLI
+| Server | Transport | Description |
+|--------|-----------|-------------|
+| todoist | stdio | Task management |
+| github | stdio | Repos, issues, PRs |
+| notion | stdio | Pages and databases |
+| stripe | stdio | Payments and billing |
+| linear | stdio | Project management |
+| google-maps | stdio | Places, geocoding, directions |
+| hetzner | stdio | Cloud infrastructure |
+| miro | stdio | Collaborative whiteboard |
+| wise | stdio | International payments |
+| tavily | stdio | AI-optimized web search |
+| apify | streamable-http | Web scraping and automation |
 
 ```bash
-mcp-bridge                        # stdio mode (default)
-mcp-bridge --verbose              # info-level logs to stderr
-mcp-bridge --debug                # full protocol logs to stderr
-mcp-bridge --config ./config.json # custom config file
-
-mcp-bridge init                   # create ~/.mcp-bridge/ with template
-mcp-bridge install <server>       # install from catalog
-mcp-bridge catalog                # list available servers
-mcp-bridge servers                # list configured servers
-mcp-bridge search <query>         # search catalog
-mcp-bridge update --check         # check for updates
-mcp-bridge update                 # install updates
+mcp-bridge install todoist    # Interactive setup with API key prompt
+mcp-bridge catalog            # Full list
+mcp-bridge search payments    # Search by keyword
 ```
 
 ## Library Usage
 
+Use as a dependency in your own MCP server or OpenClaw plugin:
+
 ```typescript
 import { McpRouter, StandaloneServer, loadConfig } from "@aiwerk/mcp-bridge";
 
+// Quick start
 const config = loadConfig({ configPath: "./config.json" });
 const server = new StandaloneServer(config, console);
 await server.startStdio();
 ```
 
+```typescript
+// Use the router directly
+import { McpRouter } from "@aiwerk/mcp-bridge";
+
+const router = new McpRouter(servers, config, logger);
+const result = await router.dispatch("todoist", "call", "find-tasks", { query: "today" });
+```
+
+## 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)    │  │
+                        │               └──────────────────┘  │
+                        └──────────────────────────────────────┘
+```
+
+## Related
+
+- **[@aiwerk/openclaw-mcp-bridge](https://github.com/AIWerk/openclaw-mcp-bridge)** — OpenClaw plugin wrapper (uses this package as core)
+- **[MCP Specification](https://spec.modelcontextprotocol.io)** — Model Context Protocol spec
+- **[Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers)** — Community server directory
+
 ## License
 
-MIT
+MIT — [AIWerk](https://aiwerk.ch)

package/dist/src/index.d.ts

@@ -13,3 +13,4 @@ export { pickRegisteredToolName } from "./tool-naming.js";
 export { StandaloneServer } from "./standalone-server.js";
 export { checkForUpdate, getUpdateNotice, runUpdate, resetNoticeFlag } from "./update-checker.js";
 export type { UpdateInfo } from "./update-checker.js";
+export { filterServers, buildFilteredDescription } from "./smart-filter.js";

package/dist/src/index.js

@@ -19,3 +19,5 @@ export { pickRegisteredToolName } from "./tool-naming.js";
 export { StandaloneServer } from "./standalone-server.js";
 // Update checker
 export { checkForUpdate, getUpdateNotice, runUpdate, resetNoticeFlag } from "./update-checker.js";
+// Smart filter
+export { filterServers, buildFilteredDescription } from "./smart-filter.js";

package/dist/src/smart-filter.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Smart Filter v2 - Phase 1: Keyword-based filtering
+ * Zero external dependencies, graceful degradation
+ */
+import type { Logger, McpServerConfig, McpTool } from "./types.js";
+/** Smart filter configuration for router mode. */
+export interface SmartFilterConfig {
+    enabled?: boolean;
+    embedding?: "auto" | "ollama" | "openai" | "gemini" | "keyword";
+    topServers?: number;
+    hardCap?: number;
+    topTools?: number;
+    serverThreshold?: number;
+    toolThreshold?: number;
+    fallback?: "keyword";
+    alwaysInclude?: string[];
+    timeoutMs?: number;
+    telemetry?: boolean;
+}
+/** Extended server config with optional keywords for smart filter. */
+export interface PluginServerConfig extends McpServerConfig {
+    keywords?: string[];
+}
+export type OpenClawLogger = Logger;
+export interface FilterableServer {
+    name: string;
+    description: string;
+    keywords: string[];
+    tools: McpTool[];
+}
+export interface FilterResult {
+    servers: FilterableServer[];
+    tools: Array<{
+        serverId: string;
+        tool: McpTool;
+    }>;
+    metadata: {
+        queryUsed: string;
+        totalServersBeforeFilter: number;
+        totalToolsBeforeFilter: number;
+        filterMode: "keyword" | "disabled";
+        timeoutOccurred: boolean;
+        confidenceScore?: number;
+    };
+}
+export interface UserTurn {
+    content: string;
+    timestamp: number;
+}
+/**
+ * Smart Filter implementation - Phase 1
+ */
+export declare class SmartFilter {
+    private config;
+    private logger;
+    constructor(config: SmartFilterConfig, logger: OpenClawLogger);
+    /**
+     * Main filter entry point
+     */
+    filter(servers: Record<string, PluginServerConfig>, allTools: Map<string, McpTool[]>, userTurns: UserTurn[]): Promise<FilterResult>;
+    private performFilter;
+    /**
+     * Extract meaningful intent from last 1-3 user turns
+     */
+    private synthesizeQuery;
+    private extractMeaningfulContent;
+    private prepareFilterableServers;
+    private normalizeKeywords;
+    /**
+     * Score servers using weighted overlap scoring
+     */
+    private scoreServers;
+    private tokenize;
+    private calculateServerScore;
+    private getSemanticScore;
+    private countOverlap;
+    /**
+     * Select servers using dynamic topServers with confidence-based expansion
+     */
+    private selectServers;
+    /**
+     * Filter tools within selected servers
+     */
+    private filterTools;
+    private calculateToolScore;
+    private calculateConfidenceScore;
+    private createUnfilteredResult;
+    private logTelemetry;
+}
+export declare const DEFAULTS: Required<SmartFilterConfig>;
+/** Lowercase, split on whitespace + punctuation, preserve numbers, drop empties. */
+export declare function tokenize(text: string): string[];
+/** Normalize keywords: lowercase, trim, dedup, strip empties, cap at MAX_KEYWORDS. */
+export declare function validateKeywords(raw: string[]): string[];
+/**
+ * Extract a meaningful intent string from the last 1-3 user turns.
+ * Returns null if no meaningful query can be extracted.
+ */
+export declare function synthesizeQuery(userTurns: string[]): string | null;
+export interface ServerScore {
+    name: string;
+    score: number;
+}
+/**
+ * Score a single server against a query using weighted word overlap.
+ * desc_matches * 1.0 + kw_only_matches * 0.5, normalized by query length.
+ */
+export declare function scoreServer(queryTokens: string[], serverName: string, description: string, keywords: string[]): number;
+/** Score all servers, return sorted highest-first. */
+export declare function scoreAllServers(queryTokens: string[], servers: Record<string, PluginServerConfig>): ServerScore[];
+/**
+ * Select top servers with dynamic expansion toward hardCap.
+ * If top score < threshold AND gap small → show all (true uncertainty).
+ */
+export declare function selectTopServers(scores: ServerScore[], topServers: number, hardCap: number, threshold: number, alwaysInclude: string[]): string[];
+export interface SmartFilterResult {
+    filteredServers: string[];
+    allServers: string[];
+    query: string | null;
+    scores: ServerScore[];
+    reason: "filtered" | "no-query" | "timeout" | "error" | "disabled";
+}
+/**
+ * Run the smart filter. Returns the list of server names to include.
+ * Guarantees: never throws, never blocks longer than timeoutMs.
+ */
+export declare function filterServers(servers: Record<string, PluginServerConfig>, userTurns: string[], config: SmartFilterConfig, logger?: OpenClawLogger): SmartFilterResult;
+/** Build a filtered router tool description string. */
+export declare function buildFilteredDescription(allServers: Record<string, PluginServerConfig>, filteredNames: string[]): string;

package/dist/src/smart-filter.js

@@ -0,0 +1,559 @@
+/**
+ * Smart Filter v2 - Phase 1: Keyword-based filtering
+ * Zero external dependencies, graceful degradation
+ */
+/**
+ * Smart Filter implementation - Phase 1
+ */
+export class SmartFilter {
+    config;
+    logger;
+    constructor(config, logger) {
+        // Apply defaults
+        this.config = {
+            enabled: config.enabled ?? false,
+            embedding: config.embedding ?? "auto",
+            topServers: config.topServers ?? 5,
+            hardCap: config.hardCap ?? 8,
+            topTools: config.topTools ?? 10,
+            serverThreshold: config.serverThreshold ?? 0.01, // Very low threshold for maximum recall
+            toolThreshold: config.toolThreshold ?? 0.05, // Much lower threshold for better recall  
+            fallback: config.fallback ?? "keyword",
+            alwaysInclude: config.alwaysInclude ?? [],
+            timeoutMs: config.timeoutMs ?? 500,
+            telemetry: config.telemetry ?? false,
+        };
+        this.logger = logger;
+    }
+    /**
+     * Main filter entry point
+     */
+    async filter(servers, allTools, userTurns) {
+        if (!this.config.enabled) {
+            return this.createUnfilteredResult(servers, allTools, "disabled");
+        }
+        const startTime = Date.now();
+        let timeoutOccurred = false;
+        try {
+            // Set up timeout
+            const timeoutPromise = new Promise((resolve) => {
+                setTimeout(() => {
+                    timeoutOccurred = true;
+                    this.logger.warn(`[smart-filter] Filter timeout after ${this.config.timeoutMs}ms, falling back to show all`);
+                    resolve(this.createUnfilteredResult(servers, allTools, "keyword"));
+                }, this.config.timeoutMs);
+            });
+            const filterPromise = this.performFilter(servers, allTools, userTurns);
+            const result = await Promise.race([filterPromise, timeoutPromise]);
+            result.metadata.timeoutOccurred = timeoutOccurred;
+            const duration = Date.now() - startTime;
+            if (this.config.telemetry) {
+                this.logTelemetry(result, duration);
+            }
+            return result;
+        }
+        catch (error) {
+            this.logger.warn(`[smart-filter] Filter failed: ${error instanceof Error ? error.message : String(error)}, falling back to show all`);
+            const result = this.createUnfilteredResult(servers, allTools, "keyword");
+            result.metadata.timeoutOccurred = timeoutOccurred;
+            return result;
+        }
+    }
+    async performFilter(servers, allTools, userTurns) {
+        // Step 1: Query synthesis
+        const query = this.synthesizeQuery(userTurns);
+        if (!query) {
+            this.logger.debug("[smart-filter] No meaningful query found, showing all servers");
+            return this.createUnfilteredResult(servers, allTools, "keyword", "");
+        }
+        // Step 2: Prepare filterable servers
+        const filterableServers = this.prepareFilterableServers(servers, allTools);
+        // Step 3: Level 1 - Server filtering
+        const serverScores = this.scoreServers(query, filterableServers);
+        const selectedServers = this.selectServers(serverScores, filterableServers);
+        // Step 4: Level 2 - Tool filtering
+        const toolResults = this.filterTools(query, selectedServers);
+        return {
+            servers: selectedServers.map(s => s.server),
+            tools: toolResults,
+            metadata: {
+                queryUsed: query,
+                totalServersBeforeFilter: Object.keys(servers).length,
+                totalToolsBeforeFilter: Array.from(allTools.values()).flat().length,
+                filterMode: "keyword",
+                timeoutOccurred: false,
+                confidenceScore: this.calculateConfidenceScore(serverScores),
+            },
+        };
+    }
+    /**
+     * Extract meaningful intent from last 1-3 user turns
+     */
+    synthesizeQuery(userTurns) {
+        if (!userTurns || userTurns.length === 0) {
+            return "";
+        }
+        // Take last 1-3 turns, newest first
+        const recentTurns = userTurns
+            .slice(-3)
+            .reverse()
+            .map(turn => turn.content.trim());
+        for (const content of recentTurns) {
+            const cleanedQuery = this.extractMeaningfulContent(content);
+            if (cleanedQuery.length >= 3) {
+                return cleanedQuery;
+            }
+        }
+        // If all recent turns are too short, try combining them
+        const combined = recentTurns
+            .map(content => this.extractMeaningfulContent(content))
+            .filter(content => content.length > 0)
+            .join(" ")
+            .trim();
+        return combined.length >= 3 ? combined : "";
+    }
+    extractMeaningfulContent(content) {
+        // Remove metadata patterns
+        const cleaned = content
+            .replace(/\[.*?\]/g, "") // [timestamps], [commands]
+            .replace(/^\s*[>]*\s*/gm, "") // quote markers
+            .replace(/^\s*[-*•]\s*/gm, "") // list markers
+            .trim();
+        // Filter out noise words/confirmations
+        const noisePatterns = [
+            /^(yes|no|ok|okay|sure|thanks?|thank you)\.?$/i,
+            /^(do it|go ahead|proceed)\.?$/i,
+            /^(yes,?\s+(do it|go ahead|proceed))\.?$/i,
+            /^\?+$/,
+            /^\.+$/,
+            /^!+$/,
+        ];
+        if (noisePatterns.some(pattern => pattern.test(cleaned))) {
+            return "";
+        }
+        // Remove trailing "please" and other politeness words
+        const withoutPoliteness = cleaned
+            .replace(/\s+please\.?$/i, "")
+            .replace(/\s+thanks?\.?$/i, "")
+            .trim();
+        return withoutPoliteness;
+    }
+    prepareFilterableServers(servers, allTools) {
+        return Object.entries(servers).map(([name, config]) => ({
+            name,
+            description: config.description || "",
+            keywords: this.normalizeKeywords(config.keywords || []),
+            tools: allTools.get(name) || [],
+        }));
+    }
+    normalizeKeywords(keywords) {
+        return keywords
+            .slice(0, 30) // Max 30 keywords
+            .map(kw => kw.toLowerCase().trim())
+            .filter(kw => kw.length > 0)
+            .filter((kw, index, arr) => arr.indexOf(kw) === index); // Deduplicate
+    }
+    /**
+     * Score servers using weighted overlap scoring
+     */
+    scoreServers(query, servers) {
+        const queryWords = this.tokenize(query.toLowerCase());
+        return servers.map(server => ({
+            server,
+            score: this.calculateServerScore(queryWords, server),
+        }));
+    }
+    tokenize(text) {
+        return text
+            .toLowerCase()
+            .replace(/[^\w\s]/g, " ")
+            .split(/\s+/)
+            .filter(word => word.length > 0);
+    }
+    calculateServerScore(queryWords, server) {
+        if (queryWords.length === 0)
+            return 0;
+        const descriptionWords = this.tokenize(server.description);
+        const keywordWords = server.keywords;
+        const allServerWords = [...descriptionWords, ...keywordWords];
+        // Calculate overlaps
+        const descMatches = this.countOverlap(queryWords, descriptionWords);
+        const keywordOnlyMatches = this.countOverlap(queryWords, keywordWords) - descMatches;
+        // Add basic synonym matching for common terms
+        let semanticMatches = 0;
+        for (const queryWord of queryWords) {
+            semanticMatches += this.getSemanticScore(queryWord, allServerWords);
+        }
+        // Also check for partial/substring matches for better recall
+        let partialMatches = 0;
+        for (const queryWord of queryWords) {
+            for (const serverWord of allServerWords) {
+                if (queryWord.length > 3 && serverWord.includes(queryWord)) {
+                    partialMatches += 0.3; // Partial match gets partial credit
+                }
+            }
+        }
+        // Weighted scoring: description 1.0x, keywords 0.7x, semantic 0.5x, partial matches 0.3x
+        const score = (descMatches * 1.0 + Math.max(0, keywordOnlyMatches) * 0.7 + semanticMatches * 0.5 + partialMatches) / queryWords.length;
+        return score;
+    }
+    getSemanticScore(queryWord, serverWords) {
+        // Comprehensive synonym/semantic matching
+        const synonymMap = {
+            // Finance/payment terms
+            money: ["payment", "transfer", "currency", "invoice", "billing", "charge", "account", "balance"],
+            payment: ["money", "transfer", "invoice", "billing", "charge", "process"],
+            send: ["transfer", "payment", "international"],
+            transfer: ["send", "payment", "money", "international"],
+            invoice: ["bill", "charge", "payment", "billing", "customer"],
+            account: ["balance", "money", "payment"],
+            balance: ["account", "money"],
+            international: ["transfer", "money", "payment"],
+            // Task/productivity terms  
+            task: ["todo", "reminder", "project", "management", "productivity"],
+            todo: ["task", "reminder", "management"],
+            create: ["add", "new", "task", "issue"],
+            project: ["task", "management", "board", "productivity"],
+            manage: ["task", "project", "productivity"],
+            schedule: ["meeting", "calendar", "appointment"],
+            meeting: ["schedule", "calendar"],
+            // Development terms
+            code: ["repo", "repository", "commit", "branch", "github"],
+            issue: ["bug", "ticket", "github", "repository"],
+            bug: ["issue", "github"],
+            repository: ["repo", "code", "github"],
+            commit: ["code", "repository", "github"],
+            // Location/maps terms
+            location: ["map", "address", "directions", "geocode", "places"],
+            directions: ["map", "route", "location"],
+            address: ["location", "geocode"],
+            geocode: ["address", "location"],
+            restaurant: ["location", "places", "map"],
+            nearby: ["location", "map"],
+            // Storage/document terms
+            upload: ["store", "save", "file", "document"],
+            document: ["file", "note", "upload", "storage"],
+            store: ["save", "upload", "note"],
+            notes: ["document", "store"],
+            // Infrastructure terms
+            deploy: ["infrastructure", "cloud", "server"],
+            cloud: ["infrastructure", "deploy"],
+            server: ["infrastructure", "monitoring"],
+            infrastructure: ["cloud", "server", "deploy"],
+            monitoring: ["server", "infrastructure"],
+            // Collaboration terms
+            whiteboard: ["collaboration", "brainstorming"],
+            brainstorming: ["whiteboard", "collaboration"],
+            collaboration: ["whiteboard", "design"],
+            // Search terms
+            search: ["find", "information", "papers"],
+            find: ["search", "information"],
+            information: ["search", "find"],
+            // Web scraping terms
+            analyze: ["data", "extract", "website"],
+            extract: ["data", "scraping", "website"],
+            website: ["scraping", "analyze", "extract"],
+            data: ["extract", "analyze", "scraping"],
+            traffic: ["website", "analyze"],
+        };
+        const synonyms = synonymMap[queryWord.toLowerCase()] || [];
+        let matches = 0;
+        for (const synonym of synonyms) {
+            if (serverWords.includes(synonym)) {
+                matches += 1;
+            }
+        }
+        return matches;
+    }
+    countOverlap(words1, words2) {
+        const set2 = new Set(words2);
+        return words1.filter(word => set2.has(word)).length;
+    }
+    /**
+     * Select servers using dynamic topServers with confidence-based expansion
+     */
+    selectServers(serverScores, allServers) {
+        // Include always-included servers first
+        const alwaysIncluded = allServers
+            .filter(s => this.config.alwaysInclude.includes(s.name))
+            .map(server => ({ server, score: 1.0 }));
+        // Sort all servers by score
+        const allScoredServers = serverScores
+            .filter(({ server }) => !this.config.alwaysInclude.includes(server.name))
+            .sort((a, b) => b.score - a.score);
+        // Primary filter: servers that meet threshold
+        const thresholdServers = allScoredServers.filter(({ score }) => score >= this.config.serverThreshold);
+        // Fallback: if too few servers pass threshold, include more based on ranking
+        let scoredServers = thresholdServers;
+        if (thresholdServers.length < 2) {
+            // Take at least top 3 servers regardless of threshold for better recall
+            scoredServers = allScoredServers.slice(0, Math.max(3, this.config.topServers));
+            this.logger.debug(`[smart-filter] Only ${thresholdServers.length} servers met threshold, expanding to top ${scoredServers.length}`);
+        }
+        // Dynamic topServers based on confidence
+        let numServers = this.config.topServers;
+        if (scoredServers.length >= 2) {
+            const topScore = scoredServers[0].score;
+            const cutoffScore = scoredServers[Math.min(this.config.topServers - 1, scoredServers.length - 1)].score;
+            const gap = topScore - cutoffScore;
+            // If gap is small (uncertain), expand toward hard cap
+            if (gap < 0.1 && scoredServers.length > numServers) {
+                numServers = Math.min(this.config.hardCap, scoredServers.length);
+                this.logger.debug(`[smart-filter] Low confidence (gap: ${gap.toFixed(3)}), expanding to ${numServers} servers`);
+            }
+        }
+        const selectedScored = scoredServers.slice(0, numServers);
+        return [...alwaysIncluded, ...selectedScored];
+    }
+    /**
+     * Filter tools within selected servers
+     */
+    filterTools(query, selectedServers) {
+        const queryWords = this.tokenize(query);
+        const allTools = [];
+        for (const { server } of selectedServers) {
+            for (const tool of server.tools) {
+                const score = this.calculateToolScore(queryWords, tool);
+                if (score >= this.config.toolThreshold) {
+                    allTools.push({ serverId: server.name, tool, score });
+                }
+            }
+        }
+        // Sort by score and take top N
+        return allTools
+            .sort((a, b) => b.score - a.score)
+            .slice(0, this.config.topTools)
+            .map(({ serverId, tool }) => ({ serverId, tool }));
+    }
+    calculateToolScore(queryWords, tool) {
+        if (queryWords.length === 0)
+            return 0;
+        const nameWords = this.tokenize(tool.name);
+        const descWords = this.tokenize(tool.description || "");
+        const nameMatches = this.countOverlap(queryWords, nameWords);
+        const descMatches = this.countOverlap(queryWords, descWords) - this.countOverlap(queryWords, nameWords);
+        // Weighted: description 1.0x, name 0.5x (name is less descriptive usually)
+        const score = (descMatches * 1.0 + nameMatches * 0.5) / queryWords.length;
+        return score;
+    }
+    calculateConfidenceScore(serverScores) {
+        if (serverScores.length < 2)
+            return 1.0;
+        const scores = serverScores.map(s => s.score).sort((a, b) => b - a);
+        const topScore = scores[0];
+        const secondScore = scores[1];
+        // Confidence based on gap between top scores
+        if (topScore === 0)
+            return 0;
+        return Math.min(1.0, (topScore - secondScore) / topScore);
+    }
+    createUnfilteredResult(servers, allTools, filterMode, queryUsed = "") {
+        const filterableServers = this.prepareFilterableServers(servers, allTools);
+        const tools = Array.from(allTools.entries()).flatMap(([serverId, tools]) => tools.map(tool => ({ serverId, tool })));
+        return {
+            servers: filterableServers,
+            tools,
+            metadata: {
+                queryUsed,
+                totalServersBeforeFilter: Object.keys(servers).length,
+                totalToolsBeforeFilter: tools.length,
+                filterMode,
+                timeoutOccurred: false,
+            },
+        };
+    }
+    logTelemetry(result, durationMs) {
+        const telemetry = {
+            timestamp: new Date().toISOString(),
+            query: result.metadata.queryUsed,
+            serversReturned: result.servers.length,
+            toolsReturned: result.tools.length,
+            totalServersBefore: result.metadata.totalServersBeforeFilter,
+            totalToolsBefore: result.metadata.totalToolsBeforeFilter,
+            filterMode: result.metadata.filterMode,
+            durationMs,
+            confidenceScore: result.metadata.confidenceScore,
+            timeoutOccurred: result.metadata.timeoutOccurred,
+        };
+        this.logger.debug("[smart-filter] Telemetry:", JSON.stringify(telemetry));
+    }
+}
+// ── Standalone utility exports (for testing and external use) ────────────────
+const MAX_KEYWORDS = 30;
+const NOISE_WORDS = new Set([
+    "yes", "no", "ok", "okay", "sure", "yep", "nope", "yeah", "nah",
+    "do", "it", "please", "thanks", "thank", "you", "hi", "hello",
+    "hey", "right", "alright", "fine", "got", "hmm", "hm",
+]);
+export const DEFAULTS = {
+    enabled: false,
+    embedding: "keyword",
+    topServers: 5,
+    hardCap: 8,
+    topTools: 10,
+    serverThreshold: 0.15,
+    toolThreshold: 0.10,
+    fallback: "keyword",
+    alwaysInclude: [],
+    timeoutMs: 500,
+    telemetry: false,
+};
+/** Lowercase, split on whitespace + punctuation, preserve numbers, drop empties. */
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[\s\p{P}]+/u)
+        .filter(t => t.length > 0);
+}
+/** Normalize keywords: lowercase, trim, dedup, strip empties, cap at MAX_KEYWORDS. */
+export function validateKeywords(raw) {
+    const seen = new Set();
+    const out = [];
+    for (const kw of raw) {
+        const normalized = kw.toLowerCase().trim();
+        if (normalized.length === 0 || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        out.push(normalized);
+        if (out.length >= MAX_KEYWORDS)
+            break;
+    }
+    return out;
+}
+/**
+ * Extract a meaningful intent string from the last 1-3 user turns.
+ * Returns null if no meaningful query can be extracted.
+ */
+export function synthesizeQuery(userTurns) {
+    const recent = userTurns.slice(-3).reverse();
+    for (const turn of recent) {
+        const tokens = tokenize(turn).filter(t => !NOISE_WORDS.has(t));
+        if (tokens.length >= 2) {
+            return tokens.join(" ");
+        }
+    }
+    return null;
+}
+/**
+ * Score a single server against a query using weighted word overlap.
+ * desc_matches * 1.0 + kw_only_matches * 0.5, normalized by query length.
+ */
+export function scoreServer(queryTokens, serverName, description, keywords) {
+    if (queryTokens.length === 0)
+        return 0;
+    const descTokens = new Set(tokenize(description));
+    for (const t of tokenize(serverName))
+        descTokens.add(t);
+    const kwTokens = new Set(validateKeywords(keywords).flatMap(kw => tokenize(kw)));
+    let descMatches = 0;
+    let kwOnlyMatches = 0;
+    for (const qt of queryTokens) {
+        if (descTokens.has(qt)) {
+            descMatches++;
+        }
+        else if (kwTokens.has(qt)) {
+            kwOnlyMatches++;
+        }
+    }
+    return (descMatches * 1.0 + kwOnlyMatches * 0.5) / queryTokens.length;
+}
+/** Score all servers, return sorted highest-first. */
+export function scoreAllServers(queryTokens, servers) {
+    const scores = [];
+    for (const [name, cfg] of Object.entries(servers)) {
+        scores.push({ name, score: scoreServer(queryTokens, name, cfg.description ?? "", cfg.keywords ?? []) });
+    }
+    return scores.sort((a, b) => b.score - a.score);
+}
+/**
+ * Select top servers with dynamic expansion toward hardCap.
+ * If top score < threshold AND gap small → show all (true uncertainty).
+ */
+export function selectTopServers(scores, topServers, hardCap, threshold, alwaysInclude) {
+    if (scores.length === 0)
+        return [];
+    const topScore = scores[0].score;
+    if (topScore < threshold && scores.length > 1) {
+        const gap = topScore - scores[Math.min(scores.length - 1, topServers - 1)].score;
+        if (gap < 0.05) {
+            return scores.map(s => s.name);
+        }
+    }
+    let k = Math.min(topServers, scores.length);
+    if (k < scores.length && k < hardCap) {
+        const kthScore = scores[k - 1].score;
+        while (k < Math.min(hardCap, scores.length)) {
+            if (scores[k].score >= kthScore * 0.8 && scores[k].score >= threshold) {
+                k++;
+            }
+            else {
+                break;
+            }
+        }
+    }
+    const selected = new Set();
+    for (let i = 0; i < k && i < scores.length; i++) {
+        if (scores[i].score >= threshold || i === 0) {
+            selected.add(scores[i].name);
+        }
+    }
+    for (const name of alwaysInclude)
+        selected.add(name);
+    return [...selected];
+}
+/**
+ * Run the smart filter. Returns the list of server names to include.
+ * Guarantees: never throws, never blocks longer than timeoutMs.
+ */
+export function filterServers(servers, userTurns, config, logger) {
+    const allServers = Object.keys(servers);
+    const showAll = (reason, query = null) => ({
+        filteredServers: allServers,
+        allServers,
+        query,
+        scores: [],
+        reason,
+    });
+    if (!config.enabled)
+        return showAll("disabled");
+    try {
+        const merged = { ...DEFAULTS, ...config };
+        const startTime = Date.now();
+        const query = synthesizeQuery(userTurns);
+        if (!query)
+            return showAll("no-query");
+        if (Date.now() - startTime > merged.timeoutMs) {
+            logger?.warn("[smart-filter] Timeout during query synthesis");
+            return showAll("timeout", query);
+        }
+        const queryTokens = tokenize(query);
+        if (queryTokens.length === 0)
+            return showAll("no-query");
+        const scores = scoreAllServers(queryTokens, servers);
+        if (Date.now() - startTime > merged.timeoutMs) {
+            logger?.warn("[smart-filter] Timeout during scoring");
+            return showAll("timeout", query);
+        }
+        const filteredServers = selectTopServers(scores, merged.topServers, merged.hardCap, merged.serverThreshold, merged.alwaysInclude);
+        return { filteredServers, allServers, query, scores, reason: "filtered" };
+    }
+    catch (err) {
+        logger?.error("[smart-filter] Error during filtering, showing all servers:", err);
+        return showAll("error");
+    }
+}
+/** Build a filtered router tool description string. */
+export function buildFilteredDescription(allServers, filteredNames) {
+    const included = new Set(filteredNames);
+    const serverList = Object.entries(allServers)
+        .filter(([name]) => included.has(name))
+        .map(([name, cfg]) => {
+        const desc = cfg.description;
+        return desc ? `${name} (${desc})` : name;
+    })
+        .join(", ");
+    if (!serverList) {
+        return "Call MCP server tools. No servers matched the current context.";
+    }
+    return `Call any MCP server tool. Servers: ${serverList}. Use action='list' to discover tools and required parameters, action='call' to execute a tool, action='refresh' to clear cache and re-discover tools, and action='status' to check server connection states. If the user mentions a specific tool by name, the call action auto-connects and works without listing first.`;
+}

package/package.json

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