mcp-proxy-conductor 0.1.3 → 0.2.0

package/README.md

@@ -31,9 +31,10 @@ notifications.
 - Downstream transports: **stdio**, **Streamable HTTP**, **SSE**.
 - Aggregates **tools, resources, and prompts** from all downstreams, with per-server
   namespacing (`serverId__name`) so names never collide.
-- **Persistence** — added servers are stored and reconnected on the next start.
-- Auth passed through per downstream (env vars for stdio, headers for HTTP/SSE), behind a
-  pluggable `SecretProvider` interface.
+- **Lazy connections**: downstreams connect on first use and disconnect after an idle
+  timeout; capabilities are served from a cache so tools are advertised without connecting.
+- **Credentials in the OS keychain** — referenced from config, never stored in plaintext.
+- **Persistence** — added servers are stored and reconnected (lazily) on the next start.
 
 ## Requirements
 
@@ -59,24 +60,22 @@ Or add it manually to your client's MCP config:
 
 Restart the client once. ai-conductor then exposes its meta-tools.
 
-## Usage
+## Managing downstream servers
 
-Manage downstream servers conversationally through the meta-tools:
+Manage downstreams conversationally through the meta-tools:
 
 - **`add_server`** — add and connect a downstream server at runtime (persists).
-  - `id`: unique, alphanumeric/hyphen, no underscores.
+  - `id`: unique, alphanumeric/hyphen, **no underscores**.
   - `transport`: one of
     - `{ "type": "stdio", "command": "...", "args": [...], "env": { ... } }`
     - `{ "type": "http", "url": "https://…/mcp", "headers": { ... } }`
     - `{ "type": "sse", "url": "https://…/sse", "headers": { ... } }`
-- **`remove_server`** — disconnect and remove a downstream server (persists).
-  - `id`: the server id.
-- **`list_servers`** — list managed servers with connection state and capability counts.
+- **`remove_server`** — disconnect and remove a downstream server (persists). Arg: `id`.
+- **`list_servers`** — list managed servers with connection state (`idle`/`connected`/
+  `error`), whether capabilities come from cache, and capability counts.
 
 ### Example
 
-Adding an stdio-based downstream:
-
 ```json
 {
   "id": "filesystem",
@@ -88,14 +87,57 @@ Adding an stdio-based downstream:
 }
 ```
 
-Once connected, its tools appear as `filesystem__<toolname>` and are callable
-immediately — no restart.
+Its tools then appear as `filesystem__<toolname>`, callable immediately — no restart.
+
+## Credentials
+
+Secrets live in the **OS keychain** (macOS Keychain, Windows Credential Manager, Linux
+Secret Service) — never in `config.json` and never passed through the chat.
+
+**1. Store a secret** with the CLI (the value is read from hidden stdin, not the chat):
+
+```bash
+mcp-proxy-conductor secret set my-token
+# or pipe it (e.g. in scripts):
+printf '%s' "$MY_TOKEN" | mcp-proxy-conductor secret set my-token
+
+# remove it again:
+mcp-proxy-conductor secret rm my-token
+```
+
+**2. Reference it** in `add_server` via `${keychain:<name>}`:
+
+```json
+{
+  "id": "uptime",
+  "transport": {
+    "type": "http",
+    "url": "https://example.com/mcp",
+    "headers": { "Authorization": "Bearer ${keychain:my-token}" }
+  }
+}
+```
+
+References are resolved at connect time. Supported placeholder schemes (usable in any
+`env` or `headers` value, and combinable within a string):
+
+| Reference | Resolves from |
+|---|---|
+| `${keychain:NAME}` | OS keychain (service `mcp-proxy-conductor`) |
+| `${env:VAR}` | process environment |
+| `${VAR}` | process environment (shorthand) |
+
+> **Headless Linux** without a running Secret Service daemon cannot use the keychain —
+> use `${env:…}` there instead. A missing or unreachable secret surfaces as an `error`
+> state for that one downstream (visible in `list_servers`); other servers keep working.
 
-### Secrets
+## Lazy connections
 
-`env` and `headers` values support `${VAR}` references that are expanded from the
-environment at connect time, so you can avoid hardcoding tokens, e.g.
-`"Authorization": "Bearer ${UPTIMEROBOT_TOKEN}"`.
+To scale to many downstreams, connections are **late-bound**: at startup nothing is
+connected — tools/resources/prompts are advertised from a persisted capability cache. A
+downstream connects on the **first actual call** and is evicted after an idle timeout
+(default **5 minutes**, override with `CONDUCTOR_IDLE_TIMEOUT_MS`, in ms; `0` disables
+eviction). The first call to an idle server therefore pays a one-time connect latency.
 
 ## Development
 
@@ -108,14 +150,14 @@ pnpm build       # tsup → dist/index.js
 
 ## Status & limitations
 
-This is an MVP focused on the local, single-user case. Known limitations:
+Local, single-user focus. Known limitations:
 
-- No automatic reconnect/backoff for a downstream that crashes (remove + add to recover).
+- No automatic reconnect/backoff for a downstream that crashes (it returns to `idle` and
+  reconnects on the next call).
 - Change notifications are coarse (all `listChanged` types emitted on any change).
 - HTTP downstreams do not auto-fall back to SSE; the transport type is explicit.
 
-Planned, not yet implemented: multi-tenant/SaaS mode, MCP registry lookup, OS-keychain
-secret backend.
+Planned, not yet implemented: multi-tenant/SaaS mode and MCP registry lookup.
 
 ## License
 

package/dist/index.js

@@ -70,26 +70,111 @@ var ConfigStore = class {
 };
 
 // src/secrets/provider.ts
