@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/engine/mcp/http.mjs

@@ -0,0 +1,201 @@
+/**
+ * lib/engine/mcp/http.mjs — the MCP streamable HTTP transport (client side).
+ *
+ * Per the MCP specification (2025-03-26 and 2025-06-18):
+ *   · every client message is an HTTP POST of one JSON-RPC message to the
+ *     endpoint, with `Accept: application/json, text/event-stream`;
+ *   · a notification or response is answered 202 Accepted with no body;
+ *   · a request is answered either with `application/json` (the response
+ *     object) or with `text/event-stream`, whose `data:` frames carry JSON-RPC
+ *     messages — possibly server requests first — ending with the response;
+ *   · the server may assign a session in the initialize response's
+ *     `Mcp-Session-Id` header, which the client then sends on every request;
+ *     a 404 for a request carrying it means the session has expired;
+ *   · after initialization the client sends `MCP-Protocol-Version`;
+ *   · the client ends a session with an HTTP DELETE carrying the session id.
+ *
+ * The optional GET stream for server-initiated messages (`openEventStream`)
+ * is opened once after initialization, with `Accept: text/event-stream` and
+ * the session headers. A server that does not offer it answers 405 (or any
+ * non-stream response), which is not an error. Messages on it — typically
+ * `notifications/tools/list_changed` — are delivered like any other. If the
+ * server ends the stream it is not reopened; it is aborted when the session
+ * closes.
+ *
+ * @module lib/engine/mcp/http
+ */
+
+import { readSse } from "../wire/sse.mjs";
+
+/**
+ * @param {object} p
+ * @param {string} p.url
+ * @param {Record<string,string>} [p.headers]
+ * @param {typeof fetch} [p.fetchImpl]
+ */
+export function createHttpTransport({ url, headers = {}, fetchImpl = fetch }) {
+  /** @type {string|null} */
+  let sessionId = null;
+  /** @type {string|null} */
+  let protocolVersion = null;
+  /** @type {(msg:unknown)=>void} */
+  let deliver = () => {};
+  let closed = false;
+  const inflight = new Set();
+  /** @type {AbortController|null} */
+  let streamController = null;
+
+  const requestHeaders = () => ({
+    ...headers,
+    "content-type": "application/json",
+    accept: "application/json, text/event-stream",
+    ...(sessionId ? { "mcp-session-id": sessionId } : {}),
+    ...(protocolVersion ? { "mcp-protocol-version": protocolVersion } : {}),
+  });
+
+  return {
+    /** @param {(msg:unknown)=>void} onMessage @param {(reason:string)=>void} _onClose */
+    start(onMessage, _onClose) {
+      deliver = onMessage;
+      return { ok: true };
+    },
+
+    /** @param {string} v */
+    setProtocolVersion(v) {
+      protocolVersion = v;
+    },
+
+    get sessionId() {
+      return sessionId;
+    },
+
+    /**
+     * @param {any} msg
+     * @param {{signal?:AbortSignal}} [o]
+     * @returns {Promise<{ok:true, completed?:boolean}|{ok:false, error:string}>}
+     */
+    async send(msg, o = {}) {
+      if (closed) return { ok: false, error: "the HTTP session is closed" };
+      const controller = new AbortController();
+      const onAbort = () => controller.abort();
+      o.signal?.addEventListener("abort", onAbort, { once: true });
+      inflight.add(controller);
+      try {
+        const hadSession = sessionId !== null;
+        let res;
+        try {
+          res = await fetchImpl(url, { method: "POST", headers: requestHeaders(), body: JSON.stringify(msg), signal: controller.signal });
+        } catch (e) {
+          return { ok: false, error: `HTTP request to ${url} failed: ${e instanceof Error ? e.message : e}` };
+        }
+        const assigned = res.headers.get("mcp-session-id");
+        if (assigned && msg.method === "initialize") sessionId = assigned;
+        if (res.status === 202) return { ok: true, completed: msg.id !== undefined };
+        if (res.status === 404 && hadSession) {
+          await res.body?.cancel().catch(() => {});
+          return { ok: false, error: "the MCP server's session has expired (HTTP 404)" };
+        }
+        if (!res.ok) {
+          const text = await res.text().catch(() => "");
+          return { ok: false, error: `HTTP ${res.status} from ${url}${text ? `: ${text.slice(0, 300)}` : ""}` };
+        }
+        const type = (res.headers.get("content-type") || "").toLowerCase();
+        if (type.includes("text/event-stream")) {
+          if (!res.body) return { ok: true, completed: true };
+          try {
+            for await (const frame of readSse(res.body)) {
+              if (!frame.data) continue;
+              try {
+                deliver(JSON.parse(frame.data));
+              } catch {
+                /* a non-JSON frame is not a message */
+              }
+            }
+          } catch (e) {
+            return { ok: false, error: `the response stream from ${url} broke: ${e instanceof Error ? e.message : e}` };
+          }
+          return { ok: true, completed: true };
+        }
+        const text = await res.text();
+        if (text.trim() === "") return { ok: true, completed: true };
+        try {
+          deliver(JSON.parse(text));
+        } catch {
+          return { ok: false, error: `the response from ${url} was not JSON` };
+        }
+        return { ok: true, completed: true };
+      } finally {
+        inflight.delete(controller);
+        o.signal?.removeEventListener("abort", onAbort);
+      }
+    },
+
+    /**
+     * Open the GET stream for server-initiated messages (once). Never rejects.
+     * @returns {Promise<{ok:true}|{ok:false, status:number|null}>}
+     */
+    async openEventStream() {
+      if (closed || streamController) return { ok: false, status: null };
+      const controller = new AbortController();
+      streamController = controller;
+      let res;
+      try {
+        res = await fetchImpl(url, {
+          method: "GET",
+          headers: {
+            ...headers,
+            accept: "text/event-stream",
+            ...(sessionId ? { "mcp-session-id": sessionId } : {}),
+            ...(protocolVersion ? { "mcp-protocol-version": protocolVersion } : {}),
+          },
+          signal: controller.signal,
+        });
+      } catch {
+        return { ok: false, status: null };
+      }
+      const type = (res.headers.get("content-type") || "").toLowerCase();
+      if (!res.ok || !type.includes("text/event-stream") || !res.body) {
+        await res.body?.cancel().catch(() => {});
+        return { ok: false, status: res.status };
+      }
+      const body = res.body;
+      void (async () => {
+        try {
+          for await (const frame of readSse(body)) {
+            if (!frame.data) continue;
+            try {
+              deliver(JSON.parse(frame.data));
+            } catch {
+              /* a non-JSON frame is not a message */
+            }
+          }
+        } catch {
+          /* the stream ended or was aborted; it is optional */
+        }
+      })();
+      return { ok: true };
+    },
+
+    stderrTail: () => "",
+
+    /** End the session (best effort) and abort anything still in flight. */
+    async close() {
+      if (closed) return;
+      closed = true;
+      streamController?.abort();
+      for (const c of inflight) c.abort();
+      if (!sessionId) return;
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), 2_000);
+      timer.unref?.();
+      try {
+        const res = await fetchImpl(url, { method: "DELETE", headers: { ...headers, "mcp-session-id": sessionId }, signal: controller.signal });
+        await res.body?.cancel().catch(() => {});
+      } catch {
+        /* the server may not allow DELETE (405) or may already be gone */
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+  };
+}

