@piagent/platform 1.2.0 → 1.2.2

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

@@ -1,5 +1,14 @@
 import fs from "node:fs";
 import path from "node:path";
+import {
+  REPOSITORY_RELATIVE_KINDS,
+  canEnumerateImportKind,
+  declaredImports,
+  importKindFiles,
+  importedServers,
+  unreadableImportTargets
+} from "./mcp-import-kinds.js";
+import { erasesToolOrigin } from "./mcp-tool-naming.js";
 
 // 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
@@ -61,7 +70,7 @@ export function readMcpConfig(file) {
     raw = fs.readFileSync(file, "utf8");
   } catch (error) {
     if (error && typeof error === "object" && error.code === "ENOENT") {
-      return { settings: {}, mcpServers: {}, rest: {} };
+      return { settings: {}, mcpServers: {}, imports: [], rawImports: [], rest: {} };
     }
     throw new McpConfigError(`cannot read MCP config: ${file}`);
   }
@@ -71,11 +80,24 @@ export function readMcpConfig(file) {
   } 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;
+  // A JSON array, string or number parses fine and is not a config. Reading it
+  // as empty meant a later write replaced somebody's file with `{}` plus whatever
+  // the write added, so the document that could not be understood was destroyed
+  // rather than reported.
+  if (!isRecord(document)) {
+    throw new McpConfigError(`MCP config is not a JSON object: ${file}`);
+  }
+  const { settings, mcpServers, imports, ...rest } = document;
   return {
     settings: isRecord(settings) ? settings : {},
     mcpServers: isRecord(mcpServers) ? mcpServers : {},
+    // Pulled out of `rest` deliberately. While it rode along in the spread it
+    // was preserved by every write and read by nothing here, which is the exact
+    // shape of a key that decides what loads without anything checking it.
+    imports: declaredImports(imports),
+    // The list exactly as written, so a write can put back kinds this version
+    // does not recognise. Nothing reads this to decide behaviour.
+    rawImports: Array.isArray(imports) ? imports.filter((kind) => typeof kind === "string") : [],
     rest
   };
 }
