@aiwerk/mcp-bridge 1.0.0

package/src/standalone-server.ts

@@ -0,0 +1,385 @@
+import { McpRouter } from "./mcp-router.js";
+import { fetchToolsList, initializeProtocol, PACKAGE_VERSION } from "./protocol.js";
+import { pickRegisteredToolName } from "./tool-naming.js";
+import {
+  BridgeConfig,
+  Logger,
+  McpRequest,
+  McpResponse,
+  McpServerConfig,
+  McpTool,
+  McpTransport,
+} from "./types.js";
+import { SseTransport } from "./transport-sse.js";
+import { StdioTransport } from "./transport-stdio.js";
+import { StreamableHttpTransport } from "./transport-streamable-http.js";
+
+interface DirectToolEntry {
+  serverName: string;
+  originalName: string;
+  registeredName: string;
+  description: string;
+  inputSchema: any;
+}
+
+/**
+ * Standalone MCP server that wraps the router.
+ * Implements the MCP protocol (initialize, tools/list, tools/call)
+ * and forwards tool calls to backend MCP servers.
+ */
+export class StandaloneServer {
+  private config: BridgeConfig;
+  private logger: Logger;
+  private router: McpRouter | null = null;
+  private initialized = false;
+
+  // Direct mode state
+  private directTools: DirectToolEntry[] = [];
+  private directConnections = new Map<string, { transport: McpTransport; initialized: boolean }>();
+
+  constructor(config: BridgeConfig, logger: Logger) {
+    this.config = config;
+    this.logger = logger;
+
+    if (this.isRouterMode()) {
+      this.router = new McpRouter(config.servers || {}, config, logger);
+    }
+  }
+
+  private isRouterMode(): boolean {
+    return (this.config.mode ?? "router") === "router";
+  }
+
+  /** Start stdio mode: read JSON-RPC from stdin, write responses to stdout. */
+  async startStdio(): Promise<void> {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+
+    stdin.setEncoding("utf8");
+    let buffer = "";
+
+    stdin.on("data", (chunk: string) => {
+      buffer += chunk;
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        this.processLine(trimmed, stdout);
+      }
+    });
+
+    stdin.on("end", () => {
+      this.logger.info("[mcp-bridge] stdin closed, shutting down");
+      this.shutdown().catch(err => {
+        this.logger.error("[mcp-bridge] Shutdown error:", err);
+      });
+    });
+
+    this.logger.info("[mcp-bridge] Stdio server ready");
+  }
+
+  private processLine(line: string, stdout: NodeJS.WriteStream): void {
+    let request: any;
+    try {
+      request = JSON.parse(line);
+    } catch {
+      this.writeResponse(stdout, {
+        jsonrpc: "2.0",
+        id: 0,
+        error: { code: -32700, message: "Parse error" }
+      });
+      return;
+    }
+
+    // Notifications (no id) — just acknowledge
+    if (request.id === undefined || request.id === null) {
+      // notifications/initialized, etc. — no response needed
+      return;
+    }
+
+    this.handleRequest(request).then(response => {
+      this.writeResponse(stdout, response);
+    }).catch(err => {
+      this.writeResponse(stdout, {
+        jsonrpc: "2.0",
+        id: request.id,
+        error: { code: -32603, message: err instanceof Error ? err.message : String(err) }
+      });
+    });
+  }
+
+  private writeResponse(stdout: NodeJS.WriteStream, response: any): void {
+    stdout.write(JSON.stringify(response) + "\n");
+  }
+
+  /** Handle a single MCP JSON-RPC request. */
+  async handleRequest(request: McpRequest): Promise<McpResponse> {
+    const id = request.id ?? 0;
+
+    switch (request.method) {
+      case "initialize":
+        return this.handleInitialize(id);
+
+      case "tools/list":
+        return this.handleToolsList(id);
+
+      case "tools/call":
+        return this.handleToolsCall(id, request.params);
+
+      case "ping":
+        return { jsonrpc: "2.0", id, result: {} };
+
+      default:
+        return {
+          jsonrpc: "2.0",
+          id,
+          error: { code: -32601, message: `Method not found: ${request.method}` }
+        };
+    }
+  }
+
+  private handleInitialize(id: number): McpResponse {
+    this.initialized = true;
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: {
+        protocolVersion: "2024-11-05",
+        capabilities: {
+          tools: {}
+        },
+        serverInfo: {
+          name: "mcp-bridge",
+          version: PACKAGE_VERSION
+        }
+      }
+    };
+  }
+
+  private async handleToolsList(id: number): Promise<McpResponse> {
+    if (this.isRouterMode()) {
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          tools: [{
+            name: "mcp",
+            description: McpRouter.generateDescription(this.config.servers),
+            inputSchema: {
+              type: "object",
+              properties: {
+                server: { type: "string", description: "Server name" },
+                action: { type: "string", description: "list | call | refresh | status" },
+                tool: { type: "string", description: "Tool name for action=call" },
+                params: { type: "object", description: "Tool arguments" }
+              },
+              required: ["server"]
+            }
+          }]
+        }
+      };
+    }
+
+    // Direct mode: discover all tools from all servers
+    await this.discoverDirectTools();
+    const tools = this.directTools.map(t => ({
+      name: t.registeredName,
+      description: t.description,
+      inputSchema: t.inputSchema
+    }));
+
+    return { jsonrpc: "2.0", id, result: { tools } };
+  }
+
+  private async handleToolsCall(id: number, params: any): Promise<McpResponse> {
+    const toolName = params?.name;
+    const toolArgs = params?.arguments ?? {};
+
+    if (!toolName) {
+      return {
+        jsonrpc: "2.0",
+        id,
+        error: { code: -32602, message: "Missing tool name" }
+      };
+    }
+
+    if (this.isRouterMode()) {
+      if (toolName !== "mcp") {
+        return {
+          jsonrpc: "2.0",
+          id,
+          error: { code: -32004, message: `Unknown tool: ${toolName}. In router mode, use the 'mcp' tool.` }
+        };
+      }
+
+      const result = await this.router!.dispatch(
+        toolArgs.server,
+        toolArgs.action,
+        toolArgs.tool,
+        toolArgs.params
+      );
+
+      // Check if result is an error
+      if ("error" in result) {
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify(result) }]
+          }
+        };
+      }
+
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          content: [{ type: "text", text: JSON.stringify(result) }]
+        }
+      };
+    }
+
+    // Direct mode: find and call the tool
+    const entry = this.directTools.find(t => t.registeredName === toolName);
+    if (!entry) {
+      return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+          code: -32004,
+          message: `Unknown tool: ${toolName}`,
+          data: { errorType: "unknown_tool" }
+        }
+      };
+    }
+
+    try {
+      const conn = this.directConnections.get(entry.serverName);
+      if (!conn || !conn.transport.isConnected()) {
+        return {
+          jsonrpc: "2.0",
+          id,
+          error: {
+            code: -32001,
+            message: `Server '${entry.serverName}' not connected`,
+            data: { errorType: "connection_failed", server: entry.serverName, retriable: true }
+          }
+        };
+      }
+
+      const response = await conn.transport.sendRequest({
+        jsonrpc: "2.0",
+        method: "tools/call",
+        params: { name: entry.originalName, arguments: toolArgs }
+      });
+
+      if (response.error) {
+        return {
+          jsonrpc: "2.0",
+          id,
+          error: {
+            code: -32005,
+            message: response.error.message,
+            data: { errorType: "mcp_error", server: entry.serverName }
+          }
+        };
+      }
+
+      return { jsonrpc: "2.0", id, result: response.result };
+    } catch (err) {
+      return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+          code: -32001,
+          message: err instanceof Error ? err.message : String(err),
+          data: { errorType: "connection_failed", server: entry.serverName, retriable: true }
+        }
+      };
+    }
+  }
+
+  /** Connect to all backend servers and discover their tools (direct mode). */
+  private async discoverDirectTools(): Promise<void> {
+    if (this.directTools.length > 0) return; // Already discovered
+
+    const globalNames = new Set<string>();
+
+    for (const [serverName, serverConfig] of Object.entries(this.config.servers)) {
+      try {
+        const transport = this.createTransport(serverName, serverConfig);
+        await transport.connect();
+        await initializeProtocol(transport, PACKAGE_VERSION);
+
+        this.directConnections.set(serverName, { transport, initialized: true });
+
+        const tools = await fetchToolsList(transport);
+        const localNames = new Set<string>();
+
+        for (const tool of tools) {
+          const registeredName = pickRegisteredToolName(
+            serverName,
+            tool.name,
+            this.config.toolPrefix,
+            localNames,
+            globalNames,
+            this.logger
+          );
+          localNames.add(registeredName);
+          globalNames.add(registeredName);
+
+          this.directTools.push({
+            serverName,
+            originalName: tool.name,
+            registeredName,
+            description: tool.description,
+            inputSchema: tool.inputSchema
+          });
+        }
+
+        this.logger.info(`[mcp-bridge] Discovered ${tools.length} tools from ${serverName}`);
+      } catch (err) {
+        this.logger.error(`[mcp-bridge] Failed to connect to ${serverName}:`, err);
+      }
+    }
+  }
+
+  private createTransport(serverName: string, serverConfig: McpServerConfig): McpTransport {
+    const onReconnected = async () => {
+      this.logger.info(`[mcp-bridge] ${serverName} reconnected`);
+    };
+
+    switch (serverConfig.transport) {
+      case "sse":
+        return new SseTransport(serverConfig, this.config, this.logger, onReconnected);
+      case "stdio":
+        return new StdioTransport(serverConfig, this.config, this.logger, onReconnected);
+      case "streamable-http":
+        return new StreamableHttpTransport(serverConfig, this.config, this.logger, onReconnected);
+      default:
+        throw new Error(`Unsupported transport: ${serverConfig.transport}`);
+    }
+  }
+
+  /** Graceful shutdown: disconnect all backend servers. */
+  async shutdown(): Promise<void> {
+    this.logger.info("[mcp-bridge] Shutting down...");
+
+    if (this.router) {
+      await this.router.disconnectAll();
+    }
+
+    for (const [name, conn] of this.directConnections) {
+      try {
+        await conn.transport.disconnect();
+      } catch (err) {
+        this.logger.error(`[mcp-bridge] Error disconnecting ${name}:`, err);
+      }
+    }
+    this.directConnections.clear();
+
+    this.logger.info("[mcp-bridge] Shutdown complete");
+  }
+}

