mcp-proxy-conductor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Cornelißen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# ai-conductor
+
+A local **MCP proxy / aggregator**. You register it **once** with an MCP client (e.g.
+Claude Desktop or Claude Code), and it sits in front of multiple, **dynamically managed**
+downstream MCP servers.
+
+> Published on npm as [`mcp-proxy-conductor`](https://www.npmjs.com/package/mcp-proxy-conductor).
+
+## Why
+
+Individual MCP servers are fiddly to set up and force an agent restart on every change.
+ai-conductor decouples that: downstream servers are added/removed **at runtime**, without
+restarting the upstream client. New tools appear immediately via MCP `listChanged`
+notifications.
+
+```
+  Claude (MCP client)
+        │  upstream: stdio
+        ▼
+  ┌─────────────────────────┐
+  │      ai-conductor       │   MCP server upstream, MCP client downstream
+  └─────────────────────────┘
+        │  downstream: stdio | Streamable HTTP | SSE
+        ▼
+  Server A   Server B   Server C  …  (managed at runtime)
+```
+
+## Features
+
+- **Runtime management** of downstream servers via built-in meta-tools — no client restart.
+- 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.
+
+## Requirements
+
+- Node.js ≥ 20
+
+## Install & register
+
+Register ai-conductor with your MCP client. With the Claude Code CLI:
+
+```bash
+claude mcp add conductor -s user -- npx -y mcp-proxy-conductor
+```
+
+Or add it manually to your client's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "conductor": { "command": "npx", "args": ["-y", "mcp-proxy-conductor"] }
+  }
+}
+```
+
+Restart the client once. ai-conductor then exposes its meta-tools.
+
+## Usage
+
+Manage downstream servers conversationally through the meta-tools:
+
+- **`add_server`** — add and connect a downstream server at runtime (persists).
+  - `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.
+
+### Example
+
+Adding an stdio-based downstream:
+
+```json
+{
+  "id": "filesystem",
+  "transport": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/some/dir"]
+  }
+}
+```
+
+Once connected, its tools appear as `filesystem__<toolname>` and are callable
+immediately — no restart.
+
+### Secrets
+
+`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}"`.
+
+## Development
+
+```bash
+pnpm install
+pnpm test        # vitest
+pnpm typecheck
+pnpm build       # tsup → dist/index.js
+```
+
+## Status & limitations
+
+This is an MVP focused on the local, single-user case. Known limitations:
+
+- No automatic reconnect/backoff for a downstream that crashes (remove + add to recover).
+- 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.
+
+## License
+
+[MIT](LICENSE) © Patrick Cornelißen

package/dist/index.js

