@aiwerk/mcp-bridge 1.0.0 → 1.0.2

package/dist/src/mcp-router.js

@@ -0,0 +1,271 @@
+import { SseTransport } from "./transport-sse.js";
+import { StdioTransport } from "./transport-stdio.js";
+import { StreamableHttpTransport } from "./transport-streamable-http.js";
+import { fetchToolsList, initializeProtocol, PACKAGE_VERSION } from "./protocol.js";
+const DEFAULT_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
+const DEFAULT_MAX_CONCURRENT = 5;
+export class McpRouter {
+    servers;
+    clientConfig;
+    logger;
+    transportRefs;
+    idleTimeoutMs;
+    maxConcurrent;
+    states = new Map();
+    constructor(servers, clientConfig, logger, transportRefs) {
+        this.servers = servers;
+        this.clientConfig = clientConfig;
+        this.logger = logger;
+        this.transportRefs = {
+            sse: transportRefs?.sse ?? SseTransport,
+            stdio: transportRefs?.stdio ?? StdioTransport,
+            streamableHttp: transportRefs?.streamableHttp ?? StreamableHttpTransport
+        };
+        this.idleTimeoutMs = clientConfig.routerIdleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+        this.maxConcurrent = clientConfig.routerMaxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+    }
+    static generateDescription(servers) {
+        const serverNames = Object.keys(servers);
+        if (serverNames.length === 0) {
+            return "Call MCP server tools. No servers configured.";
+        }
+        const serverList = serverNames
+            .map((name) => {
+            const desc = servers[name].description;
+            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='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.`;
+    }
+    async dispatch(server, action = "call", tool, params) {
+        try {
+            const normalizedAction = action || "call";
+            // Status action: no server required, shows all server states
+            if (normalizedAction === "status") {
+                return this.getStatus();
+            }
+            if (!server) {
+                return this.error("invalid_params", "server is required");
+            }
+            if (!this.servers[server]) {
+                return this.error("unknown_server", `Server '${server}' not found`, Object.keys(this.servers));
+            }
+            if (normalizedAction === "list") {
+                try {
+                    const tools = await this.getToolList(server);
+                    return { server, action: "list", tools };
+                }
+                catch (error) {
+                    return this.error("connection_failed", `Failed to connect to ${server}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            if (normalizedAction === "refresh") {
+                try {
+                    const state = await this.ensureConnected(server);
+                    state.toolsCache = undefined;
+                    state.toolNames = [];
+                    const tools = await this.getToolList(server);
+                    return { server, action: "refresh", refreshed: true, tools };
+                }
+                catch (error) {
+                    return this.error("connection_failed", `Failed to connect to ${server}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            if (normalizedAction !== "call") {
+                return this.error("invalid_params", `action must be one of: list, call, refresh`);
+            }
+            if (!tool) {
+                return this.error("invalid_params", "tool is required for action=call");
+            }
+            try {
+                await this.getToolList(server);
+            }
+            catch (error) {
+                return this.error("connection_failed", `Failed to connect to ${server}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const state = this.states.get(server);
+            if (!state.toolNames.includes(tool)) {
+                return this.error("unknown_tool", `Tool '${tool}' not found on server '${server}'`, state.toolNames);
+            }
+            this.markUsed(server);
+            const response = await state.transport.sendRequest({
+                jsonrpc: "2.0",
+                method: "tools/call",
+                params: {
+                    name: tool,
+                    arguments: params ?? {}
+                }
+            });
+            if (response.error) {
+                return this.error("mcp_error", response.error.message, undefined, response.error.code);
+            }
+            return { server, action: "call", tool, result: response.result };
+        }
+        catch (error) {
+            return this.error("mcp_error", error instanceof Error ? error.message : String(error));
+        }
+    }
+    async getToolList(server) {
+        if (!this.servers[server]) {
+            throw new Error(`Server '${server}' not found`);
+        }
+        const state = await this.ensureConnected(server);
+        if (state.toolsCache) {
+            this.markUsed(server);
+            return state.toolsCache;
+        }
+        const tools = await fetchToolsList(state.transport);
+        state.toolNames = tools.map((tool) => tool.name);
+        state.toolsCache = tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description || "",
+            requiredParams: this.extractRequiredParams(tool)
+        }));
+        this.markUsed(server);
+        return state.toolsCache;
+    }
+    getStatus() {
+        const serverStatuses = Object.entries(this.servers).map(([name, config]) => {
+            const state = this.states.get(name);
+            let status = "disconnected";
+            if (state?.transport.isConnected()) {
+                const idleMs = Date.now() - state.lastUsedAt;
+                status = idleMs > 60_000 ? "idle" : "connected";
+            }
+            return {
+                name,
+                transport: config.transport,
+                status,
+                tools: state?.toolNames.length ?? 0,
+                ...(state?.lastUsedAt ? { lastUsed: new Date(state.lastUsedAt).toISOString() } : {})
+            };
+        });
+        return { action: "status", servers: serverStatuses };
+    }
+    async disconnectAll() {
+        for (const serverName of Object.keys(this.servers)) {
+            await this.disconnectServer(serverName);
+        }
+    }
+    async ensureConnected(server) {
+        let state = this.states.get(server);
+        if (!state) {
+            const transport = this.createTransport(server, this.servers[server]);
+            state = {
+                transport,
+                initialized: false,
+                toolNames: [],
+                lastUsedAt: Date.now(),
+                idleTimer: null
+            };
+            this.states.set(server, state);
+        }
+        if (state.initPromise) {
+            await state.initPromise;
+            return state;
+        }
+        state.initPromise = (async () => {
+            if (!state.transport.isConnected()) {
+                await state.transport.connect();
+            }
+            if (!state.initialized) {
+                await initializeProtocol(state.transport, PACKAGE_VERSION);
+                state.initialized = true;
+            }
+            this.markUsed(server);
+            await this.enforceMaxConcurrent(server);
+        })();
+        try {
+            await state.initPromise;
+            return state;
+        }
+        finally {
+            state.initPromise = undefined;
+        }
+    }
+    async enforceMaxConcurrent(activeServer) {
+        const connectedServers = [...this.states.entries()]
+            .filter(([_, s]) => s.transport.isConnected())
+            .map(([name, s]) => ({ name, lastUsedAt: s.lastUsedAt }));
+        if (connectedServers.length <= this.maxConcurrent) {
+            return;
+        }
+        connectedServers.sort((a, b) => a.lastUsedAt - b.lastUsedAt);
+        for (const candidate of connectedServers) {
+            if (candidate.name === activeServer) {
+                continue;
+            }
+            await this.disconnectServer(candidate.name);
+            this.logger.info(`[mcp-bridge] Router evicted idle server via LRU: ${candidate.name}`);
+            return;
+        }
+    }
+    async disconnectServer(server) {
+        const state = this.states.get(server);
+        if (!state)
+            return;
+        if (state.idleTimer) {
+            clearTimeout(state.idleTimer);
+            state.idleTimer = null;
+        }
+        if (state.transport.isConnected()) {
+            await state.transport.disconnect();
+        }
+        state.initialized = false;
+        state.toolsCache = undefined;
+        state.toolNames = [];
+    }
+    markUsed(server) {
+        const state = this.states.get(server);
+        if (!state)
+            return;
+        state.lastUsedAt = Date.now();
+        if (state.idleTimer) {
+            clearTimeout(state.idleTimer);
+        }
+        state.idleTimer = setTimeout(() => {
+            this.disconnectServer(server).catch((error) => {
+                this.logger.warn(`[mcp-bridge] Router idle disconnect failed for ${server}:`, error);
+            });
+        }, this.idleTimeoutMs);
+        // Don't keep the process alive just for idle disconnect
+        if (state.idleTimer && typeof state.idleTimer.unref === "function") {
+            state.idleTimer.unref();
+        }
+    }
+    createTransport(serverName, serverConfig) {
+        const onReconnected = async () => {
+            const state = this.states.get(serverName);
+            if (!state)
+                return;
+            state.initialized = false;
+            state.toolsCache = undefined;
+            state.toolNames = [];
+        };
+        if (serverConfig.transport === "sse") {
+            return new this.transportRefs.sse(serverConfig, this.clientConfig, this.logger, onReconnected);
+        }
+        if (serverConfig.transport === "stdio") {
+            return new this.transportRefs.stdio(serverConfig, this.clientConfig, this.logger, onReconnected);
+        }
+        if (serverConfig.transport === "streamable-http") {
+            return new this.transportRefs.streamableHttp(serverConfig, this.clientConfig, this.logger, onReconnected);
+        }
+        throw new Error(`Unsupported transport: ${serverConfig.transport}`);
+    }
+    extractRequiredParams(tool) {
+        const required = tool.inputSchema?.required;
+        if (!Array.isArray(required)) {
+            return [];
+        }
+        return required.filter((name) => typeof name === "string");
+    }
+    error(error, message, available, code) {
+        return {
+            error,
+            message,
+            ...(available ? { available } : {}),
+            ...(typeof code === "number" ? { code } : {})
+        };
+    }
+}

package/dist/src/protocol.d.ts

@@ -0,0 +1,4 @@
+import { McpTool, McpTransport } from "./types.js";
+export declare const PACKAGE_VERSION: string;
+export declare function initializeProtocol(transport: McpTransport, version: string): Promise<void>;
+export declare function fetchToolsList(transport: McpTransport): Promise<McpTool[]>;

package/dist/src/protocol.js

@@ -0,0 +1,58 @@
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export const PACKAGE_VERSION = (() => {
+    try {
+        return JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+export async function initializeProtocol(transport, version) {
+    const initRequest = {
+        jsonrpc: "2.0",
+        method: "initialize",
+        params: {
+            protocolVersion: "2024-11-05",
+            capabilities: {},
+            clientInfo: {
+                name: "mcp-bridge",
+                version: version || PACKAGE_VERSION
+            }
+        }
+    };
+    const response = await transport.sendRequest(initRequest);
+    if (response.error) {
+        throw new Error(`Initialize failed: ${response.error.message}`);
+    }
+    await transport.sendNotification({
+        jsonrpc: "2.0",
+        method: "notifications/initialized"
+    });
+}
+export async function fetchToolsList(transport) {
+    const allTools = [];
+    let cursor;
+    while (true) {
+        const request = {
+            jsonrpc: "2.0",
+            method: "tools/list",
+            ...(cursor ? { params: { cursor } } : {})
+        };
+        const response = await transport.sendRequest(request);
+        if (response.error) {
+            throw new Error(response.error.message);
+        }
+        const pageTools = Array.isArray(response.result?.tools) ? response.result.tools : [];
+        allTools.push(...pageTools);
+        const nextCursor = response.result?.nextCursor;
+        if (!nextCursor) {
+            break;
+        }
+        cursor = nextCursor;
+    }
+    return allTools;
+}

package/dist/src/schema-convert.d.ts

@@ -0,0 +1,11 @@
+type TSchema = any;
+type TypeBoxMod = {
+    Type: any;
+} | null;
+export declare function setTypeBoxLoader(loader: (() => Promise<TypeBoxMod>) | null): void;
+export declare function setSchemaLogger(logger: {
+    warn: (...args: unknown[]) => void;
+}): void;
+export declare function convertJsonSchemaToTypeBox(schema: any, depth?: number): Promise<TSchema>;
+export declare function createToolParameters(inputSchema: any): Promise<TSchema>;
+export {};

package/dist/src/schema-convert.js

@@ -0,0 +1,150 @@
+let cachedTypeBoxPromise = null;
+// Overridable loader for dependency injection (used by tests)
+let typeBoxLoader = null;
+export function setTypeBoxLoader(loader) {
+    typeBoxLoader = loader;
+    cachedTypeBoxPromise = null; // auto-reset cache
+}
+async function getTypeBox() {
+    // If a test loader is set, always use it (bypass cache)
+    if (typeBoxLoader) {
+        return typeBoxLoader();
+    }
+    if (cachedTypeBoxPromise) {
+        return cachedTypeBoxPromise;
+    }
+    cachedTypeBoxPromise = (async () => {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const mod = await import("@sinclair/typebox");
+            const Type = mod?.Type ?? mod?.default?.Type;
+            if (!Type) {
+                throw new Error("TypeBox module missing Type export");
+            }
+            return { Type };
+        }
+        catch (error) {
+            return null;
+        }
+    })();
+    return cachedTypeBoxPromise;
+}
+async function anyFallback() {
+    const typeBox = await getTypeBox();
+    if (typeBox?.Type) {
+        return typeBox.Type.Any();
+    }
+    // Empty schema {} is valid JSON Schema (matches anything), unlike { type: "any" } which is invalid.
+    // This only triggers if @sinclair/typebox is missing — run `npm install` in the plugin directory.
+    schemaLogger.warn("[mcp-bridge] TypeBox unavailable — using permissive empty schema fallback. Run `npm install` to fix.");
+    return {};
+}
+// Logger can be injected via setSchemaLogger(); defaults to console
+let schemaLogger = console;
+export function setSchemaLogger(logger) {
+    schemaLogger = logger;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function convertJsonSchemaToTypeBox(schema, depth = 0) {
+    const typeBox = await getTypeBox();
+    const Type = typeBox?.Type;
+    if (!Type) {
+        return anyFallback();
+    }
+    try {
+        if (depth > 10) {
+            schemaLogger.warn("[mcp-bridge] JSON schema depth limit exceeded (>10), falling back to Type.Any()");
+            return Type.Any();
+        }
+        if (!schema || typeof schema !== "object") {
+            return Type.Any();
+        }
+        // anyOf and oneOf both map to Type.Union (TypeBox doesn't distinguish)
+        const unionSource = schema.anyOf || schema.oneOf;
+        if (Array.isArray(unionSource) && unionSource.length > 0) {
+            const variants = await Promise.all(unionSource.map((item) => convertJsonSchemaToTypeBox(item, depth + 1)));
+            return Type.Union(variants);
+        }
+        // allOf maps to Type.Intersect
+        if (Array.isArray(schema.allOf) && schema.allOf.length > 0) {
+            const parts = await Promise.all(schema.allOf.map((item) => convertJsonSchemaToTypeBox(item, depth + 1)));
+            return Type.Intersect(parts);
+        }
+        switch (schema.type) {
+            case "string": {
+                if (schema.enum) {
+                    return Type.Union(schema.enum.map((value) => Type.Literal(value)));
+                }
+                const stringOptions = {};
+                if (schema.minLength !== undefined)
+                    stringOptions.minLength = schema.minLength;
+                if (schema.maxLength !== undefined)
+                    stringOptions.maxLength = schema.maxLength;
+                if (schema.pattern !== undefined)
+                    stringOptions.pattern = schema.pattern;
+                return Type.String(stringOptions);
+            }
+            case "number":
+            case "integer": {
+                const numberOptions = {};
+                if (schema.minimum !== undefined)
+                    numberOptions.minimum = schema.minimum;
+                if (schema.maximum !== undefined)
+                    numberOptions.maximum = schema.maximum;
+                return Type.Number(numberOptions);
+            }
+            case "boolean":
+                return Type.Boolean();
+            case "array":
+                if (schema.items) {
+                    return Type.Array(await convertJsonSchemaToTypeBox(schema.items, depth + 1));
+                }
+                return Type.Array(Type.Any());
+            case "object":
+                if (schema.properties) {
+                    const propertyEntries = Object.entries(schema.properties);
+                    if (propertyEntries.length > 100) {
+                        schemaLogger.warn("[mcp-bridge] JSON schema object has too many properties (>100), falling back to Type.Any()");
+                        return Type.Any();
+                    }
+                    const properties = {};
+                    const requiredSet = new Set(Array.isArray(schema.required) ? schema.required : []);
+                    for (const [key, value] of propertyEntries) {
+                        const converted = await convertJsonSchemaToTypeBox(value, depth + 1);
+                        properties[key] = requiredSet.has(key) ? converted : Type.Optional(converted);
+                    }
+                    return Type.Object(properties);
+                }
+                return Type.Object({});
+            case "null":
+                return Type.Null();
+            default:
+                return Type.Any();
+        }
+    }
+    catch (error) {
+        schemaLogger.warn("[mcp-bridge] Failed to convert JSON schema, falling back to Type.Any()");
+        return Type.Any();
+    }
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function createToolParameters(inputSchema) {
+    const typeBox = await getTypeBox();
+    const Type = typeBox?.Type;
+    if (!Type) {
+        // TypeBox missing — return the raw JSON Schema as-is
+        schemaLogger.warn("[mcp-bridge] TypeBox unavailable — passing raw JSON Schema. Run `npm install` to fix.");
+        return inputSchema ?? {};
+    }
+    if (!inputSchema) {
+        return Type.Object({});
+    }
+    // If the inputSchema is already a proper object schema, convert it
+    if (inputSchema.type === "object") {
+        return convertJsonSchemaToTypeBox(inputSchema, 0);
+    }
+    // If it's not an object, wrap it in an object
+    return Type.Object({
+        input: await convertJsonSchemaToTypeBox(inputSchema, 0)
+    });
+}

package/dist/src/standalone-server.d.ts

@@ -0,0 +1,30 @@
+import { BridgeConfig, Logger, McpRequest, McpResponse } from "./types.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 declare class StandaloneServer {
+    private config;
+    private logger;
+    private router;
+    private initialized;
+    private directTools;
+    private directConnections;
+    constructor(config: BridgeConfig, logger: Logger);
+    private isRouterMode;
+    /** Start stdio mode: read JSON-RPC from stdin, write responses to stdout. */
+    startStdio(): Promise<void>;
+    private processLine;
+    private writeResponse;
+    /** Handle a single MCP JSON-RPC request. */
+    handleRequest(request: McpRequest): Promise<McpResponse>;
+    private handleInitialize;
+    private handleToolsList;
+    private handleToolsCall;
+    /** Connect to all backend servers and discover their tools (direct mode). */
+    private discoverDirectTools;
+    private createTransport;
+    /** Graceful shutdown: disconnect all backend servers. */
+    shutdown(): Promise<void>;
+}