-var REF = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
-var EnvSecretProvider = class {
-  constructor(env = process.env) {
-    this.env = env;
-  }
+var REF = /\$\{([^}]+)\}/g;
+var SecretResolver = class {
   env;
+  keychain;
+  constructor(opts = {}) {
+    this.env = opts.env ?? process.env;
+    this.keychain = opts.keychain;
+  }
   async resolve(value) {
-    return value.replace(REF, (_, name) => {
-      const v = this.env[name];
-      if (v === void 0) throw new Error(`Secret reference \${${name}} is not set in the environment`);
-      return v;
-    });
+    return value.replace(REF, (_, token) => this.lookup(token));
   }
   async resolveRecord(record) {
     const out = {};
     for (const [k, v] of Object.entries(record)) out[k] = await this.resolve(v);
     return out;
   }
+  // Resolve a single placeholder token (the text between ${ and }).
+  lookup(token) {
+    const idx = token.indexOf(":");
+    const scheme = idx === -1 ? "env" : token.slice(0, idx);
+    const name = idx === -1 ? token : token.slice(idx + 1);
+    if (scheme === "env") {
+      const v = this.env[name];
+      if (v === void 0) throw new Error(`Secret reference \${${token}} is not set in the environment`);
+      return v;
+    }
+    if (scheme === "keychain") {
+      if (!this.keychain) throw new Error(`Cannot resolve \${${token}}: no keychain backend configured`);
+      const v = this.keychain.get(name);
+      if (v === null) {
+        throw new Error(`Secret '${name}' not found in the OS keychain (store it with: mcp-proxy-conductor secret set ${name})`);
+      }
+      return v;
+    }
+    throw new Error(`Unknown secret scheme '${scheme}' in \${${token}}`);
+  }
 };
 
+// src/secrets/keychain.ts
+import { Entry } from "@napi-rs/keyring";
+var KEYCHAIN_SERVICE = "mcp-proxy-conductor";
+function osKeychain(service = KEYCHAIN_SERVICE) {
+  return {
+    get: (name) => new Entry(service, name).getPassword(),
+    set: (name, value) => {
+      new Entry(service, name).setPassword(value);
+    },
+    delete: (name) => new Entry(service, name).deletePassword()
+  };
+}
+
+// src/cli/secret.ts
+import { createInterface } from "readline";
+var USAGE = "usage: mcp-proxy-conductor secret <set|rm> <name>";
+async function runSecretCommand(args, backend, io) {
+  const [sub, name] = args;
+  if (sub === "set") {
+    if (!name) {
+      io.out(USAGE);
+      return 1;
+    }
+    const value = await io.readSecret();
+    if (!value) {
+      io.out("aborted: empty value, nothing stored");
+      return 1;
+    }
+    backend.set(name, value);
+    io.out(`stored secret '${name}' in the OS keychain.`);
+    return 0;
+  }
+  if (sub === "rm") {
+    if (!name) {
+      io.out(USAGE);
+      return 1;
+    }
+    const existed = backend.delete(name);
+    io.out(existed ? `removed secret '${name}'.` : `no secret '${name}' found.`);
+    return 0;
+  }
+  io.out(USAGE);
+  return 1;
+}
+function promptHidden(promptText) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    let promptWritten = false;
+    rl._writeToOutput = () => {
+      if (!promptWritten) {
+        process.stdout.write(promptText);
+        promptWritten = true;
+      }
+    };
+    rl.question(promptText, (answer) => {
+      rl.close();
+      process.stdout.write("\n");
+      resolve(answer);
+    });
+  });
+}
+async function readAllStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8").replace(/\r?\n$/, "");
+}
+
 // src/registry/transport.ts
 import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
@@ -115,7 +200,7 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 
 // src/version.ts
-var VERSION = "0.1.3";
+var VERSION = "0.2.0";
 
 // src/registry/connection.ts
 var EMPTY = { tools: [], resources: [], prompts: [] };
@@ -550,7 +635,7 @@ function tryJson(raw) {
 // src/index.ts
 async function createConductor(opts = {}) {
   const store = opts.store ?? new ConfigStore();
-  const secrets = new EnvSecretProvider();
+  const secrets = opts.secrets ?? new SecretResolver({ env: process.env, keychain: osKeychain() });
   const transportFactory = opts.transportFactory ?? ((def) => buildTransport(def, secrets));
   let server;
   const onChange = () => {
@@ -601,13 +686,24 @@ function isMainModule(argv1, importMetaUrl) {
   }
 }
 if (isMainModule(process.argv[1], import.meta.url)) {
-  createConductor().then(async (c) => {
-    installShutdownHandlers(c);
-    await c.start();
-  }).catch((err) => {
-    console.error("ai-conductor failed to start:", err);
-    process.exit(1);
-  });
+  const argv = process.argv.slice(2);
+  if (argv[0] === "secret") {
+    runSecretCommand(argv.slice(1), osKeychain(), {
+      readSecret: () => process.stdin.isTTY ? promptHidden("Secret value: ") : readAllStdin(),
+      out: (m) => console.log(m)
+    }).then((code) => process.exit(code)).catch((err) => {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    });
+  } else {
+    createConductor().then(async (c) => {
+      installShutdownHandlers(c);
+      await c.start();
+    }).catch((err) => {
+      console.error("ai-conductor failed to start:", err);
+      process.exit(1);
+    });
+  }
 }
 export {
   createConductor,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-proxy-conductor",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Local MCP proxy that aggregates dynamically managed downstream MCP servers, managed at runtime without restarting the client.",
   "type": "module",
   "license": "MIT",
@@ -42,6 +42,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
+    "@napi-rs/keyring": "^1.3.0",
     "env-paths": "^3.0.0",
     "zod": "^3.23.8"
   },