@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/agent-settings/src/deploy/mcp-deploy.ts

@@ -0,0 +1,175 @@
+/**
+ * Writes assets/mcp.json's server list into a target repository's MCP
+ * surfaces, per the deploy profile (profile.ts) — generically: which
+ * surfaces exist, their target files, container keys and array-formatting
+ * style all come from the profile, not from a hardcoded surface list here.
+ * Touches only entries a PREVIOUS run of this deploy recorded as its own
+ * (lock.ts): a same-name server the target repo already owns is left
+ * untouched and reported as a conflict, and a server dropped from
+ * assets/mcp.json is removed only when the lock shows this deploy wrote
+ * it.
+ *
+ * Fails loud: missing assets/target dirs, an invalid profile, or a
+ * malformed target JSON/codex file all throw. There is no partial-success
+ * return value.
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { stringifyPretty } from "./json-pretty.js";
+import {
+  legacyTakeoverForCodexBlock,
+  legacyTakeoverForMcpJsonSurface,
+  type LegacyJsonPath,
+  type LegacyLockDoc,
+  readLegacyLock,
+  stripLegacyOwnership,
+} from "./legacy-lock.js";
+import { type SettingsLock, type McpLockEntry, readLock, writeLock } from "./lock.js";
+import { hasForeignTopLevelTable, mergeCodexBlock, mergeServerMap } from "./mcp-merge.js";
+import { renderCodexManagedBlock, renderMcpJsonEntry } from "./mcp-render.js";
+import { loadMcpSource, type McpServerSpec } from "./mcp-source.js";
+import { type DeployProfile, type McpTopLevelTable, loadProfile } from "./profile.js";
+
+export interface DeployMcpOptions {
+  readonly targetRepo: string;
+  /** Defaults to loadProfile() — pass explicitly when the caller has already resolved real on-disk paths. */
+  readonly profile?: DeployProfile;
+  /** Defaults to loading `profile.mcp.source` relative to the package root. */
+  readonly servers?: readonly McpServerSpec[];
+}
+
+export interface McpFileConflict {
+  readonly file: string;
+  readonly server: string;
+  readonly reason: string;
+}
+
+export interface DeployMcpResult {
+  readonly written: readonly string[];
+  readonly unchanged: readonly string[];
+  readonly conflicts: readonly McpFileConflict[];
+  readonly lockPath: string;
+}
+
+function readExistingJson(path: string): Record<string, unknown> | undefined {
+  if (!existsSync(path)) return undefined;
+  let doc: unknown;
+  try {
+    doc = JSON.parse(readFileSync(path, "utf8"));
+  } catch (cause) {
+    throw new Error(`target MCP file is not valid JSON: ${path} (${(cause as Error).message})`);
+  }
+  if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
+    throw new Error(`target MCP file is not a JSON object: ${path}`);
+  }
+  return doc as Record<string, unknown>;
+}
+
+function writeIfChanged(path: string, content: string, changed: boolean): void {
+  if (!changed) return;
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+}
+
+function serializeJsonStyle(jsonStyle: "width-aware" | "expanded", value: Record<string, unknown>): string {
+  return jsonStyle === "width-aware" ? stringifyPretty(value as never) : JSON.stringify(value, null, 2);
+}
+
+export function deployMcp(options: DeployMcpOptions): DeployMcpResult {
+  const { targetRepo } = options;
+  if (!existsSync(targetRepo) || !statSync(targetRepo).isDirectory()) {
+    throw new Error(`deploy target is not a directory: ${targetRepo}`);
+  }
+
+  const profile = options.profile ?? loadProfile();
+  const servers = options.servers ?? loadMcpSource();
+  const marker = profile.mcp.marker ?? "adl";
+
+  const lock = readLock(targetRepo);
+  const legacyLockPath = profile.legacyLock !== undefined ? join(targetRepo, profile.legacyLock) : undefined;
+  const legacyDoc: LegacyLockDoc | undefined = legacyLockPath !== undefined ? readLegacyLock(legacyLockPath) : undefined;
+  const newMcpEntries: Record<string, McpLockEntry> = {};
+  const written: string[] = [];
+  const unchanged: string[] = [];
+  const conflicts: McpFileConflict[] = [];
+  const legacyMergedRemovals: { file: string; paths: LegacyJsonPath[] }[] = [];
+  const legacyTomlRemovals: string[] = [];
+  let anyLegacyTakeover = false;
+
+  for (const surface of profile.mcp.surfaces) {
+    const targetAbs = join(targetRepo, surface.file);
+    const prevEntry = lock.mcp[surface.file];
+
+    if (surface.format === "toml-block") {
+      const existingText = existsSync(targetAbs) ? readFileSync(targetAbs, "utf8") : undefined;
+
+      const allowedTopLevel: McpTopLevelTable[] = [];
+      for (const table of surface.topLevel ?? []) {
+        if (hasForeignTopLevelTable(existingText, table.table)) {
+          conflicts.push({
+            file: surface.file,
+            server: table.table,
+            reason: `a [${table.table}] table already exists outside the managed block; deploy left it untouched`,
+          });
+        } else {
+          allowedTopLevel.push(table);
+        }
+      }
+
+      const rendered = renderCodexManagedBlock(servers, marker, surface.tableKey as string, surface.entry, allowedTopLevel);
+      const { fileContent, changed } = mergeCodexBlock(existingText, rendered);
+      writeIfChanged(targetAbs, fileContent, changed);
+      (changed ? written : unchanged).push(surface.file);
+      newMcpEntries[surface.file] = { kind: "block", owned: true };
+      // The managed block is always regenerated (M3) regardless of prior
+      // ownership; a legacy hash match only tells us whether the block we
+      // just replaced was ours to take over, for bookkeeping in the legacy
+      // lock (see legacy-lock.ts's header for why this is safe here).
+      if (legacyTakeoverForCodexBlock(existingText, legacyDoc, surface.file)) {
+        legacyTomlRemovals.push(surface.file);
+        anyLegacyTakeover = true;
+      }
+      continue;
+    }
+
+    const previousOwned = prevEntry !== undefined && prevEntry.kind === "json" ? prevEntry.servers : [];
+    const existingRaw = readExistingJson(targetAbs);
+
+    const topKey = surface.containerKey as string;
+    const legacyTakeover = legacyTakeoverForMcpJsonSurface(existingRaw, legacyDoc, surface.file, topKey);
+    if (legacyTakeover.matched) {
+      legacyMergedRemovals.push({ file: surface.file, paths: legacyTakeover.ownedServers.map((name): LegacyJsonPath => [topKey, name]) });
+      anyLegacyTakeover = true;
+    }
+    const effectivePreviousOwned = legacyTakeover.matched ? [...new Set([...previousOwned, ...legacyTakeover.ownedServers])] : previousOwned;
+    const desired = new Map<string, unknown>(servers.map((spec) => [spec.name, renderMcpJsonEntry(surface.entry, spec)]));
+
+    const { fileContent, ownedServers, conflicts: serverConflicts, changed } = mergeServerMap(existingRaw, topKey, desired, effectivePreviousOwned);
+    for (const c of serverConflicts) conflicts.push({ file: surface.file, server: c.server, reason: c.reason });
+
+    writeIfChanged(targetAbs, `${serializeJsonStyle(surface.jsonStyle as "width-aware" | "expanded", fileContent)}\n`, changed);
+    (changed ? written : unchanged).push(surface.file);
+    newMcpEntries[surface.file] = { kind: "json", servers: ownedServers };
+  }
+
+  writeLock(targetRepo, { schema: 1, mcp: newMcpEntries, agents: lock.agents, leanCtx: lock.leanCtx });
+
+  // Once anything was actually taken over, this package's own footprint in
+  // the legacy lock (the four MCP `merged` sections and the codex `toml`
+  // block entry) is stale: ownership has fully moved to
+  // .agents/agent-settings.lock.json just written above. A legacy lock
+  // present but untouched by any takeover (no hash matched, or this repo
+  // never had one) is left exactly as found.
+  if (anyLegacyTakeover && legacyDoc !== undefined && legacyLockPath !== undefined) {
+    stripLegacyOwnership(legacyDoc, legacyLockPath, { mergedEntries: legacyMergedRemovals, toml: legacyTomlRemovals });
+  }
+
+  return {
+    written: written.sort(),
+    unchanged: unchanged.sort(),
+    conflicts: conflicts.sort((a, b) => `${a.file}/${a.server}`.localeCompare(`${b.file}/${b.server}`)),
+    lockPath: join(targetRepo, ".agents/agent-settings.lock.json"),
+  };
+}
+
+export type { SettingsLock };

