@aiwerk/mcp-bridge 1.0.0 → 1.0.2

package/dist/src/standalone-server.js

@@ -0,0 +1,312 @@
+import { McpRouter } from "./mcp-router.js";
+import { fetchToolsList, initializeProtocol, PACKAGE_VERSION } from "./protocol.js";
+import { pickRegisteredToolName } from "./tool-naming.js";
+import { SseTransport } from "./transport-sse.js";
+import { StdioTransport } from "./transport-stdio.js";
+import { StreamableHttpTransport } from "./transport-streamable-http.js";
+/**
+ * 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 {
+    config;
+    logger;
+    router = null;
+    initialized = false;
+    // Direct mode state
+    directTools = [];
+    directConnections = new Map();
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+        if (this.isRouterMode()) {
+            this.router = new McpRouter(config.servers || {}, config, logger);
+        }
+    }
+    isRouterMode() {
+        return (this.config.mode ?? "router") === "router";
+    }
+    /** Start stdio mode: read JSON-RPC from stdin, write responses to stdout. */
+    async startStdio() {
+        const stdin = process.stdin;
+        const stdout = process.stdout;
+        stdin.setEncoding("utf8");
+        let buffer = "";
+        stdin.on("data", (chunk) => {
+            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");
+    }
+    processLine(line, stdout) {
+        let request;
+        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) }
+            });
+        });
+    }
+    writeResponse(stdout, response) {
+        stdout.write(JSON.stringify(response) + "\n");
+    }
+    /** Handle a single MCP JSON-RPC request. */
+    async handleRequest(request) {
+        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}` }
+                };
+        }
+    }
+    handleInitialize(id) {
+        this.initialized = true;
+        return {
+            jsonrpc: "2.0",
+            id,
+            result: {
+                protocolVersion: "2024-11-05",
+                capabilities: {
+                    tools: {}
+                },
+                serverInfo: {
+                    name: "mcp-bridge",
+                    version: PACKAGE_VERSION
+                }
+            }
+        };
+    }
+    async handleToolsList(id) {
+        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 } };
+    }
+    async handleToolsCall(id, params) {
+        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). */
+    async discoverDirectTools() {
+        if (this.directTools.length > 0)
+            return; // Already discovered
+        const globalNames = new Set();
+        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();
+                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);
+            }
+        }
+    }
+    createTransport(serverName, serverConfig) {
+        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() {
+        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/dist/src/tool-naming.d.ts

@@ -0,0 +1,3 @@
+export declare function pickRegisteredToolName(serverName: string, toolName: string, toolPrefix: boolean | "auto" | undefined, localNames: Set<string>, globalNames: Set<string>, logger?: {
+    warn: (...args: unknown[]) => void;
+}): string;

package/dist/src/tool-naming.js

@@ -0,0 +1,38 @@
+function isNameTaken(name, localNames, globalNames) {
+    return localNames.has(name) || globalNames.has(name);
+}
+export function pickRegisteredToolName(serverName, toolName, toolPrefix, localNames, globalNames, logger) {
+    // toolPrefix: true = always prefix (default), false = never prefix, "auto" = prefix only on collision
+    const effectivePrefix = toolPrefix === undefined ? true : toolPrefix;
+    let candidate;
+    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/dist/src/transport-base.d.ts

@@ -0,0 +1,76 @@
+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 declare abstract class BaseTransport implements McpTransport {
+    protected config: McpServerConfig;
+    protected clientConfig: any;
+    protected connected: boolean;
+    protected pendingRequests: Map<number, PendingRequest>;
+    protected logger: any;
+    protected reconnectTimer: NodeJS.Timeout | null;
+    protected onReconnected?: () => Promise<void>;
+    protected backoffDelay: number;
+    constructor(config: McpServerConfig, clientConfig: any, logger: any, onReconnected?: () => Promise<void>);
+    abstract connect(): Promise<void>;
+    abstract disconnect(): Promise<void>;
+    abstract sendRequest(request: McpRequest): Promise<McpResponse>;
+    abstract sendNotification(notification: any): Promise<void>;
+    isConnected(): boolean;
+    /** 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;
+    /** Reject and clear all pending requests with the given reason. */
+    protected rejectAllPending(reason: string): void;
+    /**
+     * Schedule a reconnection attempt with exponential backoff and jitter.
+     * Rejects all pending requests before scheduling.
+     */
+    protected scheduleReconnect(): void;
+    /** Cancel any scheduled reconnection timer. */
+    protected cleanupReconnectTimer(): void;
+}
+/**
+ * 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 declare function resolveEnvVars(value: string, contextDescription: string, extraEnv?: Record<string, string | undefined>): string;
+/**
+ * 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 declare function resolveEnvRecord(record: Record<string, string>, contextPrefix: string, extraEnv?: Record<string, string | undefined>): Record<string, string>;
+/**
+ * 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 declare function resolveArgs(args: string[], extraEnv?: Record<string, string | undefined>): string[];
+/**
+ * Warn if a URL uses non-TLS HTTP to a remote (non-localhost) host.
+ */
+export declare function warnIfNonTlsRemoteUrl(rawUrl: string, logger: any): void;

package/dist/src/transport-base.js

@@ -0,0 +1,163 @@
+/**
+ * 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 class BaseTransport {
+    config;
+    clientConfig;
+    connected = false;
+    pendingRequests = new Map();
+    logger;
+    reconnectTimer = null;
+    onReconnected;
+    backoffDelay = 0;
+    constructor(config, clientConfig, logger, onReconnected) {
+        this.config = config;
+        this.clientConfig = clientConfig;
+        this.logger = logger;
+        this.onReconnected = onReconnected;
+    }
+    isConnected() {
+        return this.connected;
+    }
+    /**
+     * 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
+     */
+    handleMessage(message) {
+        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. */
+    rejectAllPending(reason) {
+        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.
+     */
+    scheduleReconnect() {
+        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. */
+    cleanupReconnectTimer() {
+        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, contextDescription, extraEnv) {
+    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, contextPrefix, extraEnv) {
+    const resolved = {};
+    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, extraEnv) {
+    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, logger) {
+    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.
+    }
+}

package/dist/src/transport-sse.d.ts

@@ -0,0 +1,16 @@
+import { McpRequest, McpResponse } from "./types.js";
+import { BaseTransport } from "./transport-base.js";
+export declare class SseTransport extends BaseTransport {
+    private endpointUrl;
+    private sseAbortController;
+    private currentDataBuffer;
+    protected get transportName(): string;
+    connect(): Promise<void>;
+    private _onEndpointReceived;
+    private startEventStream;
+    private processEventLine;
+    sendNotification(notification: any): Promise<void>;
+    sendRequest(request: McpRequest): Promise<McpResponse>;
+    private isSameOrigin;
+    disconnect(): Promise<void>;
+}