@eznix/mcp-gateway 1.3.3

package/examples/README.md

@@ -0,0 +1,34 @@
+# Example Configurations
+
+Copy `config.json` to `~/.config/mcp-gateway/config.json` and customize.
+
+## Example Servers
+
+| Server | Type | Description |
+|--------|------|-------------|
+| filesystem | remote | File system operations via HTTP |
+| github | remote | GitHub API operations |
+
+## Usage
+
+```bash
+# Copy to your config location
+cp config.json ~/.config/mcp-gateway/config.json
+
+# Edit as needed
+nano ~/.config/mcp-gateway/config.json
+
+# Run gateway
+bun run index.ts
+```
+
+## Local Server Example
+
+```json
+{
+  "my-server": {
+    "type": "local",
+    "command": ["bun", "run", "/path/to/your/server.ts"]
+  }
+}
+```

package/examples/config.json

@@ -0,0 +1,10 @@
+{
+  "gh_grep": {
+    "type": "remote",
+    "url": "https://mcp.grep.app"
+  },
+  "playwright": {
+    "type": "local",
+    "command": ["bunx", "@playwright/mcp@latest"]
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@eznix/mcp-gateway",
+  "version": "1.3.3",
+  "description": "MCP Gateway - Aggregate multiple MCP servers into a single gateway",
+  "type": "module",
+  "bin": {
+    "mcp-gateway": "./dist/index.js"
+  },
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "start:docker": "bun run src/docker.ts",
+    "build": "bun build src/index.ts --outdir dist --target node",
+    "build:docker": "bun build src/docker.ts --target bun --outfile=gateway",
+    "docker:build": "docker build -t mcp-gateway .",
+    "docker:run": "docker run -p 3000:3000 -v ./examples/config.json:/home/gateway/.config/mcp-gateway/config.json:ro mcp-gateway"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^25.0.9",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "lru-cache": "^11.2.4",
+    "minisearch": "^7.2.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,63 @@
+import { readFileSync, existsSync, watch, type FSWatcher } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+import type { GatewayConfig } from "./types.js";
+
+const DEFAULT_CONFIG_PATH = join(homedir(), ".config", "mcp-gateway", "config.json");
+
+export class Config {
+  private config: GatewayConfig;
+  private configPath: string;
+  private watcher?: FSWatcher;
+
+  constructor(path?: string) {
+    this.configPath = path || process.env.MCP_GATEWAY_CONFIG || DEFAULT_CONFIG_PATH;
+    this.config = this.load();
+  }
+
+  get<K extends keyof GatewayConfig>(key: K): GatewayConfig[K] | undefined {
+    return this.config[key];
+  }
+
+  getAll(): GatewayConfig {
+    return { ...this.config };
+  }
+
+  set(key: string, value: any): void {
+    this.config[key] = value;
+  }
+
+  getPath(): string {
+    return this.configPath;
+  }
+
+  reload(): GatewayConfig {
+    this.config = this.load();
+    return this.config;
+  }
+
+  watch(callback: (config: GatewayConfig) => void): void {
+    if (this.watcher) return;
+    this.watcher = watch(this.configPath, (event: string) => {
+      if (event !== "change") return;
+      this.reload();
+      callback(this.config);
+    });
+    console.error(`  Watching config: ${this.configPath}`);
+  }
+
+  stopWatching(): void {
+    this.watcher?.close();
+    this.watcher = undefined;
+  }
+
+  private load(): GatewayConfig {
+    if (!existsSync(this.configPath)) return {};
+    return JSON.parse(readFileSync(this.configPath, "utf-8"));
+  }
+}
+
+export function getDefaultConfigPath(): string {
+  return process.env.MCP_GATEWAY_CONFIG || DEFAULT_CONFIG_PATH;
+}

package/src/connections.ts

@@ -0,0 +1,116 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { WebSocketClientTransport } from "@modelcontextprotocol/sdk/client/websocket.js";
+import type { UpstreamConfig, ToolCatalogEntry } from "./types.js";
+import { SearchEngine } from "./search.js";
+import { JobManager } from "./jobs.js";
+
+export class ConnectionManager {
+  private upstreams = new Map<string, Client>();
+
+  constructor(
+    private searchEngine: SearchEngine,
+    private jobManager: JobManager,
+  ) {}
+
+  async connect(serverKey: string, config: UpstreamConfig): Promise<void> {
+    if (config.type === "local") {
+      await this.connectLocal(serverKey, config);
+    } else {
+      await this.connectRemote(serverKey, config);
+    }
+  }
+
+  private async connectLocal(serverKey: string, config: UpstreamConfig): Promise<void> {
+    const [cmd, ...args] = config.command || [];
+    if (!cmd) throw new Error(`Missing command for ${serverKey}`);
+
+    const transport = new StdioClientTransport({ command: cmd, args });
+    await this.connectTransport(serverKey, config, transport);
+  }
+
+  private async connectRemote(serverKey: string, config: UpstreamConfig): Promise<void> {
+    const url = new URL(config.url || "");
+    const transportType = config.transport || (url.protocol === "ws:" || url.protocol === "wss:" ? "websocket" : "streamable_http");
+    const transport = transportType === "websocket" ? new WebSocketClientTransport(url) : new StreamableHTTPClientTransport(url);
+    await this.connectTransport(serverKey, config, transport);
+  }
+
+  private async connectTransport(serverKey: string, config: UpstreamConfig, transport: any): Promise<void> {
+    transport.onclose = () => console.error(`[${serverKey}] Connection closed`);
+    transport.onerror = (error: Error) => {
+      // Suppress JSON parse errors from server logs
+      if (error.message.includes("JSON Parse error")) return;
+      console.error(`[${serverKey}] Connection error:`, error.message);
+    };
+
+    const client = new Client({ name: `gateway-${serverKey}`, version: "1.0.0" }, {});
+    await client.connect(transport);
+    this.upstreams.set(serverKey, client);
+
+    await this.refreshCatalog(serverKey, client);
+    console.error(`[${serverKey}] Connected with ${this.countTools(serverKey)} tools`);
+  }
+
+  private async refreshCatalog(serverKey: string, client: Client): Promise<void> {
+    const response = await client.listTools();
+    for (const tool of response.tools) {
+      const entry: ToolCatalogEntry = {
+        id: `${serverKey}::${tool.name}`,
+        server: serverKey,
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      };
+      this.searchEngine.addTool(entry);
+    }
+  }
+
+  private countTools(serverKey: string): number {
+    return this.searchEngine.getTools().filter((t) => t.server === serverKey).length;
+  }
+
+  async connectWithRetry(serverKey: string, config: UpstreamConfig, maxRetries = 5, baseDelay = 1000): Promise<void> {
+    let lastError: Error | undefined;
+    for (let i = 0; i < maxRetries; i++) {
+      try {
+        return await this.connect(serverKey, config);
+      } catch (error) {
+        lastError = error as Error;
+        if (i < maxRetries - 1) {
+          const delay = baseDelay * Math.pow(2, i);
+          console.error(`[${serverKey}] Connection failed (${i + 1}/${maxRetries}), retry in ${delay}ms`);
+          await new Promise((r) => setTimeout(r, delay));
+        }
+      }
+    }
+    throw lastError;
+  }
+
+  getClient(serverKey: string): Client | undefined {
+    return this.upstreams.get(serverKey);
+  }
+
+  getAllClients(): Map<string, Client> {
+    return new Map(this.upstreams);
+  }
+
+  async disconnect(serverKey: string): Promise<void> {
+    const client = this.upstreams.get(serverKey);
+    if (client) {
+      await client.close();
+      this.upstreams.delete(serverKey);
+    }
+  }
+
+  async disconnectAll(): Promise<void> {
+    for (const [key] of this.upstreams) {
+      await this.disconnect(key);
+    }
+  }
+
+  getConnectedServers(): string[] {
+    return Array.from(this.upstreams.keys());
+  }
+}

package/src/docker.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+import packageJson from "../package.json" with { type: "json" };
+import { MCPGateway } from "./gateway.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer } from "http";
+
+async function main() {
+  const gateway = new MCPGateway();
+  const transport = await gateway.startWithHttp(3000);
+
+  const server = createServer(async (req, res) => {
+    if (req.url === "/") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({
+        name: "MCP Gateway",
+        description: "Aggregate multiple MCP servers into a single gateway",
+        version: packageJson.version,
+        endpoints: {
+          mcp: "/mcp",
+          health: "/health"
+        }
+      }, null, 2));
+      return;
+    }
+
+    if (req.url === "/health") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: "ok" }));
+      return;
+    }
+
+    if (req.url === "/mcp" && req.method === "POST") {
+      transport.handleRequest(req, res);
+      return;
+    }
+
+    if (req.url === "/mcp" && req.method === "GET") {
+      transport.handleRequest(req, res);
+      return;
+    }
+
+    res.writeHead(404);
+    res.end("Not found");
+  });
+
+  server.listen(3000, () => {
+    console.error("HTTP server listening on http://localhost:3000");
+    console.error("MCP endpoint: http://localhost:3000/mcp");
+  });
+
+  process.on("SIGINT", async () => {
+    server.close();
+    await gateway.shutdown();
+    process.exit(0);
+  });
+  process.on("SIGTERM", async () => {
+    server.close();
+    await gateway.shutdown();
+    process.exit(0);
+  });
+}
+
+main().catch((err) => { console.error("Fatal error:", err); process.exit(1); });