package/packages/agent-settings/src/deploy/mcp-inspect.ts

@@ -0,0 +1,56 @@
+/**
+ * Reads what is ACTUALLY on disk for one MCP surface in a target repo —
+ * server names, and (for the JSON surfaces) their rendered values — used by
+ * both list.ts and doctor.ts. Independent of the lock: the lock says what
+ * WE wrote, this says what IS there.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { McpSurface } from "./profile.js";
+
+function topKeyFor(surface: McpSurface): string {
+  return surface.containerKey as string;
+}
+
+/** Server names present in a JSON surface's server map, or in a codex-toml-block's `[<tableKey>.<name>]` sections. `[]` when the file does not exist. */
+export function readDeployedMcpServerNames(targetRepo: string, surface: McpSurface): readonly string[] {
+  const absPath = join(targetRepo, surface.file);
+  if (!existsSync(absPath)) return [];
+
+  if (surface.format === "toml-block") {
+    const tableKey = surface.tableKey as string;
+    const re = new RegExp(`^\\[${tableKey.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\.(.+)\\]$`);
+    const names: string[] = [];
+    for (const line of readFileSync(absPath, "utf8").split("\n")) {
+      const m = re.exec(line.trim());
+      if (m?.[1] !== undefined) names.push(m[1]);
+    }
+    return names;
+  }
+
+  let doc: unknown;
+  try {
+    doc = JSON.parse(readFileSync(absPath, "utf8"));
+  } catch {
+    return [];
+  }
+  const servers = (doc as Record<string, unknown> | null)?.[topKeyFor(surface)];
+  if (typeof servers !== "object" || servers === null || Array.isArray(servers)) return [];
+  return Object.keys(servers as Record<string, unknown>);
+}
+
+/** For a JSON surface only: the rendered value currently on disk for `name`, or `undefined` if absent/unparsable/not a JSON surface. */
+export function readDeployedMcpServerValue(targetRepo: string, surface: McpSurface, name: string): unknown {
+  if (surface.format === "toml-block") return undefined;
+  const absPath = join(targetRepo, surface.file);
+  if (!existsSync(absPath)) return undefined;
+  let doc: unknown;
+  try {
+    doc = JSON.parse(readFileSync(absPath, "utf8"));
+  } catch {
+    return undefined;
+  }
+  const servers = (doc as Record<string, unknown> | null)?.[topKeyFor(surface)];
+  if (typeof servers !== "object" || servers === null) return undefined;
+  return (servers as Record<string, unknown>)[name];
+}

