@aiwerk/mcp-bridge 2.8.22 → 2.8.24

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
@@ -558,12 +557,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 +577,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 +673,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,23 @@ function whichCmd(name) {
         return false;
     }
 }
-function cmdInit(logger, register) {
+function cmdInit(logger, register, mode) {
     initConfigDir(logger);
+    // Apply --mode if config exists and mode was specified
+    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 */ }
+        }
+    }
     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"];
@@ -329,23 +352,27 @@ function registerClient(client, bridgeCmd, bridgeArgs, cmd) {
         }
     }
 }
-function cmdCatalog(logger) {
-    const catalogPath = join(PACKAGE_ROOT, "servers", "index.json");
-    if (!existsSync(catalogPath)) {
-        logger.error("Server catalog not found");
+async function cmdCatalog(logger, offline) {
+    const client = new CatalogClient({ logger });
+    try {
+        const result = await client.list({ limit: 200 });
+        const recipes = result.results || [];
+        process.stdout.write(`\nAvailable servers (${recipes.length} from catalog.aiwerk.ch):\n\n`);
+        process.stdout.write("  Server                Auth        Category         Description\n");
+        process.stdout.write("  " + "─".repeat(90) + "\n");
+        for (const r of recipes) {
+            const name = (r.name || "").padEnd(22);
+            const auth = (r.authSummary || "none").padEnd(12);
+            const cat = (r.category || "").padEnd(17);
+            const desc = (r.description || "").slice(0, 60);
+            process.stdout.write(`  ${name}${auth}${cat}${desc}\n`);
+        }
+        process.stdout.write("\n");
+    }
+    catch (err) {
+        logger.error(`Failed to fetch catalog: ${err instanceof Error ? err.message : String(err)}`);
         process.exit(1);
     }
-    const catalog = JSON.parse(readFileSync(catalogPath, "utf-8"));
-    const servers = catalog.recipes || catalog.servers || {};
-    process.stdout.write("\nAvailable servers:\n\n");
-    process.stdout.write("  Server          Transport    Description\n");
-    process.stdout.write("  " + "─".repeat(60) + "\n");
-    for (const [name, info] of Object.entries(servers)) {
-        const padded = name.padEnd(16);
-        const transport = (info.transport || "stdio").padEnd(13);
-        process.stdout.write(`  ${padded}${transport}${info.description || ""}\n`);
-    }
-    process.stdout.write("\n");
 }
 function cmdServers(logger, configPath) {
     try {
@@ -371,28 +398,26 @@ function cmdServers(logger, configPath) {
         process.exit(1);
     }
 }
-function cmdSearch(query, logger) {
-    const catalogPath = join(PACKAGE_ROOT, "servers", "index.json");
-    if (!existsSync(catalogPath)) {
-        logger.error("Server catalog not found");
-        process.exit(1);
+async function cmdSearch(query, logger) {
+    const client = new CatalogClient({ logger });
+    try {
+        const searchResponse = await client.search(query);
+        const results = Array.isArray(searchResponse) ? searchResponse : searchResponse.results || [];
+        if (results.length === 0) {
+            process.stdout.write(`No servers matching "${query}"\n`);
+            return;
+        }
+        process.stdout.write(`\nSearch results for "${query}" (${results.length} found):\n\n`);
+        for (const [i, r] of results.entries()) {
+            const auth = r.authSummary || (r.authRequired ? "required" : "none");
+            process.stdout.write(`  ${i + 1}  ${(r.name || "").padEnd(22)}[${auth}] ${r.description || ""}\n`);
+        }
+        process.stdout.write("\n");
     }
-    const catalog = JSON.parse(readFileSync(catalogPath, "utf-8"));
-    const servers = catalog.recipes || catalog.servers || {};
-    const lowerQuery = query.toLowerCase();
-    const matches = Object.entries(servers).filter(([name, info]) => {
-        return name.toLowerCase().includes(lowerQuery) ||
-            (info.description || "").toLowerCase().includes(lowerQuery);
-    });
-    if (matches.length === 0) {
-        process.stdout.write(`No servers matching "${query}"\n`);
-        return;
+    catch (err) {
+        logger.error(`Search failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
     }
-    process.stdout.write(`\nSearch results for "${query}":\n\n`);
-    matches.forEach(([name, info], i) => {
-        process.stdout.write(`  ${i + 1}  ${name.padEnd(16)}${info.description || ""}\n`);
-    });
-    process.stdout.write("\n");
 }
 function resolveConfigPath(configPath) {
     if (!configPath) {
@@ -764,10 +789,10 @@ async function main() {
             printHelp();
             break;
         case "init":
-            cmdInit(logger, args.register);
+            cmdInit(logger, args.register, args.mode);
             break;
         case "catalog":
-            cmdCatalog(logger);
+            await cmdCatalog(logger, args.offline);
             break;
         case "servers":
             cmdServers(logger, args.configPath);
@@ -777,7 +802,7 @@ async function main() {
                 process.stderr.write("Usage: mcp-bridge search <query>\n");
                 process.exit(1);
             }
-            cmdSearch(args.positional[0], logger);
+            await cmdSearch(args.positional[0], logger);
             break;
         case "usage":
             cmdUsage(args.configPath, logger);

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.js

@@ -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.` };
                 }

package/package.json

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