@eznix/mcp-gateway 1.3.6 → 1.5.2

package/README.md

@@ -124,8 +124,29 @@ Each entry specifies:
 - `command` (local only): Array with command and arguments to spawn the upstream server
 - `url` (remote only): Full URL of the remote MCP server
 - `transport` (optional, remote only): Override transport detection (`"streamable_http"` or `"websocket"`). Usually auto-detected from URL protocol.
+- `environment` (local only): Environment variables to pass to the spawned process, with `{env:VAR_NAME}` substitution support
 - `enabled`: Set to false to skip connecting to this server
 
+#### Environment Variables with Substitution
+
+Local MCP servers support environment variable substitution using `{env:VAR_NAME}` syntax:
+
+```json
+{
+  "jupyter-lab": {
+    "type": "local",
+    "command": ["uvx", "jupyter-mcp-server@latest"],
+    "environment": {
+      "JUPYTER_URL": "http://localhost:{env:JUPYTER_PORT}/",
+      "JUPYTER_TOKEN": "{env:JUPYTER_TOKEN}",
+      "DEBUG": "true"
+    }
+  }
+}
+```
+
+The `{env:VAR_NAME}` placeholders are resolved from the current process environment. If an environment variable is not set, it's replaced with an empty string.
+
 ### Docker
 
 Run MCP Gateway in Docker with HTTP transport:

package/dist/index.js

@@ -5,25 +5,43 @@ var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: () => mod[key],
+        get: __accessProp.bind(mod, key),
         enumerable: true
       });
