@piagent/platform 1.1.8 → 1.2.0

package/packages/piagent-core/mcp/mcp-auth-readiness.js

@@ -0,0 +1,197 @@
+import fs from "node:fs";
+import path from "node:path";
+import { REPOSITORY_SCOPES } from "./mcp-config-layers.js";
+import { approvalState } from "./mcp-approval-store.js";
+import { CATALOG_OPTIONAL_ENV } from "./mcp-server-catalog.js";
+
+// Whether a configured server can actually be used, answered from state this
+// process already has. No network, no child process: this runs at session start,
+// and a check that costs a round trip would be paid on every session for
+// information that changes when somebody edits a config.
+//
+// The line it will not cross is guessing. Two things are knowable here — an
+// environment variable a config references is set or it is not, an executable is
+// on PATH or it is not — and those are reported. Whether an OAuth sign-in is
+// still valid is known to Pi and not to this file, so it is reported as
+// "sign-in is handled elsewhere" rather than as a failure that may not be one.
+
+const ENV_REFERENCE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+/**
+ * @typedef {"disabled"|"rejected"|"approval-changed"|"pending-approval"|"needs-command"|"needs-env"|"oauth"|"ready"} ReadinessState
+ */
+
+/**
+ * States that mean the server will not answer a tool call. `oauth` is not one of
+ * them: it may well be signed in already.
+ * @type {Set<ReadinessState>}
+ */
+export const BLOCKING_STATES = new Set([
+  "disabled", "rejected", "approval-changed", "pending-approval", "needs-command", "needs-env"
+]);
+
+/**
+ * Every `${VAR}` a server entry references, wherever it appears.
+ * @param {unknown} entry
+ * @returns {string[]}
+ */
+export function referencedEnvVars(entry) {
+  const names = new Set();
+  walk(entry, (text) => {
+    for (const match of text.matchAll(ENV_REFERENCE)) names.add(match[1]);
+  });
+  return [...names].sort();
+}
+
+/** @param {unknown} value @param {(text: string) => void} visit @returns {void} */
+function walk(value, visit) {
+  if (typeof value === "string") {
+    visit(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) walk(item, visit);
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const item of Object.values(value)) walk(item, visit);
+  }
+}
+
+/**
+ * @param {string} command
+ * @param {{env?: Record<string, string|undefined>}} [options]
+ * @returns {boolean}
+ */
+export function commandOnPath(command, options = {}) {
+  const env = options.env ?? process.env;
+  if (typeof command !== "string" || command.length === 0) return false;
+  // An explicit path is checked where it points rather than searched for.
+  if (command.includes(path.sep)) return isExecutable(command);
+  for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+    if (!directory) continue;
+    if (isExecutable(path.join(directory, command))) return true;
+  }
+  return false;
+}
+
+/** @param {string} file @returns {boolean} */
+function isExecutable(file) {
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @typedef {object} ServerReadiness
+ * @property {string} name
+ * @property {string} scope
+ * @property {ReadinessState} state
+ * @property {string} detail human-readable, never contains a value
+ * @property {string} [remedy] the command that resolves it
+ * @property {string[]} missingEnv
+ */
+
+/**
+ * @param {{name: string, scope: string, entry: Record<string, unknown>}} server
+ * @param {{projectPath: string, env?: Record<string, string|undefined>, home?: string, store?: Record<string, unknown>}} options
+ * @returns {ServerReadiness}
+ */
+export function evaluateServerReadiness(server, options) {
+  const env = options.env ?? process.env;
+  const base = { name: server.name, scope: server.scope, missingEnv: /** @type {string[]} */ ([]) };
+
+  if (server.entry.enabled === false) {
+    return { ...base, state: "disabled", detail: "disabled in config", remedy: `piagent-mcp enable ${server.name} --scope ${server.scope}` };
+  }
+
+  if (REPOSITORY_SCOPES.has(server.scope)) {
+    const approval = approvalState({
+      projectPath: options.projectPath,
+      name: server.name,
+      entry: server.entry,
+      store: options.store,
+      home: options.home
+    });
+    if (approval.state === "rejected") {
+      return { ...base, state: "rejected", detail: "rejected for this project", remedy: `piagent-mcp approve ${server.name}` };
+    }
+    if (approval.state === "changed") {
+      return {
+        ...base,
+        state: "approval-changed",
+        detail: "definition changed since it was approved",
+        remedy: `piagent-mcp get ${server.name} then piagent-mcp approve ${server.name}`
+      };
+    }
+    if (approval.state === "pending") {
+      return {
+        ...base,
+        state: "pending-approval",
+        detail: `defined by this repository in ${server.scope} scope and not approved here`,
+        remedy: `piagent-mcp approve ${server.name}`
+      };
+    }
+  }
+
+  if (typeof server.entry.command === "string" && !commandOnPath(server.entry.command, { env })) {
+    return {
+      ...base,
+      state: "needs-command",
+      detail: `${server.entry.command} is not on PATH`,
+      remedy: `install ${server.entry.command}, or edit the server with piagent-mcp add ${server.name} --scope ${server.scope} -- <command>`
+    };
+  }
+
+  const optional = new Set(CATALOG_OPTIONAL_ENV[server.name] ?? []);
+  const missingEnv = referencedEnvVars(server.entry)
+    .filter((name) => !optional.has(name))
+    .filter((name) => !env[name]?.trim());
+  if (missingEnv.length > 0) {
+    return {
+      ...base,
+      missingEnv,
+      state: "needs-env",
+      detail: `${missingEnv.join(", ")} ${missingEnv.length === 1 ? "is" : "are"} referenced but not set`,
+      remedy: `export ${missingEnv[0]}=... in your shell profile`
+    };
+  }
+
+  if (server.entry.auth === "oauth") {
+    return {
+      ...base,
+      state: "oauth",
+      detail: "signs in with OAuth; Pi holds the session",
+      remedy: `/mcp-auth ${server.name} inside Pi if it is not signed in`
+    };
+  }
+
+  return { ...base, state: "ready", detail: "ready" };
+}
+
+/**
+ * One line for the session start, or nothing when every server is usable.
+ *
+ * Only definite problems are named. A server waiting on OAuth is left out
+ * because this process cannot tell a signed-in one from a signed-out one, and a
+ * notice that appears every session regardless of state stops being read.
+ *
+ * @param {ServerReadiness[]} readiness
+ * @returns {string|undefined}
+ */
+export function readinessNotice(readiness) {
+  const blocked = readiness.filter((item) => BLOCKING_STATES.has(item.state));
+  if (blocked.length === 0) return undefined;
+  const waiting = blocked.filter((item) => item.state === "pending-approval" || item.state === "approval-changed");
+  const parts = blocked.slice(0, 4).map((item) => `${item.name} (${item.detail})`);
+  const overflow = blocked.length > parts.length ? `, and ${blocked.length - parts.length} more` : "";
+  const lead = waiting.length > 0
+    ? "MCP servers need a decision or setup"
+    : "MCP servers are configured but cannot connect";
+  // This line is only ever printed at session start, so it names the command
+  // that answers it from there rather than sending the reader to a shell.
+  return `${lead}: ${parts.join("; ")}${overflow}. Run \`/piagent-mcp doctor\` for what each one needs.`;
+}

package/packages/piagent-core/mcp/mcp-command-actions.js

@@ -0,0 +1,291 @@
+import { REPOSITORY_SCOPES, collectServers, isRecord, readMcpConfig, writeMcpConfig } from "./mcp-config-layers.js";
+import { approvalState, clearApproval, recordApproval } from "./mcp-approval-store.js";
+import { maskServerEntry } from "./mcp-server-entry.js";
+import {
+  McpViewError,
+  blockedRows,
+  collectServerRows,
+  describeServer,
+  formatDoctorReport,
+  formatServerDetail,
+  formatServerTable
+} from "./mcp-session-view.js";
+
+// What `/piagent-mcp` does, separated from how a session shows it.
+//
+// Each action takes plain options and returns a report: a one-line notice, the
+// lines to display, and the structured detail behind them. Nothing here knows
+// about `pi`, a UI, or a terminal, so the menu path and the typed-subcommand
+// path cannot drift into doing different things — they call the same function.
+
+export { McpViewError };
+
+/** Actions that only read. The rest write a config file or an approval. */
+export const READ_ACTIONS = new Set(["status", "get", "doctor"]);
+
+/** Actions that name a single server. `reset` accepts one but does not need it. */
+export const SERVER_ACTIONS = new Set(["get", "approve", "reject", "reset", "enable", "disable"]);
+
+/** Writes that belong in a shell, with the command to run there. */
+export const TERMINAL_ONLY = new Map([
+  ["add", "piagent-mcp add <name> [--scope <scope>] --url <url> | -- <command> [args...]"],
+  ["remove", "piagent-mcp remove <name> --scope <scope>"],
+  ["preset", "piagent-mcp --preset <core|popular|design> --scope <scope>"]
+]);
+
+export const HELP_LINES = [
+  "/piagent-mcp                    open the menu",
+  "/piagent-mcp status             every configured server, with scope and readiness",
+  "/piagent-mcp get <name>         one server in detail, credential values masked",
+  "/piagent-mcp doctor             what each server still needs before it can answer",
+  "/piagent-mcp approve <name>     allow a server this repository defines",
+  "/piagent-mcp reject <name>      refuse it",
+  "/piagent-mcp reset [name]       forget the decision, or every decision",
+  "/piagent-mcp enable|disable <name>",
+  "",
+  "Adding, removing and presets are terminal commands: run `piagent-mcp --help`.",
+  "Live connection state and OAuth sign-in belong to the adapter: /mcp and /mcp-auth."
+];
+
+/**
+ * The menu, built from what this project actually has.
+ *
+ * An entry is offered only when it would do something: approving is not offered
+ * when no server here needs a decision, and a menu that lists impossible actions
+ * teaches the reader to stop reading it. Counts go in the labels so the menu
+ * answers part of the question before anything is picked.
+ *
+ * @param {{projectPath: string}} options
+ */
+export function menuOptions(options) {
+  const rows = collectServerRows({ projectPath: options.projectPath });
+  const stuck = blockedRows(rows);
+  const repositoryRows = rows.filter((row) => REPOSITORY_SCOPES.has(row.scope));
+  const decisions = repositoryRows.map((row) => ({
+    row,
+    state: approvalState({ projectPath: options.projectPath, name: row.name, entry: row.entry }).state
+  }));
+  const undecided = decisions.filter((item) => item.state !== "approved");
+  const decided = decisions.filter((item) => item.state !== "pending");
+  const disabled = rows.filter((row) => row.readiness.state === "disabled");
+  const enabled = rows.filter((row) => row.readiness.state !== "disabled");
+
+  const entries = [
+    {
+      value: "status",
+      label: rows.length === 0 ? "Servers — none configured" : `Servers — ${rows.length - stuck.length}/${rows.length} ready`,
+      description: "Every server visible from this project, with its scope and state"
+    }
+  ];
+  if (stuck.length > 0) {
+    entries.push({
+      value: "doctor",
+      label: `Doctor — ${stuck.length} need attention`,
+      description: "What each blocked server still needs",
+      recommended: true
+    });
+  } else if (rows.length > 0) {
+    entries.push({ value: "doctor", label: "Doctor — all reachable", description: "Re-check what each server needs" });
+  }
+  if (rows.length > 0) {
+    entries.push({ value: "get", label: "Inspect a server", description: "Full definition, credential values masked" });
+  }
+  if (undecided.length > 0) {
+    entries.push({
+      value: "approve",
+      label: `Approve a repository server — ${undecided.length} waiting`,
+      description: "This repository defines it; nobody on this machine has allowed it yet",
+      recommended: stuck.length === 0
+    });
+    entries.push({ value: "reject", label: "Reject a repository server", description: "Refuse it for this project" });
+  } else if (repositoryRows.length > 0) {
+    entries.push({ value: "reject", label: "Reject a repository server", description: "Withdraw a server this project had allowed" });
+  }
+  if (decided.length > 0) {
+    entries.push({ value: "reset", label: "Forget a decision", description: "Return a server to pending so it is asked again" });
+  }
+  if (enabled.length > 0) {
+    entries.push({ value: "disable", label: "Turn a server off", description: "Stop using it without losing its definition" });
+  }
+  if (disabled.length > 0) {
+    entries.push({ value: "enable", label: `Turn a server back on — ${disabled.length} off`, description: "Restore a disabled server" });
+  }
+  entries.push({ value: "add", label: "Add a server", description: "Shows the terminal command; writing config is not a slash command" });
+  entries.push({ value: "help", label: "All subcommands", description: "Everything /piagent-mcp accepts" });
+  return { entries, rows };
+}
+
+/**
+ * Servers an action can be applied to. Approving a server the repository does
+ * not define is not a thing, so it is not offered.
+ *
+ * @param {{projectPath: string, action: string}} options
+ */
+export function serverChoices(options) {
+  const { projectPath, action } = options;
+  const rows = collectServerRows({ projectPath });
+  const filtered = rows.filter((row) => {
+    if (action === "approve" || action === "reject" || action === "reset") return REPOSITORY_SCOPES.has(row.scope);
+    if (action === "enable") return row.readiness.state === "disabled";
+    if (action === "disable") return row.readiness.state !== "disabled";
+    return true;
+  });
+  return filtered.map((row) => ({
+    value: row.name,
+    label: `${row.name} (${row.scope})`,
+    description: row.readiness.detail
+  }));
+}
+
+/** @param {{projectPath: string, scope?: string}} options */
+export function status(options) {
+  const rows = collectServerRows({ projectPath: options.projectPath, scopes: options.scope ? [options.scope] : undefined });
+  const stuck = blockedRows(rows);
+  return {
+    notify: {
+      message: rows.length === 0 ? "MCP: no servers configured" : `MCP: ${rows.length - stuck.length}/${rows.length} ready`,
+      level: stuck.length > 0 ? "warning" : "info"
+    },
+    lines: rows.length === 0
+      ? ["No MCP servers configured.", "Seed the pinned baseline in a terminal: piagent-mcp --preset core --scope global"]
+      : [formatServerTable(rows), ...(stuck.length > 0 ? ["", `${stuck.length} not usable yet. Run /piagent-mcp doctor.`] : [])],
+    details: {
+      project: options.projectPath,
+      servers: rows.map((row) => ({ name: row.name, scope: row.scope, state: row.readiness.state, detail: row.readiness.detail }))
+    }
+  };
+}
+
+/** @param {{projectPath: string, name: string, scope?: string}} options */
+export function detail(options) {
+  const found = describeServer({
+    projectPath: options.projectPath,
+    name: options.name,
+    scope: options.scope,
+    listHint: "/piagent-mcp",
+    scopeHint: "--scope"
+  });
+  return {
+    notify: { message: `MCP ${options.name}: ${found.readiness.state}`, level: "info" },
+    lines: formatServerDetail(found, { inSession: true }),
+    details: { name: options.name, scope: found.scope, file: found.file, state: found.readiness.state, entry: found.masked }
+  };
+}
+
+/**
+ * The Docker daemon probe is deliberately absent: it spawns a process, and this
+ * runs inside the session's own turn. `piagent-mcp doctor` in a terminal does it.
+ *
+ * @param {{projectPath: string}} options
+ */
+export function doctor(options) {
+  const rows = collectServerRows({ projectPath: options.projectPath });
+  const report = formatDoctorReport(rows, { rerun: "/piagent-mcp doctor", inSession: true });
+  return {
+    notify: {
+      message: report.problems === 0 ? "MCP: every server can be reached" : `MCP: ${report.problems} need attention`,
+      level: report.problems === 0 ? "info" : "warning"
+    },
+    lines: [
+      ...report.lines,
+      ...(report.problems === 0 ? [] : ["", "The Docker daemon check is terminal-only: piagent-mcp doctor"])
+    ],
+    details: { project: options.projectPath, problems: report.problems }
+  };
+}
+
+/** @param {{projectPath: string, name: string, decision: "approved"|"rejected"}} options */
+export function decide(options) {
+  const { projectPath, name, decision } = options;
+  const matches = collectServers({ projectPath, scopes: [...REPOSITORY_SCOPES] }).filter((server) => server.name === name);
+  if (matches.length === 0) {
+    throw new McpViewError(
+      `${name} is not defined by this repository. Approval only applies to servers in ${[...REPOSITORY_SCOPES].join(" or ")} scope.`
+    );
+  }
+  if (matches.length > 1) {
+    throw new McpViewError(`${name} is defined in ${matches.map((server) => server.scope).join(" and ")}; remove one.`);
+  }
+
+  const server = matches[0];
+  const before = approvalState({ projectPath, name, entry: server.entry });
+  // Approving without reading it is the failure this gate exists to prevent, so
+  // the definition is put in front of the operator alongside the decision.
+  const preview = decision === "approved" && before.state !== "approved"
+    ? [JSON.stringify(maskServerEntry(server.entry), null, 2), ""]
+    : [];
+  recordApproval({ projectPath, name, entry: server.entry, decision });
+  const after = approvalState({ projectPath, name, entry: server.entry });
+  return {
+    notify: { message: `MCP ${name}: ${decision}`, level: "info" },
+    lines: [
+      ...preview,
+      `${decision === "approved" ? "Approved" : "Rejected"} MCP server ${name} (${server.scope}) for ${projectPath}`,
+      `Pinned to this definition: ${after.digest}`,
+      "Changing the server's command, URL or arguments returns it to pending."
+    ],
+    details: { name, scope: server.scope, decision, digest: after.digest, previous: before.state }
+  };
+}
+
+/** @param {{projectPath: string, name?: string}} options */
+export function reset(options) {
+  const { projectPath, name } = options;
+  clearApproval({ projectPath, name });
+  return {
+    notify: { message: name ? `MCP ${name}: decision forgotten` : "MCP: all decisions forgotten", level: "info" },
+    lines: [name
+      ? `Forgot the decision for ${name} in ${projectPath}`
+      : `Forgot every MCP approval decision for ${projectPath}`],
+    details: { name: name ?? null, decision: "reset" }
+  };
+}
+
+/** @param {{projectPath: string, name: string, scope?: string, enabled: boolean}} options */
+export function toggle(options) {
+  const { projectPath, name, scope, enabled } = options;
+  const found = describeServer({ projectPath, name, scope, listHint: "/piagent-mcp", scopeHint: "--scope" });
+  const config = readMcpConfig(found.file);
+  const entry = { ...(isRecord(config.mcpServers[name]) ? config.mcpServers[name] : {}) };
+  if (enabled) delete entry.enabled;
+  else entry.enabled = false;
+  config.mcpServers[name] = entry;
+  writeMcpConfig(found.file, config);
+  return {
+    notify: { message: `MCP ${name}: ${enabled ? "enabled" : "disabled"}`, level: "info" },
+    lines: [
+      `${enabled ? "Enabled" : "Disabled"} MCP server ${name} in ${found.scope} scope`,
+      `File modified: ${found.file}`,
+      ...(enabled ? [] : ["The definition is kept, so /piagent-mcp enable restores it."]),
+      "The adapter reads this at startup: run /reload for it to take effect in this session."
+    ],
+    details: { name, scope: found.scope, file: found.file, enabled }
+  };
+}
+
+/** @param {string} action */
+export function terminalOnly(action) {
+  const command = TERMINAL_ONLY.get(action);
+  if (!command) return undefined;
+  return {
+    notify: { message: `MCP: ${action} is a terminal command`, level: "warning" },
+    // Why this line sits where it does belongs in the docs. What an operator
+    // needs here is the command to run and the reason it is not this one.
+    lines: [
+      `${action} writes a server definition, so it stays in the terminal:`,
+      `  ${command}`,
+      "",
+      "Shell quoting, ${VAR} references and a `--` command line are a shell's job.",
+      "Re-reading them here would be a second, worse parser."
+    ],
+    details: { action, command }
+  };
+}
+
+export function help() {
+  return {
+    notify: { message: "MCP: subcommands", level: "info" },
+    lines: HELP_LINES,
+    details: { actions: [...READ_ACTIONS, ...SERVER_ACTIONS] }
+  };
+}

package/packages/piagent-core/mcp/mcp-config-layers.js

@@ -0,0 +1,133 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// Four files can define MCP servers, and which one a change belongs in is the
+// first thing anyone gets wrong. The scope names are the vocabulary the CLI
+// exposes, so they are resolved in exactly one place.
+//
+// `global` and `pi-project` are the two that matter for safety. `global` is
+// outside every repository, so nothing a repository contains can reach it.
+// `project` is the file a repository can carry, which is why servers found there
+// are the ones the approval gate covers.
+
+const BASELINE_SETTINGS = {
+  toolPrefix: "server",
+  directTools: false,
+  idleTimeout: 10,
+  outputGuard: true
+};
+
+export const SCOPES = ["global", "pi-global", "project", "pi-project"];
+
+/** Scopes whose file a repository can carry, and which therefore need approval. */
+export const REPOSITORY_SCOPES = new Set(["project", "pi-project"]);
+
+/**
+ * @param {string} scope
+ * @param {{projectPath?: string, env?: Record<string, string|undefined>, home?: string}} [options]
+ * @returns {string}
+ */
+export function configPathForScope(scope, options = {}) {
+  const env = options.env ?? process.env;
+  const home = options.home ?? env.HOME ?? "";
+  const projectPath = options.projectPath ?? process.cwd();
+  switch (scope) {
+    case "global":
+      return path.join(env.XDG_CONFIG_HOME || path.join(home, ".config"), "mcp", "mcp.json");
+    case "pi-global":
+      return path.join(env.PI_CODING_AGENT_DIR || path.join(home, ".pi", "agent"), "mcp.json");
+    case "project":
+      return path.join(projectPath, ".mcp.json");
+    case "pi-project":
+      return path.join(projectPath, ".pi", "mcp.json");
+    default:
+      throw new McpConfigError(`unsupported scope: ${scope}`);
+  }
+}
+
+export class McpConfigError extends Error {}
+
+/**
+ * Read a config file into the shape the rest of this module assumes. A file that
+ * is missing reads as empty; a file that is present but malformed throws, because
+ * silently treating it as empty would let a write drop servers somebody
+ * configured by hand.
+ * @param {string} file
+ * @returns {{settings: Record<string, unknown>, mcpServers: Record<string, unknown>, rest: Record<string, unknown>}}
+ */
+export function readMcpConfig(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return { settings: {}, mcpServers: {}, rest: {} };
+    }
+    throw new McpConfigError(`cannot read MCP config: ${file}`);
+  }
+  let document;
+  try {
+    document = JSON.parse(raw);
+  } catch (error) {
+    throw new McpConfigError(`cannot parse MCP config: ${file}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!isRecord(document)) return { settings: {}, mcpServers: {}, rest: {} };
+  const { settings, mcpServers, ...rest } = document;
+  return {
+    settings: isRecord(settings) ? settings : {},
+    mcpServers: isRecord(mcpServers) ? mcpServers : {},
+    rest
+  };
+}
+
+/**
+ * @param {string} file
+ * @param {{settings: Record<string, unknown>, mcpServers: Record<string, unknown>, rest?: Record<string, unknown>}} config
+ * @returns {void}
+ */
+export function writeMcpConfig(file, config) {
+  const document = {
+    ...(config.rest ?? {}),
+    settings: { ...BASELINE_SETTINGS, ...config.settings },
+    mcpServers: config.mcpServers
+  };
+  const output = `${JSON.stringify(document, null, 2)}\n`;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  // Written beside the target and renamed, so a crash mid-write leaves the old
+  // config rather than a truncated one that would read as "no servers".
+  const temporary = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, output);
+  fs.renameSync(temporary, file);
+}
+
+/**
+ * Every server visible from a project, with the scope each came from. Later
+ * scopes do not merge into earlier ones: a name defined twice is reported twice,
+ * because which definition a client picks is the client's rule, not ours, and
+ * hiding the duplicate is how a project-scoped override goes unnoticed.
+ * @param {{projectPath?: string, env?: Record<string, string|undefined>, home?: string, scopes?: string[]}} [options]
+ * @returns {{name: string, scope: string, file: string, entry: Record<string, unknown>}[]}
+ */
+export function collectServers(options = {}) {
+  const found = [];
+  for (const scope of options.scopes ?? SCOPES) {
+    const file = configPathForScope(scope, options);
+    let config;
+    try {
+      config = readMcpConfig(file);
+    } catch {
+      // A layer this process cannot parse is reported as empty rather than
+      // failing the whole listing; `piagent-mcp get` on that scope still throws.
+      continue;
+    }
+    for (const [name, entry] of Object.entries(config.mcpServers)) {
+      if (isRecord(entry)) found.push({ name, scope, file, entry });
+    }
+  }
+  return found;
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+export function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}