@aiwerk/mcp-bridge 2.8.23 → 2.8.25

package/README.md

@@ -8,7 +8,7 @@
 
 🌐 **[aiwerkmcp.com](https://aiwerkmcp.com)** — Learn more about the AIWerk MCP Platform
 
-Works with **Claude Desktop**, **Cursor**, **Windsurf**, **Cline**, **OpenClaw**, or any MCP client.
+Works with **Claude Code**, **Codex (OpenAI)**, **Claude Desktop**, **Cursor**, **Windsurf**, **Cline**, **OpenClaw**, or any MCP client.
 
 ## Why?
 
@@ -39,8 +39,8 @@ npm install -g @aiwerk/mcp-bridge
 ## Quick Start
 
 ```bash
-# 1. Initialize config
-mcp-bridge init
+# 1. Initialize config and register with Claude Code
+mcp-bridge init --register claude-code
 
 # 2. Install a server from the catalog
 mcp-bridge install todoist
@@ -48,8 +48,7 @@ mcp-bridge install todoist
 # 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
+# 4. Restart Claude Code — bridge is ready
 ```
 
 ## Use with Claude Desktop
@@ -418,9 +417,24 @@ Returns promoted tools (sorted by frequency) and full usage stats. All tracking
 | Mode | Tools exposed | Best for |
 |------|--------------|----------|
 | `router` (default) | Single `mcp` meta-tool | 3+ servers, token-conscious agents |
-| `direct` | All tools individually | Few servers, simple agents |
+| `direct` | All tools individually | Clients with deferred/lazy tool loading (Claude Code), few servers |
 
-**Router mode** — the agent calls `mcp(server="todoist", action="list")` to discover, then `mcp(server="todoist", tool="find-tasks", params={...})` to execute.
+Switch modes via CLI or config:
+
+```bash
+mcp-bridge init --mode direct    # all tools exposed individually
+mcp-bridge init --mode router    # single mcp meta-tool (default)
+```
+
+Or set in `~/.mcp-bridge/config.json`:
+
+```json
+{ "mode": "direct" }
+```
+
+**Router mode** — the agent calls `mcp(server="todoist", action="list")` to discover, then `mcp(server="todoist", tool="find-tasks", params={...})` to execute. Best when you have many servers and want minimal token usage.
+
+**Direct mode** — all tools from all servers are registered individually as `todoist_find_tasks`, `github_list_repos`, etc. The bridge still provides unified config, catalog install, OAuth2, security, retries, and reconnection. Ideal for clients that support deferred/lazy tool loading, where tools are registered but not loaded into context until needed.
 
 ### Multi-Server Tool Resolution
 
@@ -558,12 +572,16 @@ 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 --debug                # Full debug metadata in tool responses
 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 init                   # Create ~/.mcp-bridge/ with template config
+mcp-bridge init --register claude-code  # Init + register with Claude Code
+mcp-bridge init --register codex        # Init + register with Codex
+mcp-bridge init --register cursor       # Init + register with Cursor
+mcp-bridge init --register windsurf     # Init + register with Windsurf
+mcp-bridge install <server>       # Install from online catalog
+mcp-bridge catalog                # Browse 100+ available servers
 mcp-bridge servers                # List configured servers
 mcp-bridge search <query>         # Search catalog by keyword
 mcp-bridge update [--check]       # Check for / install updates
@@ -574,33 +592,36 @@ mcp-bridge auth logout <server>   # Remove stored token
 mcp-bridge auth status            # Show auth status for all servers
 ```
 
+## Agent Integration
+
+When connected to an MCP client (Claude Code, Codex, Cursor, etc.), the bridge exposes a single `mcp` meta-tool. Agents can discover and install servers at runtime:
+
+```
+mcp(action="search", params={query: "task management"})  # Search catalog
+mcp(action="install", params={name: "todoist"})           # Install server (persisted to config)
+mcp(action="catalog")                                      # Browse all servers
+mcp(action="list", server="todoist")                       # Discover tools on a server
+mcp(action="call", server="todoist", tool="find-tasks", params={query: "today"})
+```
+
+The tool description automatically includes all connected servers with their descriptions, so agents know which server to use for what. New servers installed via the bridge are persisted to `~/.mcp-bridge/config.json` and survive restarts.
+
 ## Server Catalog
 
-Built-in catalog with pre-configured servers:
-
-| 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 |
-| atlassian | stdio | Confluence and Jira |
-| chrome-devtools | stdio | Chrome browser automation |
-| hostinger | sse | Web hosting management |
+Browse and install from the [AIWerk MCP Catalog](https://catalog.aiwerk.ch) with 100+ verified, signed recipes:
 
 ```bash
-mcp-bridge install todoist    # Interactive setup with API key prompt
-mcp-bridge catalog            # Full list
-mcp-bridge search payments    # Search by keyword
+mcp-bridge catalog                # Browse all 100+ servers
+mcp-bridge search payments        # Search by keyword
+mcp-bridge install todoist        # Install from catalog
 ```
 
+Popular servers include: todoist, github, notion, stripe, linear, google-maps, slack, supabase, mongodb, playwright, docker, and many more.
+
+All catalog recipes are Ed25519 signed and security-audited. The bridge verifies signatures before installation.
+
+> **Note**: The bundled `servers/` directory is deprecated. All servers now come from the online catalog.
+
 ## Library Usage
 
 Use as a dependency in your own MCP server or OpenClaw plugin:
@@ -667,11 +688,14 @@ For production deployments with high security requirements, consider adding an e
 | ✅ | OAuth2 Client Credentials | 2.1.0 |
 | ✅ | OAuth2 Authorization Code + PKCE | 2.5.0 |
 | ✅ | OAuth2 Device Code flow (headless) | 2.6.0 |
-| 🔜 | Auto-discovery (zero-config server registration) | planned |
+| ✅ | Agent-driven discovery (search/install at runtime) | 2.8.6 |
 | 🔜 | Hosted bridge (bridge.aiwerk.ch) | planned |
 | ✅ | Remote catalog integration | 2.8.0 |
+| ✅ | CLI online catalog | 2.8.23 |
+| ✅ | Debug mode (_debug metadata) | 2.8.4 |
 | 🔜 | OpenTelemetry / Prometheus metrics | planned |
 | 🔜 | PII redaction | planned |
+| 🔜 | Skill system (recipe.json skills for agents) | planned |
 
 See [docs/hosted-bridge-spec.md](docs/hosted-bridge-spec.md) for the hosted bridge architecture.
 

package/dist/bin/mcp-bridge.js

@@ -106,6 +106,14 @@ function parseArgs(argv) {
                 }
                 args.register = argv[i];
                 break;
+            case "--mode":
+                i++;
+                if (argv[i] !== "router" && argv[i] !== "direct") {
+                    process.stderr.write("Error: --mode must be 'router' or 'direct'\n");
+                    process.exit(1);
+                }
+                args.mode = argv[i];
+                break;
             case "--daily":
                 i++;
                 args.daily = parseInt(argv[i], 10);
@@ -179,7 +187,7 @@ Usage:
   mcp-bridge                        Start in stdio mode (default)
   mcp-bridge --sse --port 3000      Start as SSE server
   mcp-bridge --http --port 3000     Start as streamable-http server
-  mcp-bridge init [--register <client>]  Create config + optionally register with a client
+  mcp-bridge init [--register <client>] [--mode router|direct]  Create config + optionally register
   mcp-bridge install <server>       Install a server from the catalog
   mcp-bridge catalog [--offline]    List available servers
   mcp-bridge servers                List configured servers
@@ -211,8 +219,24 @@ function whichCmd(name) {
         return false;
     }
 }
-function cmdInit(logger, register) {
+function cmdInit(logger, register, mode) {
     initConfigDir(logger);
+    // Apply --mode to config
+    if (mode) {
+        const configPath = join(homedir(), ".mcp-bridge", "config.json");
+        if (existsSync(configPath)) {
+            try {
+                const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+                if (raw.mode !== mode) {
+                    raw.mode = mode;
+                    writeFileSync(configPath, JSON.stringify(raw, null, 2) + "\n", "utf-8");
+                    process.stdout.write(`Mode set to "${mode}" in ${configPath}\n`);
+                }
+            }
+            catch { /* ignore parse errors */ }
+        }
+    }
+    // If --register is specified, do both mode + register
     const isGlobal = __dirname.includes("node_modules") && (__dirname.includes("/lib/node_modules/") || __dirname.includes("\\lib\\node_modules\\"));
     const bridgeCmd = isGlobal ? "mcp-bridge" : "node";
     const bridgeArgs = isGlobal ? ["serve"] : [join(__dirname, "..", "bin", "mcp-bridge.js"), "serve"];
@@ -766,7 +790,7 @@ async function main() {
             printHelp();
             break;
         case "init":
-            cmdInit(logger, args.register);
+            cmdInit(logger, args.register, args.mode);
             break;
         case "catalog":
             await cmdCatalog(logger, args.offline);

package/dist/src/catalog-client.d.ts

@@ -42,6 +42,7 @@ export interface CatalogRecipe {
         type: string;
         required?: boolean;
         envVars?: string[];
+        credentialsUrl?: string;
     };
     [key: string]: unknown;
 }

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

@@ -110,6 +110,11 @@ export type RouterDispatchResponse = {
     message: string;
     missingEnvVars?: string[];
     credentialsUrl?: string;
+} | {
+    action: "set-mode";
+    mode: string;
+    message: string;
+    requiresRestart?: boolean;
 } | {
     action: "intent";
     intent: string;

package/dist/src/mcp-router.js

@@ -77,7 +77,7 @@ export class McpRouter {
             return desc ? `${name} (${desc})` : name;
         })
             .join(", ");
-        return `MCP server multiplexer with ${serverNames.length} connected servers: ${serverList}. Actions: 'call' to execute a tool, 'list' to discover tools on a server, 'batch' for multiple calls in one round-trip, 'status' to check connections, 'refresh' to re-discover tools. To add new MCP servers, always use this tool first (not npm install): 'search' to find servers in the verified catalog (100+ signed, security-audited recipes), 'install' to add a server by name. If the user mentions a specific tool by name, the call action auto-connects and works without listing first.`;
+        return `MCP server multiplexer with ${serverNames.length} connected servers: ${serverList}. Actions: 'call' to execute a tool, 'list' to discover tools on a server, 'batch' for multiple calls in one round-trip, 'status' to check connections, 'refresh' to re-discover tools. To add new MCP servers, always use this tool first (not npm install): 'search' to find servers in the verified catalog (100+ signed, security-audited recipes), 'install' to add a server by name. Use 'set-mode' with params.mode='direct' to expose all tools individually (requires restart). If the user mentions a specific tool by name, the call action auto-connects and works without listing first.`;
     }
     async dispatch(server, action = "call", tool, params) {
         try {
@@ -165,6 +165,10 @@ export class McpRouter {
                 if (!serverName) {
                     return this.error("invalid_params", "server name is required for action=install (pass as server field or params.name)");
                 }
+                // Sanitize serverName: only lowercase alphanumeric + hyphens (matches recipe spec id format)
+                if (!/^[a-z0-9][a-z0-9-]*$/.test(serverName)) {
+                    return this.error("invalid_params", `Invalid server name "${serverName}". Must match /^[a-z0-9][a-z0-9-]*$/ (lowercase alphanumeric + hyphens).`);
+                }
                 if (this.servers[serverName]) {
                     return { action: "install", server: serverName, installed: true, message: `Server "${serverName}" is already configured.` };
                 }
@@ -336,8 +340,41 @@ export class McpRouter {
                     return this.error("connection_failed", `Failed to connect to ${server}: ${error instanceof Error ? error.message : String(error)}`);
                 }
             }
+            // Set mode (persists to config, requires bridge restart to take effect)
+            if (normalizedAction === "set-mode") {
+                const newMode = params?.mode;
+                if (newMode !== "router" && newMode !== "direct") {
+                    return this.error("invalid_params", "mode must be 'router' or 'direct'");
+                }
+                try {
+                    const os = await import("os");
+                    const fs = await import("fs");
+                    const path = await import("path");
+                    const configPath = path.join(os.homedir(), ".mcp-bridge", "config.json");
+                    if (fs.existsSync(configPath)) {
+                        const raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+                        const oldMode = raw.mode || "router";
+                        if (oldMode === newMode) {
+                            return { action: "set-mode", mode: newMode, message: `Already in "${newMode}" mode.` };
+                        }
+                        raw.mode = newMode;
+                        fs.writeFileSync(configPath, JSON.stringify(raw, null, 2) + "\n", "utf-8");
+                        this.logger.info(`Mode changed from "${oldMode}" to "${newMode}" in ${configPath}`);
+                        return {
+                            action: "set-mode",
+                            mode: newMode,
+                            message: `Mode changed to "${newMode}". Restart the bridge for changes to take effect.`,
+                            requiresRestart: true,
+                        };
+                    }
+                    return this.error("mcp_error", "Config file not found");
+                }
+                catch (err) {
+                    return this.error("mcp_error", `Failed to set mode: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
             if (normalizedAction !== "call") {
-                return this.error("invalid_params", `action must be one of: list, call, batch, refresh, schema, intent, status, promotions, search, catalog, install`);
+                return this.error("invalid_params", `action must be one of: list, call, batch, refresh, schema, intent, status, promotions, search, catalog, install, set-mode`);
             }
             if (!tool) {
                 return this.error("invalid_params", "tool is required for action=call");

package/package.json

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