mcp-proxy-conductor 0.2.0 → 0.3.0

package/README.md

@@ -89,6 +89,37 @@ Manage downstreams conversationally through the meta-tools:
 
 Its tools then appear as `filesystem__<toolname>`, callable immediately — no restart.
 
+## Discovering servers from registries
+
+Instead of typing transport details by hand, discover servers from MCP registries and
+install them through meta-tools:
+
+- **`list_registries`** — enumerate available registries with capability flags
+  (`canConnect`, `canDetectSecrets`).
+- **`search_registry(query, sources?)`** — search for servers. **Defaults to the official
+  registry** (`registry.modelcontextprotocol.io`); pass `sources` (ids from
+  `list_registries`) to widen the search.
+- **`install_from_registry(ref, { id?, env?, secretBindings? })`** — install a result by
+  its `ref`. For entries that need secrets, store them with `secret set` and pass
+  `secretBindings: { ENV_NAME: "<keychain-name>" }`; for required non-secret env, pass
+  `env: { ENV_NAME: "<value>" }`.
+
+Example: search, then install a server that needs a secret:
+
+```text
+search_registry { "query": "filesystem" }
+→ official:com.example/fs  (connectable, requiredSecrets: ["API_TOKEN"])
+
+mcp-proxy-conductor secret set fs-token        # in your terminal
+install_from_registry { "ref": "official:com.example/fs", "secretBindings": { "API_TOKEN": "fs-token" } }
+```
+
+**Sources & capability asymmetry:** the **official** registry provides structured run
+details and secret flags, so auto-connect and secret detection work fully. **Glama** is a
+discovery source (it lists servers but not a runnable command, so its entries are not
+auto-connectable — use the results to then `add_server` manually). Per-source failures are
+reported in the search result, never crashing the search.
+
 ## Credentials
 
 Secrets live in the **OS keychain** (macOS Keychain, Windows Credential Manager, Linux
@@ -157,7 +188,7 @@ Local, single-user focus. Known limitations:
 - 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 and MCP registry lookup.
+Planned, not yet implemented: multi-tenant/SaaS mode.
 
 ## License
 

package/dist/index.js

@@ -200,7 +200,7 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 
 // src/registry/connection.ts
 var EMPTY = { tools: [], resources: [], prompts: [] };
@@ -484,16 +484,64 @@ var Aggregator = class {
   }
 };
 