+  if (canCache)
+    cache.set(mod, to);
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
@@ -6278,7 +6296,7 @@ var require_formats = __commonJS((exports) => {
   }
   var TIME = /^(\d\d):(\d\d):(\d\d(?:\.\d+)?)(z|([+-])(\d\d)(?::?(\d\d))?)?$/i;
   function getTime(strictTimeZone) {
-    return function time(str) {
+    return function time3(str) {
       const matches = TIME.exec(str);
       if (!matches)
         return false;
@@ -14190,8 +14208,9 @@ class Config {
     this.watcher = watch(this.configPath, (event) => {
       if (event !== "change")
         return;
+      const oldConfig = this.getAll();
       this.reload();
-      callback(this.config);
+      callback(oldConfig, this.config);
     });
     console.error(`  Watching config: ${this.configPath}`);
   }
@@ -24784,6 +24803,20 @@ class WebSocketClientTransport {
 }
 
 // src/connections.ts
+function parseEnvironmentVariables(env) {
+  if (!env)
+    return;
+  const parsed = {};
+  const processEnv = process.env;
+  for (const [key, value] of Object.entries(env)) {
+    const substitutedValue = value.replace(/\{env:(\w+)\}/g, (_, envVarName) => {
+      return processEnv[envVarName] || "";
+    });
+    parsed[key] = substitutedValue;
+  }
+  return parsed;
+}
+
 class ConnectionManager {
   searchEngine;
   jobManager;
@@ -24803,7 +24836,12 @@ class ConnectionManager {
     const [cmd, ...args] = config2.command || [];
     if (!cmd)
       throw new Error(`Missing command for ${serverKey}`);
-    const transport = new StdioClientTransport({ command: cmd, args });
+    const env = parseEnvironmentVariables(config2.environment);
+    const transport = new StdioClientTransport({
+      command: cmd,
+      args,
+      env
+    });
     await this.connectTransport(serverKey, config2, transport);
   }
   async connectRemote(serverKey, config2) {
@@ -24866,6 +24904,10 @@ class ConnectionManager {
   async disconnect(serverKey) {
     const client = this.upstreams.get(serverKey);
     if (client) {
+      const tools = this.searchEngine.getTools().filter((t) => t.server === serverKey);
+      for (const tool of tools) {
+        this.searchEngine.removeTool(tool.id);
+      }
       await client.close();
       this.upstreams.delete(serverKey);
     }
@@ -24882,7 +24924,7 @@ class ConnectionManager {
 // package.json
 var package_default = {
   name: "@eznix/mcp-gateway",
-  version: "1.3.6",
+  version: "1.5.2",
   description: "MCP Gateway - Aggregate multiple MCP servers into a single gateway",
   type: "module",
   bin: {
@@ -24895,7 +24937,7 @@ var package_default = {
     "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",
-    preversion: 'bun run build && git add dist && git commit -m "chore: update build"',
+    preversion: 'bun run build && git add dist && git diff --cached --quiet || git commit -m "chore: update build"',
     prepublishOnly: "bun run build",
     postversion: "git push && git push --tag"
   },
@@ -26187,7 +26229,7 @@ class MCPGateway {
     this.connectAll().catch((err) => {
       console.error(`Background connection error: ${err.message}`);
     });
-    this.config.watch((cfg) => this.handleConfigChange(cfg));
+    this.config.watch((oldCfg, newCfg) => this.handleConfigChange(oldCfg, newCfg));
   }
   async startWithHttp(port = 3000) {
     console.error(`MCP Gateway starting (http://localhost:${port})...`);
@@ -26196,11 +26238,10 @@ class MCPGateway {
       sessionIdGenerator: undefined
     });
     await this.server.connect(transport);
-    this.config.watch((cfg) => this.handleConfigChange(cfg));
+    this.config.watch((oldCfg, newCfg) => this.handleConfigChange(oldCfg, newCfg));
     return transport;
   }
-  handleConfigChange(newConfig) {
-    const oldConfig = this.config.getAll();
+  handleConfigChange(oldConfig, newConfig) {
     const oldServers = new Set(Object.keys(oldConfig));
     const newServers = new Set(Object.keys(newConfig));
     const toRemove = [...oldServers].filter((s) => !newServers.has(s));
@@ -26214,13 +26255,30 @@ class MCPGateway {
       for (const key of toUpdate) {
         const oldC = oldConfig[key];
         const newC = newConfig[key];
-        if (oldC && newC && oldC.enabled === false && newC.enabled !== false) {
+        if (oldC && oldC.enabled !== false && newC && newC.enabled === false) {
+          await this.connections.disconnect(key);
+          console.error(`    ${key} disabled`);
+          continue;
+        }
+        if (oldC && oldC.enabled === false && newC && newC.enabled !== false) {
           try {
             await this.connections.connectWithRetry(key, newC);
-            console.error(`    ${key} connected`);
+            console.error(`    ${key} enabled`);
           } catch (e) {
             console.error(`    ${key} failed: ${e.message}`);
           }
+          continue;
+        }
+        if (oldC && newC && oldC.enabled !== false && newC.enabled !== false) {
+          if (JSON.stringify(oldC) !== JSON.stringify(newC)) {
+            await this.connections.disconnect(key);
+            try {
+              await this.connections.connectWithRetry(key, newC);
+              console.error(`    ${key} reconnected (config changed)`);
+            } catch (e) {
+              console.error(`    ${key} failed: ${e.message}`);
+            }
+          }
         }
       }
       for (const key of toAdd) {

package/examples/config.json

@@ -6,5 +6,24 @@
   "playwright": {
     "type": "local",
     "command": ["bunx", "@playwright/mcp@latest"]
+  },
+  "JupyterLab": {
+    "type": "local",
+    "command": ["uvx", "jupyter-mcp-server@latest"],
+    "environment": {
+      "JUPYTER_URL": "http://localhost:{env:JUPYTER_PORT}/",
+      "JUPYTER_TOKEN": "{env:JUPYTER_TOKEN}",
+      "ALLOW_IMG_OUTPUT": "true"
+    },
+    "enabled": true
+  },
+  "custom-server": {
+    "type": "local",
+    "command": ["python", "scripts/server.py"],
+    "environment": {
+      "API_KEY": "{env:API_KEY}",
+      "DEBUG": "true",
+      "DATABASE_URL": "postgresql://{env:DB_USER}:{env:DB_PASS}@localhost:5432/mydb"
+    }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eznix/mcp-gateway",
-  "version": "1.3.6",
+  "version": "1.5.2",
   "description": "MCP Gateway - Aggregate multiple MCP servers into a single gateway",
   "type": "module",
   "bin": {
@@ -13,7 +13,7 @@
     "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",
-    "preversion": "bun run build && git add dist && git commit -m \"chore: update build\"",
+    "preversion": "bun run build && git add dist && git diff --cached --quiet || git commit -m \"chore: update build\"",
     "prepublishOnly": "bun run build",
     "postversion": "git push && git push --tag"
   },

package/src/config.ts

@@ -37,12 +37,13 @@ export class Config {
     return this.config;
   }
 
-  watch(callback: (config: GatewayConfig) => void): void {
+  watch(callback: (oldConfig: GatewayConfig, newConfig: GatewayConfig) => void): void {
     if (this.watcher) return;
     this.watcher = watch(this.configPath, (event: string) => {
       if (event !== "change") return;
+      const oldConfig = this.getAll();  // snapshot before reload
       this.reload();
-      callback(this.config);
+      callback(oldConfig, this.config);
     });
     console.error(`  Watching config: ${this.configPath}`);
   }

package/src/connections.ts

@@ -6,6 +6,28 @@ import type { UpstreamConfig, ToolCatalogEntry } from "./types.js";
 import { SearchEngine } from "./search.js";
 import { JobManager } from "./jobs.js";
 
+/**
+ * Parse environment variables with {env:VAR_NAME} substitution.
+ * Replaces {env:VAR} with the corresponding value from process.env.
+ * If the environment variable is not set, the placeholder is replaced with an empty string.
+ */
+export function parseEnvironmentVariables(env?: Record<string, string>): Record<string, string> | undefined {
+  if (!env) return undefined;
+
+  const parsed: Record<string, string> = {};
+  const processEnv = process.env as Record<string, string>;
+
+  for (const [key, value] of Object.entries(env)) {
+    // Replace all {env:VAR_NAME} patterns with actual environment variable values
+    const substitutedValue = value.replace(/\{env:(\w+)\}/g, (_, envVarName: string) => {
+      return processEnv[envVarName] || "";
+    });
+    parsed[key] = substitutedValue;
+  }
+
+  return parsed;
+}
+
 export class ConnectionManager {
   private upstreams = new Map<string, Client>();
 
@@ -26,7 +48,14 @@ export class ConnectionManager {
     const [cmd, ...args] = config.command || [];
     if (!cmd) throw new Error(`Missing command for ${serverKey}`);
 
-    const transport = new StdioClientTransport({ command: cmd, args });
+    // Parse environment variables with {env:VAR_NAME} substitution
+    const env = parseEnvironmentVariables(config.environment);
+
+    const transport = new StdioClientTransport({
+      command: cmd,
+      args,
+      env
+    });
     await this.connectTransport(serverKey, config, transport);
   }
 
@@ -99,6 +128,12 @@ export class ConnectionManager {
   async disconnect(serverKey: string): Promise<void> {
     const client = this.upstreams.get(serverKey);
     if (client) {
+      // Remove all tools for this server from the search index
+      const tools = this.searchEngine.getTools().filter((t) => t.server === serverKey);
+      for (const tool of tools) {
+        this.searchEngine.removeTool(tool.id);
+      }
+      
       await client.close();
       this.upstreams.delete(serverKey);
     }

package/src/gateway.ts

@@ -50,7 +50,7 @@ export class MCPGateway {
       console.error(`Background connection error: ${err.message}`);
     });
 
-    this.config.watch((cfg) => this.handleConfigChange(cfg));
+    this.config.watch((oldCfg, newCfg) => this.handleConfigChange(oldCfg, newCfg));
   }
 
   async startWithHttp(port: number = 3000): Promise<StreamableHTTPServerTransport> {
@@ -61,13 +61,12 @@ export class MCPGateway {
       sessionIdGenerator: undefined,
     });
     await this.server.connect(transport);
-    this.config.watch((cfg) => this.handleConfigChange(cfg));
+    this.config.watch((oldCfg, newCfg) => this.handleConfigChange(oldCfg, newCfg));
 
     return transport;
   }
 
-  private handleConfigChange(newConfig: GatewayConfig): void {
-    const oldConfig = this.config.getAll();
+  private handleConfigChange(oldConfig: GatewayConfig, newConfig: GatewayConfig): void {
     const oldServers = new Set(Object.keys(oldConfig));
     const newServers = new Set(Object.keys(newConfig));
 
@@ -84,8 +83,37 @@ export class MCPGateway {
       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}`); }
+        
+        // Handle disabling a server
+        if (oldC && oldC.enabled !== false && newC && newC.enabled === false) {
+          await this.connections.disconnect(key);
+          console.error(`    ${key} disabled`);
+          continue;
+        }
+        
+        // Handle enabling a previously disabled server
+        if (oldC && oldC.enabled === false && newC && newC.enabled !== false) {
+          try { 
+            await this.connections.connectWithRetry(key, newC); 
+            console.error(`    ${key} enabled`); 
+          } catch (e: any) { 
+            console.error(`    ${key} failed: ${e.message}`); 
+          }
+          continue;
+        }
+        
+        // Handle config changes for enabled servers (reconnect)
+        if (oldC && newC && oldC.enabled !== false && newC.enabled !== false) {
+          // Deep compare to detect any config changes
+          if (JSON.stringify(oldC) !== JSON.stringify(newC)) {
+            await this.connections.disconnect(key);
+            try {
+              await this.connections.connectWithRetry(key, newC);
+              console.error(`    ${key} reconnected (config changed)`);
+            } catch (e: any) {
+              console.error(`    ${key} failed: ${e.message}`);
+            }
+          }
         }
       }
 

package/src/types.ts

@@ -4,9 +4,10 @@ export interface UpstreamConfig {
   url?: string;
   transport?: "streamable_http" | "websocket";
   endpoint?: string;
+  environment?: Record<string, string>; // Environment variables with support for {env:VAR_NAME} substitution
   enabled?: boolean;
-  lazy?: boolean;  // if true, only connect on first request
-  idleTimeout?: number;  // milliseconds before sleeping (default: 2hrs)
+  lazy?: boolean; // if true, only connect on first request
+  idleTimeout?: number; // milliseconds before sleeping (default: 2hrs)
 }
 
 export interface GatewayConfig {

package/tests/parseEnvironmentVariables.test.ts

@@ -0,0 +1,192 @@
+import { test, expect, beforeAll, afterAll } from "bun:test";
+import { parseEnvironmentVariables } from "../src/connections.js";
+
+// Store original environment variables
+const originalEnv: Record<string, string | undefined> = {};
+
+beforeAll(() => {
+  // Save original environment variables
+  for (const key of ["TEST_VAR_1", "TEST_VAR_2", "MISSING_VAR", "JUPYTER_TOKEN", "JUPYTER_PORT"]) {
+    originalEnv[key] = process.env[key];
+  }
+  
+  // Set test environment variables
+  process.env.TEST_VAR_1 = "test-value-1";
+  process.env.TEST_VAR_2 = "test-value-2";
+  process.env.JUPYTER_TOKEN = "my-secret-token";
+  process.env.JUPYTER_PORT = "8888";
+  
+  // Ensure MISSING_VAR is not set
+  delete process.env.MISSING_VAR;
+});
+
+afterAll(() => {
+  // Restore original environment variables
+  for (const key of ["TEST_VAR_1", "TEST_VAR_2", "MISSING_VAR", "JUPYTER_TOKEN", "JUPYTER_PORT"]) {
+    if (originalEnv[key] !== undefined) {
+      process.env[key] = originalEnv[key];
+    } else {
+      delete process.env[key];
+    }
+  }
+});
+
+test("parseEnvironmentVariables returns undefined when env is undefined", () => {
+  const result = parseEnvironmentVariables(undefined);
+  expect(result).toBeUndefined();
+});
+
+test("parseEnvironmentVariables returns undefined when env is empty object", () => {
+  const result = parseEnvironmentVariables({});
+  expect(result).toEqual({});
+});
+
+test("parseEnvironmentVariables preserves values without substitution", () => {
+  const input = {
+    STATIC_VALUE: "hello world",
+    NUMBER_VALUE: "12345",
+    URL_VALUE: "https://example.com/api"
+  };
+  
+  const result = parseEnvironmentVariables(input);
+  expect(result).toEqual(input);
+});
+
+test("parseEnvironmentVariables substitutes existing environment variables", () => {
+  const input = {
+    STATIC: "static",
+    SUBSTITUTED: "{env:TEST_VAR_1}",
+    ANOTHER_SUB: "{env:TEST_VAR_2}"
+  };
+  
+  const expected = {
+    STATIC: "static",
+    SUBSTITUTED: "test-value-1",
+    ANOTHER_SUB: "test-value-2"
+  };
+  
+  const result = parseEnvironmentVariables(input);
+  expect(result).toEqual(expected);
+});
+
+test("parseEnvironmentVariables substitutes multiple variables in same value", () => {
+  const input = {
+    COMBINED: "prefix-{env:TEST_VAR_1}-middle-{env:TEST_VAR_2}-suffix"
+  };
+  
+  const expected = {
+    COMBINED: "prefix-test-value-1-middle-test-value-2-suffix"
+  };
+  
+  const result = parseEnvironmentVariables(input);
+  expect(result).toEqual(expected);
+});
+
+test("parseEnvironmentVariables replaces missing variables with empty string", () => {
+  const input = {
+    PRESENT: "{env:TEST_VAR_1}",
+    MISSING: "{env:MISSING_VAR}",
+    AFTER_MISSING: "value-after-{env:MISSING_VAR}"
+  };
+  
+  const expected = {
+    PRESENT: "test-value-1",
+    MISSING: "",
+    AFTER_MISSING: "value-after-"
+  };
+  
+  const result = parseEnvironmentVariables(input);
+  expect(result).toEqual(expected);
+});
+
+test("parseEnvironmentVariables works with JupyterLab example from README", () => {
+  const input = {
+    JUPYTER_URL: "http://localhost:{env:JUPYTER_PORT}/",
+    JUPYTER_TOKEN: "{env:JUPYTER_TOKEN}",
+    ALLOW_IMG_OUTPUT: "true"
+  };
+  
+  const expected = {
+    JUPYTER_URL: "http://localhost:8888/",
+    JUPYTER_TOKEN: "my-secret-token",
+    ALLOW_IMG_OUTPUT: "true"
+  };
+  
+  const result = parseEnvironmentVariables(input);
+  expect(result).toEqual(expected);
+});
+
+test("parseEnvironmentVariables handles database URL with multiple substitutions", () => {
+  const input = {
+    DATABASE_URL: "postgresql://{env:DB_USER}:{env:DB_PASS}@localhost:5432/mydb"
+  };
+  
+  // Set up the environment variables for this test
+  const originalDbUser = process.env.DB_USER;
+  const originalDbPass = process.env.DB_PASS;
+  
+  try {
+    process.env.DB_USER = "admin";
+    process.env.DB_PASS = "secret123";
+    
+    const expected = {
+      DATABASE_URL: "postgresql://admin:secret123@localhost:5432/mydb"
+    };
+    
+    const result = parseEnvironmentVariables(input);
+    expect(result).toEqual(expected);
+  } finally {
+    // Restore
+    if (originalDbUser !== undefined) {
+      process.env.DB_USER = originalDbUser;
+    } else {
+      delete process.env.DB_USER;
+    }
+    
+    if (originalDbPass !== undefined) {
+      process.env.DB_PASS = originalDbPass;
+    } else {
+      delete process.env.DB_PASS;
+    }
+  }
+});
+
+test("parseEnvironmentVariables handles empty values", () => {
+  const input = {
+    EMPTY_STRING: "",
+    SPACES: "   "
+  };
+  
+  const result = parseEnvironmentVariables(input);
+  expect(result).toEqual(input);
+});
+
+test("parseEnvironmentVariables is case-sensitive for variable names", () => {
+  const input = {
+    LOWERCASE: "{env:test_var_1}",  // Note: different case than TEST_VAR_1
+  };
+  
+  const expected = {
+    LOWERCASE: ""  // Should be empty because test_var_1 is not set
+  };
+  
+  const result = parseEnvironmentVariables(input);
+  expect(result).toEqual(expected);
+});
+
+test("parseEnvironmentVariables handles complex patterns", () => {
+  const input = {
+    NESTED: "prefix-{env:TEST_VAR_1}-middle-{env:TEST_VAR_2}-suffix-{env:JUPYTER_TOKEN}",
+    WITH_NUMBERS: "server-{env:JUPYTER_PORT}.example.com",
+    MIXED: "{env:TEST_VAR_1}-{env:MISSING}-{env:TEST_VAR_2}"
+  };
+  
+  const expected = {
+    NESTED: "prefix-test-value-1-middle-test-value-2-suffix-my-secret-token",
+    WITH_NUMBERS: "server-8888.example.com",
+    MIXED: "test-value-1--test-value-2"
+  };
+  
+  const result = parseEnvironmentVariables(input);
+  expect(result).toEqual(expected);
+});