@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/engine/mcp/client.mjs

@@ -0,0 +1,254 @@
+/**
+ * lib/engine/mcp/client.mjs — connect to one MCP server and use its tools and resources.
+ *
+ * Lifecycle (MCP specification):
+ *   1. `initialize` offering our protocol version (2025-06-18), our client
+ *      info, and no optional capabilities;
+ *   2. the server answers with the version it will speak — accepted if it is
+ *      one we support, otherwise the connection is closed with an error;
+ *   3. `notifications/initialized`; on streamable HTTP the optional GET
+ *      stream is then opened for server-initiated messages (a server that
+ *      does not offer it answers 405, which is fine);
+ *   4. `tools/list`, following `nextCursor` pages.
+ *
+ * A `notifications/tools/list_changed` from the server (on stdio, or the
+ * HTTP GET stream) sets `toolsChanged`; the run re-lists at its next turn
+ * boundary (`refreshTools`, via mcp/index.mjs), never mid-turn.
+ *
+ * Resources: when the server declares the `resources` capability,
+ * `listResources` (paginated `resources/list`) and `readResource`
+ * (`resources/read`) back the ListMcpResources / ReadMcpResource tools.
+ *
+ * `connectMcpServer` never throws for an expected failure (a missing binary,
+ * a server that exits, a bad version, a timeout): it returns `{ok:false}`.
+ * `callTool` likewise returns an engine tool result; a crashed server becomes
+ * an error result naming the server and its last stderr, and the run goes on
+ * (mcp/supervisor.mjs restarts a crashed stdio server once per run). Image
+ * content is attached to the result (`images`) for the wire to send.
+ *
+ * A stdio server inherits the run's environment minus every credential-shaped
+ * variable, the org credential included (context/child-env.mjs, CF-22): a
+ * credential reaches it only when its entry's `inheritEnv` names it, or the
+ * run's `envPassthrough` names an extended-shape one. Its config `env` is
+ * applied on top, so a server that needs a value gets it by naming it. Every error string
+ * this module returns — it reaches stderr, the JSON result and the transcript —
+ * has credential values, the server's header and env values, and URL secrets
+ * removed.
+ *
+ * @module lib/engine/mcp/client
+ */
+
+import { configuredCommandEnv, redactSecrets } from "../context/child-env.mjs";
+import { createRpcPeer } from "./jsonrpc.mjs";
+import { createStdioTransport } from "./stdio.mjs";
+import { createHttpTransport } from "./http.mjs";
+import { mapCallToolResult, mapReadResourceResult } from "./results.mjs";
+
+export const CLIENT_PROTOCOL_VERSION = "2025-06-18";
+export const SUPPORTED_PROTOCOL_VERSIONS = Object.freeze(["2025-06-18", "2025-03-26", "2024-11-05"]);
+export const DEFAULT_STARTUP_TIMEOUT_MS = 30_000;
+export const DEFAULT_TOOL_TIMEOUT_MS = 10 * 60_000;
+const MAX_LIST_PAGES = 100;
+
+/**
+ * @typedef {{ok:true, content:string, images?:Array<{mediaType:string, data:string}>}|{ok:false, error:string}} ToolOutcome
+ * @typedef {Object} McpConnection
+ * @property {string} name
+ * @property {string} protocolVersion
+ * @property {{name?:string, version?:string}|null} serverInfo
+ * @property {string|null} instructions
+ * @property {Record<string, any>} capabilities
+ * @property {Array<{name:string, description?:string, inputSchema?:object, annotations?:{readOnlyHint?:boolean}}>} tools
+ * @property {boolean} toolsChanged
+ * @property {() => Promise<{ok:true, tools:any[]}|{ok:false, error:string}>} refreshTools
+ * @property {(tool:string, args:object, o?:{signal?:AbortSignal, timeoutMs?:number}) => Promise<ToolOutcome>} callTool
+ * @property {(o?:{signal?:AbortSignal}) => Promise<{ok:true, resources:any[]}|{ok:false, error:string}>} listResources
+ * @property {(uri:string, o?:{signal?:AbortSignal}) => Promise<ToolOutcome>} readResource
+ * @property {() => boolean} isAlive
+ * @property {() => Promise<void>} close
+ */
+
+/**
+ * @param {import('./config.mjs').McpServerConfig} config
+ * @param {object} [deps]
+ * @param {{name:string, version:string}} [deps.clientInfo]
+ * @param {number} [deps.startupTimeoutMs]
+ * @param {number} [deps.toolTimeoutMs]
+ * @param {Record<string,string|undefined>} [deps.env]   base environment for stdio servers
+ * @param {string[]} [deps.envPassthrough]  extended-shape secrets every stdio server may inherit (CF-22)
+ * @param {string} [deps.cwd]
+ * @param {typeof import('node:child_process').spawn} [deps.spawnImpl]
+ * @param {typeof fetch} [deps.fetchImpl]
+ * @param {boolean} [deps.eventStream]  open the HTTP GET stream (default true)
+ * @returns {Promise<{ok:true, connection:McpConnection} | {ok:false, error:string}>}
+ */
+export async function connectMcpServer(config, deps = {}) {
+  const baseEnv = deps.env ?? process.env;
+  // Credential-named config env values, every header value, every URL query value.
+  const redact = (/** @type string */ text) =>
+    redactSecrets(text, {
+      env: { ...baseEnv, ...(config.transport === "stdio" ? config.env : {}) },
+      values: config.transport === "stdio" ? [] : [...Object.values(config.headers ?? {}), ...new URL(config.url).searchParams.values()],
+    });
+  const r = await connect(config, deps, baseEnv);
+  if (!r.ok) return { ok: false, error: redact(r.error) };
+  const c = r.connection;
+  const clean = (/** @type {any} */ res) => (res.ok ? res : { ...res, error: redact(res.error) });
+  const call = c.callTool;
+  c.callTool = async (tool, args, o) => clean(await call(tool, args, o));
+  const read = c.readResource;
+  c.readResource = async (uri, o) => clean(await read(uri, o));
+  const list = c.listResources;
+  c.listResources = async (o) => clean(await list(o));
+  const refresh = c.refreshTools;
+  c.refreshTools = async () => clean(await refresh());
+  return r;
+}
+
+/**
+ * @param {import('./config.mjs').McpServerConfig} config
+ * @param {Parameters<typeof connectMcpServer>[1] & {}} deps
+ * @param {Record<string,string|undefined>} baseEnv
+ * @returns {Promise<{ok:true, connection:McpConnection} | {ok:false, error:string}>}
+ */
+async function connect(config, deps, baseEnv) {
+  const startupTimeoutMs = deps.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+  const toolTimeoutMs = deps.toolTimeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;
+  const name = config.name;
+
+  const transport =
+    config.transport === "stdio"
+      ? createStdioTransport({
+          command: config.command,
+          args: config.args,
+          env: { ...configuredCommandEnv(baseEnv, { inheritEnv: config.inheritEnv ?? [], passthrough: deps.envPassthrough ?? [] }), ...config.env },
+          cwd: config.cwd ?? deps.cwd,
+          spawnImpl: deps.spawnImpl,
+        })
+      : createHttpTransport({ url: config.url, headers: config.headers, fetchImpl: deps.fetchImpl });
+
+  /** @type {string|null} */
+  let closeReason = null;
+  let toolsChanged = false;
+  const peer = createRpcPeer({
+    send: (m, o) => transport.send(m, o),
+    onNotification: (m) => {
+      if (m.method === "notifications/tools/list_changed") toolsChanged = true;
+    },
+  });
+  const started = transport.start(
+    (msg) => peer.receive(msg),
+    (reason) => {
+      closeReason = reason;
+      peer.close(reason);
+    },
+  );
+  const describe = (/** @type string */ why) => {
+    const tail = transport.stderrTail();
+    return `MCP server "${name}": ${why}${tail ? `\n--- server stderr (tail) ---\n${tail}` : ""}`;
+  };
+  if (!started.ok) return { ok: false, error: describe(started.error) };
+
+  const fail = async (/** @type string */ why) => {
+    await transport.close();
+    return { ok: /** @type {false} */ (false), error: describe(why) };
+  };
+
+  const init = await peer.request(
+    "initialize",
+    { protocolVersion: CLIENT_PROTOCOL_VERSION, capabilities: {}, clientInfo: deps.clientInfo ?? { name: "cohort-engine", version: "0" } },
+    { timeoutMs: startupTimeoutMs },
+  );
+  if (!init.ok) return fail(`initialize failed: ${init.error.message}`);
+  const version = init.result?.protocolVersion;
+  if (!SUPPORTED_PROTOCOL_VERSIONS.includes(version)) {
+    return fail(`the server speaks protocol version ${JSON.stringify(version)}; supported: ${SUPPORTED_PROTOCOL_VERSIONS.join(", ")}`);
+  }
+  if ("setProtocolVersion" in transport) transport.setProtocolVersion(version);
+  peer.notify("notifications/initialized");
+  if ("openEventStream" in transport && deps.eventStream !== false) void transport.openEventStream();
+
+  /**
+   * Every page of a list method. A server without the capability (-32601) has none.
+   * @param {string} method @param {string} key @param {{signal?:AbortSignal, timeoutMs:number}} o
+   * @returns {Promise<{ok:true, items:any[]}|{ok:false, error:string}>}
+   */
+  const listAll = async (method, key, o) => {
+    const items = [];
+    let cursor;
+    for (let page = 0; page < MAX_LIST_PAGES; page++) {
+      const listed = await peer.request(method, cursor ? { cursor } : {}, o);
+      if (!listed.ok) {
+        if (listed.error.kind === "rpc" && listed.error.code === -32601 && page === 0) break;
+        return { ok: false, error: `${method} failed: ${listed.error.message}` };
+      }
+      const list = Array.isArray(listed.result?.[key]) ? listed.result[key] : [];
+      items.push(...list);
+      cursor = listed.result?.nextCursor;
+      if (!cursor) break;
+    }
+    return { ok: true, items };
+  };
+
+  const listed = await listAll("tools/list", "tools", { timeoutMs: startupTimeoutMs });
+  if (!listed.ok) return fail(listed.error);
+  const validTools = (/** @type any[] */ items) => items.filter((t) => t && typeof t.name === "string");
+
+  /** @type {McpConnection} */
+  const connection = {
+    name,
+    protocolVersion: version,
+    serverInfo: init.result?.serverInfo ?? null,
+    instructions: typeof init.result?.instructions === "string" ? init.result.instructions : null,
+    capabilities: init.result?.capabilities && typeof init.result.capabilities === "object" ? init.result.capabilities : {},
+    tools: validTools(listed.items),
+    get toolsChanged() {
+      return toolsChanged;
+    },
+    isAlive: () => closeReason === null && !peer.closed,
+    async refreshTools() {
+      if (!connection.isAlive()) return { ok: false, error: describe(`is not running (${closeReason ?? "closed"}); its tools could not be re-listed`) };
+      toolsChanged = false;
+      const again = await listAll("tools/list", "tools", { timeoutMs: startupTimeoutMs });
+      if (!again.ok) return { ok: false, error: describe(again.error) };
+      connection.tools = validTools(again.items);
+      return { ok: true, tools: connection.tools };
+    },
+    async callTool(tool, args, o = {}) {
+      if (!connection.isAlive()) return { ok: false, error: describe(`is not running (${closeReason ?? "closed"}); ${tool} was not called`) };
+      const r = await peer.request("tools/call", { name: tool, arguments: args ?? {} }, { signal: o.signal, timeoutMs: o.timeoutMs ?? toolTimeoutMs });
+      if (r.ok) return mapCallToolResult(r.result, { attachImages: true });
+      return rpcFailure(r.error, tool);
+    },
+    async listResources(o = {}) {
+      if (!connection.isAlive()) return { ok: false, error: describe(`is not running (${closeReason ?? "closed"})`) };
+      const r = await listAll("resources/list", "resources", { signal: o.signal, timeoutMs: startupTimeoutMs });
+      return r.ok ? { ok: true, resources: r.items.filter((x) => x && typeof x.uri === "string") } : { ok: false, error: describe(r.error) };
+    },
+    async readResource(uri, o = {}) {
+      if (!connection.isAlive()) return { ok: false, error: describe(`is not running (${closeReason ?? "closed"}); ${uri} was not read`) };
+      const r = await peer.request("resources/read", { uri }, { signal: o.signal, timeoutMs: toolTimeoutMs });
+      if (r.ok) return mapReadResourceResult(r.result, { attachImages: true });
+      return rpcFailure(r.error, `resources/read ${uri}`);
+    },
+    async close() {
+      peer.close("closed by the engine");
+      await transport.close();
+    },
+  };
+
+  /** @param {import('./jsonrpc.mjs').RpcError} error @param {string} what @returns {{ok:false, error:string}} */
+  function rpcFailure(error, what) {
+    switch (error.kind) {
+      case "rpc":
+        return { ok: false, error: `MCP server "${name}" refused ${what}: ${error.message} (code ${error.code})` };
+      case "aborted":
+        return { ok: false, error: `${what} was cancelled.` };
+      case "timeout":
+        return { ok: false, error: `MCP server "${name}" did not answer ${what}: ${error.message}` };
+      default:
+        return { ok: false, error: describe(`failed during ${what}: ${error.message}`) };
+    }
+  }
+  return { ok: true, connection };
+}