+// src/registry-lookup/install.ts
+function normalizeId(s) {
+  const cleaned = s.replace(/[^A-Za-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+  return cleaned || "server";
+}
+function buildServerDefinition(entry, req) {
+  if (!entry.install) {
+    return {
+      guidance: `'${entry.ref}' has no run details from source '${entry.source}'. Add it manually with add_server (provide command/args or a url).`
+    };
+  }
+  const id = normalizeId(req.id ?? entry.name);
+  if (entry.install.type !== "stdio") {
+    return {
+      def: { id, enabled: true, transport: { type: entry.install.type, url: entry.install.url } }
+    };
+  }
+  const unboundSecrets = entry.requiredEnv.filter((e) => e.required && e.secret).filter((e) => !(req.secretBindings && e.name in req.secretBindings));
+  if (unboundSecrets.length > 0) {
+    const names = unboundSecrets.map((e) => e.name).join(", ");
+    const example = unboundSecrets[0].name;
+    return {
+      guidance: `'${entry.ref}' needs secret(s): ${names}. Store each with 'mcp-proxy-conductor secret set <name>', then re-run install_from_registry with secretBindings, e.g. { "${example}": "<keychain-name>" }.`
+    };
+  }
+  const missingEnv = entry.requiredEnv.filter((e) => e.required && !e.secret).filter((e) => !(req.env && e.name in req.env));
+  if (missingEnv.length > 0) {
+    const names = missingEnv.map((e) => e.name).join(", ");
+    return {
+      guidance: `'${entry.ref}' needs env value(s): ${names}. Re-run install_from_registry with env: { "${missingEnv[0].name}": "<value>" }.`
+    };
+  }
+  const env = { ...req.env ?? {} };
+  for (const [envName, keychainName] of Object.entries(req.secretBindings ?? {})) {
+    env[envName] = `\${keychain:${keychainName}}`;
+  }
+  return {
+    def: {
+      id,
+      enabled: true,
+      transport: { type: "stdio", command: entry.install.command, args: entry.install.args, env }
+    }
+  };
+}
+
 // 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) {
+  constructor(manager, store, registry) {
     this.manager = manager;
     this.store = store;
+    this.registry = registry;
   }
   manager;
   store;
+  registry;
+  lastEntries = /* @__PURE__ */ new Map();
   definitions() {
     return [
       {
@@ -517,30 +565,67 @@ var MetaTools = class {
         name: "list_servers",
         description: "List managed downstream servers: connection state (idle/connected/error), whether capabilities are served from cache, and capability counts.",
         inputSchema: { type: "object", properties: {} }
+      },
+      {
+        name: "list_registries",
+        description: "List available MCP registries to search, with capability flags (canConnect, canDetectSecrets).",
+        inputSchema: { type: "object", properties: {} }
+      },
+      {
+        name: "search_registry",
+        description: "Search MCP registries for servers. Defaults to the official registry; pass sources (from list_registries) to include others.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: { type: "string" },
+            sources: { type: "array", items: { type: "string" }, description: 'Registry ids to search; default ["official"]' },
+            limit: { type: "number", description: "Max results per source (default 10)" }
+          },
+          required: ["query"]
+        }
+      },
+      {
+        name: "install_from_registry",
+        description: "Install a server found via search_registry by its ref. Provide secretBindings { ENV_NAME: keychain-name } for required secrets, and env { ENV_NAME: value } for required non-secret env.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            ref: { type: "string", description: "The ref from a search_registry result" },
+            id: { type: "string", description: "Optional downstream id (defaults to a normalized name)" },
+            env: { type: "object" },
+            secretBindings: { type: "object" }
+          },
+          required: ["ref"]
+        }
       }
     ];
   }
   has(name) {
-    return ["add_server", "remove_server", "list_servers"].includes(name);
+    return ["add_server", "remove_server", "list_servers", "list_registries", "search_registry", "install_from_registry"].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));
+      if (name === "list_registries") return this.listRegistries();
+      if (name === "search_registry") return await this.searchRegistry(args);
+      if (name === "install_from_registry") return await this.installFromRegistry(args);
       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 });