package/lib/engine/mcp/index.mjs

@@ -0,0 +1,146 @@
+/**
+ * lib/engine/mcp/index.mjs — MCP servers → engine tools.
+ *
+ * `startMcpServers` connects every configured server in parallel and turns
+ * each tool it lists into an engine tool object named `mcp__<server>__<tool>`
+ * (see naming.mjs). A server that fails to start is reported in `statuses` and
+ * `errors`, and the run continues without it — the same posture as a tool
+ * that errors. A tool whose name is too long or collides is reported and not
+ * exposed.
+ *
+ * Each connection is supervised (supervisor.mjs): a stdio server that crashes
+ * is restarted once, on the next call. `refreshChanged` re-lists the tools of
+ * servers that sent `notifications/tools/list_changed` (or came back with a
+ * different list after a restart) and rebuilds the tool list; the run calls it
+ * at a turn boundary.
+ *
+ * MCP tools are marked `passthroughInput`: their input schemas are the
+ * server's, which the engine's small validator does not fully understand, so
+ * the loop checks only that the input is an object with the required keys and
+ * forwards it unchanged.
+ *
+ * @module lib/engine/mcp/index
+ */
+
+import { connectMcpServer } from "./client.mjs";
+import { mcpToolName } from "./naming.mjs";
+import { superviseConnection } from "./supervisor.mjs";
+
+/**
+ * @typedef {{name:string, source:string, transport:string, status:'connected'|'failed', tools:number, error?:string}} McpServerStatus
+ * @typedef {ReturnType<typeof superviseConnection>} SupervisedConnection
+ */
+
+/**
+ * @param {import('./config.mjs').McpServerConfig[]} servers
+ * @param {Parameters<typeof connectMcpServer>[1] & {connect?:typeof connectMcpServer}} [deps]
+ */
+export async function startMcpServers(servers, deps = {}) {
+  const connect = deps.connect ?? connectMcpServer;
+  const connected = await Promise.all(servers.map((s) => connect(s, deps).then((r) => ({ s, r }))));
+  /** @type {McpServerStatus[]} */
+  const statuses = [];
+  /** @type {string[]} */
+  const errors = [];
+  /** @type {Array<{s:import('./config.mjs').McpServerConfig, conn:SupervisedConnection, status:McpServerStatus}>} */
+  const live = [];
+
+  for (const { s, r } of connected) {
+    if (!r.ok) {
+      statuses.push({ name: s.name, source: s.source, transport: s.transport, status: "failed", tools: 0, error: r.error });
+      errors.push(r.error);
+      continue;
+    }
+    const status = { name: s.name, source: s.source, transport: s.transport, status: /** @type {'connected'} */ ("connected"), tools: 0 };
+    statuses.push(status);
+    live.push({ s, conn: superviseConnection(s, deps, r.connection, { connect }), status });
+  }
+
+  /** @param {string[]} sink */
+  const build = (sink) => {
+    /** @type {import('../tools/index.mjs').Tool[]} */
+    const tools = [];
+    const taken = new Set();
+    for (const { s, conn, status } of live) {
+      let count = 0;
+      for (const t of conn.tools) {
+        const named = mcpToolName(s.name, t.name);
+        if (!named.ok) {
+          sink.push(named.error);
+          continue;
+        }
+        if (taken.has(named.name)) {
+          sink.push(`MCP tool name "${named.name}" is produced by more than one tool; only the first is exposed`);
+          continue;
+        }
+        taken.add(named.name);
+        tools.push(mcpTool(named.name, s, t, conn));
+        count++;
+      }
+      status.tools = count;
+    }
+    return tools;
+  };
+  let tools = build(errors);
+
+  return {
+    get tools() {
+      return tools;
+    },
+    statuses,
+    errors,
+    /** @type {SupervisedConnection[]} */
+    connections: live.map((l) => l.conn),
+    /**
+     * Re-list servers whose tools changed; rebuild the tool list if any did.
+     * @returns {Promise<{changed:boolean, tools:import('../tools/index.mjs').Tool[], errors:string[]}>}
+     */
+    async refreshChanged() {
+      const problems = [];
+      let changed = false;
+      for (const { conn } of live) {
+        if (!conn.toolsChanged) continue;
+        const r = await conn.refreshTools();
+        if (r.ok) changed = true;
+        else problems.push(r.error);
+      }
+      if (changed) tools = build(problems);
+      return { changed, tools, errors: problems };
+    },
+    /** Shut every server down; never throws. */
+    async close() {
+      await Promise.all(live.map(({ conn }) => conn.close().catch(() => {})));
+    },
+  };
+}
+
+/**
+ * @param {string} name
+ * @param {import('./config.mjs').McpServerConfig} server
+ * @param {{name:string, description?:string, inputSchema?:any, annotations?:{readOnlyHint?:boolean}}} t
+ * @param {{callTool:(tool:string, args:object, o?:{signal?:AbortSignal})=>Promise<any>}} conn
+ * @returns {import('../tools/index.mjs').Tool & {passthroughInput:true, mcp:object}}
+ */
+function mcpTool(name, server, t, conn) {
+  const schema = t.inputSchema && typeof t.inputSchema === "object" && !Array.isArray(t.inputSchema) ? { ...t.inputSchema } : {};
+  if (schema.type === undefined) schema.type = "object";
+  if (schema.properties === undefined) schema.properties = {};
+  return {
+    name,
+    description: typeof t.description === "string" && t.description.trim() !== "" ? t.description : `${t.name} (from the ${server.name} MCP server)`,
+    input_schema: schema,
+    // Read-only hints are the server's claim; they schedule parallel batches
+    // only. No permission is granted on their strength, and plan mode refuses
+    // every MCP tool whatever its hint.
+    readOnly: t.annotations?.readOnlyHint === true,
+    passthroughInput: true,
+    mcp: {
+      server: server.name,
+      tool: t.name,
+      transport: server.transport,
+      command: server.transport === "stdio" ? server.command : null,
+      args: server.transport === "stdio" ? server.args : [],
+    },
+    run: (input, ctx) => conn.callTool(t.name, input, { signal: ctx.signal }),
+  };
+}

