@aiwerk/mcp-bridge 1.0.0

package/src/transport-streamable-http.ts

@@ -0,0 +1,188 @@
+import { McpRequest, McpResponse, McpServerConfig, nextRequestId } from "./types.js";
+import { BaseTransport, resolveEnvRecord, warnIfNonTlsRemoteUrl } from "./transport-base.js";
+
+export class StreamableHttpTransport extends BaseTransport {
+  private sessionId?: string;
+
+  protected get transportName(): string { return "streamable-http"; }
+
+  async connect(): Promise<void> {
+    if (!this.config.url) {
+      throw new Error("Streamable HTTP transport requires URL");
+    }
+
+    warnIfNonTlsRemoteUrl(this.config.url, this.logger);
+    // Validate that all header env vars resolve (fail fast)
+    resolveEnvRecord(this.config.headers || {}, "header");
+    await this.probeServer();
+
+    this.connected = true;
+    this.backoffDelay = this.clientConfig.reconnectIntervalMs || 30000;
+    this.logger.info(`[mcp-bridge] Streamable HTTP transport ready for ${this.config.url}`);
+  }
+
+  async sendRequest(request: McpRequest): Promise<McpResponse> {
+    if (!this.connected || !this.config.url) {
+      throw new Error("Streamable HTTP transport not connected");
+    }
+
+    const id = nextRequestId();
+    const requestWithId = { ...request, id };
+
+    return new Promise((resolve, reject) => {
+      const requestTimeout = this.clientConfig.requestTimeoutMs || 60000;
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(id);
+        reject(new Error(`Request timeout after ${requestTimeout}ms`));
+      }, requestTimeout);
+
+      this.pendingRequests.set(id, { resolve, reject, timeout });
+
+      const headers = resolveEnvRecord({
+        "Accept": "application/json, text/event-stream",
+        ...this.config.headers,
+        "Content-Type": "application/json"
+      }, "header");
+
+      if (this.sessionId) {
+        headers["mcp-session-id"] = this.sessionId;
+      }
+
+      fetch(this.config.url!, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(requestWithId)
+      })
+        .then(async response => {
+          const responseSessionId = response.headers.get("mcp-session-id");
+          if (responseSessionId) {
+            this.sessionId = responseSessionId;
+          }
+
+          if (!response.ok) {
+            clearTimeout(timeout);
+            this.pendingRequests.delete(id);
+            reject(new Error(`HTTP ${response.status}: ${response.statusText}`));
+            return;
+          }
+
+          try {
+            const contentType = response.headers.get("content-type") || "";
+            let jsonResponse: any;
+
+            if (contentType.includes("text/event-stream")) {
+              const text = await response.text();
+              const dataLines = text.split('\n')
+                .filter((line: string) => line.startsWith('data:'))
+                .map((line: string) => line.substring(5).trim());
+              if (dataLines.length > 0) {
+                jsonResponse = JSON.parse(dataLines[dataLines.length - 1]);
+              } else {
+                throw new Error("No data lines in SSE response");
+              }
+            } else {
+              jsonResponse = await response.json();
+            }
+
+            this.handleMessage(jsonResponse);
+          } catch (error) {
+            clearTimeout(timeout);
+            this.pendingRequests.delete(id);
+            reject(new Error("Failed to parse response: " + (error instanceof Error ? error.message : String(error))));
+          }
+        })
+        .catch(error => {
+          clearTimeout(timeout);
+          this.pendingRequests.delete(id);
+
+          if (error.name === 'TypeError' && error.message.includes('fetch')) {
+            this.logger.error("Connection error, scheduling reconnect:", error.message);
+            this.scheduleReconnect();
+          }
+
+          reject(error);
+        });
+    });
+  }
+
+  async sendNotification(notification: any): Promise<void> {
+    if (!this.connected || !this.config.url) {
+      throw new Error("Streamable HTTP transport not connected");
+    }
+
+    const headers = resolveEnvRecord({
+      "Accept": "application/json, text/event-stream",
+      ...this.config.headers,
+      "Content-Type": "application/json"
+    }, "header");
+
+    if (this.sessionId) {
+      headers["mcp-session-id"] = this.sessionId;
+    }
+
+    try {
+      const response = await fetch(this.config.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(notification)
+      });
+
+      const responseSessionId = response.headers.get("mcp-session-id");
+      if (responseSessionId) {
+        this.sessionId = responseSessionId;
+      }
+
+      if (!response.ok && response.status >= 500) {
+        throw new Error(`Server error: HTTP ${response.status}`);
+      }
+    } catch (error) {
+      if (error instanceof Error && error.name === 'TypeError' && error.message.includes('fetch')) {
+        this.logger.error("Connection error during notification, scheduling reconnect:", error.message);
+        this.scheduleReconnect();
+      }
+      throw error;
+    }
+  }
+
+  private async probeServer(): Promise<void> {
+    if (!this.config.url) return;
+
+    try {
+      const optionsResponse = await fetch(this.config.url, { method: "OPTIONS" });
+      if (optionsResponse.ok) return;
+
+      const headers = resolveEnvRecord(this.config.headers || {}, "header");
+      const headResponse = await fetch(this.config.url, { method: "HEAD", headers });
+      if (!headResponse.ok) {
+        this.logger.warn(`[mcp-bridge] Streamable HTTP server probe: OPTIONS ${optionsResponse.status}, HEAD ${headResponse.status} (non-blocking, connection continues)`);
+      }
+    } catch (error: any) {
+      this.logger.warn(`[mcp-bridge] Streamable HTTP server probe failed (non-blocking): ${error?.message || error}`);
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    this.connected = false;
+    this.cleanupReconnectTimer();
+
+    // Send DELETE request if we have a session to clean up
+    if (this.sessionId && this.config.url) {
+      try {
+        const headers = resolveEnvRecord(this.config.headers || {}, "header");
+        headers["mcp-session-id"] = this.sessionId;
+
+        await fetch(this.config.url, {
+          method: "DELETE",
+          headers
+        });
+
+        this.sessionId = undefined;
+        this.logger.info("Streamable HTTP session cleaned up");
+      } catch (error) {
+        this.logger.warn("Failed to clean up session on disconnect:", error);
+      }
+    }
+
+    this.rejectAllPending("Connection closed");
+  }
+}