@@ -86,13 +108,35 @@ export function readMcpConfig(file) {
  * @returns {void}
  */
 export function writeMcpConfig(file, config) {
+  // `declaredImports` keeps only the kinds this version knows. Writing that back
+  // deleted any kind a newer adapter understands and this one does not, turning
+  // an unrelated `add` into a silent downgrade of somebody's config. The raw list
+  // is preserved and the known kinds are what the rest of this module reads.
+  const raw = Array.isArray(config.rawImports) ? config.rawImports : declaredImports(config.imports);
   const document = {
     ...(config.rest ?? {}),
+    // Written back rather than dropped. This key is refused at the gate when a
+    // repository carries it, and deleting a line out of somebody's own config
+    // as a side effect of an unrelated `add` is not a fix.
+    ...(raw.length > 0 ? { imports: raw } : {}),
     settings: { ...BASELINE_SETTINGS, ...config.settings },
     mcpServers: config.mcpServers
   };
   const output = `${JSON.stringify(document, null, 2)}\n`;
   fs.mkdirSync(path.dirname(file), { recursive: true });
+  // A symlink here points the write somewhere the caller did not name. Renaming
+  // over it replaces the link itself, so the file the operator has been editing
+  // stops being the file this reads -- and following it would write through a
+  // link a repository could have planted.
+  let existing;
+  try {
+    existing = fs.lstatSync(file);
+  } catch (error) {
+    if (!error || typeof error !== "object" || error.code !== "ENOENT") throw error;
+  }
+  if (existing?.isSymbolicLink()) {
+    throw new McpConfigError(`refusing to write through a symlink: ${file}`);
+  }
   // 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`;
@@ -106,10 +150,30 @@ export function writeMcpConfig(file, config) {
  * 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>}[]}
+ * `origin` is the scope name for a server the layer declares directly, and
+ * `import:<kind>` for one reached through an `imports` key, so a caller can say
+ * where a server came from rather than only which layer named it.
+ *
+ * `requiresApproval` says whether this server is one a repository put into the
+ * session. Scope alone cannot answer that: a `global` config importing a
+ * repository-relative kind carries a scope of `global` and a definition that
+ * came out of the clone. Deciding it here keeps the gate and the listing on one
+ * rule — the listing reporting `ready` for a server the gate is blocking is
+ * worse than either answer alone, because it sends the operator looking
+ * anywhere but at the approval.
+ *
+ * @returns {{name: string, scope: string, file: string, entry: Record<string, unknown>, origin: string, requiresApproval: boolean}[]}
  */
 export function collectServers(options = {}) {
   const found = [];
+  const seen = new Set();
+  const push = (server) => {
+    const key = `${server.name}\u0000${server.file}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    found.push(server);
+  };
+
   for (const scope of options.scopes ?? SCOPES) {
     const file = configPathForScope(scope, options);
     let config;
@@ -117,16 +181,285 @@ export function collectServers(options = {}) {
       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.
+      // failing the whole listing; `piagent-mcp get` on that scope still throws
+      // and `piagent-mcp doctor` reports it as unreadable.
       continue;
     }
     for (const [name, entry] of Object.entries(config.mcpServers)) {
-      if (isRecord(entry)) found.push({ name, scope, file, entry });
+      if (isRecord(entry)) push({ name, scope, file, entry, origin: scope, requiresApproval: REPOSITORY_SCOPES.has(scope) });
+    }
+  }
+
+  // Imports of a repository-relative kind are scanned across every layer, not
+  // just the ones the caller asked for. Which file declares the import decides
+  // nothing: what makes the servers repository-scoped is that the file they are
+  // read from travels with the clone. A `global` config importing `vscode`
+  // therefore puts a repository's servers into every session on this machine,
+  // and that has to reach the gate the same way `.mcp.json` does.
+  //
+  // The other direction matters too: whichever kind a repository-scoped config
+  // names, the repository is choosing which servers a session runs. Those are
+  // the operator's own definitions, so the question is not whether to trust the
+  // command but whether this project was meant to start it — which is the same
+  // question the gate already asks.
+  if (options.includeRepositoryImports !== false) {
+    for (const scope of SCOPES) {
+      let config;
+      try {
+        config = readMcpConfig(configPathForScope(scope, options));
+      } catch {
+        continue;
+      }
+      const repositoryScoped = REPOSITORY_SCOPES.has(scope);
+      for (const kind of config.imports) {
+        if (!repositoryScoped && !REPOSITORY_RELATIVE_KINDS.has(kind)) continue;
+        for (const server of importedServers(kind, options)) {
+          // Both branches that reach here are the repository choosing a
+          // server: it either declared the import itself, or the file being
+          // read travels with the clone.
+          push({ name: server.name, scope, file: server.file, entry: server.entry, origin: `import:${kind}`, requiresApproval: true });
+        }
+      }
     }
   }
+
   return found;
 }
 
+/**
+ * The definition a same-named server actually runs under.
+ *
+ * The adapter merges server maps key by key in scope order, so a later layer
+ * that names an existing server overrides only the keys it sets. A repository
+ * declaring `{"args": ["--evil"]}` therefore inherits `command` from the
+ * operator's own global config, and reading that layer alone shows an argument
+ * list with no command attached — which is not what will run, and not what an
+ * operator should be asked to consent to.
+ *
+ * The digest deliberately stays over the repository's own fragment: that is the
+ * part the repository controls, and hashing the merge would return a server to
+ * pending every time the operator edited their own global config.
+ *
+ * @param {{projectPath?: string, name: string, entry?: Record<string, unknown>, env?: Record<string, string|undefined>, home?: string}} options
+ * @returns {Record<string, unknown>}
+ */
+export function mergedServerEntry(options) {
+  let merged = {};
+  let seen = false;
+  for (const scope of SCOPES) {
+    let config;
+    try {
+      config = readMcpConfig(configPathForScope(scope, options));
+    } catch {
+      continue;
+    }
+    const entry = config.mcpServers[options.name];
+    if (!isRecord(entry)) continue;
+    merged = { ...merged, ...entry };
+    seen = true;
+  }
+  // A server reached through `imports` is in no layer's `mcpServers`, so the
+  // entry the caller already has is the whole definition.
+  return seen ? merged : { ...(options.entry ?? {}) };
+}
+
+/**
+ * Layers that exist but cannot be read. `collectServers` skips these so one bad
+ * file does not take out the whole listing, which is the right call for a
+ * listing and the wrong one for a diagnosis: a config nothing can parse
+ * contributes no servers and is indistinguishable from a config that defines
+ * none. Somewhere has to say which of the two it was.
+ *
+ * @param {{projectPath?: string, env?: Record<string, string|undefined>, home?: string, scopes?: string[]}} [options]
+ * @returns {{scope: string, file: string, detail: string}[]}
+ */
+export function unreadableLayers(options = {}) {
+  const problems = [];
+  for (const scope of options.scopes ?? SCOPES) {
+    const file = configPathForScope(scope, options);
+    let config;
+    try {
+      config = readMcpConfig(file);
+    } catch (error) {
+      problems.push({ scope, file, detail: error instanceof Error ? error.message : String(error) });
+      continue;
+    }
+    // A layer can also be unreadable one step removed: it parses, declares an
+    // import, and the file that import names is the one nothing can read. That
+    // layer contributes no servers for a reason the layer itself does not show,
+    // so the diagnosis has to follow the declaration to where it points.
+    for (const kind of config.imports) {
+      for (const target of unreadableImportTargets(kind, options)) {
+        problems.push({
+          scope,
+          file: target.file,
+          detail: `${file} imports ${kind}, and that config is present but unreadable: ${target.detail}`
+        });
+      }
+    }
+  }
+  return problems;
+}
+
+/**
+ * Repository-scoped layers that declare `imports`. A repository reaching into
+ * another tool's config on this machine is refused on the declaration rather
+ * than on its contents: one of the six kinds is TOML that nothing here parses,
+ * so an enumeration would be incomplete, and a repository has no business
+ * deciding which of the operator's personal servers a session loads regardless.
+ *
+ * @param {{projectPath?: string, env?: Record<string, string|undefined>, home?: string}} [options]
+ * @returns {{scope: string, file: string, kinds: string[]}[]}
+ */
+export function repositoryImportDeclarations(options = {}) {
+  const declarations = [];
+  for (const scope of REPOSITORY_SCOPES) {
+    const file = configPathForScope(scope, options);
+    let config;
+    try {
+      config = readMcpConfig(file);
+    } catch {
+      continue;
+    }
+    const kinds = declaredImports(config.imports);
+    if (kinds.length > 0) declarations.push({ scope, file, kinds });
+  }
+  return declarations;
+}
+
+/**
+ * The `settings` block a session actually runs under.
+ *
+ * The adapter merges `settings` across all four layers in scope order, later
+ * layers winning key by key — it is one session-wide block, not a per-server
+ * one. Reading a single layer therefore answers a different question than the
+ * one that matters: `directTools` set in one file and `toolPrefix: "none"` set
+ * in another produce a session with neither property, and a check that looked at
+ * either file alone saw nothing wrong with it.
+ *
+ * @param {{projectPath?: string, env?: Record<string, string|undefined>, home?: string}} [options]
+ * @returns {{settings: Record<string, unknown>, contributors: Record<string, string>}}
+ */
+export function mergedSettings(options = {}) {
+  const settings = { ...BASELINE_SETTINGS };
+  /** @type {Record<string, string>} */
+  const contributors = {};
+  for (const scope of SCOPES) {
+    let config;
+    try {
+      config = readMcpConfig(configPathForScope(scope, options));
+    } catch {
+      continue;
+    }
+    for (const [key, item] of Object.entries(config.settings)) {
+      settings[key] = item;
+      contributors[key] = scope;
+    }
+  }
+  return { settings, contributors };
+}
+
+/**
+ * Every file any decision in this module can depend on, including the ones that
+ * matter by being absent.
+ *
+ * The guard caches its gate and recomputes when a signature over these changes.
+ * That signature used to be built by hand from the repository layers, and when
+ * the scan below grew to read merged settings from all four scopes and to stat
+ * import targets outside the repository, the signature did not grow with it —
+ * so adding `directTools` to a personal global config left an already-loaded
+ * guard permitting calls that `piagent-mcp doctor` was reporting as blocked.
+ *
+ * Derived from the same traversal the readers use, so a reader that starts
+ * consulting a new file is watched for that file without anything else being
+ * updated to match. An absent file is listed too: `imports: ["codex"]` becomes
+ * a block the moment `~/.codex/config.toml` appears.
+ *
+ * @param {{projectPath?: string, env?: Record<string, string|undefined>, home?: string}} [options]
+ * @returns {string[]}
+ */
+export function mcpDecisionInputs(options = {}) {
+  const inputs = [];
+  for (const scope of SCOPES) {
+    const file = configPathForScope(scope, options);
+    inputs.push(file);
+    let config;
+    try {
+      config = readMcpConfig(file);
+    } catch {
+      // Unreadable still counts: the file is watched, and becoming readable is
+      // a change the gate has to see.
+      continue;
+    }
+    // Every location the kind can be read from, whether or not it has one now.
+    // A kind that resolves to nothing today is exactly the kind whose file
+    // appearing tomorrow changes the answer.
+    for (const kind of config.imports) inputs.push(...importKindFiles(kind, options));
+  }
+  return [...new Set(inputs)];
+}
+
+/**
+ * Config that leaves the gate with nothing to check, so the only sound answer is
+ * to refuse every tool call.
+ *
+ * Kept here rather than in the guard because three surfaces have to agree on it.
+ * The guard enforces it; `doctor` and `list` are where an operator goes to find
+ * out why a session stopped working. When only the guard knew, `doctor` reported
+ * "No MCP servers configured" and exited 0 while nothing could run — an answer
+ * that sends the operator looking anywhere but at the config that caused it.
+ *
+ * @param {{projectPath?: string, env?: Record<string, string|undefined>, home?: string}} [options]
+ * @returns {{scope: string, file: string, detail: string}[]}
+ */
+export function unverifiableMcpConfig(options = {}) {
+  const problems = [];
+  const merged = mergedSettings(options);
+  if (erasesToolOrigin(merged.settings)) {
+    // Which files to edit, not just that something is wrong: the two keys can be
+    // set in different layers, and naming only one of them sends the operator to
+    // a file where the other half is not.
+    const scopes = [...new Set(["directTools", "toolPrefix"].map((key) => merged.contributors[key]).filter(Boolean))];
+    const files = scopes.map((scope) => configPathForScope(scope, options));
+    problems.push({
+      scope: scopes.join(" + ") || "global",
+      file: files[0] ?? configPathForScope("global", options),
+      detail: `${files.join(" and ")} together turn on directTools with toolPrefix "none", which strips the ` +
+        "server name off every tool and leaves nothing to check an approval against. " +
+        "Remove that setting, then approve servers individually."
+    });
+  }
+
+  for (const scope of REPOSITORY_SCOPES) {
+    const file = configPathForScope(scope, options);
+    let config;
+    try {
+      config = readMcpConfig(file);
+    } catch {
+      // Unreadable is a different diagnosis with its own report, and nothing is
+      // assumed about the contents of a file nobody could read.
+      continue;
+    }
+    for (const kind of config.imports) {
+      if (canEnumerateImportKind(kind)) continue;
+      // An import of a kind nothing here can parse is only a hole when the file
+      // it names exists. Refusing on the declaration alone blocked every session
+      // whose repository listed a tool the operator does not even have installed,
+      // which is a config to clean up rather than a session to stop.
+      const present = importKindFiles(kind, options).filter((candidate) => fs.existsSync(candidate));
+      if (present.length === 0) continue;
+      problems.push({
+        scope,
+        file,
+        detail: `${file} imports servers from ${kind} config, which this platform cannot enumerate ` +
+          `(${present.join(", ")}), so which servers reach this session is unknown. ` +
+          "Remove the import and declare the servers you want directly."
+      });
+    }
+  }
+  return problems;
+}
+
 /** @param {unknown} value @returns {value is Record<string, unknown>} */
 export function isRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);

package/packages/piagent-core/mcp/mcp-import-kinds.js

@@ -0,0 +1,240 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// Defined here rather than imported from the layer module, which imports this
+// one: a cycle between the two would resolve, but only by accident of ordering.
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+// The adapter accepts an `imports` key that pulls server definitions out of
+// other coding tools' config files. Those definitions land in a session without
+// ever appearing in any of the four scopes this platform manages, so anything
+// the approval gate is meant to cover has to be resolved here too.
+//
+// Each kind is described by two independent sets of locations. One is where the
+// adapter looks today; the other is where the tool actually keeps its config.
+// They disagree for three of the six kinds, and the gate has to hold under both:
+// reading only the adapter's location misses a definition the moment the adapter
+// is corrected, and reading only the real location misses what loads right now.
+// The union is the safe direction to be wrong in — a server listed here that
+// never loads costs one approval prompt, a server that loads without being
+// listed costs the gate.
+//
+// Only `vscode` resolves inside the project. That one distinction is what makes
+// it dangerous: a cloned repository carries the file it points at, so the
+// servers it defines travel with the clone exactly like `.mcp.json` does.
+
+/**
+ * @typedef {{
+ *   adapterPaths: (home: string, projectPath: string) => string[],
+ *   actualPaths: (home: string, projectPath: string) => string[],
+ *   serverKeys: string[],
+ *   repositoryRelative: boolean,
+ *   parsedAsJson: boolean
+ * }} ImportKind
+ */
+
+/** @type {Record<string, ImportKind>} */
+export const IMPORT_KINDS = {
+  cursor: {
+    adapterPaths: (home) => [path.join(home, ".cursor", "mcp.json")],
+    actualPaths: (home) => [path.join(home, ".cursor", "mcp.json")],
+    serverKeys: ["mcpServers", "mcp-servers"],
+    repositoryRelative: false,
+    parsedAsJson: true
+  },
+  "claude-code": {
+    adapterPaths: (home) => [
+      path.join(home, ".claude", "mcp.json"),
+      path.join(home, ".claude.json"),
+      path.join(home, ".claude", "claude_desktop_config.json")
+    ],
+    // Servers added at user scope sit at the top level of `~/.claude.json`;
+    // servers added at local scope are nested per project and are not read by
+    // either side, which is worth knowing but changes nothing here.
+    actualPaths: (home) => [path.join(home, ".claude.json")],
+    serverKeys: ["mcpServers"],
+    repositoryRelative: false,
+    parsedAsJson: true
+  },
+  "claude-desktop": {
+    adapterPaths: (home) => [
+      path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json")
+    ],
+    actualPaths: (home) => [
+      path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json")
+    ],
+    serverKeys: ["mcpServers"],
+    repositoryRelative: false,
+    parsedAsJson: true
+  },
+  codex: {
+    adapterPaths: (home) => [path.join(home, ".codex", "config.json")],
+    // The real file is TOML under a `mcp_servers` table, and nothing here parses
+    // TOML. Enumeration is therefore incomplete for this kind, which is what
+    // `canEnumerateImportKind` reports: a repository that declares it is refused
+    // on the declaration, because listing the servers that happen to be readable
+    // says nothing about the ones that are not.
+    actualPaths: (home) => [path.join(home, ".codex", "config.toml")],
+    serverKeys: ["mcpServers", "mcp_servers"],
+    repositoryRelative: false,
+    parsedAsJson: false
+  },
+  windsurf: {
+    adapterPaths: (home) => [path.join(home, ".windsurf", "mcp.json")],
+    actualPaths: (home) => [path.join(home, ".codeium", "windsurf", "mcp_config.json")],
+    serverKeys: ["mcpServers", "mcp-servers"],
+    repositoryRelative: false,
+    parsedAsJson: true
+  },
+  vscode: {
+    adapterPaths: (_home, projectPath) => [path.join(projectPath, ".vscode", "mcp.json")],
+    actualPaths: (_home, projectPath) => [path.join(projectPath, ".vscode", "mcp.json")],
+    // The adapter reads `mcpServers`; the documented format uses `servers`. Both
+    // are read so the gate covers a hand-written file either way.
+    serverKeys: ["mcpServers", "mcp-servers", "servers"],
+    repositoryRelative: true,
+    parsedAsJson: true
+  }
+};
+
+/** Import kinds whose file a repository carries, and which therefore need approval. */
+export const REPOSITORY_RELATIVE_KINDS = new Set(
+  Object.entries(IMPORT_KINDS)
+    .filter(([, kind]) => kind.repositoryRelative)
+    .map(([name]) => name)
+);
+
+/**
+ * Whether every server this kind can contribute is visible to this platform.
+ *
+ * False means the answer from `importedServers` is a subset of unknown size, not
+ * a list. A caller deciding what to block needs to know the difference: blocking
+ * what came back would look like coverage while saying nothing about the rest.
+ *
+ * @param {string} kindName
+ * @returns {boolean}
+ */
+export function canEnumerateImportKind(kindName) {
+  return IMPORT_KINDS[kindName]?.parsedAsJson === true;
+}
+
+/**
+ * The `imports` a config document declares, as a list of known kind names. An
+ * unknown kind is dropped rather than rejected: the adapter ignores it too, and
+ * a name this version does not recognise is not evidence of anything.
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+export function declaredImports(value) {
+  if (!Array.isArray(value)) return [];
+  const kinds = [];
+  for (const entry of value) {
+    if (typeof entry !== "string") continue;
+    const kind = entry.trim();
+    if (Object.hasOwn(IMPORT_KINDS, kind) && !kinds.includes(kind)) kinds.push(kind);
+  }
+  return kinds;
+}
+
+/**
+ * Every file an import kind can be read from, adapter location and real location
+ * alike. Exported because "does this kind actually resolve to anything on this
+ * machine" is a question two callers ask, and each answering it from its own
+ * copy of the path list is how the two answers drift apart.
+ *
+ * @param {string} kindName
+ * @param {{projectPath?: string, home?: string}} [options]
+ * @returns {string[]}
+ */
+export function importKindFiles(kindName, options = {}) {
+  const kind = IMPORT_KINDS[kindName];
+  if (!kind) return [];
+  const home = options.home ?? os.homedir();
+  const projectPath = options.projectPath ?? process.cwd();
+  return [...new Set([...kind.adapterPaths(home, projectPath), ...kind.actualPaths(home, projectPath)])];
+}
+
+/**
+ * Every server an import kind can put into a session, from either location and
+ * under any of the keys that location might use. Files that are missing
+ * contribute nothing; a file that exists but cannot be parsed is reported by
+ * `unreadableImportTargets`, because "no servers" and "servers nobody could
+ * read" are the two answers an operator most needs told apart.
+ *
+ * @param {string} kindName
+ * @param {{projectPath?: string, home?: string}} [options]
+ * @returns {{name: string, file: string, entry: Record<string, unknown>}[]}
+ */
+export function importedServers(kindName, options = {}) {
+  const kind = IMPORT_KINDS[kindName];
+  if (!kind) return [];
+  const files = importKindFiles(kindName, options);
+
+  const found = [];
+  const seen = new Set();
+  for (const file of files) {
+    if (!kind.parsedAsJson && !file.endsWith(".json")) continue;
+    let document;
+    try {
+      document = JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch {
+      continue;
+    }
+    if (!isRecord(document)) continue;
+    for (const key of kind.serverKeys) {
+      const servers = document[key];
+      if (!isRecord(servers)) continue;
+      for (const [name, entry] of Object.entries(servers)) {
+        // A name defined under two keys of the same file is one server; a name
+        // defined in two files is reported once, keyed by the first file seen,
+        // because approving it twice would ask the same question twice.
+        const dedupe = `${name}\u0000${file}`;
+        if (seen.has(dedupe) || !isRecord(entry)) continue;
+        seen.add(dedupe);
+        found.push({ name, file, entry });
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Import targets that exist but cannot be read into servers. `importedServers`
+ * skips these, which is right for a listing and wrong for a diagnosis: the
+ * caller cannot otherwise tell a tool that defines no servers from a tool whose
+ * config nothing could parse, and only one of those two is a gap in the gate.
+ *
+ * @param {string} kindName
+ * @param {{projectPath?: string, home?: string}} [options]
+ * @returns {{kind: string, file: string, detail: string}[]}
+ */
+export function unreadableImportTargets(kindName, options = {}) {
+  const kind = IMPORT_KINDS[kindName];
+  if (!kind) return [];
+  const problems = [];
+  for (const file of importKindFiles(kindName, options)) {
+    if (!kind.parsedAsJson && !file.endsWith(".json")) continue;
+    let raw;
+    try {
+      raw = fs.readFileSync(file, "utf8");
+    } catch (error) {
+      // Absent is the normal case for five of six kinds and is not a problem.
+      if (error && typeof error === "object" && error.code === "ENOENT") continue;
+      problems.push({ kind: kindName, file, detail: `cannot read ${file}` });
+      continue;
+    }
+    let document;
+    try {
+      document = JSON.parse(raw);
+    } catch (error) {
+      problems.push({ kind: kindName, file, detail: `cannot parse ${file}: ${error instanceof Error ? error.message : String(error)}` });
+      continue;
+    }
+    if (!isRecord(document)) problems.push({ kind: kindName, file, detail: `${file} is not a JSON object` });
+  }
+  return problems;
+}