dynmcp 0.1.1 → 0.2.0

package/README.md

@@ -102,6 +102,64 @@ When no `--` command is provided, `dynmcp` looks for a config file in this order
 
 MCP names (the keys in the config) must match `^[a-z0-9][a-z0-9-]*$`.
 
+## Environment Variable Interpolation
+
+Config files can reference environment variables in any string-typed leaf value using shell-style syntax. This is useful for keeping secrets (bearer tokens, API keys) and host-specific values (paths, ports) out of the config file itself.
+
+```json
+{
+  "mcp": {
+    "remote": {
+      "transport": "streamable-http",
+      "url": "${MCP_URL:-https://example.com/mcp}",
+      "headers": {
+        "Authorization": "Bearer ${MCP_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+### Syntax
+
+| Form | Behavior |
+|---|---|
+| `${VAR}` | Replaced with the value of `VAR`. Hard error at startup if `VAR` is undefined. |
+| `${VAR:-default}` | Replaced with `VAR` if set and non-empty, otherwise the literal `default` (may contain spaces, colons, etc.). |
+| `$${...}` | Escape — emits a literal `${...}` with no interpolation. |
+
+Interpolation only applies to **leaf string values** inside the `mcp` map (and nested objects/arrays within it). Map keys, the top-level `$schema` field, and the top-level `env` field are never interpolated. Partial-string interpolation works — `"Bearer ${TOKEN}"` is valid.
+
+If any referenced variables are missing without a default, `dynmcp` exits at startup with an error listing **all** of them at once (not one at a time).
+
+### Sources (`env` field)
+
+A top-level `env` field controls where variables are read from:
+
+| Value | Behavior |
+|---|---|
+| `"enable"` (default) | Loads `.env` file (if present) and merges with `process.env`. `.env` values take precedence over `process.env` for the same key. |
+| `"dotenv"` | Loads from `.env` file only. `process.env` is ignored. |
+| `"process"` | Reads from `process.env` only. No `.env` file is loaded. |
+| `"disable"` | Disables interpolation entirely — `${VAR}` is left literal. |
+
+```json
+{
+  "env": "process",
+  "mcp": { /* ... */ }
+}
+```
+
+### `.env` File Discovery
+
+By default, `dynmcp` looks for a file literally named `.env` in the current working directory. To use a different path, pass `--env` / `-e`:
+
+```bash
+dynmcp --env ./secrets.env
+```
+
+Combining `--env` with `env: "disable"` or `env: "process"` is rejected as incoherent (no `.env` would be loaded). If `--env` points to a file that does not exist, `dynmcp` exits with an error.
+
 ## CLI Reference
 
 ```
@@ -113,6 +171,7 @@ dynmcp [options] [-- <upstream-command> [upstream-args...]]
 | `--version` | `-v` | Print the package version and exit |
 | `--help` | `-h` | Print usage information and exit |
 | `--config <path>` | `-c` | Path to config file (JSON or YAML) |
+| `--env <path>` | `-e` | Path to a custom `.env` file for variable interpolation |
 | `--` | | Everything after is the upstream MCP command (single-MCP mode) |
 
 ### Mode Resolution

package/dist/index.cjs