package/src/tool-naming.ts

@@ -0,0 +1,51 @@
+function isNameTaken(name: string, localNames: Set<string>, globalNames: Set<string>): boolean {
+  return localNames.has(name) || globalNames.has(name);
+}
+
+export function pickRegisteredToolName(
+  serverName: string,
+  toolName: string,
+  toolPrefix: boolean | "auto" | undefined,
+  localNames: Set<string>,
+  globalNames: Set<string>,
+  logger?: { warn: (...args: unknown[]) => void }
+): string {
+  // toolPrefix: true = always prefix, false = never prefix, "auto" = prefix only on collision (default)
+  const effectivePrefix = toolPrefix === undefined ? "auto" : toolPrefix;
+
+  let candidate: string;
+  if (effectivePrefix === true) {
+    // Always prefix with server name
+    candidate = `${serverName}_${toolName}`.replace(/[^a-zA-Z0-9_]/g, "_");
+  } else if (effectivePrefix === false) {
+    // Never prefix — use raw tool name, no collision fallback
+    candidate = toolName.replace(/[^a-zA-Z0-9_]/g, "_");
+  } else {
+    // "auto" — try without prefix, auto-prefix on collision
+    const unprefixed = toolName.replace(/[^a-zA-Z0-9_]/g, "_");
+    if (isNameTaken(unprefixed, localNames, globalNames)) {
+      const prefixedName = `${serverName}_${toolName}`.replace(/[^a-zA-Z0-9_]/g, "_");
+      logger?.warn(
+        `[mcp-bridge] Global tool name collision detected for "${unprefixed}". Auto-prefixing with server name: "${prefixedName}"`
+      );
+      candidate = prefixedName;
+    } else {
+      candidate = unprefixed;
+    }
+  }
+
+  const uniqueBase = candidate;
+  let suffix = 2;
+  while (isNameTaken(candidate, localNames, globalNames)) {
+    candidate = `${uniqueBase}_${suffix}`;
+    suffix += 1;
+  }
+
+  if (candidate !== uniqueBase) {
+    logger?.warn(
+      `[mcp-bridge] Tool name collision after sanitization on server ${serverName}: "${uniqueBase}" -> "${candidate}"`
+    );
+  }
+
+  return candidate;
+}