package/packages/agent-settings/src/deploy/mcp-merge.ts

@@ -0,0 +1,164 @@
+/**
+ * Merges rendered MCP server entries into an existing (or absent) target
+ * file, touching only entries a PREVIOUS run of this deploy recorded as its
+ * own (per lock.ts) — every other key, and every server entry this deploy
+ * did not write, survives untouched (M4). Two shapes:
+ *  - `mergeServerMap` for the four JSON surfaces (claude-json/cursor-json/
+ *    kimi-json/opencode-json): `{...otherKeys, <topKey>: {...servers}}`.
+ *  - `mergeCodexBlock` for codex-toml-block: the whole marker-delimited
+ *    span is regenerated from the current source every run (M3) and
+ *    everything outside it is left byte-for-byte; an old block using a
+ *    different marker id (e.g. the pre-agent-settings `adl-repo` one) is
+ *    replaced, never left duplicated (M3). `hasForeignTopLevelTable` is the
+ *    same "never touch what's not ours" rule applied to a `topLevel` table
+ *    (profile.ts's `McpTopLevelTable`, e.g. `[features]`): mcp-deploy.ts
+ *    calls it before rendering and drops (reports as a conflict, never
+ *    emits) any table the target file already carries OUTSIDE the managed
+ *    block, since TOML forbids declaring the same table twice.
+ *
+ * For a target that does not exist yet, `existing` is `undefined` and the
+ * result is built fresh in source order — this is what makes a deploy into
+ * an empty repo reproduce this repo's own committed `.mcp.json` /
+ * `.cursor/mcp.json` / `.kimi-code/mcp.json` / the `mcp` key of
+ * `opencode.json` / the codex block (up to its marker line) byte-for-byte.
+ */
+export interface McpServerConflict {
+  readonly server: string;
+  readonly reason: string;
+}
+
+export interface JsonServerMergeResult {
+  readonly fileContent: Record<string, unknown>;
+  /** New lock contents: the MCP server names this deploy now owns in this file's server map. */
+  readonly ownedServers: readonly string[];
+  readonly conflicts: readonly McpServerConflict[];
+  readonly changed: boolean;
+}
+
+/**
+ * For the JSON surfaces: `{...otherTopLevelKeys, <topKey>: {...servers}}`.
+ * `desired` must be provided in the exact order a fresh file should list
+ * servers in. A same-name server already present and NOT recorded as ours
+ * in a previous run (`previousOwned`) is a conflict: left untouched,
+ * reported, never claimed in `ownedServers` (M4/D5-equivalent for MCP).
+ */
+export function mergeServerMap(
+  existing: Record<string, unknown> | undefined,
+  topKey: string,
+  desired: ReadonlyMap<string, unknown>,
+  previousOwned: readonly string[],
+): JsonServerMergeResult {
+  const base: Record<string, unknown> = existing ? { ...existing } : {};
+  const existingServersRaw = base[topKey];
+  const existingServers: Record<string, unknown> =
+    typeof existingServersRaw === "object" && existingServersRaw !== null && !Array.isArray(existingServersRaw)
+      ? (existingServersRaw as Record<string, unknown>)
+      : {};
+
+  const prevOwnedSet = new Set(previousOwned);
+  const newServers: Record<string, unknown> = {};
+  for (const [name, value] of Object.entries(existingServers)) {
+    if (prevOwnedSet.has(name)) continue; // ours from a previous run — dropped here, re-added below from `desired` (or removed if no longer desired)
+    newServers[name] = value; // a user's own server (or another tool's), never touched
+  }
+
+  const conflicts: McpServerConflict[] = [];
+  const owned: string[] = [];
+  for (const [name, value] of desired) {
+    if (Object.prototype.hasOwnProperty.call(newServers, name)) {
+      conflicts.push({ server: name, reason: "a user-owned MCP server already exists with this name; deploy left it untouched" });
+      continue; // never overwrite it, never claim it in the lock
+    }
+    newServers[name] = value;
+    owned.push(name);
+  }
+
+  base[topKey] = newServers;
+  const changed = existing === undefined || JSON.stringify(existingServers) !== JSON.stringify(newServers);
+
+  return { fileContent: base, ownedServers: owned, conflicts, changed };
+}
+
+export interface CodexBlockMergeResult {
+  readonly fileContent: string;
+  readonly changed: boolean;
+}
+
+const BLOCK_OPEN_RE = /^# >>> (\S+) \(managed by [^)]*\) >>>$/;
+
+function blockCloseRe(markerId: string): RegExp {
+  return new RegExp(`^# <<< ${markerId} <<<$`);
+}
+
+interface BlockSpan {
+  readonly startIdx: number;
+  readonly endIdx: number;
+}
+
+/**
+ * Finds the existing managed block's line range (any marker id), if
+ * present — shared by `mergeCodexBlock` and `hasForeignTopLevelTable` so
+ * both agree on what counts as "inside the block". Throws if a block-open
+ * line is found with no matching close line (malformed file — fails loud
+ * rather than guessing).
+ */
+function findManagedBlockSpan(lines: readonly string[]): BlockSpan | undefined {
+  const startIdx = lines.findIndex((line) => BLOCK_OPEN_RE.test(line));
+  if (startIdx === -1) return undefined;
+  const markerId = BLOCK_OPEN_RE.exec(lines[startIdx] ?? "")?.[1] ?? "";
+  const closeRe = blockCloseRe(markerId);
+  const endIdx = lines.findIndex((line, i) => i > startIdx && closeRe.test(line));
+  if (endIdx === -1) {
+    throw new Error(`managed block starting at line ${startIdx + 1} has no matching "# <<< ${markerId} <<<" close line`);
+  }
+  return { startIdx, endIdx };
+}
+
+/** Drops a text's trailing empty line from a final "\n", so slice/splice math treats it as a plain list of real lines. */
+function splitToRealLines(text: string): string[] {
+  const lines = text.length > 0 ? text.split("\n") : [];
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return lines;
+}
+
+/**
+ * Replaces (or appends) the managed block in a codex `config.toml`-shaped
+ * text file. Any existing block — regardless of its marker id — is
+ * replaced by `newBlock`; text outside the block is left byte-for-byte.
+ */
+export function mergeCodexBlock(existingText: string | undefined, newBlock: string): CodexBlockMergeResult {
+  const original = existingText ?? "";
+  const lines = splitToRealLines(original);
+  const span = findManagedBlockSpan(lines);
+
+  const newLines =
+    span === undefined
+      ? lines.length === 0
+        ? [...newBlock.split("\n")]
+        : [...lines, "", ...newBlock.split("\n")]
+      : [...lines.slice(0, span.startIdx), ...newBlock.split("\n"), ...lines.slice(span.endIdx + 1)];
+
+  const fileContent = `${newLines.join("\n")}\n`;
+  return { fileContent, changed: fileContent !== original };
+}
+
+/**
+ * True when `tableName` (e.g. "features") appears as a top-level TOML
+ * table (`^[tableName]$`, exact) OUTSIDE the existing managed block (any
+ * marker) — meaning it is foreign/user-owned, and a managed block must not
+ * also declare it (TOML forbids duplicate tables). A table found only
+ * INSIDE the existing managed block does not count as foreign: that is
+ * this deploy's own prior output, always regenerated (M3) — see
+ * mcp-deploy.ts's caller for how this gates a `topLevel` table down to a
+ * conflict instead of a collision.
+ */
+export function hasForeignTopLevelTable(existingText: string | undefined, tableName: string): boolean {
+  if (existingText === undefined) return false;
+  const lines = splitToRealLines(existingText);
+  const span = findManagedBlockSpan(lines);
+  const re = new RegExp(`^\\[${tableName}\\]\\s*$`);
+  return lines.some((line, i) => {
+    if (span !== undefined && i >= span.startIdx && i <= span.endIdx) return false;
+    return re.test(line);
+  });
+}

