@eznix/mcp-gateway 1.3.6 → 1.4.0

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

@@ -24784,6 +24784,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 +24817,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) {
@@ -24882,7 +24901,7 @@ class ConnectionManager {
 // package.json
 var package_default = {
   name: "@eznix/mcp-gateway",
-  version: "1.3.6",
+  version: "1.4.0",
   description: "MCP Gateway - Aggregate multiple MCP servers into a single gateway",
   type: "module",
   bin: {
@@ -24895,7 +24914,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"
   },

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.4.0",
   "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/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);
   }
 

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);
+});