+  async persistAndAdd(def) {
     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 addServer(args) {
+    const def = ServerDefinitionSchema.parse({ id: args.id, transport: args.transport, enabled: true });
+    await this.persistAndAdd(def);
+    return ok(`server '${def.id}' added (state: ${this.manager.get(def.id)?.state}).`);
   }
   async removeServer(args) {
     const id = String(args.id ?? "");
@@ -551,6 +636,46 @@ var MetaTools = class {
     await this.store.save(config);
     return ok(`server '${id}' removed.`);
   }
+  listRegistries() {
+    if (!this.registry) return fail("registry lookup is not configured");
+    return ok(JSON.stringify(this.registry.list(), null, 2));
+  }
+  async searchRegistry(args) {
+    if (!this.registry) return fail("registry lookup is not configured");
+    const query = String(args.query ?? "");
+    if (!query) return fail("query is required");
+    const sources = Array.isArray(args.sources) ? args.sources : void 0;
+    const limit = typeof args.limit === "number" ? args.limit : 10;
+    const outcome = await this.registry.search(query, sources, limit);
+    for (const e of outcome.entries) this.lastEntries.set(e.ref, e);
+    const view = outcome.entries.map((e) => ({
+      ref: e.ref,
+      source: e.source,
+      name: e.name,
+      description: e.description,
+      connectable: e.install !== void 0,
+      requiredSecrets: e.requiredEnv.filter((v) => v.secret).map((v) => v.name)
+    }));
+    const payload = { results: view };
+    if (outcome.errors.length > 0) payload.errors = outcome.errors;
+    return ok(JSON.stringify(payload, null, 2));
+  }
+  async installFromRegistry(args) {
+    if (!this.registry) return fail("registry lookup is not configured");
+    const ref = String(args.ref ?? "");
+    const entry = this.lastEntries.get(ref);
+    if (!entry) return fail(`unknown ref '${ref}'. Run search_registry first and use a ref from its results.`);
+    const plan = buildServerDefinition(entry, {
+      id: args.id ? String(args.id) : void 0,
+      env: args.env ?? void 0,
+      secretBindings: args.secretBindings ?? void 0
+    });
+    if (!plan.def) return ok(plan.guidance ?? "cannot install this entry automatically.");
+    const def = ServerDefinitionSchema.parse(plan.def);
+    if (this.manager.get(def.id)) return fail(`server '${def.id}' already exists`);
+    await this.persistAndAdd(def);
+    return ok(`installed '${def.id}' from ${entry.source} (state: ${this.manager.get(def.id)?.state}).`);
+  }
 };
 
 // src/server/upstream.ts
@@ -632,6 +757,153 @@ function tryJson(raw) {
   }
 }
 
