@pi-archimedes/mcp 2.3.0

package/src/direct-tools.ts

@@ -0,0 +1,250 @@
+import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { BUILTIN_NAMES, findFormattingCollisions, formatToolName } from "./tool-naming.js";
+import { autoAuthenticate, needsAuthToolResult } from "./auto-auth.js";
+import type { CachedTool, ToolPrefix } from "./types.js";
+import type { ServerClient } from "./server-client.js";
+import { renderDirectCall, renderDirectResult, type RenderContext } from "./renderer.js";
+
+/**
+ * Track which final prefixed tool names have been registered, at module
+ * level, keyed by SERVER name. Registration is cache-driven (no live client
+ * to key on anymore), and pi's tool registry cannot accept the same name
+ * twice. Each registration pass REPLACES the server's set with the names
+ * claimed in that pass, so stale entries from shrunken tool lists are
+ * evicted and a later session_start can re-register (pi can never
+ * unregister; the module-level set only gates re-registration). Entries for
+ * servers that are no longer configured are pruned by
+ * pruneRegisteredNames() at session_start — without that, a removed server's
+ * claimed names would block a surviving server from claiming the same final
+ * name (e.g. under toolPrefix "none"). Within one process the dedup check
+ * still spans ALL servers' sets, so two servers that would format to the
+ * same final name (e.g. identical raw names under toolPrefix "none") never
+ * double-register. The module is re-imported by the extension loader on
+ * /reload, which resets this map for the fresh pi registry.
+ */
+const registeredNames = new Map<string, Set<string>>();
+
+/**
+ * Per-server formatted-name collisions already warned about (module-level so
+ * repeated registration passes don't re-warn for the same collision). Key:
+ * serverName + finalName + raw names. Reset by clearRegisteredForTest.
+ */
+const warnedCollisions = new Set<string>();
+
+/** Test-only: reset the module-level registration state. */
+export function clearRegisteredForTest(): void {
+  registeredNames.clear();
+  warnedCollisions.clear();
+}
+
+/** Test-only: snapshot of the per-server registered (prefixed) names. */
+export function getRegisteredNamesForTest(): ReadonlyMap<string, ReadonlySet<string>> {
+  return registeredNames;
+}
+
+/** True when ANY server has already claimed this final prefixed name */
+function isClaimed(name: string): boolean {
+  for (const set of registeredNames.values()) {
+    if (set.has(name)) return true;
+  }
+  return false;
+}
+
+/**
+ * Drop tracked entries for servers that are no longer configured, freeing
+ * their claimed final names for re-registration by surviving servers
+ * (e.g. a removed server that claimed "foo" under toolPrefix "none" must
+ * not block a remaining server that exposes a raw tool named "foo").
+ * Call at session_start with the set of currently configured server names,
+ * before the registration pass.
+ */
+export function pruneRegisteredNames(activeServerNames: ReadonlySet<string>): void {
+  for (const name of [...registeredNames.keys()]) {
+    if (!activeServerNames.has(name)) registeredNames.delete(name);
+  }
+}
+
+/** Per-server direct-tool filtering knobs (subset of EffectiveServerSettings) */
+export interface DirectToolFilter {
+  /** true = all, string[] = subset of raw tool names */
+  directTools: boolean | string[];
+  /** Only expose these tools (whitelist) */
+  includeTools?: string[];
+  /** Never expose these tools (blacklist) */
+  excludeTools?: string[];
+}
+
+/**
+ * Apply per-server direct-tool filtering to a tool list:
+ * directTools (true → passthrough, string[] → subset), then includeTools
+ * (intersect), then excludeTools (subtract).
+ */
+export function filterDirectTools(
+  tools: CachedTool[],
+  filter: DirectToolFilter,
+): CachedTool[] {
+  if (filter.directTools === false) return [];
+  let out = tools;
+  if (Array.isArray(filter.directTools)) {
+    const subset = new Set(filter.directTools);
+    out = out.filter((t) => subset.has(t.name));
+  }
+  if (filter.includeTools !== undefined) {
+    const include = new Set(filter.includeTools);
+    out = out.filter((t) => include.has(t.name));
+  }
+  if (filter.excludeTools !== undefined) {
+    const exclude = new Set(filter.excludeTools);
+    out = out.filter((t) => !exclude.has(t.name));
+  }
+  return out;
+}
+
+export interface RegisterDirectToolsOptions {
+  serverName: string;
+  /** Tool-name prefix strategy already resolved over the global config */
+  prefix: ToolPrefix;
+  /** Tools to register (raw server tool names, from cache or discovery) */
+  tools: CachedTool[];
+  /**
+   * Whether a needs-auth server auto-triggers interactive OAuth at call time.
+   * Read at CALL time (fresh config), not registration time — mirrors the
+   * proxy call action.
+   */
+  autoAuth?: () => boolean;
+  /** Lazily resolve (and connect, if needed) the owning client at call time */
+  resolveClient: (serverName: string) => Promise<ServerClient>;
+}
+
+/**
+ * Register a server's tools as individual pi tools.
+ * Skips tools whose final prefixed name was already claimed (by this server
+ * in an earlier pass OR by any other server) — the returned list includes
+ * those skipped names, so callers see the full intended set.
+ * Skips tools whose final prefixed name would shadow a pi builtin (e.g. a bare
+ * "read" under toolPrefix "none") — warns instead so the collision is visible.
+ * Warns once per distinct collision when TWO raw tools of this server format
+ * to the same final name (e.g. "a.b" and "a_b") — an inherent, non-injective
+ * ambiguity of the name format, not a bug in registration.
+ * The executor resolves the live client LAZILY at call time via
+ * options.resolveClient — no client is connected at registration time.
+ * After the pass, the server's tracked set is REPLACED by the names claimed
+ * in this pass (evicting stale entries from removed servers / shrunken lists).
+ * Returns the list of (claimed) prefixed tool names so they can be tracked.
+ */
+export function registerDirectTools(
+  pi: ExtensionAPI,
+  options: RegisterDirectToolsOptions,
+): string[] {
+  const { serverName, prefix, tools, resolveClient, autoAuth = () => false } = options;
+  const registered: string[] = [];
+
+  // Surface ambiguous raw tool names: formatToolName is not injective, so
+  // e.g. "a.b" and "a_b" both format to the same final name and name
+  // resolution would be first-match-wins. Warn once per distinct collision.
+  for (const { finalName, rawNames } of findFormattingCollisions(serverName, prefix, tools)) {
+    const key = `${serverName}\u0000${finalName}\u0000${rawNames.join(",")}`;
+    if (warnedCollisions.has(key)) continue;
+    warnedCollisions.add(key);
+    console.warn(
+      `[mcp] server "${serverName}": tools ${rawNames.map((n) => `"${n}"`).join(" and ")} both format to "${finalName}" — name resolution is ambiguous (first match wins)`,
+    );
+  }
+
+  // The names this pass INTENDS to own (non-builtin, formatted). After the
+  // pass, this becomes the server's tracked set — evicting stale entries
+  // from earlier passes.
+  const intendedThisPass = new Set<string>();
+
+  for (const tool of tools) {
+    const prefixedName = formatToolName(tool.name, serverName, prefix);
+
+    // Never shadow a pi builtin tool name (matters mainly for toolPrefix "none")
+    if (BUILTIN_NAMES.has(prefixedName)) {
+      console.warn(
+        `[mcp] skipping tool "${tool.name}" from server "${serverName}": "${prefixedName}" collides with a built-in tool name`,
+      );
+      continue;
+    }
+    intendedThisPass.add(prefixedName);
+
+    // Skip registration if this final prefixed name was already claimed — by
+    // this server in an earlier pass OR by another server (guards against
+    // repeated session_start / probe passes and cross-server collisions)
+    if (isClaimed(prefixedName)) {
+      registered.push(prefixedName);
+      continue;
+    }
+
+    // Accept any object — we let the MCP server validate args against its own schema
+    const parameters = Type.Object({}, { additionalProperties: true });
+
+    pi.registerTool({
+      name: prefixedName,
+      label: `MCP: ${tool.name}`,
+      description: `[${serverName}] ${tool.description ?? "(no description)"}`,
+      parameters,
+
+      renderCall(args: unknown, theme: Theme, context: unknown) {
+        const typedContext = context as RenderContext;
+        return renderDirectCall(
+          prefixedName,
+          args as Record<string, unknown>,
+          theme,
+          typedContext,
+        );
+      },
+
+      renderResult(result: unknown, options: unknown, theme: Theme, context: unknown) {
+        const typedResult = result as {
+          content: Array<{ type: string; text?: string }>;
+          details?: Record<string, unknown>;
+        };
+        const typedOptions = options as { expanded?: boolean; isPartial?: boolean };
+        const typedContext = context as RenderContext;
+        return renderDirectResult(prefixedName, typedResult, typedOptions, theme, typedContext);
+      },
+
+      async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+        const args = params as Record<string, unknown>;
+        // Lazy connect: resolve (and connect, if needed) the owning client NOW,
+        // not at registration time.
+        const client = await resolveClient(serverName);
+        // needs-auth at call time: guidance by default, inline auto-auth +
+        // one retry when enabled (mirrors the proxy call action).
+        if (client.status === "needs-auth") {
+          if (!autoAuth()) {
+            return needsAuthToolResult(serverName);
+          }
+          const outcome = await autoAuthenticate(ctx, client);
+          if (!outcome.proceed) {
+            return needsAuthToolResult(serverName, outcome.error);
+          }
+        }
+        // The call below is the (single) retry after a successful auto-auth
+        const result = await client.callTool(tool.name, args, signal);
+        // Cast MCP ContentBlock[] to pi's (TextContent | ImageContent)[]
+        // Both are discriminated unions on `type`; we only surface text + image blocks
+        const content = result.content as Array<
+          | { type: "text"; text: string }
+          | { type: "image"; data: string; mimeType: string }
+        >;
+        return {
+          content,
+          details: { server: client.name, tool: tool.name },
+          isError: result.isError,
+        };
+      },
+    });
+
+    registered.push(prefixedName);
+  }
+
+  // Replace this server's tracked set with the names intended in this pass,
+  // evicting stale entries from earlier (larger) passes so a later
+  // session_start can re-register shrunken/changed tool lists.
+  registeredNames.set(serverName, intendedThisPass);
+
+  return registered;
+}

