@aiwerk/mcp-bridge 2.8.3 → 2.8.5

package/dist/bin/mcp-bridge.js

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
-import { readFileSync, existsSync, writeFileSync } from "fs";
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from "fs";
 import { join, dirname, resolve, extname } from "path";
 import { fileURLToPath } from "url";
-import { platform, homedir } from "os";
-import { execFileSync } from "child_process";
-import { loadConfig, initConfigDir, warnDeprecatedBundledRecipes } from "../src/config.js";
+import { homedir } from "os";
+import { loadConfig, initConfigDir, warnDeprecatedBundledRecipes, recipeToServerConfig, collectRequiredEnvVars } from "../src/config.js";
 import { StandaloneServer } from "../src/standalone-server.js";
 import { PACKAGE_VERSION } from "../src/protocol.js";
 import { checkForUpdate, runUpdate } from "../src/update-checker.js";
 import { FileTokenStore } from "../src/token-store.js";
 import { performAuthCodeLogin, performDeviceCodeLogin } from "../src/cli-auth.js";
 import { RateLimiter } from "../src/rate-limiter.js";
+import { CatalogClient } from "../src/catalog-client.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // After tsc, this file lives at dist/bin/mcp-bridge.js.
@@ -195,6 +195,26 @@ All logs go to stderr. Stdout is reserved for the MCP protocol (stdio mode).
 }
 function cmdInit(logger) {
     initConfigDir(logger);
+    // Check if installed globally
+    const isGlobal = __dirname.includes("node_modules") && !__dirname.includes(homedir());
+    process.stdout.write(`
+Next step: add mcp-bridge to your MCP client.
+
+Add this to your client's MCP server config:
+
+  {
+    "mcp-bridge": {
+      "command": "${isGlobal ? "mcp-bridge" : "node"}",
+      "args": ${isGlobal ? '["serve"]' : `["${join(__dirname, "..", "bin", "mcp-bridge.js")}", "serve"]`}
+    }
+  }
+
+Supported clients: Claude Code (~/.claude/settings.json),
+  Cursor (~/.cursor/mcp.json), Claude Desktop, Windsurf, OpenClaw, etc.
+${!isGlobal ? "\nTip: Install globally for a cleaner setup:\n  npm install -g @aiwerk/mcp-bridge\n" : ""}
+After adding, restart your client. The bridge will appear as an 'mcp' tool
+with search, install, and catalog actions to discover and add MCP servers.
+`);
 }
 function cmdCatalog(logger) {
     const catalogPath = join(PACKAGE_ROOT, "servers", "index.json");
@@ -373,30 +393,68 @@ function cmdLimit(args, logger) {
         process.exit(1);
     }
 }