+// src/registry-lookup/aggregate.ts
+var RegistryAggregator = class {
+  constructor(sources, timeoutMs = 8e3) {
+    this.timeoutMs = timeoutMs;
+    this.sources = new Map(sources.map((s) => [s.id, s]));
+  }
+  timeoutMs;
+  sources;
+  list() {
+    return [...this.sources.values()].map((s) => ({
+      id: s.id,
+      title: s.title,
+      canConnect: s.capabilities.canConnect,
+      canDetectSecrets: s.capabilities.canDetectSecrets
+    }));
+  }
+  async search(query, sourceIds = ["official"], limit = 10) {
+    for (const id of sourceIds) {
+      if (!this.sources.has(id)) throw new Error(`unknown registry '${id}' (call list_registries to see available sources)`);
+    }
+    const results = await Promise.all(
+      sourceIds.map(async (id) => {
+        const src = this.sources.get(id);
+        try {
+          const entries = await this.withTimeout(src.search(query, limit), id);
+          return { entries, error: void 0 };
+        } catch (err) {
+          return { entries: [], error: { source: id, error: err instanceof Error ? err.message : String(err) } };
+        }
+      })
+    );
+    return {
+      entries: results.flatMap((r) => r.entries),
+      errors: results.flatMap((r) => r.error ? [r.error] : [])
+    };
+  }
+  withTimeout(p, id) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error(`${id} timed out after ${this.timeoutMs}ms`)), this.timeoutMs);
+      timer.unref?.();
+      p.then((v) => {
+        clearTimeout(timer);
+        resolve(v);
+      }, (e) => {
+        clearTimeout(timer);
+        reject(e);
+      });
+    });
+  }
+};
+
+// src/registry-lookup/official.ts
+var OfficialRegistry = class {
+  constructor(fetchImpl = globalThis.fetch, baseUrl = "https://registry.modelcontextprotocol.io") {
+    this.fetchImpl = fetchImpl;
+    this.baseUrl = baseUrl;
+  }
+  fetchImpl;
+  baseUrl;
+  id = "official";
+  title = "Official MCP Registry";
+  capabilities = { canConnect: true, canDetectSecrets: true };
+  async search(query, limit) {
+    const url = `${this.baseUrl}/v0/servers?search=${encodeURIComponent(query)}&limit=${limit}`;
+    const res = await this.fetchImpl(url);
+    if (!res.ok) throw new Error(`official registry returned HTTP ${res.status}`);
+    const body = await res.json();
+    return (body.servers ?? []).map((s) => this.toEntry(s.server));
+  }
+  // Prefer a remote (no child process); else the first npm package as stdio. install and
+  // requiredEnv are derived from the SAME chosen package so they never describe different
+  // packages. requiredEnv is only populated for a stdio install (a remote's auth is not
+  // described by package env vars).
+  toEntry(server) {
+    const remote = server.remotes?.[0];
+    const pkg = (server.packages ?? []).find((p) => p.registryType === "npm") ?? server.packages?.[0];
+    let install;
+    let requiredEnv = [];
+    if (remote?.url) {
+      install = { type: remote.type === "sse" ? "sse" : "http", url: remote.url };
+    } else if (pkg?.identifier) {
+      install = {
+        type: "stdio",
+        command: pkg.runtimeHint || "npx",
+        args: ["-y", pkg.identifier],
+        envNames: (pkg.environmentVariables ?? []).map((e) => e.name)
+      };
+      requiredEnv = (pkg.environmentVariables ?? []).map((e) => ({
+        name: e.name,
+        description: e.description,
+        required: !!e.isRequired,
+        secret: !!e.isSecret
+      }));
+    }
+    return {
+      source: this.id,
+      ref: `${this.id}:${server.name}`,
+      name: server.name,
+      description: server.description ?? "",
+      install,
+      requiredEnv
+    };
+  }
+};
+
+// src/registry-lookup/glama.ts
+var GlamaRegistry = class {
+  constructor(fetchImpl = globalThis.fetch, baseUrl = "https://glama.ai") {
+    this.fetchImpl = fetchImpl;
+    this.baseUrl = baseUrl;
+  }
+  fetchImpl;
+  baseUrl;
+  id = "glama";
+  title = "Glama";
+  // Glama lists repository + an env schema but no runnable command and no isSecret flag,
+  // so it is a discovery-only source (no auto-connect, no secret detection).
+  capabilities = { canConnect: false, canDetectSecrets: false };
+  async search(query, limit) {
+    const url = `${this.baseUrl}/api/mcp/v1/servers?query=${encodeURIComponent(query)}&first=${limit}`;
+    const res = await this.fetchImpl(url);
+    if (!res.ok) throw new Error(`glama registry returned HTTP ${res.status}`);
+    const body = await res.json();
+    return (body.servers ?? []).map((s) => this.toEntry(s));
+  }
+  toEntry(s) {
+    return {
+      source: this.id,
+      ref: `${this.id}:${s.id}`,
+      name: s.name,
+      description: s.description ?? "",
+      install: void 0,
+      requiredEnv: this.envOf(s.environmentVariablesJsonSchema)
+    };
+  }
+  envOf(schema) {
+    const required = new Set(schema?.required ?? []);
+    return Object.entries(schema?.properties ?? {}).map(([name, p]) => ({
+      name,
+      description: p.description,
+      required: required.has(name),
+      secret: false
+      // Glama does not flag secrets
+    }));
+  }
+};
+
 // src/index.ts
 async function createConductor(opts = {}) {
   const store = opts.store ?? new ConfigStore();
@@ -649,7 +921,8 @@ async function createConductor(opts = {}) {
   const idleMs = opts.idleMs ?? (Number.isFinite(rawIdleMs) ? rawIdleMs : 3e5);
   const manager = new DownstreamManager(transportFactory, { onChange, cache, idleMs });
   const aggregator = new Aggregator(manager);
-  const meta = new MetaTools(manager, store);
+  const registry = opts.registry ?? new RegistryAggregator([new OfficialRegistry(), new GlamaRegistry()]);
+  const meta = new MetaTools(manager, store, registry);
   server = buildUpstreamServer(aggregator, meta);
   const config = await store.load();
   await manager.start(config.servers);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-proxy-conductor",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local MCP proxy that aggregates dynamically managed downstream MCP servers, managed at runtime without restarting the client.",
   "type": "module",
   "license": "MIT",