package/src/gateway.ts

@@ -0,0 +1,114 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+
+import type { GatewayConfig } from "./types.js";
+import { Config } from "./config.js";
+import { SearchEngine } from "./search.js";
+import { JobManager } from "./jobs.js";
+import { ConnectionManager } from "./connections.js";
+import { createServer } from "./handlers.js";
+
+export class MCPGateway {
+  private config: Config;
+  private searchEngine: SearchEngine;
+  private jobManager: JobManager;
+  private connections: ConnectionManager;
+  private server: McpServer;
+
+  constructor(configPath?: string) {
+    this.config = new Config(configPath);
+    this.searchEngine = new SearchEngine();
+    this.jobManager = new JobManager();
+    this.connections = new ConnectionManager(this.searchEngine, this.jobManager);
+    this.server = createServer(this.searchEngine, this.connections, this.jobManager);
+  }
+
+  async connectAll(): Promise<void> {
+    const allConfig = this.config.getAll();
+    const connections = Object.entries(allConfig)
+      .filter(([_, c]) => c.enabled !== false)
+      .map(([k, c]) => this.connections.connectWithRetry(k, c));
+    const results = await Promise.allSettled(connections);
+
+    let success = 0, failed = 0;
+    for (const r of results) r.status === "fulfilled" ? success++ : failed++;
+
+    this.searchEngine.warmup();
+    console.error(`Connected: ${this.searchEngine.getTools().length} tools from ${success} servers (${failed} failed)`);
+  }
+
+  async startWithStdio(): Promise<void> {
+    console.error("MCP Gateway starting (stdio)...");
+
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+
+    console.log(`__MCP_GATEWAY_STDIO_READY__`);
+
+    this.connectAll().catch((err) => {
+      console.error(`Background connection error: ${err.message}`);
+    });
+
+    this.config.watch((cfg) => this.handleConfigChange(cfg));
+  }
+
+  async startWithHttp(port: number = 3000): Promise<StreamableHTTPServerTransport> {
+    console.error(`MCP Gateway starting (http://localhost:${port})...`);
+    await this.connectAll();
+
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+    });
+    await this.server.connect(transport);
+    this.config.watch((cfg) => this.handleConfigChange(cfg));
+
+    return transport;
+  }
+
+  private handleConfigChange(newConfig: GatewayConfig): void {
+    const oldConfig = this.config.getAll();
+    const oldServers = new Set(Object.keys(oldConfig));
+    const newServers = new Set(Object.keys(newConfig));
+
+    const toRemove = [...oldServers].filter((s) => !newServers.has(s));
+    const toAdd = [...newServers].filter((s) => !oldServers.has(s));
+    const toUpdate = [...newServers].filter((s) => oldServers.has(s));
+
+    const doReload = async () => {
+      for (const key of toRemove) {
+        await this.connections.disconnect(key);
+        console.error(`    ${key} disconnected`);
+      }
+
+      for (const key of toUpdate) {
+        const oldC = oldConfig[key];
+        const newC = newConfig[key];
+        if (oldC && newC && oldC.enabled === false && newC.enabled !== false) {
+          try { await this.connections.connectWithRetry(key, newC); console.error(`    ${key} connected`); } catch (e: any) { console.error(`    ${key} failed: ${e.message}`); }
+        }
+      }
+
+      for (const key of toAdd) {
+        const c = newConfig[key];
+        if (c && c.enabled !== false) {
+          try { await this.connections.connectWithRetry(key, c); console.error(`    ${key} connected`); } catch (e: any) { console.error(`    ${key} failed: ${e.message}`); }
+        }
+      }
+
+      this.searchEngine.warmup();
+      console.error(`Reloaded: ${this.searchEngine.getTools().length} tools from ${this.connections.getConnectedServers().length} servers`);
+    };
+
+    // Debounce reload
+    setTimeout(() => doReload(), 1000);
+  }
+
+  async shutdown(): Promise<void> {
+    console.error("Shutting down gateway...");
+    this.config.stopWatching();
+    await this.jobManager.shutdown();
+    await this.connections.disconnectAll();
+    console.error("Gateway shutdown complete");
+  }
+}