package/lib/engine/mcp/jsonrpc.mjs

@@ -0,0 +1,147 @@
+/**
+ * lib/engine/mcp/jsonrpc.mjs — a JSON-RPC 2.0 peer, transport-agnostic.
+ *
+ * The MCP client is one of these over a transport. The peer owns request ids,
+ * the pending-request table, per-request timeouts and cancellation, and the
+ * replies to the few requests a server may send the client (`ping`). It never
+ * rejects: every request resolves to a result union, so a dead server is a
+ * value the caller reports, not an exception that unwinds a run.
+ *
+ * @module lib/engine/mcp/jsonrpc
+ */
+
+/**
+ * @typedef {{kind:'rpc', code:number, message:string, data?:unknown}
+ *   | {kind:'timeout', message:string}
+ *   | {kind:'closed', message:string}
+ *   | {kind:'aborted', message:string}
+ *   | {kind:'transport', message:string}} RpcError
+ * @typedef {{ok:true, result:any} | {ok:false, error:RpcError}} RpcOutcome
+ */
+
+/**
+ * @param {object} p
+ * @param {(msg:object, o?:{signal?:AbortSignal}) => ({ok:true, completed?:boolean}|{ok:false, error:string}|Promise<{ok:true, completed?:boolean}|{ok:false, error:string}>)} p.send
+ *   `completed:true` means the transport has delivered everything it will ever
+ *   deliver for this message (an HTTP response body has ended).
+ * @param {(line:string) => void} [p.log]
+ * @param {(msg:{method:string, params?:any}) => void} [p.onNotification]  server notifications
+ *   (e.g. notifications/tools/list_changed); a throwing handler is contained
+ */
+export function createRpcPeer({ send, log = () => {}, onNotification = () => {} }) {
+  let nextId = 1;
+  /** @type {Map<number, (o:RpcOutcome) => void>} */
+  const pending = new Map();
+  /** @type {string|null} */
+  let closedReason = null;
+
+  /**
+   * @param {string} method
+   * @param {object} [params]
+   * @param {{timeoutMs?:number, signal?:AbortSignal}} [o]
+   * @returns {Promise<RpcOutcome>}
+   */
+  function request(method, params, o = {}) {
+    if (closedReason !== null) return Promise.resolve({ ok: false, error: { kind: "closed", message: closedReason } });
+    const id = nextId++;
+    return new Promise((resolve) => {
+      /** @type {ReturnType<typeof setTimeout>|null} */
+      let timer = null;
+      const onAbort = () => {
+        finish({ ok: false, error: { kind: "aborted", message: "the request was cancelled" } });
+        notify("notifications/cancelled", { requestId: id, reason: "cancelled by the client" });
+      };
+      const finish = (/** @type RpcOutcome */ outcome) => {
+        if (!pending.has(id)) return;
+        pending.delete(id);
+        if (timer) clearTimeout(timer);
+        o.signal?.removeEventListener("abort", onAbort);
+        resolve(outcome);
+      };
+      pending.set(id, finish);
+      if (o.timeoutMs && o.timeoutMs > 0) {
+        timer = setTimeout(() => {
+          finish({ ok: false, error: { kind: "timeout", message: `no response to ${method} within ${o.timeoutMs} ms` } });
+          notify("notifications/cancelled", { requestId: id, reason: "timed out" });
+        }, o.timeoutMs);
+        // Not unref'd: a caller awaiting only this request must keep the
+        // process alive until it resolves. `finish` always clears it.
+      }
+      if (o.signal?.aborted) return onAbort();
+      o.signal?.addEventListener("abort", onAbort, { once: true });
+
+      const msg = { jsonrpc: "2.0", id, method, ...(params === undefined ? {} : { params }) };
+      Promise.resolve()
+        .then(() => send(msg, { signal: o.signal }))
+        .then(
+          (r) => {
+            if (!r.ok) finish({ ok: false, error: { kind: "transport", message: r.error } });
+            else if (r.completed) finish({ ok: false, error: { kind: "transport", message: `the server ended its response to ${method} without answering it` } });
+          },
+          (e) => finish({ ok: false, error: { kind: "transport", message: e instanceof Error ? e.message : String(e) } }),
+        );
+    });
+  }
+
+  /** @param {string} method @param {object} [params] */
+  function notify(method, params) {
+    if (closedReason !== null) return;
+    const msg = { jsonrpc: "2.0", method, ...(params === undefined ? {} : { params }) };
+    Promise.resolve()
+      .then(() => send(msg))
+      .catch(() => {
+        /* a notification has no one to report a failure to */
+      });
+  }
+
+  /** @param {unknown} msg  a parsed frame from the transport (object or batch array) */
+  function receive(msg) {
+    if (Array.isArray(msg)) {
+      for (const m of msg) receive(m);
+      return;
+    }
+    if (!msg || typeof msg !== "object") return;
+    const m = /** @type {any} */ (msg);
+    if (m.method !== undefined) {
+      // A request or notification from the server.
+      if (m.id === undefined || m.id === null) {
+        try {
+          onNotification(m);
+        } catch {
+          /* a notification handler defect must not break the connection */
+        }
+        return;
+      }
+      const reply =
+        m.method === "ping"
+          ? { jsonrpc: "2.0", id: m.id, result: {} }
+          : { jsonrpc: "2.0", id: m.id, error: { code: -32601, message: `the client does not support ${m.method}` } };
+      Promise.resolve()
+        .then(() => send(reply))
+        .catch(() => {
+          /* the server will time out its own request */
+        });
+      return;
+    }
+    const finish = pending.get(Number(m.id));
+    if (!finish) {
+      log(`ignored a response for unknown request id ${JSON.stringify(m.id)}`);
+      return;
+    }
+    if (m.error) {
+      const e = m.error;
+      finish({ ok: false, error: { kind: "rpc", code: Number(e.code), message: String(e.message ?? "error"), data: e.data } });
+    } else {
+      finish({ ok: true, result: m.result });
+    }
+  }
+
+  /** Resolve every pending request as closed; later requests resolve closed at once. @param {string} reason */
+  function close(reason) {
+    if (closedReason !== null) return;
+    closedReason = reason;
+    for (const finish of [...pending.values()]) finish({ ok: false, error: { kind: "closed", message: reason } });
+  }
+
+  return { request, notify, receive, close, get closed() { return closedReason !== null; } };
+}