package/packages/agent-settings/src/deploy/mcp-render.ts

@@ -0,0 +1,80 @@
+/**
+ * Renders assets/mcp.json's canonical `{command, args}` server list into a
+ * surface's own wire shape — generically, from that McpSurface's own
+ * `entry` field list (JSON containers) or `entry` + `tableKey` (the codex
+ * TOML block) in deploy-profile.json (profile.ts). This module hard-codes
+ * no surface name, no target key, and no constant value; only the fixed
+ * MEANING of the `from` vocabulary (command/args/commandArgs) and the
+ * TOML/managed-block text mechanics are code, per profile.ts's header.
+ * Pure: no filesystem I/O, no ownership/merge policy (mcp-merge.ts's job).
+ */
+import type { McpEntryField, McpFromToken, McpTopLevelTable } from "./profile.js";
+import type { McpServerSpec } from "./mcp-source.js";
+
+function resolveFrom(token: McpFromToken, spec: McpServerSpec): string | readonly string[] {
+  switch (token) {
+    case "command":
+      return spec.command;
+    case "args":
+      return spec.args;
+    case "commandArgs":
+      return [spec.command, ...spec.args];
+  }
+}
+
+function fieldValue(field: McpEntryField, spec: McpServerSpec): unknown {
+  if (field.const !== undefined) return field.const;
+  if (field.from !== undefined) return resolveFrom(field.from, spec);
+  throw new Error(`mcp entry field "${field.key}" sets neither "from" nor "const"`);
+}
+
+/** Builds one server's rendered value object for a JSON surface, e.g. `{command, args}` or `{type: "stdio", command, args}`, in `entry`'s own key order. */
+export function renderMcpJsonEntry(entry: readonly McpEntryField[], spec: McpServerSpec): Record<string, unknown> {
+  const obj: Record<string, unknown> = {};
+  for (const field of entry) obj[field.key] = fieldValue(field, spec);
+  return obj;
+}
+
+/** `"value"` / `["a", "b"]` / `true` — a TOML value literal for a string, string array, boolean or number. Always one line, regardless of length (matches this repo's committed `.codex/config.toml`, unlike the JSON surfaces' width-aware wrapping). */
+function tomlValueLiteral(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map((v) => JSON.stringify(v)).join(", ")}]`;
+  if (typeof value === "string") return JSON.stringify(value);
+  return String(value);
+}
+
+function tomlServerBlock(tableKey: string, entry: readonly McpEntryField[], spec: McpServerSpec): string {
+  const fieldLines = entry.map((field) => `${field.key} = ${tomlValueLiteral(fieldValue(field, spec))}`);
+  return `[${tableKey}.${spec.name}]\n${fieldLines.join("\n")}\n`;
+}
+
+/** `[table]\nkey = value\n...\n` for one `topLevel` table — every field is a constant (no per-server spec exists at this level). */
+function tomlTopLevelBlock(table: McpTopLevelTable): string {
+  const fieldLines = table.fields.map((field) => `${field.key} = ${tomlValueLiteral(field.const)}`);
+  return `[${table.table}]\n${fieldLines.join("\n")}\n`;
+}
+
+/**
+ * The full managed block body for a `toml-block` surface, markers
+ * included, e.g. `# >>> adl (managed by agent-settings; do not edit) >>>\n
+ * ...\n# <<< adl <<<`. No trailing newline — the caller controls spacing
+ * around it. The marker-line text and the blank-line spacing between
+ * server stanzas are structural (an in-place text edit needs an exact,
+ * parseable delimiter), not per-repo policy — see profile.ts's header.
+ * `topLevel` tables (e.g. `[features]`) render first, before the
+ * per-server stanzas — the caller (mcp-deploy.ts) is responsible for
+ * dropping any table that would collide with one the target file already
+ * carries outside the managed block (TOML forbids duplicate tables).
+ */
+export function renderCodexManagedBlock(
+  servers: readonly McpServerSpec[],
+  marker: string,
+  tableKey: string,
+  entry: readonly McpEntryField[],
+  topLevel: readonly McpTopLevelTable[] = [],
+): string {
+  const open = `# >>> ${marker} (managed by agent-settings; do not edit) >>>`;
+  const close = `# <<< ${marker} <<<`;
+  const blocks = [...topLevel.map(tomlTopLevelBlock), ...servers.map((s) => tomlServerBlock(tableKey, entry, s))];
+  const body = blocks.join("\n");
+  return `${open}\n${body}\n${close}`;
+}