package/src/handlers.ts

@@ -0,0 +1,113 @@
+import packageJson from "../package.json" with { type: "json" };
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import type { SearchFilters } from "./types.js";
+import { SearchEngine } from "./search.js";
+import { JobManager } from "./jobs.js";
+import { ConnectionManager } from "./connections.js";
+
+export function createServer(
+  searchEngine: SearchEngine,
+  connections: ConnectionManager,
+  jobManager: JobManager,
+): McpServer {
+  const server = new McpServer({ name: "mcp-gateway", version: packageJson.version });
+
+  server.registerTool(
+    "gateway.search",
+    {
+      title: "Search Tools",
+      description: "Search for tools across all connected MCP servers with BM25 scoring and fuzzy matching",
+      inputSchema: {
+        query: z.string(),
+        limit: z.number().optional(),
+        filters: z.object({ server: z.string() }).optional(),
+      },
+    },
+    async ({ query, limit, filters }) => {
+      const results = searchEngine.search(query, (filters as SearchFilters) || {}, limit || 10);
+      return {
+        content: [{ type: "text", text: JSON.stringify({ query, found: results.length, results }, null, 2) }],
+      };
+    },
+  );
+
+  server.registerTool(
+    "gateway.describe",
+    {
+      title: "Describe Tool",
+      description: "Get detailed information about a specific tool including full schema",
+      inputSchema: { id: z.string() },
+    },
+    async ({ id }) => {
+      const tool = searchEngine.getTool(id);
+      if (!tool) throw new Error(`TOOL_NOT_FOUND: ${id}`);
+      return { content: [{ type: "text", text: JSON.stringify(tool, null, 2) }] };
+    },
+  );
+
+  server.registerTool(
+    "gateway.invoke",
+    {
+      title: "Invoke Tool",
+      description: "Execute a tool synchronously and return the result",
+      inputSchema: {
+        id: z.string(),
+        args: z.record(z.string(), z.unknown()),
+        timeoutMs: z.number().optional(),
+      },
+    },
+    async ({ id, args, timeoutMs }) => {
+      const parts = id.split("::");
+      const serverKey = parts[0];
+      const toolName = parts[1];
+      if (!serverKey || !toolName) throw new Error(`Invalid tool ID format: ${id}`);
+
+      const client = connections.getClient(serverKey);
+      if (!client) throw new Error(`SERVER_NOT_FOUND: ${serverKey}`);
+      const tool = searchEngine.getTool(id);
+      if (!tool) throw new Error(`TOOL_NOT_FOUND: ${id}`);
+
+      const result = await Promise.race([
+        client.callTool({ name: toolName, arguments: args }),
+        new Promise((_, reject) => setTimeout(() => reject(new Error("TIMEOUT")), timeoutMs || 30000)),
+      ]);
+
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    },
+  );
+
+  server.registerTool(
+    "gateway.invoke_async",
+    {
+      title: "Invoke Tool Async",
+      description: "Start an asynchronous tool execution and return a job ID for polling",
+      inputSchema: {
+        id: z.string(),
+        args: z.record(z.string(), z.unknown()),
+        priority: z.number().optional(),
+      },
+    },
+    async ({ id, args, priority }) => {
+      const job = jobManager.createJob(id, args, priority || 0);
+      jobManager.processQueue();
+      return { content: [{ type: "text", text: JSON.stringify({ jobId: job.id, status: "queued" }, null, 2) }] };
+    },
+  );
+
+  server.registerTool(
+    "gateway.invoke_status",
+    {
+      title: "Check Job Status",
+      description: "Check the status of an async job",
+      inputSchema: { jobId: z.string() },
+    },
+    async ({ jobId }) => {
+      const job = jobManager.getJob(jobId);
+      if (!job) throw new Error(`JOB_NOT_FOUND: ${jobId}`);
+      return { content: [{ type: "text", text: JSON.stringify(job, null, 2) }] };
+    },
+  );
+
+  return server;
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { MCPGateway } from "./gateway.js";
+
+const gateway = new MCPGateway(process.argv[2]);
+gateway.startWithStdio().catch((err) => { console.error("Fatal error:", err); process.exit(1); });
+
+process.on("SIGINT", () => gateway.shutdown().then(() => process.exit(0)));
+process.on("SIGTERM", () => gateway.shutdown().then(() => process.exit(0)));

package/src/jobs.ts

@@ -0,0 +1,74 @@
+import { LRUCache } from "lru-cache";
+import type { JobRecord } from "./types.js";
+
+const MAX_CONCURRENT_JOBS = 3;
+const SHUTDOWN_TIMEOUT = 30000;
+const JOB_TTL = 1000 * 60 * 60 * 24;
+
+export class JobManager {
+  private jobs = new LRUCache<string, JobRecord>({ max: 500, ttl: JOB_TTL });
+  private jobQueue: string[] = [];
+  private runningJobs = 0;
+  private executeJobFn: ((job: JobRecord) => Promise<void>) | null = null;
+
+  constructor() {}
+
+  setExecuteJob(fn: (job: JobRecord) => Promise<void>) {
+    this.executeJobFn = fn;
+  }
+
+  createJob(toolId: string, args: any, priority = 0): JobRecord {
+    const jobId = `job_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+    const job: JobRecord = {
+      id: jobId,
+      status: "queued",
+      toolId,
+      args,
+      priority,
+      createdAt: Date.now(),
+      logs: [`Job created: ${toolId}`],
+    };
+    this.jobs.set(jobId, job);
+    this.jobQueue.push(jobId);
+    this.jobQueue.sort((a, b) => (this.jobs.get(b)?.priority || 0) - (this.jobs.get(a)?.priority || 0));
+    return job;
+  }
+
+  getJob(jobId: string): JobRecord | undefined {
+    return this.jobs.get(jobId);
+  }
+
+  processQueue() {
+    while (this.runningJobs < MAX_CONCURRENT_JOBS && this.jobQueue.length > 0) {
+      const jobId = this.jobQueue.shift()!;
+      const job = this.jobs.get(jobId);
+      if (!job || !this.executeJobFn) continue;
+
+      this.runningJobs++;
+      this.executeJobFn(job).finally(() => {
+        this.runningJobs--;
+        this.processQueue();
+      });
+    }
+  }
+
+  getRunningCount(): number {
+    return this.runningJobs;
+  }
+
+  async shutdown(): Promise<void> {
+    this.jobQueue = [];
+    const startTime = Date.now();
+    while (this.runningJobs > 0 && Date.now() - startTime < SHUTDOWN_TIMEOUT) {
+      await new Promise((r) => setTimeout(r, 500));
+    }
+  }
+
+  getStats(): { queued: number; running: number; total: number } {
+    return {
+      queued: this.jobQueue.length,
+      running: this.runningJobs,
+      total: this.jobs.size,
+    };
+  }
+}