package/lib/engine/mcp/naming.mjs

@@ -0,0 +1,66 @@
+/**
+ * lib/engine/mcp/naming.mjs — how an MCP tool is named to the model (pure).
+ *
+ *   mcp__<server>__<tool>
+ *
+ * This name is a compatibility contract, not a detail: maestro's settings
+ * (`permissions.allow: ["mcp__cohort__*"]`), its PreToolUse matchers
+ * (`mcp__cohort__(messaging_send|…)`), its prompts and skills all spell tools
+ * this way. `naming.test.mjs` pins it.
+ *
+ * Rules:
+ *   · each part (server key, tool name) has every character outside
+ *     [A-Za-z0-9_-] replaced by "_" — the set both gateway wires accept in a
+ *     function name;
+ *   · the whole name may be at most 64 characters (the wire limit). A longer
+ *     name is a RETURNED ERROR. It is never truncated or hashed: a silently
+ *     shortened name would no longer match the permission rules and hook
+ *     matchers written against the real one, which is how a gated tool slips
+ *     through a gate.
+ *
+ * @module lib/engine/mcp/naming
+ */
+
+export const MCP_PREFIX = "mcp__";
+export const MAX_TOOL_NAME_LENGTH = 64;
+
+/** @param {string} part */
+export function sanitiseNamePart(part) {
+  return String(part).replace(/[^A-Za-z0-9_-]/g, "_");
+}
+
+/**
+ * @param {string} server  the server's config key
+ * @param {string} tool    the tool name the server reported
+ * @returns {{ok:true, name:string} | {ok:false, error:string}}
+ */
+export function mcpToolName(server, tool) {
+  if (typeof server !== "string" || server === "") return { ok: false, error: "MCP server name is empty" };
+  if (typeof tool !== "string" || tool === "") return { ok: false, error: `MCP server "${server}" reported a tool with no name` };
+  const name = `${MCP_PREFIX}${sanitiseNamePart(server)}__${sanitiseNamePart(tool)}`;
+  if (name.length > MAX_TOOL_NAME_LENGTH) {
+    return {
+      ok: false,
+      error: `MCP tool "${tool}" on server "${server}" would be named "${name}" (${name.length} characters); the limit is ${MAX_TOOL_NAME_LENGTH}. Rename the server key in the MCP config to something shorter.`,
+    };
+  }
+  return { ok: true, name };
+}
+
+/**
+ * Is a server key usable at all? Checked when the config is read, so a key
+ * too long to leave room for any tool name fails before a process is spawned.
+ * @param {string} server
+ * @returns {{ok:true} | {ok:false, error:string}}
+ */
+export function validateServerName(server) {
+  if (typeof server !== "string" || server.trim() === "") return { ok: false, error: "an MCP server has an empty name" };
+  const prefix = `${MCP_PREFIX}${sanitiseNamePart(server)}__`;
+  if (prefix.length + 1 > MAX_TOOL_NAME_LENGTH) {
+    return {
+      ok: false,
+      error: `MCP server name "${server}" is too long: its tools would be named "${prefix}…", which leaves no room under the ${MAX_TOOL_NAME_LENGTH}-character limit`,
+    };
+  }
+  return { ok: true };
+}