package/src/host-configs.test.ts

@@ -0,0 +1,231 @@
+/**
+ * Tests for host-config discovery (`/mcp setup` → "Import from another tool",
+ * plan-027, Task 4).
+ *
+ * HOME is pointed at a temp dir by setting `process.env.HOME` (node's
+ * `os.homedir()` honours it on POSIX) and restored afterwards; the project
+ * `cwd` is a separate temp dir. Every case is JSON-only discovery — no
+ * network, no real HOME, no real project files.
+ *
+ * Coverage:
+ *   - finds a `~/.cursor/mcp.json` config AND a `<cwd>/.vscode/mcp.json`
+ *     config (VSCode's key is top-level `servers`, NOT `mcpServers`) with
+ *     the correct `agent` labels and extracted server records
+ *   - `~/.claude.json` — only the `mcpServers` key is taken, other top-level
+ *     keys (the file is a general Claude state file) are ignored
+ *   - returns [] when no candidate paths exist
+ *   - ignores malformed JSON (no throw) and nonexistent paths
+ *   - tolerates `//` comments via stripJsonComments
+ *   - NEVER returns configs under `<cwd>/.pi/` (pi's own layer — self-import
+ *     loop) or at `~/.config/mcp/mcp.json` (pi's global layer)
+ */
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { discoverHostConfigs } from "./host-configs.js";
+
+let home: string;
+let cwd: string;
+const previousHome = process.env.HOME;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "mcp-hostcfg-home-"));
+  cwd = mkdtempSync(join(tmpdir(), "mcp-hostcfg-cwd-"));
+  process.env.HOME = home;
+});
+
+afterEach(() => {
+  process.env.HOME = previousHome;
+  rmSync(home, { recursive: true, force: true });
+  rmSync(cwd, { recursive: true, force: true });
+});
+
+function writeJson(path: string, content: string): void {
+  mkdirSync(join(path, ".."), { recursive: true });
+  writeFileSync(path, content, "utf-8");
+}
+
+// ── discovery ────────────────────────────────────────────────────────────────
+
+describe("discoverHostConfigs", () => {
+  it("finds a cursor config in HOME and a vscode config in cwd, with labels", () => {
+    writeJson(join(home, ".cursor", "mcp.json"), JSON.stringify({
+      mcpServers: { alpha: { url: "https://alpha.example/mcp" } },
+    }));
+    writeJson(join(cwd, ".vscode", "mcp.json"), JSON.stringify({
+      // VSCode uses the top-level "servers" key (per VSCode docs) — NOT "mcpServers".
+      servers: { beta: { command: "npx", args: ["-y", "beta-mcp"] } },
+    }));
+
+    const found = discoverHostConfigs(cwd);
+
+    expect(found).toHaveLength(2);
+    const [first, second] = found;
+    expect(first).toEqual({
+      agent: "cursor",
+      path: join(home, ".cursor", "mcp.json"),
+      servers: { alpha: { url: "https://alpha.example/mcp" } },
+    });
+    expect(second).toEqual({
+      agent: "vscode",
+      path: join(cwd, ".vscode", "mcp.json"),
+      servers: { beta: { command: "npx", args: ["-y", "beta-mcp"] } },
+    });
+  });
+
+  it("labels project-scoped cursor configs (<cwd>/.cursor/mcp.json) as cursor too", () => {
+    writeJson(join(cwd, ".cursor", "mcp.json"), JSON.stringify({
+      mcpServers: { proj: { command: "uvx", args: ["proj-mcp"] } },
+    }));
+
+    const found = discoverHostConfigs(cwd);
+
+    expect(found).toHaveLength(1);
+    expect(found[0]).toEqual({
+      agent: "cursor",
+      path: join(cwd, ".cursor", "mcp.json"),
+      servers: { proj: { command: "uvx", args: ["proj-mcp"] } },
+    });
+  });
+
+  it("takes only mcpServers from ~/.claude.json (other top-level keys ignored)", () => {
+    writeJson(join(home, ".claude.json"), JSON.stringify({
+      version: 1,
+      userID: "some-user",
+      mcpServers: { gamma: { command: "uvx", args: ["gamma-mcp"] } },
+    }));
+
+    const found = discoverHostConfigs(cwd);
+
+    expect(found).toHaveLength(1);
+    expect(found[0]?.agent).toBe("claude-code");
+    expect(found[0]?.path).toBe(join(home, ".claude.json"));
+    expect(found[0]?.servers).toEqual({ gamma: { command: "uvx", args: ["gamma-mcp"] } });
+  });
+
+  it("labels ~/.claude/mcp.json as claude-code", () => {
+    writeJson(join(home, ".claude", "mcp.json"), JSON.stringify({
+      mcpServers: { delta: { url: "https://delta.example/mcp" } },
+    }));
+
+    const found = discoverHostConfigs(cwd);
+
+    expect(found).toHaveLength(1);
+    expect(found[0]?.agent).toBe("claude-code");
+    expect(found[0]?.path).toBe(join(home, ".claude", "mcp.json"));
+  });
+
+  it("labels ~/.claude/claude_desktop_config.json as claude-desktop", () => {
+    writeJson(join(home, ".claude", "claude_desktop_config.json"), JSON.stringify({
+      mcpServers: { desktop: { command: "npx", args: ["-y", "desktop-mcp"] } },
+    }));
+
+    const found = discoverHostConfigs(cwd);
+
+    expect(found).toHaveLength(1);
+    expect(found[0]?.agent).toBe("claude-desktop");
+    expect(found[0]?.path).toBe(join(home, ".claude", "claude_desktop_config.json"));
+  });
+
+  it("returns results in the documented stable order", () => {
+    writeJson(join(home, ".claude", "claude_desktop_config.json"), JSON.stringify({ mcpServers: { d: { url: "https://d.example" } } }));
+    writeJson(join(cwd, ".vscode", "mcp.json"), JSON.stringify({ servers: { v: { url: "https://v.example" } } }));
+    writeJson(join(home, ".claude", "mcp.json"), JSON.stringify({ mcpServers: { c: { url: "https://c.example" } } }));
+    writeJson(join(home, ".claude.json"), JSON.stringify({ mcpServers: { cc: { url: "https://cc.example" } } }));
+    writeJson(join(cwd, ".cursor", "mcp.json"), JSON.stringify({ mcpServers: { cp: { url: "https://cp.example" } } }));
+    writeJson(join(home, ".cursor", "mcp.json"), JSON.stringify({ mcpServers: { ch: { url: "https://ch.example" } } }));
+
+    const found = discoverHostConfigs(cwd);
+
+    expect(found.map((f) => f.path)).toEqual([
+      join(home, ".cursor", "mcp.json"),       // cursor (home)
+      join(cwd, ".cursor", "mcp.json"),         // cursor (project)
+      join(home, ".claude", "mcp.json"),        // claude-code (dir)
+      join(home, ".claude.json"),               // claude-code (file)
+      join(home, ".claude", "claude_desktop_config.json"), // claude-desktop
+      join(cwd, ".vscode", "mcp.json"),         // vscode (project)
+    ]);
+  });
+});
+
+// ── tolerance ────────────────────────────────────────────────────────────────
+
+describe("tolerance", () => {
+  it("returns [] when nothing exists", () => {
+    expect(discoverHostConfigs(cwd)).toEqual([]);
+  });
+
+  it("ignores nonexistent candidate paths without throwing", () => {
+    mkdirSync(join(home, ".cursor"), { recursive: true }); // empty dir, no mcp.json
+    mkdirSync(join(cwd, ".vscode"), { recursive: true });
+    expect(() => discoverHostConfigs(cwd)).not.toThrow();
+    expect(discoverHostConfigs(cwd)).toEqual([]);
+  });
+
+  it("ignores malformed JSON (no throw) and keeps the valid configs", () => {
+    writeJson(join(home, ".cursor", "mcp.json"), "{ this is not json !!");
+    writeJson(join(cwd, ".vscode", "mcp.json"), JSON.stringify({
+      servers: { beta: { command: "npx", args: ["-y", "beta-mcp"] } },
+    }));
+
+    expect(() => discoverHostConfigs(cwd)).not.toThrow();
+    const found = discoverHostConfigs(cwd);
+    expect(found).toHaveLength(1);
+    expect(found[0]?.agent).toBe("vscode");
+  });
+
+  it("skips a file whose top level is not an object", () => {
+    writeJson(join(home, ".cursor", "mcp.json"), JSON.stringify(["not", "an", "object"]));
+    expect(discoverHostConfigs(cwd)).toEqual([]);
+  });
+
+  it("skips a file whose mcpServers key is not an object", () => {
+    writeJson(join(home, ".cursor", "mcp.json"), JSON.stringify({ mcpServers: "nope" }));
+    writeJson(join(cwd, ".vscode", "mcp.json"), JSON.stringify({ servers: "nope" }));
+    expect(discoverHostConfigs(cwd)).toEqual([]);
+  });
+
+  it("skips non-object server entries but keeps the valid ones", () => {
+    writeJson(join(home, ".cursor", "mcp.json"), JSON.stringify({
+      mcpServers: { good: { url: "https://good.example" }, bad: "scalar" },
+    }));
+    const found = discoverHostConfigs(cwd);
+    expect(found[0]?.servers).toEqual({ good: { url: "https://good.example" } });
+  });
+
+  it("tolerates // comments in host config files", () => {
+    writeJson(join(home, ".cursor", "mcp.json"), [
+      "// cursor project mcp",
+      '{"mcpServers": {"alpha": {"url": "https://alpha.example/mcp"}},}',
+    ].join("\n"));
+
+    const found = discoverHostConfigs(cwd);
+    expect(found[0]?.servers).toEqual({ alpha: { url: "https://alpha.example/mcp" } });
+  });
+});
+
+// ── exclusions ───────────────────────────────────────────────────────────────
+
+describe("exclusions", () => {
+  it("never returns pi-owned layers: <cwd>/.pi/… and ~/.config/mcp/…", () => {
+    writeJson(join(cwd, ".pi", "mcp.json"), JSON.stringify({
+      mcpServers: { piOverride: { url: "https://pi.example" } },
+    }));
+    writeJson(join(home, ".config", "mcp", "mcp.json"), JSON.stringify({
+      mcpServers: { piGlobal: { url: "https://pi-global.example" } },
+    }));
+    writeJson(join(home, ".cursor", "mcp.json"), JSON.stringify({
+      mcpServers: { alpha: { url: "https://alpha.example/mcp" } },
+    }));
+
+    const found = discoverHostConfigs(cwd);
+
+    expect(found).toHaveLength(1);
+    expect(found[0]?.agent).toBe("cursor");
+    for (const f of found) {
+      expect(f.path.startsWith(join(cwd, ".pi"))).toBe(false);
+      expect(f.path === join(home, ".config", "mcp", "mcp.json")).toBe(false);
+    }
+  });
+});