package/src/transport-base.ts

@@ -0,0 +1,199 @@
+import { McpTransport, McpRequest, McpResponse, McpServerConfig } from "./types.js";
+
+export type PendingRequest = { resolve: Function; reject: Function; timeout: NodeJS.Timeout };
+
+/**
+ * Base class for all MCP transports. Provides shared logic for:
+ * - Message handling (JSON-RPC response routing, notification dispatch)
+ * - Pending request management with timeout
+ * - Reconnection with exponential backoff + jitter
+ * - Environment variable resolution for headers, env, and args
+ * - Non-TLS remote URL warnings
+ */
+export abstract class BaseTransport implements McpTransport {
+  protected config: McpServerConfig;
+  protected clientConfig: any;
+  protected connected = false;
+  protected pendingRequests = new Map<number, PendingRequest>();
+  protected logger: any;
+  protected reconnectTimer: NodeJS.Timeout | null = null;
+  protected onReconnected?: () => Promise<void>;
+  protected backoffDelay = 0;
+
+  constructor(config: McpServerConfig, clientConfig: any, logger: any, onReconnected?: () => Promise<void>) {
+    this.config = config;
+    this.clientConfig = clientConfig;
+    this.logger = logger;
+    this.onReconnected = onReconnected;
+  }
+
+  abstract connect(): Promise<void>;
+  abstract disconnect(): Promise<void>;
+  abstract sendRequest(request: McpRequest): Promise<McpResponse>;
+  abstract sendNotification(notification: any): Promise<void>;
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  /** Human-readable transport name for log messages (e.g. "stdio", "SSE", "streamable-http"). */
+  protected abstract get transportName(): string;
+
+  /**
+   * Route an incoming JSON-RPC message to the appropriate handler:
+   * - notifications/tools/list_changed -> trigger tool refresh
+   * - Other notifications -> debug log
+   * - Responses with id -> resolve/reject matching pending request
+   */
+  protected handleMessage(message: any): void {
+    if (!message.id && message.method === "notifications/tools/list_changed") {
+      if (this.onReconnected) {
+        this.onReconnected().catch((error) => {
+          this.logger.error("[mcp-bridge] Failed to refresh tools after list_changed notification:", error);
+        });
+      }
+      return;
+    }
+
+    if (!message.id && message.method) {
+      this.logger.debug(`[mcp-bridge] Unhandled ${this.transportName} notification: ${message.method}`);
+      return;
+    }
+
+    if (message.id && this.pendingRequests.has(message.id)) {
+      const pending = this.pendingRequests.get(message.id)!;
+      clearTimeout(pending.timeout);
+      this.pendingRequests.delete(message.id);
+
+      if (message.error) {
+        pending.reject(new Error(message.error.message || "MCP error"));
+      } else {
+        pending.resolve(message);
+      }
+    }
+  }
+
+  /** Reject and clear all pending requests with the given reason. */
+  protected rejectAllPending(reason: string): void {
+    for (const [, pending] of this.pendingRequests) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error(reason));
+    }
+    this.pendingRequests.clear();
+  }
+
+  /**
+   * Schedule a reconnection attempt with exponential backoff and jitter.
+   * Rejects all pending requests before scheduling.
+   */
+  protected scheduleReconnect(): void {
+    if (this.reconnectTimer) return;
+
+    this.connected = false;
+    this.rejectAllPending("Connection lost, request cancelled");
+
+    const baseDelay = this.clientConfig.reconnectIntervalMs || 30000;
+    if (this.backoffDelay <= 0) {
+      this.backoffDelay = baseDelay;
+    }
+    const jitter = 0.5 + Math.random(); // 0.5x-1.5x jitter
+    const reconnectInterval = Math.round(this.backoffDelay * jitter);
+    this.reconnectTimer = setTimeout(async () => {
+      this.reconnectTimer = null;
+      try {
+        await this.connect();
+        this.logger.info(`${this.transportName} transport reconnected successfully`);
+        this.backoffDelay = baseDelay;
+
+        if (this.onReconnected) {
+          await this.onReconnected();
+        }
+      } catch (error) {
+        this.logger.error("Reconnection failed:", error);
+        this.backoffDelay = Math.min(this.backoffDelay * 2, 300000);
+        this.scheduleReconnect();
+      }
+    }, reconnectInterval);
+  }
+
+  /** Cancel any scheduled reconnection timer. */
+  protected cleanupReconnectTimer(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+}
+
+// -- Shared utility functions -----------------------------------------------
+
+/**
+ * Resolve ${VAR} placeholders in a single string value using environment variables.
+ * Throws if a referenced variable is not defined.
+ *
+ * @param value - String potentially containing ${VAR} placeholders
+ * @param contextDescription - Human-readable context for error messages (e.g. 'header "Authorization"')
+ * @param extraEnv - Additional env vars to check before process.env (e.g. merged child process env)
+ */
+export function resolveEnvVars(
+  value: string,
+  contextDescription: string,
+  extraEnv?: Record<string, string | undefined>
+): string {
+  return value.replace(/\$\{(\w+)\}/g, (_, varName) => {
+    const resolved = extraEnv?.[varName] ?? process.env[varName];
+    if (resolved === undefined) {
+      throw new Error(`[mcp-bridge] Missing required environment variable "${varName}" while resolving ${contextDescription}`);
+    }
+    return resolved;
+  });
+}
+
+/**
+ * Resolve ${VAR} placeholders in all values of a Record<string, string>.
+ *
+ * @param record - Key-value pairs with potential ${VAR} placeholders in values
+ * @param contextPrefix - Prefix for error context (e.g. "header", "env key")
+ * @param extraEnv - Additional env vars to check before process.env
+ */
+export function resolveEnvRecord(
+  record: Record<string, string>,
+  contextPrefix: string,
+  extraEnv?: Record<string, string | undefined>
+): Record<string, string> {
+  const resolved: Record<string, string> = {};
+  for (const [key, value] of Object.entries(record)) {
+    resolved[key] = resolveEnvVars(value, `${contextPrefix} "${key}"`, extraEnv);
+  }
+  return resolved;
+}
+
+/**
+ * Resolve ${VAR} placeholders in an array of command arguments.
+ *
+ * @param args - Array of argument strings with potential ${VAR} placeholders
+ * @param extraEnv - Additional env vars to check before process.env
+ */
+export function resolveArgs(
+  args: string[],
+  extraEnv?: Record<string, string | undefined>
+): string[] {
+  return args.map(arg =>
+    resolveEnvVars(arg, `arg "${arg}"`, extraEnv)
+  );
+}
+
+/**
+ * Warn if a URL uses non-TLS HTTP to a remote (non-localhost) host.
+ */
+export function warnIfNonTlsRemoteUrl(rawUrl: string, logger: any): void {
+  try {
+    const parsed = new URL(rawUrl);
+    if (parsed.protocol !== "http:") return;
+    const host = parsed.hostname;
+    if (host === "localhost" || host === "127.0.0.1" || host === "::1") return;
+    logger.warn(`[mcp-bridge] WARNING: Non-TLS connection to ${host} — credentials may be transmitted in plaintext`);
+  } catch {
+    // Ignore malformed URL here; connect() validation will fail later.
+  }
+}