@@ -23,13 +23,13 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/cli.ts
-var import_node_process4 = __toESM(require("process"), 1);
+var import_node_process6 = __toESM(require("process"), 1);
 var import_commander = require("commander");
 
 // package.json
 var package_default = {
   name: "dynmcp",
-  version: "0.1.1",
+  version: "0.2.0",
   description: "Dynamic MCP context management tool for AI MCP-enabled agents and clients.",
   author: "Brandon Burrus <brandon@burrus.io>",
   license: "MIT",
@@ -96,6 +96,7 @@ var package_default = {
     boxen: "^8.0.1",
     chalk: "^5.6.2",
     commander: "^14.0.3",
+    dotenv: "^17.4.2",
     enquirer: "^2.4.1",
     fastmcp: "^4.0.1",
     figlet: "^1.11.0",
@@ -121,13 +122,16 @@ var import_figlet = __toESM(require("figlet"), 1);
 var import_chalk = __toESM(require("chalk"), 1);
 
 // src/proxy/index.ts
-var import_node_process3 = __toESM(require("process"), 1);
+var import_node_process5 = __toESM(require("process"), 1);
 var import_stdio2 = require("@modelcontextprotocol/sdk/client/stdio.js");
 
 // src/config/schema.ts
 var import_zod = require("zod");
 var MCP_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 var mcpName = import_zod.z.string().regex(MCP_NAME_PATTERN);
+var envModeSchema = import_zod.z.enum(["enable", "dotenv", "process", "disable"]).describe(
+  'Controls environment variable interpolation in config values. "enable" (default) merges .env and process.env (.env wins). "dotenv" loads .env only. "process" uses process.env only. "disable" turns interpolation off.'
+);
 var stdioTransport = import_zod.z.object({
   transport: import_zod.z.literal("stdio"),
   command: import_zod.z.string(),
@@ -153,51 +157,227 @@ var transportConfig = import_zod.z.discriminatedUnion("transport", [
   sseTransport
 ]);
 var mcpConfigSchema = import_zod.z.object({
+  env: envModeSchema.optional(),
   mcp: import_zod.z.record(mcpName, transportConfig).refine((obj) => Object.keys(obj).length > 0, { message: "At least one MCP must be configured" })
 });
 
 // src/config/loader.ts
-var import_node_fs = require("fs");
 var import_node_fs2 = require("fs");
-var import_node_path = require("path");
+var import_node_path2 = require("path");
+var import_node_process2 = __toESM(require("process"), 1);
 var import_yaml = require("yaml");
+
+// src/config/env-sources.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_node_process = __toESM(require("process"), 1);
+var import_dotenv = __toESM(require("dotenv"), 1);
+var DEFAULT_DOTENV_FILENAME = ".env";
+function loadEnv(options) {
+  const { mode, envFilePath, cwd = import_node_process.default.cwd(), processEnv = import_node_process.default.env } = options;
+  if (envFilePath !== void 0 && (mode === "disable" || mode === "process")) {
+    throw new Error(
+      `--env flag is incompatible with env mode "${mode}". --env requires env mode "enable" or "dotenv".`
+    );
+  }
+  if (mode === "disable") {
+    return { variables: {}, interpolationEnabled: false };
+  }
+  const dotenvVars = mode === "process" ? {} : readDotenvFile(envFilePath, cwd);
+  const processVars = mode === "dotenv" ? {} : filterDefined(processEnv);
+  const variables = { ...processVars, ...dotenvVars };
+  return { variables, interpolationEnabled: true };
+}
+function readDotenvFile(envFilePath, cwd) {
+  const isExplicit = envFilePath !== void 0;
+  const resolvedPath = isExplicit ? (0, import_node_path.resolve)(envFilePath) : (0, import_node_path.resolve)(cwd, DEFAULT_DOTENV_FILENAME);
+  if (!(0, import_node_fs.existsSync)(resolvedPath)) {
+    if (isExplicit) {
+      throw new Error(`.env file not found: ${resolvedPath}`);
+    }
+    return {};
+  }
+  let raw;
+  try {
+    raw = (0, import_node_fs.readFileSync)(resolvedPath, "utf-8");
+  } catch (readError) {
+    const message = readError instanceof Error ? readError.message : String(readError);
+    throw new Error(`Failed to read .env file (${resolvedPath}): ${message}`);
+  }
+  try {
+    return import_dotenv.default.parse(raw);
+  } catch (parseError) {
+    const message = parseError instanceof Error ? parseError.message : String(parseError);
+    throw new Error(`Failed to parse .env file (${resolvedPath}): ${message}`);
+  }
+}
+function filterDefined(env) {
+  const result = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (value !== void 0) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+// src/config/interpolate.ts
+var TOP_LEVEL_PASSTHROUGH_KEYS = /* @__PURE__ */ new Set(["$schema", "env"]);
+var MissingEnvVarsError = class extends Error {
+  constructor(missingVars) {
+    const list = missingVars.join(", ");
+    const plural = missingVars.length === 1 ? "" : "s";
+    super(`Missing required environment variable${plural}: ${list}`);
+    this.missingVars = missingVars;
+    this.name = "MissingEnvVarsError";
+  }
+  missingVars;
+};
+function interpolateConfig(config, env) {
+  if (config === null || typeof config !== "object" || Array.isArray(config)) {
+    return config;
+  }
+  const missing = [];
+  const result = {};
+  for (const [key, value] of Object.entries(config)) {
+    if (TOP_LEVEL_PASSTHROUGH_KEYS.has(key)) {
+      result[key] = value;
+    } else {
+      result[key] = walkNode(value, env, missing);
+    }
+  }
+  if (missing.length > 0) {
+    const unique = Array.from(new Set(missing)).sort();
+    throw new MissingEnvVarsError(unique);
+  }
+  return result;
+}
+function walkNode(node, env, missing) {
+  if (typeof node === "string") {
+    return interpolateString(node, env, missing);
+  }
+  if (Array.isArray(node)) {
+    return node.map((item) => walkNode(item, env, missing));
+  }
+  if (node !== null && typeof node === "object") {
+    const result = {};
+    for (const [key, value] of Object.entries(node)) {
+      result[key] = walkNode(value, env, missing);
+    }
+    return result;
+  }
+  return node;
+}
+function interpolateString(value, env, missing) {
+  let result = "";
+  let i = 0;
+  const len = value.length;
+  while (i < len) {
+    const ch = value[i];
+    if (ch === "$" && value[i + 1] === "$" && value[i + 2] === "{") {
+      const close = value.indexOf("}", i + 3);
+      if (close === -1) {
+        result += ch;
+        i += 1;
+        continue;
+      }
+      result += value.substring(i + 1, close + 1);
+      i = close + 1;
+      continue;
+    }
+    if (ch === "$" && value[i + 1] === "{") {
+      const close = value.indexOf("}", i + 2);
+      if (close === -1) {
+        result += value.substring(i);
+        break;
+      }
+      const expr = value.substring(i + 2, close);
+      const { name, defaultValue } = parseExpr(expr);
+      const resolved = env[name];
+      const hasValue = resolved !== void 0 && resolved !== "";
+      if (hasValue) {
+        result += resolved;
+      } else if (defaultValue !== void 0) {
+        result += defaultValue;
+      } else if (resolved !== void 0) {
+        result += "";
+      } else {
+        missing.push(name);
+      }
+      i = close + 1;
+      continue;
+    }
+    result += ch;
+    i += 1;
+  }
+  return result;
+}
+function parseExpr(expr) {
+  const sep = expr.indexOf(":-");
+  if (sep === -1) {
+    return { name: expr, defaultValue: void 0 };
+  }
+  return {
+    name: expr.substring(0, sep),
+    defaultValue: expr.substring(sep + 2)
+  };
+}
+
+// src/config/loader.ts
 var AUTO_DISCOVER_NAMES = ["mcp.json", ".mcp.json"];
+var DEFAULT_ENV_MODE = "enable";
+var VALID_ENV_MODES = ["enable", "dotenv", "process", "disable"];
 function resolveConfigPath(explicitPath) {
   if (explicitPath) {
-    const resolved = (0, import_node_path.resolve)(explicitPath);
+    const resolved = (0, import_node_path2.resolve)(explicitPath);
     if (!(0, import_node_fs2.existsSync)(resolved)) {
       throw new Error(`Config file not found: ${resolved}`);
     }
     return resolved;
   }
-  const cwd = process.cwd();
+  const cwd = import_node_process2.default.cwd();
   for (const name of AUTO_DISCOVER_NAMES) {
-    const candidate = (0, import_node_path.resolve)(cwd, name);
+    const candidate = (0, import_node_path2.resolve)(cwd, name);
     if ((0, import_node_fs2.existsSync)(candidate)) {
       return candidate;
     }
   }
-  const searched = AUTO_DISCOVER_NAMES.map((n) => (0, import_node_path.resolve)(cwd, n)).join(", ");
+  const searched = AUTO_DISCOVER_NAMES.map((n) => (0, import_node_path2.resolve)(cwd, n)).join(", ");
   throw new Error(`No config file found. Searched: ${searched}`);
 }
-function loadConfig(explicitPath) {
-  const configPath = resolveConfigPath(explicitPath);
-  const raw = (0, import_node_fs.readFileSync)(configPath, "utf-8");
+function loadConfig(options = {}) {
+  const { configPath, envFilePath } = options;
+  const resolvedPath = resolveConfigPath(configPath);
+  const raw = (0, import_node_fs2.readFileSync)(resolvedPath, "utf-8");
   let content;
   try {
-    content = isYamlFile(configPath) ? (0, import_yaml.parse)(raw) : JSON.parse(raw);
+    content = isYamlFile(resolvedPath) ? (0, import_yaml.parse)(raw) : JSON.parse(raw);
   } catch (parseError) {
     const message = parseError instanceof Error ? parseError.message : String(parseError);
-    throw new Error(`Failed to parse config file (${configPath}): ${message}`);
+    throw new Error(`Failed to parse config file (${resolvedPath}): ${message}`);
   }
-  const result = mcpConfigSchema.safeParse(content);
+  const envMode = readEnvMode(content);
+  const loadedEnv = loadEnv({ mode: envMode, envFilePath });
+  const interpolated = loadedEnv.interpolationEnabled ? interpolateConfig(content, loadedEnv.variables) : content;
+  const result = mcpConfigSchema.safeParse(interpolated);
   if (!result.success) {
     const formatted = result.error.issues.map((issue) => `  - ${issue.path.join(".")}: ${issue.message}`).join("\n");
-    throw new Error(`Invalid config file (${configPath}):
+    throw new Error(`Invalid config file (${resolvedPath}):
 ${formatted}`);
   }
   return result.data;
 }
+function readEnvMode(content) {
+  if (content === null || typeof content !== "object" || Array.isArray(content)) {
+    return DEFAULT_ENV_MODE;
+  }
+  const value = content.env;
+  if (value === void 0) return DEFAULT_ENV_MODE;
+  if (typeof value === "string" && VALID_ENV_MODES.includes(value)) {
+    return value;
+  }
+  return DEFAULT_ENV_MODE;
+}
 function isYamlFile(filePath) {
   return filePath.endsWith(".yml") || filePath.endsWith(".yaml");
 }
@@ -338,7 +518,7 @@ function buildAnnotationLines(tool) {
 }
 
 // src/proxy/upstream-client.ts
-var import_node_process = __toESM(require("process"), 1);
+var import_node_process3 = __toESM(require("process"), 1);
 var import_client = require("@modelcontextprotocol/sdk/client/index.js");
 var UpstreamClient = class {
   transport;
@@ -347,7 +527,7 @@ var UpstreamClient = class {
   constructor({ name, transport, onTransportError }) {
     this.transport = transport;
     this.onTransportError = onTransportError ?? ((error) => {
-      import_node_process.default.stderr.write(`[${name}] Upstream MCP transport error: ${error.message}
+      import_node_process3.default.stderr.write(`[${name}] Upstream MCP transport error: ${error.message}
 `);
     });
   }
@@ -459,7 +639,7 @@ var Orchestrator = class {
 };
 
 // src/proxy/server.ts
-var import_node_process2 = __toESM(require("process"), 1);
+var import_node_process4 = __toESM(require("process"), 1);
 var import_fastmcp = require("fastmcp");
 var import_zod3 = require("zod");
 var ProxyServer = class {
@@ -497,7 +677,7 @@ var ProxyServer = class {
         return result;
       }
     });
-    import_node_process2.default.stderr.write("Starting dynamic-discovery-mcp server over stdio\n");
+    import_node_process4.default.stderr.write("Starting dynamic-discovery-mcp server over stdio\n");
     await server.start({ transportType: "stdio" });
   }
 };
@@ -510,7 +690,7 @@ async function startProxy(command, args) {
     name: command,
     transport,
     onTransportError: (error) => {
-      import_node_process3.default.stderr.write(`Upstream MCP transport error: ${error.message}
+      import_node_process5.default.stderr.write(`Upstream MCP transport error: ${error.message}
 `);
       shutdown(1);
     }
@@ -519,36 +699,36 @@ async function startProxy(command, args) {
     if (isShuttingDown) return;
     isShuttingDown = true;
     upstreamClient.disconnect().catch((error) => {
-      import_node_process3.default.stderr.write(
+      import_node_process5.default.stderr.write(
         `dynmcp: error during disconnect: ${error instanceof Error ? error.message : String(error)}
 `
       );
-    }).finally(() => import_node_process3.default.exit(exitCode));
+    }).finally(() => import_node_process5.default.exit(exitCode));
   };
   try {
     await upstreamClient.connect();
   } catch (error) {
-    import_node_process3.default.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
+    import_node_process5.default.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
 `);
-    import_node_process3.default.exit(1);
+    import_node_process5.default.exit(1);
   }
   let tools;
   try {
     tools = await upstreamClient.listTools();
   } catch (error) {
-    import_node_process3.default.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
+    import_node_process5.default.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
 `);
-    import_node_process3.default.exit(1);
+    import_node_process5.default.exit(1);
   }
   const catalog = ToolCatalog.fromFlat(tools);
   const proxyServer = new ProxyServer({
     catalog,
     callTool: (name, input) => upstreamClient.callTool(name, input)
   });
-  import_node_process3.default.on("SIGINT", () => shutdown(0));
-  import_node_process3.default.on("SIGTERM", () => shutdown(0));
-  import_node_process3.default.stdin.on("end", () => shutdown(0));
-  import_node_process3.default.stdin.on("close", () => shutdown(0));
+  import_node_process5.default.on("SIGINT", () => shutdown(0));
+  import_node_process5.default.on("SIGTERM", () => shutdown(0));
+  import_node_process5.default.stdin.on("end", () => shutdown(0));
+  import_node_process5.default.stdin.on("close", () => shutdown(0));
   try {
     await proxyServer.start();
   } catch (error) {
@@ -556,9 +736,9 @@ async function startProxy(command, args) {
     throw error;
   }
 }
-async function startProxyFromConfig(configPath) {
+async function startProxyFromConfig(options = {}) {
   let isShuttingDown = false;
-  const config = loadConfig(configPath);
+  const config = loadConfig(options);
   const mcps = /* @__PURE__ */ new Map();
   for (const [name, entry] of Object.entries(config.mcp)) {
     mcps.set(name, { transport: createTransport(entry) });
@@ -566,7 +746,7 @@ async function startProxyFromConfig(configPath) {
   const orchestrator = new Orchestrator({
     mcps,
     onTransportError: (mcpName2, error) => {
-      import_node_process3.default.stderr.write(`Upstream MCP "${mcpName2}" transport error: ${error.message}
+      import_node_process5.default.stderr.write(`Upstream MCP "${mcpName2}" transport error: ${error.message}
 `);
       shutdown(1);
     }
@@ -575,27 +755,27 @@ async function startProxyFromConfig(configPath) {
     if (isShuttingDown) return;
     isShuttingDown = true;
     orchestrator.disconnectAll().catch((error) => {
-      import_node_process3.default.stderr.write(
+      import_node_process5.default.stderr.write(
         `dynmcp: error during disconnect: ${error instanceof Error ? error.message : String(error)}
 `
       );
-    }).finally(() => import_node_process3.default.exit(exitCode));
+    }).finally(() => import_node_process5.default.exit(exitCode));
   };
   try {
     await orchestrator.connect();
   } catch (error) {
-    import_node_process3.default.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
+    import_node_process5.default.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
 `);
-    import_node_process3.default.exit(1);
+    import_node_process5.default.exit(1);
   }
   const proxyServer = new ProxyServer({
     catalog: orchestrator.catalog,
     callTool: (name, input) => orchestrator.callTool(name, input)
   });
-  import_node_process3.default.on("SIGINT", () => shutdown(0));
-  import_node_process3.default.on("SIGTERM", () => shutdown(0));
-  import_node_process3.default.stdin.on("end", () => shutdown(0));
-  import_node_process3.default.stdin.on("close", () => shutdown(0));
+  import_node_process5.default.on("SIGINT", () => shutdown(0));
+  import_node_process5.default.on("SIGTERM", () => shutdown(0));
+  import_node_process5.default.stdin.on("end", () => shutdown(0));
+  import_node_process5.default.stdin.on("close", () => shutdown(0));
   try {
     await proxyServer.start();
   } catch (error) {
@@ -615,39 +795,43 @@ var cliBanner = import_chalk.default.bold.magentaBright(
 var cli = new import_commander.Command(package_default.name).description(package_default.description).version(package_default.version).addHelpText("beforeAll", cliBanner).addHelpText(
   "after",
   "\nExamples:\n  dynmcp -- npx -y chrome-devtools-mcp@latest\n  dynmcp --config ./mcp.json\n"
-).option("-c, --config <path>", "Path to config file (JSON or YAML)").allowExcessArguments(true).passThroughOptions(true).action(async (_options, cmd) => {
-  const separatorIndex = import_node_process4.default.argv.indexOf("--");
+).option("-c, --config <path>", "Path to config file (JSON or YAML)").option(
+  "-e, --env <path>",
+  "Path to a .env file for environment variable interpolation"
+).allowExcessArguments(true).passThroughOptions(true).action(async (_options, cmd) => {
+  const separatorIndex = import_node_process6.default.argv.indexOf("--");
   const configPath = cmd.opts().config;
+  const envFilePath = cmd.opts().env;
   if (separatorIndex !== -1) {
-    const [command, ...args] = import_node_process4.default.argv.slice(separatorIndex + 1);
+    const [command, ...args] = import_node_process6.default.argv.slice(separatorIndex + 1);
     if (command === void 0) {
-      import_node_process4.default.stderr.write(
+      import_node_process6.default.stderr.write(
         "dynmcp: no upstream command provided after --.\nUsage: dynmcp -- <command> [args...]\n"
       );
-      import_node_process4.default.exit(1);
+      import_node_process6.default.exit(1);
     }
     try {
       await startProxy(command, args);
     } catch (error) {
-      import_node_process4.default.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
+      import_node_process6.default.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
 `);
-      import_node_process4.default.exit(1);
+      import_node_process6.default.exit(1);
     }
     return;
   }
   try {
-    await startProxyFromConfig(configPath);
+    await startProxyFromConfig({ configPath, envFilePath });
   } catch (error) {
-    import_node_process4.default.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
+    import_node_process6.default.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
 `);
-    import_node_process4.default.exit(1);
+    import_node_process6.default.exit(1);
   }
 });
 
 // src/index.ts
-var import_node_process5 = __toESM(require("process"), 1);
+var import_node_process7 = __toESM(require("process"), 1);
 async function main() {
-  cli.parse(import_node_process5.default.argv);
+  cli.parse(import_node_process7.default.argv);
 }
 main();
 //# sourceMappingURL=index.cjs.map