bare-agent 0.53.0 → 0.54.1

package/bareagent.context.md

@@ -20,7 +20,7 @@ Eight entry points:
 - `require('bare-agent/stores')` — SQLite (FTS5), JsonFile
 - `require('bare-agent/transports')` — JsonlTransport
 - `require('bare-agent/tools')` — createBrowsingTools, createMobileTools, createShellTools, resolveToolPath, createSpawnTool, createDeferTool, spawnChild, readDeferQueue, liteCtxMcpBridgeConfig
-- `require('bare-agent/mcp')` — createMCPBridge (returns `tools` + `metaTools`), discoverServers, buildMetaTools
+- `require('bare-agent/mcp')` — createMCPBridge (returns `tools` + `metaTools`), discoverServers, buildMetaTools, listServerTools
 - `require('bare-agent/bareguard')` — wireGate (one-line bareguard Gate integration), defaultActionTranslator
 
 **TypeScript:** bareagent is pure JS + JSDoc but ships `.d.ts` declarations (generated from that JSDoc, v0.11+). Every entry point above resolves types automatically — `import { Loop } from 'bare-agent'` and `import { OpenAI } from 'bare-agent/providers'` give full autocomplete and type-checking, including required-option enforcement (e.g. `new Loop({})` is a type error: `provider` is required). No `@types/bare-agent` needed. Shared shapes (`Provider`, `Message`, `ToolDef`, `ToolCall`, `Usage`, `GenerateResult`, `Store`) are exported from the package's `types/`. The repo itself runs `tsc --checkJs` in CI on every push/PR so the JSDoc and the code can't drift.
@@ -425,18 +425,23 @@ naming the opt-in — rather than silently ignoring it. Pass `confirmServer(name
 def) => boolean` to approve each server **before its command is spawned** (return
 `false` to skip it; a throw fails closed). When no `confirmServer` is set, the
 bridge still trusts all *discovered* servers and prints a one-time warning naming
-every command it is about to spawn — `confirmServer` is how you actually *gate* it.
+every server and command it is about to spawn (an arg count only, never arg or env values) — `confirmServer` is how you actually *gate* it.
 
 **RPC timeouts (Unreleased).** Every JSON-RPC round-trip is now bounded, so a
 server that never answers can't hang the bridge or the loop. `opts.timeout`
-(default 15 s) bounds the handshake (`initialize` + `tools/list`);
+(default 15 s) bounds the handshake (`initialize` and each `tools/list` page);
 `opts.callTimeout` (default 120 s, `0` disables) bounds each `tools/call`. A
 timed-out tool call rejects with a labelled `ToolError`
 (`MCP server "s" tool "t" timed out after Nms`, `context: { timeout: true, server, tool, timeoutMs, stderr }` —
 stderr is in `context`, not the message; `wireGate`'s `onToolResult` forwards only the
 non-stderr label fields to the audit row as an allow-listed `errorContext`) rather
-than blocking forever; a server that breaks its stdin pipe surfaces as a
-failed connection, never an uncaught `EPIPE` crash.
+than blocking forever; a handshake timeout (`initialize`/`tools/list`) is labelled the same way
+(`MCP server "s" "method" timed out after Nms`, `context: { timeout: true, server, method, timeoutMs, stderr }`);
+a server that breaks its stdin pipe surfaces as a failed connection, never an uncaught `EPIPE`
+crash; and a server whose `command` cannot start (ENOENT/EACCES, or a sync `spawn()` refusal such as an empty command or NUL byte) rejects with
+`MCP server "s" failed to start: command "<cmd>" (<code>)`, `context: { spawnError: true, server, code }`
+(`code` = Node error code if a string, else `'ESPAWN'`; command only with control chars escaped, never args/env) — `listServerTools` throws it, `allow` mode puts it in `errors` + `missing`,
+bulk mode in `errors` — instead of crashing the host.
 
 ## Wiring with bareguard
 