package/lib/engine/mcp/resources.mjs

@@ -0,0 +1,89 @@
+/**
+ * lib/engine/mcp/resources.mjs — ListMcpResources and ReadMcpResource.
+ *
+ * MCP servers can publish resources (files, records, documents) beside their
+ * tools. When at least one connected server declares the `resources`
+ * capability, two engine tools expose them:
+ *
+ *   ListMcpResources {server?}       every resource, or one server's
+ *   ReadMcpResource  {server, uri}   one resource's contents; text passes
+ *                                    through, images are attached for the
+ *                                    wire (within the caps in results.mjs)
+ *
+ * Both are read-only built-ins for permissions. A server whose tools are denied
+ * outright (`mcp__<server>` or `mcp__<server>__*` deny) has its resources
+ * withheld too: it is neither listed nor readable, and when no other server
+ * publishes resources the two tools are not offered. Deny `ReadMcpResource`
+ * itself to withhold every server's resources.
+ *
+ * Authorship: tool descriptions written for Cohort Engine by the Cohort team,
+ * 2026-09-14 (original text).
+ *
+ * @module lib/engine/mcp/resources
+ */
+
+/**
+ * @typedef {{name:string, capabilities:Record<string,any>, listResources:(o?:{signal?:AbortSignal})=>Promise<any>, readResource:(uri:string, o?:{signal?:AbortSignal})=>Promise<any>}} ResourceServer
+ */
+
+/** @param {ResourceServer} c */
+const offersResources = (c) => Boolean(c.capabilities && typeof c.capabilities === "object" && c.capabilities.resources);
+
+/**
+ * @param {() => ResourceServer[]} connections  read at call time (servers can restart)
+ * @param {{isServerDenied?:(name:string)=>boolean}} [o]  a server denied outright keeps its resources to itself
+ * @returns {import('../tools/index.mjs').Tool[]}  empty when no permitted server offers resources
+ */
+export function createMcpResourceTools(connections, { isServerDenied = () => false } = {}) {
+  const servers = () => connections().filter((c) => offersResources(c) && !isServerDenied(c.name));
+  if (servers().length === 0) return [];
+  const names = () => servers().map((c) => c.name).join(", ");
+
+  /** @type {import('../tools/index.mjs').Tool} */
+  const list = {
+    name: "ListMcpResources",
+    readOnly: true,
+    description: "List the resources (documents, files, records) that connected MCP servers publish. Pass `server` to list one server's resources. Read one with ReadMcpResource.",
+    input_schema: { type: "object", properties: { server: { type: "string", description: "Only this MCP server." } } },
+    async run(input, ctx) {
+      const targets = input.server ? servers().filter((c) => c.name === input.server) : servers();
+      if (input.server && targets.length === 0) return { ok: false, error: `No connected MCP server named "${input.server}" publishes resources. Servers with resources: ${names() || "none"}.` };
+      const sections = [];
+      for (const c of targets) {
+        const r = await c.listResources({ signal: ctx.signal });
+        if (!r.ok) {
+          sections.push(`${c.name}: could not list resources (${r.error})`);
+          continue;
+        }
+        if (r.resources.length === 0) {
+          sections.push(`${c.name}: no resources`);
+          continue;
+        }
+        const lines = r.resources.map((/** @type any */ x) => `- ${x.uri}${x.name ? ` — ${x.name}` : ""}${x.mimeType ? ` (${x.mimeType})` : ""}${x.description ? `: ${String(x.description).replace(/\s+/g, " ")}` : ""}`);
+        sections.push(`${c.name}:\n${lines.join("\n")}`);
+      }
+      return { ok: true, content: sections.join("\n\n") };
+    },
+  };
+
+  /** @type {import('../tools/index.mjs').Tool} */
+  const read = {
+    name: "ReadMcpResource",
+    readOnly: true,
+    description: "Read one resource from an MCP server by its URI (as listed by ListMcpResources).",
+    input_schema: {
+      type: "object",
+      properties: {
+        server: { type: "string", description: "The MCP server that publishes the resource." },
+        uri: { type: "string", description: "The resource URI." },
+      },
+      required: ["server", "uri"],
+    },
+    async run(input, ctx) {
+      const c = servers().find((s) => s.name === input.server);
+      if (!c) return { ok: false, error: `No connected MCP server named "${input.server}" publishes resources. Servers with resources: ${names() || "none"}.` };
+      return c.readResource(input.uri, { signal: ctx.signal });
+    },
+  };
+  return [list, read];
+}