-function cmdInstall(serverName, logger) {
-    const scriptDir = join(PACKAGE_ROOT, "scripts");
+async function cmdInstall(serverName, args, logger) {
+    const configPath = resolveConfigPath(args.configPath);
+    const configDir = dirname(configPath);
+    // Ensure config dir exists
+    if (!existsSync(configDir)) {
+        mkdirSync(configDir, { recursive: true });
+    }
+    // Ensure config file exists
+    if (!existsSync(configPath)) {
+        writeFileSync(configPath, JSON.stringify({ servers: {} }, null, 2) + "\n", "utf-8");
+        logger.info(`Created config: ${configPath}`);
+    }
+    // Read current config
+    const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+    if (!raw.servers)
+        raw.servers = {};
+    // Check if already configured
+    if (raw.servers[serverName]) {
+        process.stdout.write(`Server "${serverName}" is already configured.\n`);
+        process.stdout.write(`Config: ${configPath}\n`);
+        return;
+    }
+    // Fetch recipe from catalog
+    process.stdout.write(`Fetching recipe for ${serverName}...\n`);
+    const cacheDir = join(configDir, "recipes");
+    const client = new CatalogClient({ cacheDir, logger });
+    let recipe;
     try {
-        if (platform() === "win32") {
-            const psScript = join(scriptDir, "install-server.ps1");
-            if (!existsSync(psScript)) {
-                logger.error("Install script not found (install-server.ps1)");
-                process.exit(1);
-            }
-            execFileSync("powershell", ["-ExecutionPolicy", "Bypass", "-File", psScript, serverName], { stdio: "inherit" });
-        }
-        else {
-            const scriptPath = join(scriptDir, "install-server.sh");
-            if (!existsSync(scriptPath)) {
-                logger.error("Install script not found (install-server.sh)");
-                process.exit(1);
-            }
-            execFileSync("bash", [scriptPath, serverName], { stdio: "inherit" });
-        }
+        recipe = await client.resolve(serverName);
     }
     catch (err) {
-        logger.error("Install failed:", err instanceof Error ? err.message : String(err));
+        logger.error(`Recipe not found: ${serverName}`);
+        process.exit(1);
+    }
+    // Convert recipe to server config
+    const serverConfig = recipeToServerConfig(recipe);
+    if (!serverConfig) {
+        logger.error(`Unsupported recipe format for "${serverName}"`);
         process.exit(1);
     }
+    // Check required env vars
+    const requiredVars = collectRequiredEnvVars(recipe);
+    const missing = requiredVars.filter(v => !process.env[v]);
+    // Add to config
+    raw.servers[serverName] = serverConfig;
+    writeFileSync(configPath, JSON.stringify(raw, null, 2) + "\n", "utf-8");
+    process.stdout.write(`\n✓ Added "${serverName}" to ${configPath}\n\n`);
+    if (missing.length > 0) {
+        process.stdout.write(`⚠ Missing environment variables:\n`);
+        for (const v of missing) {
+            process.stdout.write(`  ${v}\n`);
+        }
+        // Show credentials URL if available
+        const credUrl = recipe.auth?.credentialsUrl;
+        if (credUrl) {
+            process.stdout.write(`\nGet credentials: ${credUrl}\n`);
+        }
+        process.stdout.write(`\nSet them in your environment or ~/.mcp-bridge/.env before starting the bridge.\n`);
+    }
+    else {
+        process.stdout.write(`All required environment variables are set. Ready to use.\n`);
+    }
 }
 async function cmdUpdate(logger, checkOnly) {
     if (checkOnly) {
@@ -549,6 +607,9 @@ async function cmdServe(args, logger) {
         logger.error(err instanceof Error ? err.message : String(err));
         process.exit(1);
     }
+    if (args.debug) {
+        config.debug = true;
+    }
     // HTTP modes: require auth
     if ((args.sse || args.http) && !config.http?.auth) {
         logger.error("HTTP auth not configured. Set http.auth in config or use stdio mode.");
@@ -611,7 +672,7 @@ async function main() {
                 process.stderr.write("Usage: mcp-bridge install <server>\n");
                 process.exit(1);
             }
-            cmdInstall(args.positional[0], logger);
+            await cmdInstall(args.positional[0], args, logger);
             break;
         case "update":
             await cmdUpdate(logger, args.checkOnly);

package/dist/src/config.d.ts

@@ -1,4 +1,5 @@
-import { BridgeConfig, Logger } from "./types.js";
+import { BridgeConfig, Logger, McpServerConfig } from "./types.js";
+import type { CatalogRecipe } from "./catalog-client.js";
 /**
  * Load ~/.openclaw/.env as a fallback env source.
  *
@@ -60,3 +61,7 @@ export declare function mergeRecipesIntoConfig(config: BridgeConfig, options?: {
     cacheDir?: string;
     logger?: Logger;
 }): BridgeConfig;
+/** Convert a catalog recipe JSON to McpServerConfig, or null if unsupported. */
+export declare function recipeToServerConfig(recipe: CatalogRecipe): McpServerConfig | null;
+/** Collect all env var names required by a recipe. */
+export declare function collectRequiredEnvVars(recipe: CatalogRecipe): string[];

package/dist/src/config.js

@@ -330,7 +330,7 @@ export function mergeRecipesIntoConfig(config, options) {
     return { ...config, servers };
 }
 /** Convert a catalog recipe JSON to McpServerConfig, or null if unsupported. */
-function recipeToServerConfig(recipe) {
+export function recipeToServerConfig(recipe) {
     // v2 recipe: has transports array
     if (Array.isArray(recipe.transports) && recipe.transports.length > 0) {
         const t = recipe.transports[0];
@@ -374,7 +374,7 @@ function recipeToServerConfig(recipe) {
     return null;
 }
 /** Collect all env var names required by a recipe. */
-function collectRequiredEnvVars(recipe) {
+export function collectRequiredEnvVars(recipe) {
     const vars = new Set();
     // From auth.envVars
     if (Array.isArray(recipe.auth?.envVars)) {

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

@@ -1,6 +1,13 @@
 import { McpClientConfig, McpServerConfig, McpTransport, Logger } from "./types.js";
 import { OAuth2TokenManager } from "./oauth2-token-manager.js";
 type RouterErrorCode = "unknown_server" | "unknown_tool" | "connection_failed" | "mcp_error" | "invalid_params";
+interface DebugMetadata {
+    server: string;
+    tool: string;
+    transport: string;
+    latencyMs: number;
+    cached?: boolean;
+}
 interface RouterBatchResult {
     server: string;
     tool: string;
@@ -11,6 +18,7 @@ interface RouterBatchResult {
         available?: string[];
         code?: number;
     };
+    _debug?: DebugMetadata;
 }
 export interface RouterToolHint {
     name: string;
@@ -40,6 +48,7 @@ export type RouterDispatchResponse = {
     result: any;
     retries?: number;
     warning?: string;
+    _debug?: DebugMetadata;
 } | {
     server: string;
     action: "schema";

package/dist/src/mcp-router.js

@@ -65,7 +65,7 @@ export class McpRouter {
     static generateDescription(servers) {
         const serverNames = Object.keys(servers);
         if (serverNames.length === 0) {
-            return "Call MCP server tools. No servers configured.";
+            return "MCP server multiplexer with no servers configured yet. Use action='search' to find servers in the catalog (100+ available), action='install' to add a server by name, action='catalog' to browse all available servers.";
         }
         const serverList = serverNames
             .map((name) => {
@@ -73,7 +73,7 @@ export class McpRouter {
             return desc ? `${name} (${desc})` : name;
         })
             .join(", ");
-        return `Call any MCP server tool. Servers: ${serverList}. Use action='list' to discover tools and required parameters, action='call' to execute a tool, action='batch' to execute multiple calls in one round-trip, 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.`;
+        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 servers: 'search' to find servers in the catalog (100+ available), '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.`;
     }
     async dispatch(server, action = "call", tool, params) {
         try {
@@ -130,7 +130,10 @@ export class McpRouter {
                             results[idx] = {
                                 server: callServer,
                                 tool: callTool,
-                                result: "result" in response ? response.result : response
+                                result: "result" in response ? response.result : response,
+                                ...(this.clientConfig.debug && "result" in response && "_debug" in response ? {
+                                    _debug: response._debug
+                                } : {})
                             };
                         }
                     }
@@ -208,6 +211,7 @@ export class McpRouter {
             if (!tool) {
                 return this.error("invalid_params", "tool is required for action=call");
             }
+            const startTime = Date.now();
             let targetServer = server;
             if (!targetServer) {
                 await this.primeToolResolutionIndex();
@@ -249,7 +253,21 @@ export class McpRouter {
                         this.promotion.recordCall(server, tool);
                     }
                     this.toolResolver.recordCall(server, tool);
-                    return { server, action: "call", tool, result: cachedResult };
+                    return {
+                        server,
+                        action: "call",
+                        tool,
+                        result: cachedResult,
+                        ...(this.clientConfig.debug ? {
+                            _debug: {
+                                server,
+                                tool,
+                                transport: serverConfig.transport,
+                                latencyMs: Date.now() - startTime,
+                                cached: true,
+                            }
+                        } : {})
+                    };
                 }
             }
             // Rate limit: check BEFORE call, increment AFTER success
@@ -280,6 +298,14 @@ export class McpRouter {
                 action: "call",
                 tool,
                 result,
+                ...(this.clientConfig.debug ? {
+                    _debug: {
+                        server,
+                        tool,
+                        transport: serverConfig.transport,
+                        latencyMs: Date.now() - startTime,
+                    }
+                } : {}),
                 ...(rateLimitIncrement.warning ? { warning: rateLimitIncrement.warning } : {}),
                 ...(callOutcome.retries > 0 ? { retries: callOutcome.retries } : {})
             };

package/dist/src/types.d.ts

@@ -101,6 +101,8 @@ export interface McpClientConfig {
         defaultTtlMs?: number;
         cacheTtl?: Record<string, number>;
     };
+    /** When true, tool call responses include a _debug object with routing metadata. */
+    debug?: boolean;
 }
 export interface McpTool {
     name: string;

package/package.json

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