package/src/types.ts

@@ -0,0 +1,88 @@
+export interface Logger {
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+  debug: (...args: unknown[]) => void;
+}
+
+export interface McpServerConfig {
+  transport: "sse" | "stdio" | "streamable-http";
+  /** Human-readable description for router tool description generation */
+  description?: string;
+  // SSE transport
+  url?: string;
+  headers?: Record<string, string>;
+  // Stdio transport
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  // Stdio framing override (default: auto-detect from first message)
+  framing?: "auto" | "lsp" | "newline";
+}
+
+export interface McpClientConfig {
+  servers: Record<string, McpServerConfig>;
+  mode?: "direct" | "router";
+  toolPrefix?: boolean | "auto";
+  reconnectIntervalMs?: number;
+  connectionTimeoutMs?: number;
+  requestTimeoutMs?: number;
+  routerIdleTimeoutMs?: number;
+  routerMaxConcurrent?: number;
+}
+
+export interface McpTool {
+  name: string;
+  description: string;
+  inputSchema: any; // JSON Schema
+}
+
+export interface McpRequest {
+  jsonrpc: "2.0";
+  id?: number;
+  method: string;
+  params?: any;
+}
+
+let globalRequestId = 1;
+
+export function nextRequestId(): number {
+  return globalRequestId++;
+}
+
+export interface McpResponse {
+  jsonrpc: "2.0";
+  id: number;
+  result?: any;
+  error?: {
+    code: number;
+    message: string;
+    data?: any;
+  };
+}
+
+export interface McpTransport {
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  sendRequest(request: McpRequest): Promise<McpResponse>;
+  sendNotification(notification: any): Promise<void>;
+  isConnected(): boolean;
+}
+
+export interface McpServerConnection {
+  name: string;
+  transport: McpTransport;
+  tools: McpTool[];
+  isInitialized: boolean;
+  registeredToolNames: string[];
+}
+
+/** Bridge-level config loaded from ~/.mcp-bridge/config.json */
+export interface BridgeConfig extends McpClientConfig {
+  http?: {
+    auth?: {
+      type: "bearer";
+      token: string;
+    };
+  };
+}

package/src/update-checker.ts