package/packages/agent-settings/src/deploy/mcp-source.ts

@@ -0,0 +1,43 @@
+/**
+ * Reads assets/mcp.json — the canonical MCP server list, in Claude's own
+ * `{command, args}` wire shape — into an ordered structure every renderer
+ * in mcp-render.ts starts from. Pure: parses, never mutates, and preserves
+ * the source file's own key order (the order every fresh-deploy surface
+ * file must reproduce).
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export interface McpServerSpec {
+  readonly name: string;
+  readonly command: string;
+  readonly args: readonly string[];
+}
+
+export const DEFAULT_MCP_SOURCE_PATH = fileURLToPath(new URL("../../assets/mcp.json", import.meta.url));
+
+function isServerSpec(value: unknown): value is { command: string; args: readonly string[] } {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return typeof v.command === "string" && Array.isArray(v.args) && v.args.every((a) => typeof a === "string");
+}
+
+/** Loads and validates assets/mcp.json (or a fixture at another path). Throws (fails loud) on malformed JSON or an unrecognized shape. */
+export function loadMcpSource(path: string = DEFAULT_MCP_SOURCE_PATH): readonly McpServerSpec[] {
+  let doc: unknown;
+  try {
+    doc = JSON.parse(readFileSync(path, "utf8"));
+  } catch (cause) {
+    throw new Error(`mcp source is not valid JSON: ${path} (${(cause as Error).message})`);
+  }
+  const servers = (doc as { mcpServers?: unknown } | null)?.mcpServers;
+  if (typeof servers !== "object" || servers === null || Array.isArray(servers)) {
+    throw new Error(`mcp source has no "mcpServers" object: ${path}`);
+  }
+  const out: McpServerSpec[] = [];
+  for (const [name, spec] of Object.entries(servers)) {
+    if (!isServerSpec(spec)) throw new Error(`mcp source server "${name}" is not a valid {command, args} spec: ${path}`);
+    out.push({ name, command: spec.command, args: spec.args });
+  }
+  return out;
+}