package/lib/engine/mcp/config.mjs

@@ -0,0 +1,301 @@
+/**
+ * lib/engine/mcp/config.mjs — which MCP servers a run connects to.
+ *
+ * Config shape (the one maestro's `.mcp.json` and `~/.claude.json` already use):
+ *
+ *   { "mcpServers": {
+ *       "<name>": { "command": "cohort-mcp", "args": [], "env": {} },                 // stdio
+ *       "<name>": { "type": "http", "url": "https://…/mcp", "headers": {} } } }       // streamable HTTP
+ *
+ * `type` may be omitted or "stdio" for a command server; "http" (alias
+ * "streamable-http") for a URL server. The legacy HTTP+SSE transport ("sse")
+ * is refused with a clear error rather than half-supported.
+ *
+ * `${VAR}` and `${VAR:-default}` are expanded from the environment in
+ * command, args, env values, url and headers. An unset variable with no default
+ * is an error for that server (it would otherwise connect with an empty token).
+ *
+ * Layers, lowest to highest precedence (a later layer's server with the same
+ * name replaces an earlier one):
+ *
+ *   user     ~/.claude.json            mcpServers
+ *   project  <cwd>/.mcp.json           mcpServers
+ *   local    ~/.claude.json            projects[<cwd>].mcpServers
+ *   cli      --mcp-config <file|json>  (repeatable; later flags win)
+ *
+ * `--strict-mcp-config` uses ONLY the cli layer.
+ *
+ * The project layer is the repository's word, so it is trusted less:
+ *   · a project server starts only when approved (`filterProjectServers`):
+ *     `enableAllProjectMcpServers: true` or its name in `enabledMcpjsonServers`,
+ *     from user, managed or cli settings or from ~/.claude.json's
+ *     projects[<cwd>] entry; a name in `disabledMcpjsonServers` never starts;
+ *   · its `${VAR}` placeholders may not name a credential-shaped variable
+ *     (context/child-env.mjs): a repository cannot send the gateway token, a
+ *     provider key or the org token to a URL it chose;
+ *   · its `inheritEnv` may not list one either (CF-22);
+ *   · nor, for either, a variable whose VALUE looks like a credential, whatever
+ *     its name (`DATABASE_URL` with a password: context/secret-values.mjs, CF-118).
+ *
+ * `inheritEnv: ["NAME", …]` on a stdio entry is the credential opt-in: a stdio
+ * server inherits no credential-shaped variable unless its entry names it
+ * (context/child-env.mjs).
+ *
+ * Parsing and layering are pure (`parseMcpConfigText`, `resolveMcpServers`);
+ * the two readers take an injected `readFile`.
+ *
+ * @module lib/engine/mcp/config
+ */
+
+import path from "node:path";
+import { validateServerName } from "./naming.mjs";
+import { isCredentialEnv, parseEnvNameList } from "../context/child-env.mjs";
+
+/**
+ * @typedef {{name:string, source:string, transport:'stdio', command:string, args:string[], env:Record<string,string>, inheritEnv?:string[], cwd?:string}} StdioServerConfig
+ * @typedef {{name:string, source:string, transport:'http', url:string, headers:Record<string,string>}} HttpServerConfig
+ * @typedef {StdioServerConfig | HttpServerConfig} McpServerConfig
+ */
+
+/**
+ * Expand `${VAR}` / `${VAR:-default}`.
+ * @param {string} s
+ * @param {Record<string,string|undefined>} env
+ * @param {{refuse?:(name:string)=>boolean}} [o]  names that may not be expanded here
+ * @returns {{ok:true, value:string} | {ok:false, error:string}}
+ */
+export function expandEnvVars(s, env, o = {}) {
+  let missing = null;
+  let refused = null;
+  const value = String(s).replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_, name, def) => {
+    if (o.refuse?.(name)) {
+      refused ??= name;
+      return "";
+    }
+    const v = env[name];
+    if (v !== undefined && v !== "") return v;
+    if (def !== undefined) return def;
+    missing ??= name;
+    return "";
+  });
+  if (refused) return { ok: false, error: `environment variable ${refused} is a credential and may not be expanded in a project .mcp.json` };
+  return missing ? { ok: false, error: `environment variable ${missing} is not set` } : { ok: true, value };
+}
+
+/**
+ * @param {string} name
+ * @param {unknown} raw
+ * @param {string} source
+ * @param {Record<string,string|undefined>} env
+ * @param {{refuse?:(name:string)=>boolean}} [expandOpts]
+ * @returns {{ok:true, server:McpServerConfig} | {ok:false, error:string}}
+ */
+export function parseServerEntry(name, raw, source, env = {}, expandOpts = {}) {
+  const fail = (/** @type string */ msg) => ({ ok: /** @type {false} */ (false), error: `MCP server "${name}" (${source}): ${msg}` });
+  const nameOk = validateServerName(name);
+  if (!nameOk.ok) return { ok: false, error: `${nameOk.error} (${source})` };
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return fail("entry must be an object");
+  const r = /** @type {any} */ (raw);
+  const type = r.type ?? (r.url !== undefined && r.command === undefined ? "http" : "stdio");
+  const expand = (/** @type {unknown} */ v, /** @type string */ what) => {
+    if (typeof v !== "string") return { ok: false, error: `${what} must be a string` };
+    return expandEnvVars(v, env, expandOpts);
+  };
+  const expandMap = (/** @type {unknown} */ m, /** @type string */ what) => {
+    if (m === undefined || m === null) return { ok: true, value: {} };
+    if (typeof m !== "object" || Array.isArray(m)) return { ok: false, error: `${what} must be an object` };
+    /** @type {Record<string,string>} */
+    const out = {};
+    for (const [k, v] of Object.entries(m)) {
+      const e = expand(v, `${what}.${k}`);
+      if (!e.ok) return { ok: false, error: `${what}.${k}: ${e.error}` };
+      out[k] = e.value;
+    }
+    return { ok: true, value: out };
+  };
+
+  if (type === "stdio") {
+    const cmd = expand(r.command, "command");
+    if (!cmd.ok) return fail(cmd.error);
+    if (cmd.value.trim() === "") return fail("command is empty");
+    const args = [];
+    if (r.args !== undefined) {
+      if (!Array.isArray(r.args)) return fail("args must be an array of strings");
+      for (const [i, a] of r.args.entries()) {
+        const e = expand(a, `args[${i}]`);
+        if (!e.ok) return fail(`args[${i}]: ${e.error}`);
+        args.push(e.value);
+      }
+    }
+    const envMap = expandMap(r.env, "env");
+    if (!envMap.ok) return fail(envMap.error);
+    // CF-22: the credentials this server inherits, by name. A project .mcp.json may not list one.
+    const inherit = parseEnvNameList(r.inheritEnv);
+    if (!inherit.ok) return fail(`inheritEnv ${inherit.error}`);
+    const refusedInherit = expandOpts.refuse ? inherit.names.find((n) => expandOpts.refuse?.(n)) : undefined;
+    if (refusedInherit) return fail(`inheritEnv names ${refusedInherit}, a credential, which a project .mcp.json may not pass to a server`);
+    /** @type {StdioServerConfig} */
+    const server = { name, source, transport: "stdio", command: cmd.value, args, env: envMap.value };
+    if (inherit.names.length > 0) server.inheritEnv = inherit.names;
+    if (typeof r.cwd === "string") server.cwd = r.cwd;
+    return { ok: true, server };
+  }
+  if (type === "http" || type === "streamable-http") {
+    const url = expand(r.url, "url");
+    if (!url.ok) return fail(url.error);
+    try {
+      const u = new URL(url.value);
+      if (u.protocol !== "http:" && u.protocol !== "https:") return fail(`url must be http(s), got ${u.protocol}`);
+    } catch {
+      return fail(`url "${url.value}" is not a valid URL`);
+    }
+    const headers = expandMap(r.headers, "headers");
+    if (!headers.ok) return fail(headers.error);
+    return { ok: true, server: { name, source, transport: "http", url: url.value, headers: headers.value } };
+  }
+  if (type === "sse") return fail('the legacy "sse" transport is not supported; use a streamable HTTP endpoint ("type": "http")');
+  return fail(`unknown transport type "${String(type)}"`);
+}
+
+/**
+ * @param {unknown} doc  a parsed config document ({mcpServers:{…}})
+ * @param {string} source
+ * @param {Record<string,string|undefined>} env
+ * @param {{refuse?:(name:string)=>boolean}} [expandOpts]
+ * @returns {{servers: McpServerConfig[], errors: string[]}}
+ */
+export function serversFromDocument(doc, source, env = {}, expandOpts = {}) {
+  /** @type {McpServerConfig[]} */
+  const servers = [];
+  const errors = [];
+  if (doc === undefined || doc === null) return { servers, errors };
+  if (typeof doc !== "object" || Array.isArray(doc)) return { servers, errors: [`${source}: MCP config must be a JSON object`] };
+  const map = /** @type {any} */ (doc).mcpServers;
+  if (map === undefined) return { servers, errors };
+  if (!map || typeof map !== "object" || Array.isArray(map)) return { servers, errors: [`${source}: "mcpServers" must be an object`] };
+  for (const [name, raw] of Object.entries(map)) {
+    const r = parseServerEntry(name, raw, source, env, expandOpts);
+    if (r.ok) servers.push(r.server);
+    else errors.push(r.error);
+  }
+  return { servers, errors };
+}
+
+/**
+ * @param {string} text
+ * @param {string} source
+ * @param {Record<string,string|undefined>} env
+ * @param {{refuse?:(name:string)=>boolean}} [expandOpts]
+ * @returns {{servers: McpServerConfig[], errors: string[]}}
+ */
+export function parseMcpConfigText(text, source, env = {}, expandOpts = {}) {
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch (e) {
+    return { servers: [], errors: [`${source}: not valid JSON (${e instanceof Error ? e.message : e})`] };
+  }
+  return serversFromDocument(doc, source, env, expandOpts);
+}
+
+/**
+ * One `--mcp-config` value: inline JSON when it starts with "{", else a path.
+ * @param {string} value
+ * @param {{cwd:string, readFile:(p:string)=>string, env?:Record<string,string|undefined>}} deps
+ */
+export function readMcpConfigArg(value, { cwd, readFile, env = {} }) {
+  const v = String(value).trim();
+  if (v.startsWith("{")) return parseMcpConfigText(v, "--mcp-config (inline)", env);
+  const file = path.resolve(cwd, v);
+  let text;
+  try {
+    text = readFile(file);
+  } catch (e) {
+    return { servers: [], errors: [`--mcp-config ${file}: cannot read (${e instanceof Error ? e.message : e})`] };
+  }
+  return parseMcpConfigText(text, `--mcp-config ${file}`, env);
+}
+
+/**
+ * The user, project and local layers from disk. A missing file is an empty
+ * layer; an unreadable or malformed one is an error, never a silent skip.
+ * @param {{homedir:string|null, cwd:string, readFile:(p:string)=>string, exists:(p:string)=>boolean, env?:Record<string,string|undefined>}} deps
+ */
+export function loadMcpLayers({ homedir, cwd, readFile, exists, env = {} }) {
+  const errors = [];
+  /** @type {{user:McpServerConfig[], project:McpServerConfig[], local:McpServerConfig[]}} */
+  const layers = { user: [], project: [], local: [] };
+  /** Approval recorded in ~/.claude.json projects[<cwd>] (a user-owned file). */
+  const approval = { enableAll: /** @type {boolean|null} */ (null), enabled: /** @type {string[]} */ ([]), disabled: /** @type {string[]} */ ([]) };
+
+  if (homedir) {
+    const file = path.join(homedir, ".claude.json");
+    if (exists(file)) {
+      try {
+        const doc = JSON.parse(readFile(file));
+        const u = serversFromDocument({ mcpServers: doc?.mcpServers }, `user ${file}`, env);
+        layers.user = u.servers;
+        errors.push(...u.errors);
+        const proj = doc?.projects && typeof doc.projects === "object" ? doc.projects[cwd] : undefined;
+        if (proj && typeof proj.enableAllProjectMcpServers === "boolean") approval.enableAll = proj.enableAllProjectMcpServers;
+        if (proj && Array.isArray(proj.enabledMcpjsonServers)) approval.enabled.push(...proj.enabledMcpjsonServers.map(String));
+        if (proj && Array.isArray(proj.disabledMcpjsonServers)) approval.disabled.push(...proj.disabledMcpjsonServers.map(String));
+        if (proj && proj.mcpServers) {
+          const l = serversFromDocument({ mcpServers: proj.mcpServers }, `local ${file} (projects["${cwd}"])`, env);
+          layers.local = l.servers;
+          errors.push(...l.errors);
+        }
+      } catch (e) {
+        errors.push(`user ${file}: cannot read MCP servers (${e instanceof Error ? e.message : e})`);
+      }
+    }
+  }
+  const projectFile = path.join(cwd, ".mcp.json");
+  if (exists(projectFile)) {
+    try {
+      const p = parseMcpConfigText(readFile(projectFile), `project ${projectFile}`, env, { refuse: (n) => isCredentialEnv(n, env[n]) });
+      layers.project = p.servers;
+      errors.push(...p.errors);
+    } catch (e) {
+      errors.push(`project ${projectFile}: cannot read (${e instanceof Error ? e.message : e})`);
+    }
+  }
+  return { layers, errors, approval };
+}
+
+/**
+ * Keep only the project servers that are approved (pure).
+ * @param {McpServerConfig[]} servers  the project layer
+ * @param {Array<{enableAll?:boolean|null, enabled?:string[], disabled?:string[]}>} approvals  lowest precedence first
+ * @returns {{servers: McpServerConfig[], unapproved: McpServerConfig[], disabled: McpServerConfig[]}}
+ */
+export function filterProjectServers(servers, approvals) {
+  let enableAll = false;
+  const enabled = new Set();
+  const disabled = new Set();
+  for (const a of approvals) {
+    if (typeof a.enableAll === "boolean") enableAll = a.enableAll;
+    for (const n of a.enabled ?? []) enabled.add(n);
+    for (const n of a.disabled ?? []) disabled.add(n);
+  }
+  const out = { servers: /** @type {McpServerConfig[]} */ ([]), unapproved: /** @type {McpServerConfig[]} */ ([]), disabled: /** @type {McpServerConfig[]} */ ([]) };
+  for (const s of servers) {
+    if (disabled.has(s.name)) out.disabled.push(s);
+    else if (enableAll || enabled.has(s.name)) out.servers.push(s);
+    else out.unapproved.push(s);
+  }
+  return out;
+}
+
+/**
+ * Merge layers into the final server list (pure).
+ * @param {{cli: McpServerConfig[], strict: boolean, user?: McpServerConfig[], project?: McpServerConfig[], local?: McpServerConfig[]}} p
+ * @returns {McpServerConfig[]} in first-seen order, later layers replacing earlier entries
+ */
+export function resolveMcpServers({ cli, strict, user = [], project = [], local = [] }) {
+  const ordered = strict ? [cli] : [user, project, local, cli];
+  /** @type {Map<string, McpServerConfig>} */
+  const byName = new Map();
+  for (const layer of ordered) for (const s of layer) byName.set(s.name, s);
+  return [...byName.values()];
+}