@@ -0,0 +1,155 @@
+import { execSync, exec as execCb } from "child_process";
+import { Logger } from "./types.js";
+import { PACKAGE_VERSION } from "./protocol.js";
+
+export interface UpdateInfo {
+  currentVersion: string;
+  latestVersion: string;
+  updateAvailable: boolean;
+  updateCommand: string;
+}
+
+const PACKAGE_NAME = "@aiwerk/mcp-bridge";
+
+let cachedUpdateInfo: UpdateInfo | null = null;
+let noticeDelivered = false;
+
+/**
+ * Check npm registry for a newer version. Non-blocking, best-effort.
+ * Caches result for the lifetime of the process.
+ */
+export async function checkForUpdate(logger: Logger): Promise<UpdateInfo> {
+  if (cachedUpdateInfo) return cachedUpdateInfo;
+
+  const current = PACKAGE_VERSION;
+  const updateCmd = `npm update -g ${PACKAGE_NAME}`;
+
+  try {
+    const latest = await npmViewVersion(logger);
+    const updateAvailable = latest !== current && isNewer(latest, current);
+
+    cachedUpdateInfo = {
+      currentVersion: current,
+      latestVersion: latest,
+      updateAvailable,
+      updateCommand: updateCmd,
+    };
+
+    if (updateAvailable) {
+      logger.info(`[mcp-bridge] Update available: ${current} → ${latest}`);
+    } else {
+      logger.info(`[mcp-bridge] Version ${current} is up to date`);
+    }
+  } catch (err) {
+    logger.warn(`[mcp-bridge] Version check failed: ${err instanceof Error ? err.message : err}`);
+    cachedUpdateInfo = {
+      currentVersion: current,
+      latestVersion: current,
+      updateAvailable: false,
+      updateCommand: updateCmd,
+    };
+  }
+
+  return cachedUpdateInfo;
+}
+
+/**
+ * Build the notice string to inject into the first tool response.
+ * Returns empty string if no update or already delivered.
+ */
+export function getUpdateNotice(): string {
+  if (noticeDelivered || !cachedUpdateInfo?.updateAvailable) return "";
+  noticeDelivered = true;
+  return (
+    `\n\n---\nUpdate available: ${cachedUpdateInfo.currentVersion} → ${cachedUpdateInfo.latestVersion}\n` +
+    `Run: ${cachedUpdateInfo.updateCommand}`
+  );
+}
+
+/**
+ * Reset the notice flag (for testing).
+ */
+export function resetNoticeFlag(): void {
+  noticeDelivered = false;
+}
+
+/**
+ * Execute the actual npm update. Returns a result message.
+ */
+export async function runUpdate(logger: Logger): Promise<string> {
+  const info = cachedUpdateInfo ?? await checkForUpdate(logger);
+
+  if (!info.updateAvailable) {
+    return `MCP Bridge is already up to date (v${info.currentVersion}).`;
+  }
+
+  logger.info(`[mcp-bridge] Running update: ${info.updateCommand}`);
+
+  try {
+    const output = await execAsync(info.updateCommand, 60_000);
+    // Invalidate cache so next check re-fetches
+    cachedUpdateInfo = null;
+    noticeDelivered = false;
+
+    // Verify new version
+    const newVersion = npmViewVersionSync(logger);
+    return (
+      `MCP Bridge updated: ${info.currentVersion} → ${newVersion}\n` +
+      `A restart is needed to load the new version.\n\n` +
+      `npm output:\n${output.trim()}`
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.error(`[mcp-bridge] Update failed: ${msg}`);
+    return (
+      `Update failed. You can try manually:\n` +
+      `${info.updateCommand}\n\nError: ${msg}`
+    );
+  }
+}
+
+// --- helpers ---
+
+function npmViewVersion(_logger: Logger): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error("npm view timed out")), 10_000);
+    execCb(`npm view ${PACKAGE_NAME} version`, { encoding: "utf-8" }, (err, stdout) => {
+      clearTimeout(timeout);
+      if (err) return reject(err);
+      const ver = (stdout ?? "").trim();
+      if (!ver) return reject(new Error("empty version from npm"));
+      resolve(ver);
+    });
+  });
+}
+
+function npmViewVersionSync(_logger: Logger): string {
+  try {
+    return execSync(`npm view ${PACKAGE_NAME} version`, { encoding: "utf-8", timeout: 10_000 }).trim();
+  } catch {
+    return "unknown";
+  }
+}
+
+function execAsync(cmd: string, timeoutMs: number): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error(`Command timed out after ${timeoutMs}ms`)), timeoutMs);
+    execCb(cmd, { encoding: "utf-8", timeout: timeoutMs }, (err, stdout, stderr) => {
+      clearTimeout(timeout);
+      if (err) return reject(new Error(`${err.message}\n${stderr ?? ""}`));
+      resolve(stdout ?? "");
+    });
+  });
+}
+
+function isNewer(latest: string, current: string): boolean {
+  const l = latest.split(".").map(Number);
+  const c = current.split(".").map(Number);
+  for (let i = 0; i < Math.max(l.length, c.length); i++) {
+    const lv = l[i] ?? 0;
+    const cv = c[i] ?? 0;
+    if (lv > cv) return true;
+    if (lv < cv) return false;
+  }
+  return false;
+}

package/tests/collision.test.ts