package/src/host-configs.ts

@@ -0,0 +1,106 @@
+/**
+ * Discovery of MCP server definitions owned by OTHER tools, for the
+ * `/mcp setup` → "Import from another tool" flow (plan-027, Task 4).
+ *
+ * JSON-only (Codex/TOML is intentionally deferred). Candidate paths, in the
+ * DOCUMENTED STABLE ORDER returned by `discoverHostConfigs`:
+ *
+ *   1. cursor         ~/.cursor/mcp.json                key `mcpServers`
+ *   2. cursor         <cwd>/.cursor/mcp.json            key `mcpServers`
+ *   3. claude-code    ~/.claude/mcp.json                key `mcpServers`
+ *   4. claude-code    ~/.claude.json                    key `mcpServers`
+ *   5. claude-desktop ~/.claude/claude_desktop_config.json  key `mcpServers`
+ *   6. vscode         <cwd>/.vscode/mcp.json            key `servers`
+ *
+ * Notes:
+ * - `~/.claude.json` is Claude's general state file with many unrelated
+ *   top-level keys — only its `mcpServers` key is ever taken.
+ * - VSCode's `.vscode/mcp.json` uses the top-level key `servers` (per
+ *   VSCode docs), NOT `mcpServers` — do not "fix" this to mcpServers.
+ * - DELIBERATE EXCLUSIONS: `~/.config/mcp/mcp.json` (pi's own global layer)
+ *   and anything under `<cwd>/.pi/` (pi's own override layer) are never
+ *   candidate paths — importing from them would be a self-import loop. The
+ *   candidate list below is the single source of truth, so exclusions are
+ *   inherent; the test suite asserts them anyway.
+ * - Never throws: files that don't exist, don't parse, or have the wrong
+ *   shape are skipped silently (they surface as "not found" in the panel).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, sep } from "node:path";
+import { stripJsonComments } from "./config.js";
+import type { ServerDef } from "./types.js";
+
+export type HostAgent = "cursor" | "claude-code" | "claude-desktop" | "vscode";
+
+export interface HostConfig {
+  agent: HostAgent;
+  path: string;
+  servers: Record<string, ServerDef>;
+}
+
+interface Candidate {
+  agent: HostAgent;
+  /** The top-level JSON key holding the server definitions for this host. */
+  key: string;
+  pathFor: (home: string, cwd: string) => string;
+}
+
+/** The candidate list — also the documented stable order of the results. */
+const CANDIDATES: Candidate[] = [
+  { agent: "cursor", key: "mcpServers", pathFor: (home) => join(home, ".cursor", "mcp.json") },
+  { agent: "cursor", key: "mcpServers", pathFor: (_home, cwd) => join(cwd, ".cursor", "mcp.json") },
+  { agent: "claude-code", key: "mcpServers", pathFor: (home) => join(home, ".claude", "mcp.json") },
+  { agent: "claude-code", key: "mcpServers", pathFor: (home) => join(home, ".claude.json") },
+  { agent: "claude-desktop", key: "mcpServers", pathFor: (home) => join(home, ".claude", "claude_desktop_config.json") },
+  { agent: "vscode", key: "servers", pathFor: (_home, cwd) => join(cwd, ".vscode", "mcp.json") },
+];
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Parse one candidate file into a server record, or null when the file is
+ * missing, unparseable, or has the wrong shape (never throws). Server
+ * entries that are not objects are dropped; the file still counts as found
+ * when its key is a valid object.
+ */
+function readHostServers(path: string, key: string): Record<string, ServerDef> | null {
+  if (!existsSync(path)) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stripJsonComments(readFileSync(path, "utf-8")));
+  } catch {
+    return null; // malformed JSON — skip silently
+  }
+  if (!isPlainObject(parsed)) return null;
+  const bucket = parsed[key];
+  if (!isPlainObject(bucket)) return null;
+  const servers: Record<string, ServerDef> = {};
+  for (const [name, def] of Object.entries(bucket)) {
+    if (isPlainObject(def)) servers[name] = def as unknown as ServerDef;
+  }
+  return servers;
+}
+
+/**
+ * Discover MCP configs owned by other tools. `cwd` is the project root
+ * (supplies the project-scoped candidates); `~` comes from `os.homedir()`
+ * at call time. Returns found configs in the documented candidate order;
+ * empty when nothing is found.
+ */
+export function discoverHostConfigs(cwd: string): HostConfig[] {
+  const home = homedir();
+  const found: HostConfig[] = [];
+  for (const candidate of CANDIDATES) {
+    const path = candidate.pathFor(home, cwd);
+    // Hard guarantee for the documented exclusions even if the candidate
+    // list ever drifts: never return pi's own layers.
+    if (path.startsWith(join(cwd, ".pi") + sep)) continue;
+    if (path === join(home, ".config", "mcp", "mcp.json")) continue;
+    const servers = readHostServers(path, candidate.key);
+    if (servers !== null) found.push({ agent: candidate.agent, path, servers });
+  }
+  return found;
+}