@@ -0,0 +1,426 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/config/store.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname } from "path";
+import envPaths from "env-paths";
+
+// src/config/schema.ts
+import { z } from "zod";
+var ServerIdSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9-]*$/, "id must be alphanumeric/hyphen, no underscores");
+var StdioTransportSchema = z.object({
+  type: z.literal("stdio"),
+  command: z.string().min(1),
+  args: z.array(z.string()).default([]),
+  env: z.record(z.string(), z.string()).default({})
+});
+var HttpTransportSchema = z.object({
+  type: z.literal("http"),
+  url: z.string().url(),
+  headers: z.record(z.string(), z.string()).default({})
+});
+var SseTransportSchema = z.object({
+  type: z.literal("sse"),
+  url: z.string().url(),
+  headers: z.record(z.string(), z.string()).default({})
+});
+var TransportSchema = z.discriminatedUnion("type", [
+  StdioTransportSchema,
+  HttpTransportSchema,
+  SseTransportSchema
+]);
+var ServerDefinitionSchema = z.object({
+  id: ServerIdSchema,
+  enabled: z.boolean().default(true),
+  transport: TransportSchema
+});
+var ConfigSchema = z.object({
+  servers: z.array(ServerDefinitionSchema).default([])
+});
+
+// src/config/store.ts
+function defaultConfigPath() {
+  return `${envPaths("ai-conductor", { suffix: "" }).config}/config.json`;
+}
+var ConfigStore = class {
+  constructor(path = defaultConfigPath()) {
+    this.path = path;
+  }
+  path;
+  async load() {
+    let raw;
+    try {
+      raw = await readFile(this.path, "utf8");
+    } catch (err) {
+      if (err.code === "ENOENT") return ConfigSchema.parse({});
+      throw err;
+    }
+    return ConfigSchema.parse(JSON.parse(raw));
+  }
+  async save(config) {
+    const validated = ConfigSchema.parse(config);
+    await mkdir(dirname(this.path), { recursive: true });
+    await writeFile(this.path, JSON.stringify(validated, null, 2), "utf8");
+  }
+};
+
+// src/secrets/provider.ts
+var REF = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+var EnvSecretProvider = class {
+  constructor(env = process.env) {
+    this.env = env;
+  }
+  env;
+  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;
+    });
+  }
+  async resolveRecord(record) {
+    const out = {};
+    for (const [k, v] of Object.entries(record)) out[k] = await this.resolve(v);
+    return out;
+  }
+};
+
+// src/registry/transport.ts
+import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+async function buildTransport(def, secrets) {
+  const t = def.transport;
+  if (t.type === "stdio") {
+    const env = await secrets.resolveRecord(t.env);
+    return new StdioClientTransport({ command: t.command, args: t.args, env: { ...getDefaultEnvironment(), ...env } });
+  }
+  const headers = await secrets.resolveRecord(t.headers);
+  const requestInit = { headers };
+  if (t.type === "http") return new StreamableHTTPClientTransport(new URL(t.url), { requestInit });
+  return new SSEClientTransport(new URL(t.url), { requestInit });
+}
+
+// src/registry/connection.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import {
+  ToolListChangedNotificationSchema,
+  ResourceListChangedNotificationSchema,
+  PromptListChangedNotificationSchema
+} from "@modelcontextprotocol/sdk/types.js";
+var DownstreamConnection = class {
+  constructor(def, transportFactory, onChange) {
+    this.def = def;
+    this.transportFactory = transportFactory;
+    this.onChange = onChange;
+    this.client = new Client({ name: "ai-conductor", version: "0.1.0" });
+  }
+  def;
+  transportFactory;
+  onChange;
+  state = "connecting";
+  error;
+  capabilities = { tools: [], resources: [], prompts: [] };
+  client;
+  async connect() {
+    this.state = "connecting";
+    try {
+      const transport = await this.transportFactory(this.def);
+      await this.client.connect(transport);
+      this.client.onclose = () => {
+        if (this.state === "connected") this.state = "disconnected";
+        this.onChange?.();
+      };
+      this.registerNotificationHandlers();
+      await this.refresh();
+      this.state = "connected";
+    } catch (err) {
+      this.state = "error";
+      this.error = err instanceof Error ? err.message : String(err);
+      throw err;
+    }
+  }
+  registerNotificationHandlers() {
+    const refreshAndNotify = async () => {
+      await this.refresh().catch(() => void 0);
+      this.onChange?.();
+    };
+    this.client.setNotificationHandler(ToolListChangedNotificationSchema, refreshAndNotify);
+    this.client.setNotificationHandler(ResourceListChangedNotificationSchema, refreshAndNotify);
+    this.client.setNotificationHandler(PromptListChangedNotificationSchema, refreshAndNotify);
+  }
+  async refresh() {
+    const caps = this.client.getServerCapabilities() ?? {};
+    this.capabilities = {
+      tools: caps.tools ? (await this.client.listTools()).tools : [],
+      resources: caps.resources ? (await this.client.listResources()).resources : [],
+      prompts: caps.prompts ? (await this.client.listPrompts()).prompts : []
+    };
+  }
+  async close() {
+    await this.client.close().catch(() => void 0);
+    this.state = "disconnected";
+  }
+};
+
+// src/registry/manager.ts
+var DownstreamManager = class {
+  constructor(transportFactory, onChange = () => void 0) {
+    this.transportFactory = transportFactory;
+    this.onChange = onChange;
+  }
+  transportFactory;
+  onChange;
+  conns = /* @__PURE__ */ new Map();
+  // Connect all enabled definitions. Individual failures are captured as error state;
+  // they never reject start() or prevent other servers from connecting.
+  async start(defs) {
+    await Promise.all(defs.filter((d) => d.enabled).map((d) => this.connectOne(d)));
+  }
+  async connectOne(def) {
+    const conn = new DownstreamConnection(def, this.transportFactory, this.onChange);
+    this.conns.set(def.id, conn);
+    await conn.connect().catch(() => void 0);
+    this.onChange();
+    return conn;
+  }
+  async add(def) {
+    if (this.conns.has(def.id)) throw new Error(`server '${def.id}' already exists`);
+    return this.connectOne(def);
+  }
+  async remove(id) {
+    const conn = this.conns.get(id);
+    if (!conn) return;
+    await conn.close();
+    this.conns.delete(id);
+    this.onChange();
+  }
+  get(id) {
+    return this.conns.get(id);
+  }
+  connected() {
+    return [...this.conns.values()].filter((c) => c.state === "connected");
+  }
+  list() {
+    return [...this.conns.values()].map((c) => ({
+      id: c.def.id,
+      state: c.state,
+      error: c.error,
+      toolCount: c.capabilities.tools.length,
+      resourceCount: c.capabilities.resources.length,
+      promptCount: c.capabilities.prompts.length
+    }));
+  }
+  async closeAll() {
+    await Promise.all([...this.conns.values()].map((c) => c.close()));
+    this.conns.clear();
+  }
+};
+
+// src/aggregator/namespace.ts
+var DELIM = "__";
+function encodeName(serverId, name) {
+  return `${serverId}${DELIM}${name}`;
+}
+function decodeName(qualified) {
+  const idx = qualified.indexOf(DELIM);
+  if (idx === -1) throw new Error(`Not a namespaced name: ${qualified}`);
+  return { serverId: qualified.slice(0, idx), name: qualified.slice(idx + DELIM.length) };
+}
+function encodeUri(serverId, uri) {
+  const u = new URL("conductor://route/");
+  u.searchParams.set("s", serverId);
+  u.searchParams.set("u", uri);
+  return u.toString();
+}
+function decodeUri(qualified) {
+  const u = new URL(qualified);
+  const s = u.searchParams.get("s");
+  const orig = u.searchParams.get("u");
+  if (!s || orig === null) throw new Error(`Not a namespaced uri: ${qualified}`);
+  return { serverId: s, uri: orig };
+}
+
+// src/aggregator/aggregate.ts
+var Aggregator = class {
+  constructor(manager) {
+    this.manager = manager;
+  }
+  manager;
+  async listTools() {
+    return this.manager.connected().flatMap(
+      (c) => c.capabilities.tools.map((t) => ({ ...t, name: encodeName(c.def.id, t.name) }))
+    );
+  }
+  async listPrompts() {
+    return this.manager.connected().flatMap(
+      (c) => c.capabilities.prompts.map((p) => ({ ...p, name: encodeName(c.def.id, p.name) }))
+    );
+  }
+  async listResources() {
+    return this.manager.connected().flatMap(
+      (c) => c.capabilities.resources.map((r) => ({ ...r, uri: encodeUri(c.def.id, r.uri) }))
+    );
+  }
+  async callTool(qualifiedName, args) {
+    const { serverId, name } = decodeName(qualifiedName);
+    return this.connOrThrow(serverId).client.callTool({ name, arguments: args });
+  }
+  async getPrompt(qualifiedName, args) {
+    const { serverId, name } = decodeName(qualifiedName);
+    return this.connOrThrow(serverId).client.getPrompt({ name, arguments: args });
+  }
+  async readResource(qualifiedUri) {
+    const { serverId, uri } = decodeUri(qualifiedUri);
+    return this.connOrThrow(serverId).client.readResource({ uri });
+  }
+  connOrThrow(serverId) {
+    const conn = this.manager.get(serverId);
+    if (!conn || conn.state !== "connected") {
+      throw new Error(`downstream server '${serverId}' is not connected`);
+    }
+    return conn;
+  }
+};
+
+// src/meta/tools.ts
+var ok = (text) => ({ content: [{ type: "text", text }] });
+var fail = (text) => ({ content: [{ type: "text", text }], isError: true });
+var MetaTools = class {
+  constructor(manager, store) {
+    this.manager = manager;
+    this.store = store;
+  }
+  manager;
+  store;
+  definitions() {
+    return [
+      {
+        name: "add_server",
+        description: "Add and connect a downstream MCP server at runtime. Persists across restarts.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            id: { type: "string", description: "Unique id, alphanumeric/hyphen, no underscores" },
+            transport: { type: "object", description: 'Transport: {type:"stdio",command,args?,env?} | {type:"http",url,headers?} | {type:"sse",url,headers?}' }
+          },
+          required: ["id", "transport"]
+        }
+      },
+      {
+        name: "remove_server",
+        description: "Disconnect and remove a downstream MCP server. Persists across restarts.",
+        inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] }
+      },
+      {
+        name: "list_servers",
+        description: "List managed downstream servers with connection state and capability counts.",
+        inputSchema: { type: "object", properties: {} }
+      }
+    ];
+  }
+  has(name) {
+    return ["add_server", "remove_server", "list_servers"].includes(name);
+  }
+  async call(name, args) {
+    try {
+      if (name === "add_server") return await this.addServer(args);
+      if (name === "remove_server") return await this.removeServer(args);
+      if (name === "list_servers") return ok(JSON.stringify(this.manager.list(), null, 2));
+      return fail(`unknown meta-tool: ${name}`);
+    } catch (err) {
+      return fail(err instanceof Error ? err.message : String(err));
+    }
+  }
+  async addServer(args) {
+    const def = ServerDefinitionSchema.parse({ id: args.id, transport: args.transport, enabled: true });
+    await this.manager.add(def);
+    const config = await this.store.load();
+    config.servers = [...config.servers.filter((s) => s.id !== def.id), def];
+    await this.store.save(config);
+    const state = this.manager.get(def.id)?.state;
+    return ok(`server '${def.id}' added (state: ${state}).`);
+  }
+  async removeServer(args) {
+    const id = String(args.id ?? "");
+    if (!id) return fail("id is required");
+    await this.manager.remove(id);
+    const config = await this.store.load();
+    config.servers = config.servers.filter((s) => s.id !== id);
+    await this.store.save(config);
+    return ok(`server '${id}' removed.`);
+  }
+};
+
+// src/server/upstream.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+function buildUpstreamServer(aggregator, meta) {
+  const server = new Server(
+    { name: "ai-conductor", version: "0.1.0" },
+    { capabilities: { tools: { listChanged: true }, resources: { listChanged: true }, prompts: { listChanged: true } } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [...meta.definitions(), ...await aggregator.listTools()]
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const name = req.params.name;
+    const args = req.params.arguments ?? {};
+    if (!name.includes(DELIM)) return meta.call(name, args);
+    return aggregator.callTool(name, args);
+  });
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: await aggregator.listResources() }));
+  server.setRequestHandler(ReadResourceRequestSchema, async (req) => aggregator.readResource(req.params.uri));
+  server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: await aggregator.listPrompts() }));
+  server.setRequestHandler(
+    GetPromptRequestSchema,
+    async (req) => aggregator.getPrompt(req.params.name, req.params.arguments ?? {})
+  );
+  return server;
+}
+
+// src/index.ts
+async function createConductor(opts = {}) {
+  const store = opts.store ?? new ConfigStore();
+  const secrets = new EnvSecretProvider();
+  const transportFactory = opts.transportFactory ?? ((def) => buildTransport(def, secrets));
+  let server;
+  const onChange = () => {
+    if (!server?.transport) return;
+    server.sendToolListChanged();
+    server.sendResourceListChanged();
+    server.sendPromptListChanged();
+  };
+  const manager = new DownstreamManager(transportFactory, onChange);
+  const aggregator = new Aggregator(manager);
+  const meta = new MetaTools(manager, store);
+  server = buildUpstreamServer(aggregator, meta);
+  const config = await store.load();
+  await manager.start(config.servers);
+  return {
+    server,
+    manager,
+    async start() {
+      await server.connect(new StdioServerTransport());
+    }
+  };
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+  createConductor().then((c) => c.start()).catch((err) => {
+    console.error("ai-conductor failed to start:", err);
+    process.exit(1);
+  });
+}
+export {
+  createConductor
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "mcp-proxy-conductor",
+  "version": "0.1.0",
+  "description": "Local MCP proxy that aggregates dynamically managed downstream MCP servers, managed at runtime without restarting the client.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Patrick Cornelißen (https://github.com/pcornelissen)",
+  "homepage": "https://github.com/pc-software-org/ai-conductor#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pc-software-org/ai-conductor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pc-software-org/ai-conductor/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "proxy",
+    "aggregator",
+    "claude",
+    "llm",
+    "ai"
+  ],
+  "bin": {
+    "mcp-proxy-conductor": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm typecheck && pnpm test && pnpm build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "env-paths": "^3.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}