@@ -0,0 +1,60 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { pickRegisteredToolName } from "../src/tool-naming.ts";
+
+test("auto mode: collision causes second server tool to be prefixed", () => {
+  const globalNames = new Set<string>();
+
+  // "auto" (default) — no prefix unless collision
+  const first = pickRegisteredToolName("alpha", "search", "auto", new Set<string>(), globalNames);
+  globalNames.add(first);
+
+  const second = pickRegisteredToolName("beta", "search", "auto", new Set<string>(), globalNames);
+
+  assert.equal(first, "search");
+  assert.equal(second, "beta_search");
+});
+
+test("auto mode: no collision means no prefix", () => {
+  const globalNames = new Set<string>();
+
+  const first = pickRegisteredToolName("alpha", "search", "auto", new Set<string>(), globalNames);
+  globalNames.add(first);
+
+  const second = pickRegisteredToolName("beta", "list", "auto", new Set<string>(), globalNames);
+
+  assert.equal(first, "search");
+  assert.equal(second, "list");
+});
+
+test("auto mode: undefined defaults to auto", () => {
+  const globalNames = new Set<string>();
+
+  const first = pickRegisteredToolName("alpha", "search", undefined, new Set<string>(), globalNames);
+  globalNames.add(first);
+
+  const second = pickRegisteredToolName("beta", "search", undefined, new Set<string>(), globalNames);
+
+  assert.equal(first, "search");
+  assert.equal(second, "beta_search");
+});
+
+test("true mode: always prefixes", () => {
+  const globalNames = new Set<string>();
+
+  const name = pickRegisteredToolName("alpha", "search", true, new Set<string>(), globalNames);
+
+  assert.equal(name, "alpha_search");
+});
+
+test("false mode: never prefixes, uses suffix on collision", () => {
+  const globalNames = new Set<string>();
+
+  const first = pickRegisteredToolName("alpha", "search", false, new Set<string>(), globalNames);
+  globalNames.add(first);
+
+  const second = pickRegisteredToolName("beta", "search", false, new Set<string>(), globalNames);
+
+  assert.equal(first, "search");
+  assert.equal(second, "search_2");
+});

package/tests/env-resolve.test.ts

@@ -0,0 +1,68 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { resolveEnvVars, resolveEnvRecord, resolveArgs } from "../src/transport-base.ts";
+
+test("resolveEnvRecord throws when env var is missing", () => {
+  assert.throws(
+    () => resolveEnvRecord({ TOKEN: "${MISSING_TEST_ENV}" }, "env key"),
+    /Missing required environment variable/
+  );
+});
+
+test("resolveArgs resolves env vars in args", () => {
+  const env = { MY_TOKEN: "secret123" };
+  const result = resolveArgs(["--token", "${MY_TOKEN}", "--verbose"], env);
+  assert.deepStrictEqual(result, ["--token", "secret123", "--verbose"]);
+});
+
+test("resolveArgs throws when env var is missing in args", () => {
+  assert.throws(
+    () => resolveArgs(["--token", "${MISSING_TEST_ENV}"], {}),
+    /Missing required environment variable/
+  );
+});
+
+test("resolveArgs passes through args without variables", () => {
+  const result = resolveArgs(["-y", "@llmindset/mcp-miro", "--verbose"], {});
+  assert.deepStrictEqual(result, ["-y", "@llmindset/mcp-miro", "--verbose"]);
+});
+
+test("resolveEnvRecord resolves headers with env vars", () => {
+  process.env.__TEST_MCP_TOKEN = "test-secret-456";
+  try {
+    const result = resolveEnvRecord(
+      { Authorization: "Bearer ${__TEST_MCP_TOKEN}" },
+      "header"
+    );
+    assert.deepStrictEqual(result, { Authorization: "Bearer test-secret-456" });
+  } finally {
+    delete process.env.__TEST_MCP_TOKEN;
+  }
+});
+
+test("resolveEnvRecord throws for missing header env var", () => {
+  assert.throws(
+    () => resolveEnvRecord({ Authorization: "Bearer ${MISSING_TEST_ENV}" }, "header"),
+    /Missing required environment variable/
+  );
+});
+
+test("resolveEnvVars resolves single value", () => {
+  process.env.__TEST_MCP_SINGLE = "hello";
+  try {
+    const result = resolveEnvVars("prefix-${__TEST_MCP_SINGLE}-suffix", "test");
+    assert.equal(result, "prefix-hello-suffix");
+  } finally {
+    delete process.env.__TEST_MCP_SINGLE;
+  }
+});
+
+test("resolveEnvVars uses extraEnv before process.env", () => {
+  process.env.__TEST_MCP_PRIO = "from-process";
+  try {
+    const result = resolveEnvVars("${__TEST_MCP_PRIO}", "test", { __TEST_MCP_PRIO: "from-extra" });
+    assert.equal(result, "from-extra");
+  } finally {
+    delete process.env.__TEST_MCP_PRIO;
+  }
+});