@@ -1535,6 +1540,8 @@ try {
 
 **Signed per-run allow-list (`allow`).** `createMCPBridge({ allow: { server: ['raw_tool_name', ...] } })` skips `.mcp-bridge.json` entirely (never read or written — no cache, no TTL; `bridgePath`/`refresh`/`servers` ignored), takes server definitions only from `discoverServers(configPaths)`, spawns only the named servers (still `confirmServer`-vetted), connects once and exposes signed ∩ listed. Everything else is absent from `tools`, the `metaTools` catalog and `systemContext` (no "Restricted tools" text, `denied: []`), nothing goes to stdout. The return gains `missing: [{server, tool}]` (signed tools the server did not list, or whose server was not found/failed/rejected) — never a throw. `mcp_invoke` of a listed-but-unsigned name throws `ToolError` with `context.denied === true`. Bad `allow` shape (including an empty tool list) throws `ValidationError`. In every mode (not only `allow`), a server whose `tools/list` reply has no `tools` array (e.g. `{}`) now fails its connect — it lands in `errors`, its child is killed — where it used to read as a working empty server.
 
+**Annotations, listing, pagination, `errors` (Unreleased).** If a server sends `annotations` on a tool (`readOnlyHint`, `destructiveHint`, ...), each bridged tool (`ToolDef.annotations`) and each `mcp_discover` catalog entry carries them as the same unmodified object, in every mode; the key is absent when none was sent (a non-object value — null/array/string — is dropped). They are server hints, never authorization, and `systemContext` does not mention them. `listServerTools({ server, configPaths?, confirmServer?, includeProjectConfig?, timeout? })` (`bare-agent/mcp`) returns `[{name, description, annotations?}]` for one server so you can pick an `allow` list: no bridge, never reads or writes `.mcp-bridge.json`, nothing on stdout, vetted by `confirmServer` exactly like `createMCPBridge`, and the child is always killed. It throws (never returns `[]`) on server not found, declined/throwing `confirmServer`, connect/handshake failure, timeout or a malformed reply; one total deadline of 4 x `timeout` bounds the call (a small `timeout` shrinks it proportionally). `tools/list` follows `nextCursor` in every mode; more than 100 pages or a repeated cursor fails that server's connect (in `errors`; in `allow` mode its signed tools land in `missing`) rather than returning a truncated catalog. In bulk mode `errors` is always present and lists each server that did not connect this run, once (first failure message wins); a server that failed discovery but connected from the cached definition is not in `errors` but draws one separate `console.warn` saying the config edit was not applied.
+
 ```json
 {
   "discovered": "2026-04-13T12:00:00.000Z",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.53.0",
+  "version": "0.54.1",
   "files": [
     "index.js",
     "index.d.ts",

package/primitives.json

@@ -123,7 +123,7 @@
       "category": "mcp",
       "when": "you want to auto-discover MCP servers and expose them as bareagent tools in one call — with a trust hook gating command execution, or a per-run signed `allow` list that exposes only the named tools",
       "import": "import { createMCPBridge } from 'bare-agent/mcp'",
-      "signature": "createMCPBridge(opts?: object) => Promise<{tools: ToolDef[], metaTools?: ToolDef[], servers: string[], systemContext: string, denied: DeniedTool[], errors?: Array<{server: string, error: string}>, missing?: Array<{server: string, tool: string}>, close: Function}>",
+      "signature": "createMCPBridge(opts?: object) => Promise<{tools: ToolDef[], metaTools?: ToolDef[], servers: string[], systemContext: string, denied: DeniedTool[], errors: Array<{server: string, error: string}>, missing?: Array<{server: string, tool: string}>, close: Function}>",
       "fails": "a trust hook returning false skips a server (its command never runs) and a throw is fail-closed (deny); with `allow` it is in-memory only (no cache file read or written) and signed tools the server does not list land in `missing`, never a throw; returns tools plus a close() to shut servers down.",
       "example": "const { tools, close } = await createMCPBridge();\nconst loop = new Loop({ provider, tools });"
     },
@@ -262,6 +262,15 @@
       "fails": "never throws and never calls the gate; surfaces fail-open (a non-honored verdict surfaces) and bounds fields against the sink's silent caps with a visible clip marker.",
       "example": "gate.annotate(judgeToAnnotation(await judge({ request, artifact, provider })));"
     },
+    {
+      "name": "listServerTools",
+      "category": "mcp",
+      "when": "you want to list one MCP server's tools and their annotation hints before deciding what to allow — no bridge, no cache file, no tools kept alive",
+      "import": "import { listServerTools } from 'bare-agent/mcp'",
+      "signature": "listServerTools(opts: object) => Promise<Array<{name: string, description: string, annotations?: Record<string, any>}>>",
+      "fails": "throws (never returns []) when the server is not found, confirmServer declines or throws, the connect/handshake fails or times out, the total deadline trips, or the reply is malformed; the child is always reaped.",
+      "example": "const tools = await listServerTools({ server: 'files', configPaths: [cfg] });"
+    },
     {
       "name": "litectxCorpus",
       "category": "integration",

package/src/mcp-bridge.d.ts

@@ -15,6 +15,11 @@ export type McpTool = {
     name: string;
     description?: string | undefined;
     inputSchema?: Record<string, any> | undefined;
+    /**
+     * - Server-supplied behavioural HINTS (readOnlyHint,
+     * destructiveHint, ...). Untrusted metadata from the server: never an authorization signal.
+     */
+    annotations?: Record<string, any> | undefined;
 };
 /**
  * Per-server entry persisted in .mcp-bridge.json.
@@ -103,7 +108,7 @@ export type RpcClient = {
  *   discovered server is trusted — pass this to gate command execution. Presence
  *   of this hook also opts default discovery into the project-cwd `./.mcp.json`,
  *   since each command is then vetted regardless of source.
- * @returns {Promise<{tools: ToolDef[], metaTools?: ToolDef[], servers: string[], systemContext: string, denied: DeniedTool[], errors?: Array<{server: string, error: string}>, missing?: Array<{server: string, tool: string}>, close: Function}>}
+ * @returns {Promise<{tools: ToolDef[], metaTools?: ToolDef[], servers: string[], systemContext: string, denied: DeniedTool[], errors: Array<{server: string, error: string}>, missing?: Array<{server: string, tool: string}>, close: Function}>}
  * @when you want to auto-discover MCP servers and expose them as bareagent tools in one call — with a trust hook gating command execution, or a per-run signed `allow` list that exposes only the named tools
  * @fails a trust hook returning false skips a server (its command never runs) and a throw is fail-closed (deny); with `allow` it is in-memory only (no cache file read or written) and signed tools the server does not list land in `missing`, never a throw; returns tools plus a close() to shut servers down.
  * @example
@@ -126,7 +131,7 @@ export function createMCPBridge(opts?: {
     servers: string[];
     systemContext: string;
     denied: DeniedTool[];
-    errors?: Array<{
+    errors: Array<{
         server: string;
         error: string;
     }>;
@@ -180,3 +185,38 @@ export function buildMetaTools(tools: ToolDef[], discoveredAt?: string, excluded
     server: string;
     tool: string;
 }>): ToolDef[];
+/**
+ * List one configured MCP server's tools WITHOUT building a bridge: discover, vet, connect, list
+ * (following pagination), then always kill the child. Never reads or writes `.mcp-bridge.json`
+ * and prints nothing to stdout. `annotations` are the server's own HINTS, passed through unmodified
+ * (key absent when the server sent none) — never an authorization signal.
+ *
+ * Total wall-clock ceiling is DERIVED: 4 × `timeout` (initialize + three maximally slow pages) over
+ * the connect + list, excluding `confirmServer` (caller code, possibly interactive). On trip the
+ * child is killed and a TimeoutError naming the total deadline rejects. A SMALL `timeout` shrinks the
+ * total proportionally (timeout 500 ⇒ 2s total), so a server with many pages near that speed can trip it.
+ * A non-object `annotations` value from the server is treated as absent (dropped).
+ *
+ * @param {object} opts
+ * @param {string} opts.server - Server name as it appears in the discovered configs.
+ * @param {string[]} [opts.configPaths] - Explicit config paths; omitted ⇒ trusted $HOME/IDE defaults.
+ * @param {(name: string, def: ServerDef) => boolean | Promise<boolean>} [opts.confirmServer] - Same semantics as createMCPBridge: `=== true` proceeds, a throw denies. Implies includeProjectConfig.
+ * @param {boolean} [opts.includeProjectConfig=false] - Also scan `./.mcp.json` during default discovery.
+ * @param {number} [opts.timeout=15000] - Per-round-trip bound in ms (initialize and each tools/list page).
+ * @returns {Promise<Array<{name: string, description: string, annotations?: Record<string, any>}>>}
+ * @when you want to list one MCP server's tools and their annotation hints before deciding what to allow — no bridge, no cache file, no tools kept alive
+ * @fails throws (never returns []) when the server is not found, confirmServer declines or throws, the connect/handshake fails or times out, the total deadline trips, or the reply is malformed; the child is always reaped.
+ * @example
+ *   const tools = await listServerTools({ server: 'files', configPaths: [cfg] });
+ */
+export function listServerTools(opts: {
+    server: string;
+    configPaths?: string[] | undefined;
+    confirmServer?: ((name: string, def: ServerDef) => boolean | Promise<boolean>) | undefined;
+    includeProjectConfig?: boolean | undefined;
+    timeout?: number | undefined;
+}): Promise<Array<{
+    name: string;
+    description: string;
+    annotations?: Record<string, any>;
+}>>;

package/src/mcp-bridge.js

@@ -4,7 +4,7 @@ const { spawn } = require('node:child_process');
 const { readFileSync, writeFileSync, existsSync } = require('node:fs');
 const { join } = require('node:path');
 const { homedir } = require('node:os');
-const { ToolError, ValidationError } = require('./errors');
+const { ToolError, ValidationError, TimeoutError } = require('./errors');
 
 /** @typedef {import('../types').ToolDef} ToolDef */
 
@@ -23,6 +23,8 @@ const { ToolError, ValidationError } = require('./errors');
  * @property {string} name
  * @property {string} [description]
  * @property {Record<string, any>} [inputSchema]
+ * @property {Record<string, any>} [annotations] - Server-supplied behavioural HINTS (readOnlyHint,
+ *   destructiveHint, ...). Untrusted metadata from the server: never an authorization signal.
  */
 
 /**
@@ -229,6 +231,23 @@ function resolveEnv(env) {
 
 // --- JSON-RPC stdio client ---
 
+/**
+ * Labelled spawn-failure error. Names the command ONLY (args/env can carry tokens); control
+ * characters in the command are escaped so a NUL/newline can't corrupt logs. `code` is the Node
+ * error code when it is a string, else 'ESPAWN'.
+ * @param {string} name
+ * @param {any} command
+ * @param {any} err
+ * @returns {ToolError}
+ */
+function spawnFailure(name, command, err) {
+  const code = typeof err?.code === 'string' ? err.code : 'ESPAWN';
+  const shown = String(command).replace(/[\u0000-\u001f\u007f]/g, c => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+  return new ToolError(`MCP server "${name}" failed to start: command "${shown}" (${code})`, {
+    context: { spawnError: true, server: name, code },
+  });
+}
+
 /**
  * @param {string} name
  * @param {ServerDef} def
@@ -238,11 +257,28 @@ function createRpcClient(name, def) {
   const { command, args = [], env, cwd } = def;
   const mergedEnv = { ...process.env, ...resolveEnv(env) };
 
-  const child = spawn(command, args, {
-    stdio: ['pipe', 'pipe', 'pipe'],
-    env: mergedEnv,
-    ...(cwd && { cwd }),
-  });
+  /** @type {import('node:child_process').ChildProcessWithoutNullStreams} */
+  let child;
+  try {
+    child = spawn(command, args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: mergedEnv,
+      ...(cwd && { cwd }),
+    });
+  } catch (err) {
+    // spawn() throws SYNCHRONOUSLY for some bad input (empty command, NUL byte, E2BIG), so no
+    // child 'error' event will ever fire. Same labelled shape as the async path; never the args.
+    // Dead client: rpc() rejects every call; notify() is a no-op; `child` is a minimal stand-in
+    // that killServer() skips (exitCode !== null) — the simplest shape that needs no null-guards
+    // in connectAndListTools / killServer / close().
+    const dead = spawnFailure(name, command, err);
+    return {
+      rpc: () => Promise.reject(dead),
+      notify: () => {},
+      child: /** @type {any} */ ({ exitCode: -1, pid: undefined }),
+      stderr: '',
+    };
+  }
 
   /** @type {Map<number, {resolve: (v: any) => void, reject: (e: any) => void, timer: NodeJS.Timeout | null}>} */
   const pending = new Map();
@@ -295,9 +331,25 @@ function createRpcClient(name, def) {
   // and rpc()/notify() guard writability before writing.
   child.stdin.on('error', () => { /* child gone; surfaced via close + write guards */ });
 
+  // Spawn failure (ENOENT/EACCES/...): with NO 'error' listener Node re-throws it as an uncaught
+  // exception and crashes the HOST. Record it once; it WINS over any later pipe/close error and
+  // rejects every pending and future rpc. Names the command ONLY (args/env can carry tokens).
+  /** @type {ToolError | null} */
+  let spawnErr = null;
+  child.on('error', (err) => {
+    // Only a child that never got a pid is a spawn failure. Node also emits 'error' for a failed
+    // kill() or IPC send on a LIVE child; keep the listener (so it can't crash the host) but do
+    // not mark the server failed — a live server's lifecycle belongs to the 'close' handler.
+    if (child.pid !== undefined || spawnErr) return;
+    spawnErr = spawnFailure(name, command, err);
+    for (const id of [...pending.keys()]) settle(id, false, spawnErr);
+  });
+
   child.on('close', (code) => {
     for (const id of [...pending.keys()]) {
-      settle(id, false, new ToolError(`MCP server "${name}" exited (code ${code}). stderr: ${stderrBuf.slice(-500)}`));
+      // Belt-and-braces: on Node 22 the observed order is error -> EPIPE -> close, so the 'error'
+      // handler has already settled these ids; `spawnErr ||` guards a different ordering elsewhere.
+      settle(id, false, spawnErr || new ToolError(`MCP server "${name}" exited (code ${code}). stderr: ${stderrBuf.slice(-500)}`));
     }
   });
 
@@ -316,6 +368,7 @@ function createRpcClient(name, def) {
   function rpc(method, params = {}, timeoutMs = 0, label) {
     const id = nextId++;
     return new Promise((resolve, reject) => {
+      if (spawnErr) return reject(spawnErr);
       if (!child.stdin.writable) {
         return reject(new ToolError(`MCP server "${name}" stdin is not writable (process exited or pipe closed). stderr: ${stderrBuf.slice(-500)}`));
       }
@@ -329,7 +382,10 @@ function createRpcClient(name, def) {
               { context: { timeout: true, server: label.server, tool: label.tool, timeoutMs, stderr: stderrBuf.slice(-500) } },
             ));
           } else {
-            settle(id, false, new ToolError(`MCP server "${name}" "${method}" timed out after ${timeoutMs}ms. stderr: ${stderrBuf.slice(-500)}`));
+            settle(id, false, new ToolError(
+              `MCP server "${name}" "${method}" timed out after ${timeoutMs}ms`,
+              { context: { timeout: true, server: name, method, timeoutMs, stderr: stderrBuf.slice(-500) } },
+            ));
           }
         }, timeoutMs);
         timer.unref?.();
@@ -338,7 +394,10 @@ function createRpcClient(name, def) {
       const msg = JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n';
       child.stdin.write(msg, (err) => {
         // settle() no-ops if 'close'/timeout already settled this id.
-        if (err) settle(id, false, new ToolError(`MCP server "${name}" write failed: ${err.message}. stderr: ${stderrBuf.slice(-500)}`));
+        // Belt-and-braces (Node 22 order is error -> EPIPE -> close, already settled by 'error').
+        // Deferred a tick: a failed spawn's EPIPE/destroyed-stream callback can land before the
+        // 'error' event; the recorded spawn error must win, so re-check after it has had its turn.
+        if (err) setImmediate(() => settle(id, false, spawnErr || new ToolError(`MCP server "${name}" write failed: ${err.message}. stderr: ${stderrBuf.slice(-500)}`)));
       });
     });
   }
@@ -370,6 +429,14 @@ function unwrapContent(content) {
 
 // --- Tool wrapping ---
 
+/**
+ * A server "sent annotations" only when it sent a non-null, non-array object. A non-object
+ * `annotations` value (null, array, string, ...) is treated as absent (dropped), so the key stays absent downstream.
+ * @param {any} a
+ * @returns {boolean}
+ */
+const hasAnnotations = (a) => a !== null && typeof a === 'object' && !Array.isArray(a);
+
 // Runtime arg-dependent policy has moved to Loop-level (new Loop({ policy })).
 // mcp-bridge retains only the static .mcp-bridge.json allow/deny filter below —
 // that decides which tools are exposed to the Loop in the first place.
@@ -385,6 +452,8 @@ function wrapTools(serverName, mcpTools, rpc, callTimeout = 0) {
     name: `${serverName}_${t.name}`,
     description: t.description || '',
     parameters: t.inputSchema || { type: 'object', properties: {} },
+    // Server `annotations` ride through as the SAME object, unmodified; key ABSENT when none sent.
+    ...(hasAnnotations(t.annotations) && { annotations: t.annotations }),
     execute: async (args) => {
       const result = await rpc('tools/call', { name: t.name, arguments: args }, callTimeout, { server: serverName, tool: t.name });
       if (result.isError) {
@@ -440,36 +509,79 @@ async function killServer(child) {
 
 // --- Connect + list tools from a server ---
 
+// tools/list pagination cap. A server that keeps handing out cursors past this is faulty or
+// hostile; we THROW (never truncate silently — a partial catalog reads as a complete one).
+const MAX_LIST_PAGES = 100;
+
 /**
  * @param {string} name
  * @param {ServerDef} def
- * @param {number} [timeout]
+ * @param {number} [timeout] - Bound on EACH round-trip (initialize, every tools/list page).
+ * @param {{ deadlineMs?: number }} [o] - Optional ONE total wall-clock ceiling over the whole
+ *   connect+list (internal; used by listServerTools). On trip the child is killed and a labelled
+ *   TimeoutError rejects. The timer is always cleared.
  * @returns {Promise<{mcpTools: McpTool[], client: RpcClient}>}
  */
-async function connectAndListTools(name, def, timeout = 15000) {
+async function connectAndListTools(name, def, timeout = 15000, o = {}) {
   const client = createRpcClient(name, def);
+  /** @type {NodeJS.Timeout | undefined} */
+  let deadlineTimer;
 
   try {
-    // Both handshake round-trips are bounded by `timeout`. tools/list used to be
-    // unbounded — a server that answered initialize but never replied to
-    // tools/list would hang discovery (and the whole bridge) indefinitely.
-    await client.rpc('initialize', {
-      protocolVersion: '2024-11-05',
-      capabilities: {},
-      clientInfo: { name: 'bare-agent', version: '0.5.0' },
-    }, timeout);
-    client.notify('notifications/initialized');
-
-    const listed = await client.rpc('tools/list', {}, timeout);
-    // A reply without a `tools` array is a protocol-violating server, not an empty one: fail the
-    // connect HERE (inside the try, so the child is reaped) rather than let every caller's
-    // `.map`/`.filter` throw after the child is already running but before it is tracked.
-    const mcpTools = listed && listed.tools;
-    if (!Array.isArray(mcpTools)) {
-      throw new Error(`MCP server "${name}" returned a malformed tools/list reply (no tools array)`);
-    }
+    const work = (async () => {
+      // Every round-trip is bounded by `timeout`. tools/list used to be
+      // unbounded — a server that answered initialize but never replied to
+      // tools/list would hang discovery (and the whole bridge) indefinitely.
+      await client.rpc('initialize', {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: { name: 'bare-agent', version: '0.5.0' },
+      }, timeout);
+      client.notify('notifications/initialized');
+
+      // Follow `nextCursor` until the server stops sending one. A reply without a `tools` array is a
+      // protocol-violating server, not an empty one: fail the connect HERE (inside the try, so the
+      // child is reaped) rather than let every caller's `.map`/`.filter` throw after the child is
+      // already running but before it is tracked.
+      /** @type {McpTool[]} */
+      const mcpTools = [];
+      /** @type {Set<string>} */
+      const seenCursors = new Set();
+      /** @type {string | undefined} */
+      let cursor;
+      for (let pages = 1; ; pages++) {
+        const listed = await client.rpc('tools/list', cursor === undefined ? {} : { cursor }, timeout);
+        if (!listed || !Array.isArray(listed.tools)) {
+          throw new Error(`MCP server "${name}" returned a malformed tools/list reply (no tools array)`);
+        }
+        mcpTools.push(...listed.tools);
+        const next = listed.nextCursor;
+        if (typeof next !== 'string' || next === '') break;
+        if (seenCursors.has(next)) {
+          throw new Error(`MCP server "${name}" repeated a tools/list cursor (pagination loop)`);
+        }
+        if (pages >= MAX_LIST_PAGES) {
+          throw new Error(`MCP server "${name}" exceeded the tools/list page cap (${MAX_LIST_PAGES} pages); refusing to return a truncated catalog`);
+        }
+        seenCursors.add(next);
+        cursor = next;
+      }
 
-    return { mcpTools, client };
+      return { mcpTools, client };
+    })();
+
+    if (!o.deadlineMs) return await work;
+    // The loser of the race must not surface as an unhandled rejection.
+    work.catch(() => {});
+    const deadline = new Promise((_, reject) => {
+      deadlineTimer = setTimeout(() => {
+        reject(new TimeoutError(
+          `MCP server "${name}" exceeded the total deadline of ${o.deadlineMs}ms for connect + tools/list`,
+          { context: { timeout: true, bound: 'deadline', server: name, deadlineMs: o.deadlineMs } },
+        ));
+      }, o.deadlineMs);
+    });
+    return await Promise.race([work, deadline]);
   } catch (err) {
     // Connect failed (init timeout, tools/list error, etc.) — the child was
     // spawned but never returned to the caller, so the caller can't track it
@@ -477,6 +589,8 @@ async function connectAndListTools(name, def, timeout = 15000) {
     // alive and hangs the process on exit (notably node:test's file wrapper).
     await killServer(client.child);
     throw err;
+  } finally {
+    clearTimeout(deadlineTimer);
   }
 }
 
@@ -565,6 +679,7 @@ function buildMetaTools(tools, discoveredAt, excluded) {
       schema: t.parameters || { type: 'object', properties: {} },
       server: sep > 0 ? t.name.slice(0, sep) : t.name,
       tool: sep > 0 ? t.name.slice(sep + 1) : '',
+      ...(hasAnnotations(t.annotations) && { annotations: t.annotations }),
     };
   });
   const byName = new Map(tools.map(t => [t.name, t]));
@@ -636,6 +751,46 @@ function buildMetaTools(tools, discoveredAt, excluded) {
   return [mcpDiscover, mcpInvoke];
 }
 
+// --- Server vetting (shared by createMCPBridge and listServerTools) ---
+
+/**
+ * Vet a server before spawning its command. `=== true` proceeds; anything else, or a throw, denies
+ * (fail-closed). No hook ⇒ trust all.
+ * @param {((name: string, def: ServerDef) => boolean | Promise<boolean>) | null} confirmServer
+ * @returns {(name: string, def: ServerDef) => Promise<boolean>}
+ */
+function makeVetServer(confirmServer) {
+  return async (name, def) => {
+    if (!confirmServer) return true;
+    try { return (await confirmServer(name, def)) === true; }
+    catch { return false; }
+  };
+}
+
+/**
+ * Connecting to a server EXECUTES its `command`. The project-cwd `.mcp.json` is excluded from
+ * default discovery (see TRUSTED_CONFIG_PATHS / includeProjectConfig), so the untrusted-repo
+ * path is closed by default; this warning (stderr) covers the residual case where home/IDE configs
+ * (or an explicit opt-in) contribute commands and no confirmServer hook is present to vet them.
+ * Warns ONCE per returned function, BEFORE the first spawn.
+ * @param {Function | null} confirmServer
+ * @returns {(specs: Array<{name: string, command: string, args?: string[]}>) => void}
+ */
+function makeUnvettedWarner(confirmServer) {
+  let warned = false;
+  return (specs) => {
+    if (confirmServer || warned || specs.length === 0) return;
+    warned = true;
+    // Server name + command ONLY: args/env can carry tokens and stderr lands in logs. A count only.
+    const cmds = specs.map(s => `${s.name} → ${s.command}${s.args && s.args.length ? ` (${s.args.length} args)` : ''}`);
+    console.warn(
+      `[MCP Bridge] spawning ${specs.length} server command(s) without a confirmServer hook:\n  ` +
+      cmds.join('\n  ') +
+      `\n  Pass { confirmServer } to vet each command before it runs.`,
+    );
+  };
+}
+
 // --- Signed allow-list mode (opts.allow) ---
 
 /** @param {any} v @returns {string} */
@@ -793,7 +948,7 @@ async function createAllowBridge(allow, o) {
  *   discovered server is trusted — pass this to gate command execution. Presence
  *   of this hook also opts default discovery into the project-cwd `./.mcp.json`,
  *   since each command is then vetted regardless of source.
- * @returns {Promise<{tools: ToolDef[], metaTools?: ToolDef[], servers: string[], systemContext: string, denied: DeniedTool[], errors?: Array<{server: string, error: string}>, missing?: Array<{server: string, tool: string}>, close: Function}>}
+ * @returns {Promise<{tools: ToolDef[], metaTools?: ToolDef[], servers: string[], systemContext: string, denied: DeniedTool[], errors: Array<{server: string, error: string}>, missing?: Array<{server: string, tool: string}>, close: Function}>}
  * @when you want to auto-discover MCP servers and expose them as bareagent tools in one call — with a trust hook gating command execution, or a per-run signed `allow` list that exposes only the named tools
  * @fails a trust hook returning false skips a server (its command never runs) and a throw is fail-closed (deny); with `allow` it is in-memory only (no cache file read or written) and signed tools the server does not list land in `missing`, never a throw; returns tools plus a close() to shut servers down.
  * @example
@@ -816,31 +971,8 @@ async function createMCPBridge(opts = {}) {
   // Vet a server before spawning its command. Fail-closed: an undefined hook
   // trusts all (unchanged behavior); a throw denies.
   const confirmServer = typeof opts.confirmServer === 'function' ? opts.confirmServer : null;
-  /** @param {string} name @param {ServerDef} def @returns {Promise<boolean>} */
-  const vetServer = async (name, def) => {
-    if (!confirmServer) return true;
-    try { return (await confirmServer(name, def)) === true; }
-    catch { return false; }
-  };
-
-  // Connecting to a server EXECUTES its `command`. The project-cwd `.mcp.json` is excluded from
-  // default discovery (see TRUSTED_CONFIG_PATHS / includeProjectConfig), so the untrusted-repo
-  // path is closed by default; this warning covers the residual case where home/IDE configs (or an
-  // explicit opt-in) contribute commands and no confirmServer hook is present to vet them.
-  // Warn ONCE per call, BEFORE the first spawn — and the first spawn is the
-  // discovery phase on a cold/refresh run, not the main-connect phase below.
-  let warnedUnvetted = false;
-  /** @param {Array<{name: string, command: string, args?: string[]}>} specs */
-  const warnUnvettedSpawn = (specs) => {
-    if (confirmServer || warnedUnvetted || specs.length === 0) return;
-    warnedUnvetted = true;
-    const cmds = specs.map(s => `${s.name} → ${s.command} ${(s.args || []).join(' ')}`.trim());
-    console.warn(
-      `[MCP Bridge] spawning ${specs.length} server command(s) without a confirmServer hook:\n  ` +
-      cmds.join('\n  ') +
-      `\n  Pass { confirmServer } to vet each command before it runs.`,
-    );
-  };
+  const vetServer = makeVetServer(confirmServer);
+  const warnUnvettedSpawn = makeUnvettedWarner(confirmServer);
 
   if (opts.allow !== undefined) {
     const allow = validateAllow(opts.allow);
@@ -854,6 +986,29 @@ async function createMCPBridge(opts = {}) {
   let config = readBridgeConfig(bridgePath);
   const needsRefresh = opts.refresh || !config || isExpired(config);
 
+  // Per-server connect failures from BOTH passes (discovery, then main), first message wins. `errors`
+  // is derived from this once, at return time: servers that did not end up connected, once each.
+  /** @type {Map<string, string>} */
+  const failures = new Map();
+  /** @param {string} name @param {unknown} err */
+  const noteFailure = (name, err) => {
+    if (failures.has(name)) return;
+    const message = err && typeof err === 'object' && 'message' in err && typeof err.message === 'string' ? err.message : String(err);
+    failures.set(name, message);
+  };
+  /** The one place `errors` is computed (and the failure warns issued). @param {string[]} connected */
+  const finalErrors = (connected) => {
+    const up = new Set(connected);
+    const errors = [...failures].filter(([name]) => !up.has(name)).map(([server, error]) => ({ server, error }));
+    if (errors.length > 0) console.warn('[MCP Bridge] Some servers failed to connect:', errors);
+    // Discovery failed but the cached definition connected: not an error, yet the config edit was not applied.
+    const cachedUsed = [...failures].filter(([name]) => up.has(name)).map(([server, error]) => ({ server, error }));
+    if (cachedUsed.length > 0) console.warn('[MCP Bridge] Discovery failed for server(s) that connected from the cached definition (config edit not applied):', cachedUsed);
+    return errors;
+  };
+  /** Early return: nothing connected. */
+  const nothingConnected = () => ({ tools: [], servers: [], systemContext: '', denied: [], errors: finalErrors([]), close: async () => {} });
+
   if (needsRefresh) {
     // Discover from IDE configs. The project-cwd `.mcp.json` is excluded by default (untrusted-repo
     // RCE vector); it is scanned only on explicit opt-in, or when a `confirmServer` hook is present
@@ -861,9 +1016,7 @@ async function createMCPBridge(opts = {}) {
     const includeProjectConfig = opts.includeProjectConfig === true || !!confirmServer;
     const discovered = discoverServers(opts.configPaths, { includeProjectConfig });
 
-    if (discovered.size === 0 && !config) {
-      return { tools: [], servers: [], systemContext: '', denied: [], close: async () => {} };
-    }
+    if (discovered.size === 0 && !config) return nothingConnected();
 
     // Only attempt connection when discovery found something.
     // If discovered.size === 0 but config exists, fall through and use the existing config
@@ -873,9 +1026,6 @@ async function createMCPBridge(opts = {}) {
       const freshTools = new Map();
       /** @type {Map<string, RpcClient>} */
       const connectResults = new Map();
-      /** @type {Array<{server: string, error: string}>} */
-      const errors = [];
-
       const reqServers = opts.servers;
       const toDiscover = reqServers
         ? [...discovered.entries()].filter(([n]) => reqServers.includes(n))
@@ -892,14 +1042,10 @@ async function createMCPBridge(opts = {}) {
           connectResults.set(name, result.client);
           freshTools.set(name, result.mcpTools);
         } catch (err) {
-          errors.push({ server: name, error: err.message });
+          noteFailure(name, err);
         }
       }));
 
-      if (errors.length > 0) {
-        console.warn('[MCP Bridge] Some servers failed to connect:', errors);
-      }
-
       // Discovery connections are killed in `finally`: a throw from the config merge/write (e.g. an
       // unwritable bridgePath) must not strand the live children held only in connectResults.
       try {
@@ -911,7 +1057,7 @@ async function createMCPBridge(opts = {}) {
           writeBridgeConfig(bridgePath, config);
           console.log(`[MCP Bridge] Wrote ${bridgePath}`);
         } else if (!config) {
-          return { tools: [], servers: [], systemContext: '', denied: [], close: async () => {} };
+          return nothingConnected();
         }
 
       } finally {
@@ -925,9 +1071,7 @@ async function createMCPBridge(opts = {}) {
 
   // At this point config is guaranteed non-null: it either existed, was just
   // written by the refresh branch, or we returned early above.
-  if (!config) {
-    return { tools: [], servers: [], systemContext: '', denied: [], close: async () => {} };
-  }
+  if (!config) return nothingConnected();
   /** @type {BridgeConfig} */
   const cfg = config;
 
@@ -937,9 +1081,7 @@ async function createMCPBridge(opts = {}) {
     ? reqServers2.filter(n => cfg.servers[n])
     : Object.keys(cfg.servers);
 
-  if (serverNames.length === 0) {
-    return { tools: [], servers: [], systemContext: '', denied: [], close: async () => {} };
-  }
+  if (serverNames.length === 0) return nothingConnected();
 
   // Warn before the main-connect spawn too. On a warm run (config exists, no
   // refresh) this is the first and only spawn; on a cold run the discovery phase
@@ -955,8 +1097,6 @@ async function createMCPBridge(opts = {}) {
   const connected = [];
   /** @type {DeniedTool[]} */
   const denied = [];
-  /** @type {Array<{server: string, error: string}>} */
-  const errors = [];
 
   await Promise.all(serverNames.map(async (name) => {
     const serverConf = cfg.servers[name];
@@ -988,14 +1128,10 @@ async function createMCPBridge(opts = {}) {
         }
       }
     } catch (err) {
-      errors.push({ server: name, error: err.message });
+      noteFailure(name, err);
     }
   }));
 
-  if (errors.length > 0) {
-    console.warn('[MCP Bridge] Some servers failed to connect:', errors);
-  }
-
   const systemContext = buildSystemContext(connected, tools, denied);
   if (connected.length > 0) console.log(systemContext);
 
@@ -1007,11 +1143,99 @@ async function createMCPBridge(opts = {}) {
     servers: connected,
     denied,
     systemContext,
-    errors,
+    errors: finalErrors(connected),
     close: async () => {
       await Promise.all(children.map(killServer));
     },
   };
 }
 
-module.exports = { createMCPBridge, discoverServers, buildMetaTools };
+// --- listServerTools: one-shot read-only listing ---
+
+// Total-deadline multiplier for listServerTools. `timeout` bounds EACH round-trip; a server that
+// answers every page just under it could otherwise stretch a call to (1 + pages) × timeout. The one
+// total ceiling is 4 × timeout = initialize plus three further maximally-slow round-trips: a normal
+// server answers in milliseconds and a handful of pages never approaches it, while a server that
+// needs more than that is slow enough to treat as faulty. Derived, not a new option.
+const LIST_DEADLINE_MULTIPLIER = 4;
+
+/**
+ * @param {string} msg
+ * @returns {ValidationError}
+ */
+const listBad = (msg) => new ValidationError(`[MCP Bridge] listServerTools: ${msg}`, { context: { lib: 'bare-agent' } });
+
+/**
+ * List one configured MCP server's tools WITHOUT building a bridge: discover, vet, connect, list
+ * (following pagination), then always kill the child. Never reads or writes `.mcp-bridge.json`
+ * and prints nothing to stdout. `annotations` are the server's own HINTS, passed through unmodified
+ * (key absent when the server sent none) — never an authorization signal.
+ *
+ * Total wall-clock ceiling is DERIVED: 4 × `timeout` (initialize + three maximally slow pages) over
+ * the connect + list, excluding `confirmServer` (caller code, possibly interactive). On trip the
+ * child is killed and a TimeoutError naming the total deadline rejects. A SMALL `timeout` shrinks the
+ * total proportionally (timeout 500 ⇒ 2s total), so a server with many pages near that speed can trip it.
+ * A non-object `annotations` value from the server is treated as absent (dropped).
+ *
+ * @param {object} opts
+ * @param {string} opts.server - Server name as it appears in the discovered configs.
+ * @param {string[]} [opts.configPaths] - Explicit config paths; omitted ⇒ trusted $HOME/IDE defaults.
+ * @param {(name: string, def: ServerDef) => boolean | Promise<boolean>} [opts.confirmServer] - Same semantics as createMCPBridge: `=== true` proceeds, a throw denies. Implies includeProjectConfig.
+ * @param {boolean} [opts.includeProjectConfig=false] - Also scan `./.mcp.json` during default discovery.
+ * @param {number} [opts.timeout=15000] - Per-round-trip bound in ms (initialize and each tools/list page).
+ * @returns {Promise<Array<{name: string, description: string, annotations?: Record<string, any>}>>}
+ * @when you want to list one MCP server's tools and their annotation hints before deciding what to allow — no bridge, no cache file, no tools kept alive
+ * @fails throws (never returns []) when the server is not found, confirmServer declines or throws, the connect/handshake fails or times out, the total deadline trips, or the reply is malformed; the child is always reaped.
+ * @example
+ *   const tools = await listServerTools({ server: 'files', configPaths: [cfg] });
+ */
+async function listServerTools(opts) {
+  if (opts === null || typeof opts !== 'object' || Array.isArray(opts)) {
+    throw listBad(`opts must be an object (got ${typeName(opts)})`);
+  }
+  const { server, configPaths, confirmServer, includeProjectConfig, timeout = 15000 } = opts;
+  if (typeof server !== 'string' || server === '') {
+    throw listBad(`server must be a non-empty string (got ${server === '' ? 'empty string' : typeName(server)})`);
+  }
+  if (configPaths !== undefined) {
+    if (!Array.isArray(configPaths)) throw listBad(`configPaths must be an array of strings (got ${typeName(configPaths)})`);
+    for (const p of configPaths) {
+      if (typeof p !== 'string' || p === '') throw listBad(`configPaths entries must be non-empty strings (got ${p === '' ? 'empty string' : typeName(p)})`);
+    }
+  }
+  if (confirmServer !== undefined && typeof confirmServer !== 'function') {
+    throw listBad(`confirmServer must be a function (got ${typeName(confirmServer)})`);
+  }
+  if (typeof timeout !== 'number' || !Number.isFinite(timeout) || timeout <= 0) {
+    throw listBad(`timeout must be a positive finite number (got ${typeName(timeout)})`);
+  }
+
+  const confirm = typeof confirmServer === 'function' ? confirmServer : null;
+  const discovered = discoverServers(configPaths, { includeProjectConfig: includeProjectConfig === true || !!confirm });
+  const def = discovered.get(server);
+  if (!def) {
+    throw new ToolError(`MCP server "${server}" not found in discovered MCP configs`, { context: { server, notFound: true } });
+  }
+  makeUnvettedWarner(confirm)([{ name: server, command: def.command, args: def.args }]);
+  if (!(await makeVetServer(confirm)(server, def))) {
+    throw new ToolError(`MCP server "${server}" was not approved by confirmServer`, { context: { server, denied: true } });
+  }
+
+  const { mcpTools, client } = await connectAndListTools(server, def, timeout, { deadlineMs: timeout * LIST_DEADLINE_MULTIPLIER });
+  try {
+    return mcpTools.map(t => {
+      if (t === null || typeof t !== 'object' || typeof t.name !== 'string' || t.name === '') {
+        throw new ToolError(`MCP server "${server}" returned a malformed tools/list entry (no string name)`, { context: { server } });
+      }
+      return {
+        name: t.name,
+        description: t.description || '',
+        ...(hasAnnotations(t.annotations) && { annotations: t.annotations }),
+      };
+    });
+  } finally {
+    await killServer(client.child);
+  }
+}
+
+module.exports = { createMCPBridge, discoverServers, buildMetaTools, listServerTools };

package/src/mcp.d.ts

@@ -1,4 +1,5 @@
 import { createMCPBridge } from "./mcp-bridge";
 import { discoverServers } from "./mcp-bridge";
 import { buildMetaTools } from "./mcp-bridge";
-export { createMCPBridge, discoverServers, buildMetaTools };
+import { listServerTools } from "./mcp-bridge";
+export { createMCPBridge, discoverServers, buildMetaTools, listServerTools };

package/src/mcp.js

@@ -1,5 +1,5 @@
 'use strict';
 
-const { createMCPBridge, discoverServers, buildMetaTools } = require('./mcp-bridge');
+const { createMCPBridge, discoverServers, buildMetaTools, listServerTools } = require('./mcp-bridge');
 
-module.exports = { createMCPBridge, discoverServers, buildMetaTools };
+module.exports = { createMCPBridge, discoverServers, buildMetaTools, listServerTools };

package/types/index.d.ts

@@ -224,6 +224,8 @@ export interface ToolDef {
   name: string;
   description?: string;
   parameters?: Record<string, any>;
+  /** MCP tools only: the server's own behavioural hints (readOnlyHint, ...), passed through unmodified. Untrusted metadata, never an authorization signal. Absent when the server sent none; a non-object value from the server is treated as absent. */
+  annotations?: Record<string, any>;
   execute(args: any): any | Promise<any>;
 }