toolnexus 0.8.0 → 0.9.3

package/dist/client.d.ts

@@ -32,6 +32,18 @@ export interface ClientOptions {
      * (open a browser, message a channel, watch a file, forward to another agent). Omit for a durable
      * host: run() does not hang — it returns { status:"pending", pending:request } to resume later. */
     waitFor?: (request: Request) => Promise<Answer>;
+    /** §8 Gap 1. Extra top-level keys shallow-merged into EVERY LLM body after the client builds
+     * its own — a requestParams key WINS on collision (e.g. max_tokens overrides the anthropic
+     * default). `messages`/`tools`/`stream` are forbidden here (stripped + warned) — rewrite
+     * messages via bodyTransform. Applied on all four paths. Omit ⇒ body byte-identical to today. */
+    requestParams?: Record<string, unknown>;
+    /** §8 Gap 1. Receives the fully assembled body (after requestParams merge) just before marshal
+     * and returns the body to send — the escape hatch for provider-specific rewriting (e.g. tool-role
+     * message preprocessing) without a proxy. Returning a falsy value ⇒ unchanged. Runs on every call. */
+    bodyTransform?: (body: Record<string, any>) => Record<string, any> | undefined | void;
+    /** §8 Gap 2. HTTP transport for LLM requests (retries included). Omit ⇒ global fetch. Scope is the
+     * LLM path only; MCP transports use the SDK's own client. */
+    fetch?: typeof fetch;
 }
 /**
  * Semantic observability events (§8). NOT counter/histogram primitives — readable records the
@@ -191,6 +203,23 @@ export declare class Client {
     /** Cumulative Prometheus registry fed by the same events `onMetric` sees. */
     private readonly registry;
     constructor(opts: ClientOptions);
+    /**
+     * §8 Gap 4. The client's conversation store — the exact instance passed in `opts.store`, else
+     * the default in-memory store the client created. Read (`get`) and write (`save`) it directly to
+     * share state with `ask`; no consumer needs a shadow copy.
+     */
+    conversationStore(): ConversationStore;
+    /**
+     * §8 Gap 1. Apply the request-shaping contract to an assembled body: strip forbidden keys from
+     * requestParams, shallow-merge requestParams (caller wins), then run bodyTransform last. Called at
+     * every LLM body-build site so the ordering contract holds identically on all four paths.
+     */
+    private finalizeBody;
+    /** §8 Gap 5. OpenAI-style body; omits tools/tool_choice when the tool list is empty. Key order
+     * matches the pre-change body so a no-options call is byte-identical. */
+    private openaiBody;
+    /** §8 Gap 5. Anthropic-style body; omits tools when the tool list is empty. */
+    private anthropicBody;
     /** Prometheus text exposition of cumulative metrics (§8). Always valid, empty-but-valid before activity. */
     metrics(): string;
     /** Feed a semantic metric event to the built-in registry and the optional onMetric sink. */

package/dist/client.js

@@ -150,6 +150,60 @@ export class Client {
         this.opts = opts;
         this.store = opts.store ?? new InMemoryConversationStore();
     }
+    /**
+     * §8 Gap 4. The client's conversation store — the exact instance passed in `opts.store`, else
+     * the default in-memory store the client created. Read (`get`) and write (`save`) it directly to
+     * share state with `ask`; no consumer needs a shadow copy.
+     */
+    conversationStore() {
+        return this.store;
+    }
+    /**
+     * §8 Gap 1. Apply the request-shaping contract to an assembled body: strip forbidden keys from
+     * requestParams, shallow-merge requestParams (caller wins), then run bodyTransform last. Called at
+     * every LLM body-build site so the ordering contract holds identically on all four paths.
+     */
+    finalizeBody(body) {
+        const rp = this.opts.requestParams;
+        if (rp) {
+            for (const [k, v] of Object.entries(rp)) {
+                if (k === "messages" || k === "tools" || k === "stream") {
+                    console.warn(`[toolnexus] requestParams key "${k}" is not allowed — ignored (use bodyTransform)`);
+                    continue;
+                }
+                body[k] = v;
+            }
+        }
+        if (this.opts.bodyTransform) {
+            const out = this.opts.bodyTransform(body);
+            if (out)
+                return out;
+        }
+        return body;
+    }
+    /** §8 Gap 5. OpenAI-style body; omits tools/tool_choice when the tool list is empty. Key order
+     * matches the pre-change body so a no-options call is byte-identical. */
+    openaiBody(messages, tools, stream) {
+        const b = { model: this.opts.model, messages };
+        if (tools.length) {
+            b.tools = tools;
+            b.tool_choice = "auto";
+        }
+        if (stream) {
+            b.stream = true;
+            b.stream_options = { include_usage: true };
+        }
+        return this.finalizeBody(b);
+    }
+    /** §8 Gap 5. Anthropic-style body; omits tools when the tool list is empty. */
+    anthropicBody(system, messages, tools, stream) {
+        const b = { model: this.opts.model, max_tokens: 4096, system, messages };
+        if (tools.length)
+            b.tools = tools;
+        if (stream)
+            b.stream = true;
+        return this.finalizeBody(b);
+    }
     /** Prometheus text exposition of cumulative metrics (§8). Always valid, empty-but-valid before activity. */
     metrics() {
         return this.registry.render();
@@ -244,7 +298,7 @@ export class Client {
         let lastErr;
         for (let attempt = 0; attempt <= retries; attempt++) {
             try {
-                const res = await fetch(url, { ...init, signal });
+                const res = await (this.opts.fetch ?? fetch)(url, { ...init, signal });
                 if (res.ok || !RETRYABLE.has(res.status) || attempt === retries)
                     return res;
                 const ra = Number(res.headers.get("retry-after"));
@@ -341,7 +395,7 @@ export class Client {
                 const data = await this.llmCallJson(`${this.opts.baseUrl.replace(/\/$/, "")}/chat/completions`, {
                     method: "POST",
                     headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json", ...this.opts.headers },
-                    body: JSON.stringify({ model: this.opts.model, messages, tools, tool_choice: "auto" }),
+                    body: JSON.stringify(this.openaiBody(messages, tools, false)),
                 }, signal, "openai");
                 addUsage(usage, data.usage, "openai");
                 if (this.opts.hooks?.afterLLM)
@@ -442,7 +496,7 @@ export class Client {
                         "Content-Type": "application/json",
                         ...this.opts.headers,
                     },
-                    body: JSON.stringify({ model: this.opts.model, max_tokens: 4096, system, messages, tools }),
+                    body: JSON.stringify(this.anthropicBody(system, messages, tools, false)),
                 }, signal, "anthropic");
                 addUsage(usage, data.usage, "anthropic");
                 if (this.opts.hooks?.afterLLM)
@@ -523,7 +577,7 @@ export class Client {
                     const res = await this.llmFetch(`${this.opts.baseUrl.replace(/\/$/, "")}/chat/completions`, {
                         method: "POST",
                         headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json", ...this.opts.headers },
-                        body: JSON.stringify({ model: this.opts.model, messages, tools, tool_choice: "auto", stream: true, stream_options: { include_usage: true } }),
+                        body: JSON.stringify(this.openaiBody(messages, tools, true)),
                     }, signal);
                     if (!res.ok || !res.body)
                         throw new Error(`LLM ${res.status}: ${await res.text()}`);
@@ -630,7 +684,7 @@ export class Client {
                     const res = await this.llmFetch(endpoint, {
                         method: "POST",
                         headers: { "x-api-key": key, "anthropic-version": "2023-06-01", "Content-Type": "application/json", ...this.opts.headers },
-                        body: JSON.stringify({ model: this.opts.model, max_tokens: 4096, system, messages, tools, stream: true }),
+                        body: JSON.stringify(this.anthropicBody(system, messages, tools, true)),
                     }, signal);
                     if (!res.ok || !res.body)
                         throw new Error(`LLM ${res.status}: ${await res.text()}`);

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import type { ElicitRequest, ElicitResult } from "@modelcontextprotocol/sdk/types.js";
-import { type Tool, type McpStatus, type Request, type Answer } from "./types.js";
+import { type JSONSchema, type Tool, type McpStatus, type Request, type Answer } from "./types.js";
 /** Map an MCP `elicitation/create` request onto a §10 `Request`. */
 export declare function elicitationToRequest(params: ElicitRequest["params"]): Request;
 /** Map a resolved §10 `Answer` back onto an MCP `ElicitResult`. ok→accept; declined→decline; else→cancel. */
@@ -13,6 +13,10 @@ export interface LocalServer {
     enabled?: boolean;
     disabled?: boolean;
     timeout?: number;
+    /** §2 Gap 7. Per-server tool allowlist keyed on ORIGINAL tool name; same semantics as the
+     * builtins/skills filter (nil/empty ⇒ all; ≥1 true ⇒ allowlist; only-false ⇒ drop-list; unknown
+     * ⇒ ignore+warn). Applied to the listed defs before sanitize/prefix. */
+    tools?: Record<string, boolean>;
 }
 export interface RemoteServer {
     type?: "remote";
@@ -21,6 +25,8 @@ export interface RemoteServer {
     enabled?: boolean;
     disabled?: boolean;
     timeout?: number;
+    /** §2 Gap 7. Per-server tool allowlist (see LocalServer.tools). */
+    tools?: Record<string, boolean>;
 }
 export type ServerConfig = LocalServer | RemoteServer;
 export type McpConfig = Record<string, ServerConfig>;
@@ -36,7 +42,29 @@ export interface McpSource {
     status: Record<string, McpStatus>;
     close(): Promise<void>;
 }
-/** Connect to every enabled server, list + convert tools. Failures are isolated. */
+/** Connect to every enabled server, list + convert tools. Failures are isolated.
+ *  §2 Gap 3: an optional `signal` bounds each connect/list by the server timeout and aborts the
+ *  whole load promptly on parent cancellation. */
 export declare function loadMcp(input: string | object, opts?: {
     waitFor?: (request: Request) => Promise<Answer>;
+    signal?: AbortSignal;
 }): Promise<McpSource>;
+/** §2 Gap 6. One listed tool definition (original, unprefixed name). */
+export interface ToolInfo {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema;
+}
+/** §2 Gap 6. Result of a list-only pass over an MCP config. */
+export interface McpInventory {
+    /** server → its full listed tool defs, UNFILTERED by ServerConfig.tools (authors the allowlist). */
+    tools: Record<string, ToolInfo[]>;
+    status: Record<string, McpStatus>;
+}
+/**
+ * §2 Gap 6. Connect to every enabled server, list tool definitions, and DISCONNECT before
+ * returning — no toolkit, no execute wiring, nothing left running. Failure isolation as in loadMcp.
+ */
+export declare function listMcpTools(input: string | object, opts?: {
+    signal?: AbortSignal;
+}): Promise<McpInventory>;

package/dist/mcp.js

@@ -99,6 +99,42 @@ function joinTextContent(content) {
         .flatMap((item) => (isTextContent(item) ? [item.text] : []))
         .join("\n");
 }
+/**
+ * §2 Gap 7. Apply a per-server tool allowlist to the listed defs. Same semantics as the builtins
+ * and skills filters: nil/empty ⇒ all; ≥1 true ⇒ allowlist (only true names); only-false ⇒ drop-list
+ * over all-on; unknown names ignored + warned once. Keyed on ORIGINAL tool name.
+ */
+function applyToolsFilter(server, defs, filter) {
+    if (!filter)
+        return defs;
+    const keys = Object.keys(filter);
+    if (keys.length === 0)
+        return defs;
+    const hasTrue = keys.some((k) => filter[k] === true);
+    const present = new Set(defs.map((d) => d.name));
+    for (const k of keys) {
+        if (!present.has(k))
+            console.warn(`[toolnexus] server "${server}" tools filter name "${k}" matched no tool`);
+    }
+    return defs.filter((d) => (hasTrue ? filter[d.name] === true : filter[d.name] !== false));
+}
+/**
+ * §2 Gap 3. Race a promise against a per-server timeout and the caller's abort signal, so a hung
+ * connect/list is bounded (the SSE fallback included) and a parent cancellation aborts promptly.
+ */
+function raceTimeout(p, ms, signal) {
+    return new Promise((resolve, reject) => {
+        const onAbort = () => { cleanup(); reject(signal?.reason ?? new Error("aborted")); };
+        const t = setTimeout(() => { cleanup(); reject(new Error("mcp connect/list timeout")); }, ms);
+        const cleanup = () => { clearTimeout(t); signal?.removeEventListener("abort", onAbort); };
+        if (signal) {
+            if (signal.aborted)
+                return onAbort();
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+        p.then((v) => { cleanup(); resolve(v); }, (e) => { cleanup(); reject(e); });
+    });
+}
 async function paginateTools(client, timeout) {
     const result = [];
     const cursors = new Set();
@@ -144,50 +180,66 @@ function convertTool(server, def, client, timeout) {
         },
     };
 }
-/** Connect to every enabled server, list + convert tools. Failures are isolated. */
+/** Create a fresh (not-yet-connected) client, with the elicitation bridge attached if a waitFor
+ *  exists. Separated from connect so the caller ALWAYS holds a closeable reference — even if the
+ *  connect is later abandoned by a timeout/abort, `client.close()` still terminates any spawned
+ *  stdio child (no orphaned processes on cancellation). */
+function newMcpClient(waitFor) {
+    const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: waitFor ? { elicitation: {} } : {} });
+    if (waitFor) {
+        client.setRequestHandler(ElicitRequestSchema, async (request) => answerToElicitResult(await waitFor(elicitationToRequest(request.params))));
+    }
+    return client;
+}
+/** Connect an existing client's transport (remote streamable-HTTP with SSE fallback, or local stdio). */
+async function connectTransport(client, cfg) {
+    if (isRemote(cfg)) {
+        const url = new URL(cfg.url);
+        const expanded = expandEnvHeaders(cfg.headers);
+        const requestInit = expanded ? { headers: expanded } : undefined;
+        try {
+            await client.connect(new StreamableHTTPClientTransport(url, { requestInit }));
+        }
+        catch {
+            await client.connect(new SSEClientTransport(url, { requestInit }));
+        }
+    }
+    else {
+        const local = cfg;
+        const [cmd, ...args] = local.command;
+        await client.connect(new StdioClientTransport({
+            command: cmd,
+            args,
+            cwd: local.cwd,
+            env: { ...process.env, ...(local.environment ?? local.env ?? {}) },
+            stderr: "pipe",
+        }));
+    }
+}
+/** Connect to every enabled server, list + convert tools. Failures are isolated.
+ *  §2 Gap 3: an optional `signal` bounds each connect/list by the server timeout and aborts the
+ *  whole load promptly on parent cancellation. */
 export async function loadMcp(input, opts) {
     const config = parseMcpConfig(input);
     const tools = [];
     const status = {};
     const clients = [];
     const waitFor = opts?.waitFor;
+    const signal = opts?.signal;
     await Promise.all(Object.entries(config).map(async ([name, cfg]) => {
         if (!isEnabled(cfg)) {
             status[name] = "disabled";
             return;
         }
         const timeout = cfg.timeout ?? DEFAULT_TIMEOUT;
-        // Advertise elicitation + register the bridge ONLY when a waitFor exists to satisfy it —
-        // a waitFor-less host degrades cleanly (the server won't elicit). (§10 elicitation bridge)
-        const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: waitFor ? { elicitation: {} } : {} });
-        if (waitFor) {
-            client.setRequestHandler(ElicitRequestSchema, async (request) => answerToElicitResult(await waitFor(elicitationToRequest(request.params))));
-        }
+        // Create the client up front so a timed-out/aborted connect still has a closeable handle
+        // (its stdio child is killed by close() — never orphaned).
+        const client = newMcpClient(waitFor);
         try {
-            if (isRemote(cfg)) {
-                const url = new URL(cfg.url);
-                const expanded = expandEnvHeaders(cfg.headers);
-                const requestInit = expanded ? { headers: expanded } : undefined;
-                try {
-                    await client.connect(new StreamableHTTPClientTransport(url, { requestInit }));
-                }
-                catch {
-                    await client.connect(new SSEClientTransport(url, { requestInit }));
-                }
-            }
-            else {
-                const local = cfg;
-                const [cmd, ...args] = local.command;
-                await client.connect(new StdioClientTransport({
-                    command: cmd,
-                    args,
-                    cwd: local.cwd,
-                    env: { ...process.env, ...(local.environment ?? local.env ?? {}) },
-                    stderr: "pipe",
-                }));
-            }
-            const defs = await paginateTools(client, timeout);
-            for (const def of defs)
+            await raceTimeout(connectTransport(client, cfg), timeout, signal);
+            const defs = await raceTimeout(paginateTools(client, timeout), timeout, signal);
+            const kept = applyToolsFilter(name, defs, cfg.tools);
+            for (const def of kept)
                 tools.push(convertTool(name, def, client, timeout));
             clients.push(client);
             status[name] = "connected";
@@ -195,7 +247,10 @@ export async function loadMcp(input, opts) {
         catch (e) {
             status[name] = "failed";
             await client.close().catch(() => { });
-            // one bad server never breaks the toolkit
+            // Parent cancellation/deadline aborts the whole load (§2 Gap 3, A1); a per-server timeout
+            // within budget isolates just this server.
+            if (signal?.aborted)
+                throw e;
             console.warn(`[toolnexus] MCP server "${name}" failed: ${e instanceof Error ? e.message : String(e)}`);
         }
     }));
@@ -207,3 +262,48 @@ export async function loadMcp(input, opts) {
         },
     };
 }
+/**
+ * §2 Gap 6. Connect to every enabled server, list tool definitions, and DISCONNECT before
+ * returning — no toolkit, no execute wiring, nothing left running. Failure isolation as in loadMcp.
+ */
+export async function listMcpTools(input, opts) {
+    const config = parseMcpConfig(input);
+    const toolsByServer = {};
+    const status = {};
+    const signal = opts?.signal;
+    await Promise.all(Object.entries(config).map(async ([name, cfg]) => {
+        if (!isEnabled(cfg)) {
+            status[name] = "disabled";
+            return;
+        }
+        const timeout = cfg.timeout ?? DEFAULT_TIMEOUT;
+        // Client created up front so an aborted/timed-out connect is still closed (no orphaned child).
+        const client = newMcpClient();
+        try {
+            await raceTimeout(connectTransport(client, cfg), timeout, signal);
+            const defs = await raceTimeout(paginateTools(client, timeout), timeout, signal);
+            toolsByServer[name] = defs.map((d) => ({
+                name: d.name,
+                description: d.description ?? "",
+                inputSchema: {
+                    ...d.inputSchema,
+                    type: "object",
+                    properties: (d.inputSchema?.properties ?? {}),
+                },
+            }));
+            status[name] = "connected";
+        }
+        catch (e) {
+            status[name] = "failed";
+            if (signal?.aborted) {
+                await client.close().catch(() => { });
+                throw e;
+            }
+            console.warn(`[toolnexus] MCP server "${name}" failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        finally {
+            await client.close().catch(() => { });
+        }
+    }));
+    return { tools: toolsByServer, status };
+}

package/dist/toolkit.d.ts

@@ -32,6 +32,9 @@ export interface ToolkitOptions {
      * elicitation is not advertised.
      */
     waitFor?: (request: import("./types.js").Request) => Promise<import("./types.js").Answer>;
+    /** §2 Gap 3. Bounds the MCP load: each connect/list is capped by the server timeout and the
+     * whole load aborts promptly if this signal fires. Omit ⇒ unbounded as before. */
+    signal?: AbortSignal;
 }
 export declare class Toolkit {
     private readonly mcp;

package/dist/toolkit.js

@@ -34,7 +34,7 @@ export class Toolkit {
         }
     }
     static async create(opts) {
-        const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor }) : undefined;
+        const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor, signal: opts.signal }) : undefined;
         // Skills come from directories, in-memory data, and/or a lazy provider (§3,
         // S1). The provider is resolved here (create() is async) and merged with the
         // data list; a provider failure is isolated so other sources still load.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.8.0",
+  "version": "0.9.3",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",

package/src/client.ts

@@ -35,6 +35,18 @@ export interface ClientOptions {
    * (open a browser, message a channel, watch a file, forward to another agent). Omit for a durable
    * host: run() does not hang — it returns { status:"pending", pending:request } to resume later. */
   waitFor?: (request: Request) => Promise<Answer>
+  /** §8 Gap 1. Extra top-level keys shallow-merged into EVERY LLM body after the client builds
+   * its own — a requestParams key WINS on collision (e.g. max_tokens overrides the anthropic
+   * default). `messages`/`tools`/`stream` are forbidden here (stripped + warned) — rewrite
+   * messages via bodyTransform. Applied on all four paths. Omit ⇒ body byte-identical to today. */
+  requestParams?: Record<string, unknown>
+  /** §8 Gap 1. Receives the fully assembled body (after requestParams merge) just before marshal
+   * and returns the body to send — the escape hatch for provider-specific rewriting (e.g. tool-role
+   * message preprocessing) without a proxy. Returning a falsy value ⇒ unchanged. Runs on every call. */
+  bodyTransform?: (body: Record<string, any>) => Record<string, any> | undefined | void
+  /** §8 Gap 2. HTTP transport for LLM requests (retries included). Omit ⇒ global fetch. Scope is the
+   * LLM path only; MCP transports use the SDK's own client. */
+  fetch?: typeof fetch
 }
 
 /**
@@ -281,6 +293,61 @@ export class Client {
     this.store = opts.store ?? new InMemoryConversationStore()
   }
 
+  /**
+   * §8 Gap 4. The client's conversation store — the exact instance passed in `opts.store`, else
+   * the default in-memory store the client created. Read (`get`) and write (`save`) it directly to
+   * share state with `ask`; no consumer needs a shadow copy.
+   */
+  conversationStore(): ConversationStore {
+    return this.store
+  }
+
+  /**
+   * §8 Gap 1. Apply the request-shaping contract to an assembled body: strip forbidden keys from
+   * requestParams, shallow-merge requestParams (caller wins), then run bodyTransform last. Called at
+   * every LLM body-build site so the ordering contract holds identically on all four paths.
+   */
+  private finalizeBody(body: Record<string, any>): Record<string, any> {
+    const rp = this.opts.requestParams
+    if (rp) {
+      for (const [k, v] of Object.entries(rp)) {
+        if (k === "messages" || k === "tools" || k === "stream") {
+          console.warn(`[toolnexus] requestParams key "${k}" is not allowed — ignored (use bodyTransform)`)
+          continue
+        }
+        body[k] = v
+      }
+    }
+    if (this.opts.bodyTransform) {
+      const out = this.opts.bodyTransform(body)
+      if (out) return out
+    }
+    return body
+  }
+
+  /** §8 Gap 5. OpenAI-style body; omits tools/tool_choice when the tool list is empty. Key order
+   * matches the pre-change body so a no-options call is byte-identical. */
+  private openaiBody(messages: any[], tools: any[], stream: boolean): Record<string, any> {
+    const b: Record<string, any> = { model: this.opts.model, messages }
+    if (tools.length) {
+      b.tools = tools
+      b.tool_choice = "auto"
+    }
+    if (stream) {
+      b.stream = true
+      b.stream_options = { include_usage: true }
+    }
+    return this.finalizeBody(b)
+  }
+
+  /** §8 Gap 5. Anthropic-style body; omits tools when the tool list is empty. */
+  private anthropicBody(system: string, messages: any[], tools: any[], stream: boolean): Record<string, any> {
+    const b: Record<string, any> = { model: this.opts.model, max_tokens: 4096, system, messages }
+    if (tools.length) b.tools = tools
+    if (stream) b.stream = true
+    return this.finalizeBody(b)
+  }
+
   /** Prometheus text exposition of cumulative metrics (§8). Always valid, empty-but-valid before activity. */
   metrics(): string {
     return this.registry.render()
@@ -379,7 +446,7 @@ export class Client {
     let lastErr: unknown
     for (let attempt = 0; attempt <= retries; attempt++) {
       try {
-        const res = await fetch(url, { ...init, signal })
+        const res = await (this.opts.fetch ?? fetch)(url, { ...init, signal })
         if (res.ok || !RETRYABLE.has(res.status) || attempt === retries) return res
         const ra = Number(res.headers.get("retry-after"))
         await delay(ra ? ra * 1000 : base * 2 ** attempt + Math.random() * 100, signal)
@@ -470,7 +537,7 @@ export class Client {
         const data: any = await this.llmCallJson(`${this.opts.baseUrl.replace(/\/$/, "")}/chat/completions`, {
           method: "POST",
           headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json", ...this.opts.headers },
-          body: JSON.stringify({ model: this.opts.model, messages, tools, tool_choice: "auto" }),
+          body: JSON.stringify(this.openaiBody(messages, tools, false)),
         }, signal, "openai")
         addUsage(usage, data.usage, "openai")
         if (this.opts.hooks?.afterLLM) await this.opts.hooks.afterLLM({ response: data, model: this.opts.model, turn })
@@ -570,7 +637,7 @@ export class Client {
             "Content-Type": "application/json",
             ...this.opts.headers,
           },
-          body: JSON.stringify({ model: this.opts.model, max_tokens: 4096, system, messages, tools }),
+          body: JSON.stringify(this.anthropicBody(system, messages, tools, false)),
         }, signal, "anthropic")
         addUsage(usage, data.usage, "anthropic")
         if (this.opts.hooks?.afterLLM) await this.opts.hooks.afterLLM({ response: data, model: this.opts.model, turn })
@@ -646,7 +713,7 @@ export class Client {
           const res = await this.llmFetch(`${this.opts.baseUrl.replace(/\/$/, "")}/chat/completions`, {
             method: "POST",
             headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json", ...this.opts.headers },
-            body: JSON.stringify({ model: this.opts.model, messages, tools, tool_choice: "auto", stream: true, stream_options: { include_usage: true } }),
+            body: JSON.stringify(this.openaiBody(messages, tools, true)),
           }, signal)
           if (!res.ok || !res.body) throw new Error(`LLM ${res.status}: ${await res.text()}`)
           for await (const line of sseLines(res.body)) {
@@ -740,7 +807,7 @@ export class Client {
           const res = await this.llmFetch(endpoint, {
             method: "POST",
             headers: { "x-api-key": key, "anthropic-version": "2023-06-01", "Content-Type": "application/json", ...this.opts.headers },
-            body: JSON.stringify({ model: this.opts.model, max_tokens: 4096, system, messages, tools, stream: true }),
+            body: JSON.stringify(this.anthropicBody(system, messages, tools, true)),
           }, signal)
           if (!res.ok || !res.body) throw new Error(`LLM ${res.status}: ${await res.text()}`)
           for await (const line of sseLines(res.body)) {

package/src/mcp.ts

@@ -51,6 +51,10 @@ export interface LocalServer {
   enabled?: boolean
   disabled?: boolean
   timeout?: number
+  /** §2 Gap 7. Per-server tool allowlist keyed on ORIGINAL tool name; same semantics as the
+   * builtins/skills filter (nil/empty ⇒ all; ≥1 true ⇒ allowlist; only-false ⇒ drop-list; unknown
+   * ⇒ ignore+warn). Applied to the listed defs before sanitize/prefix. */
+  tools?: Record<string, boolean>
 }
 
 export interface RemoteServer {
@@ -60,6 +64,8 @@ export interface RemoteServer {
   enabled?: boolean
   disabled?: boolean
   timeout?: number
+  /** §2 Gap 7. Per-server tool allowlist (see LocalServer.tools). */
+  tools?: Record<string, boolean>
 }
 
 export type ServerConfig = LocalServer | RemoteServer
@@ -128,6 +134,40 @@ function joinTextContent(content: unknown): string {
     .join("\n")
 }
 
+/**
+ * §2 Gap 7. Apply a per-server tool allowlist to the listed defs. Same semantics as the builtins
+ * and skills filters: nil/empty ⇒ all; ≥1 true ⇒ allowlist (only true names); only-false ⇒ drop-list
+ * over all-on; unknown names ignored + warned once. Keyed on ORIGINAL tool name.
+ */
+function applyToolsFilter(server: string, defs: McpToolDef[], filter?: Record<string, boolean>): McpToolDef[] {
+  if (!filter) return defs
+  const keys = Object.keys(filter)
+  if (keys.length === 0) return defs
+  const hasTrue = keys.some((k) => filter[k] === true)
+  const present = new Set(defs.map((d) => d.name))
+  for (const k of keys) {
+    if (!present.has(k)) console.warn(`[toolnexus] server "${server}" tools filter name "${k}" matched no tool`)
+  }
+  return defs.filter((d) => (hasTrue ? filter[d.name] === true : filter[d.name] !== false))
+}
+
+/**
+ * §2 Gap 3. Race a promise against a per-server timeout and the caller's abort signal, so a hung
+ * connect/list is bounded (the SSE fallback included) and a parent cancellation aborts promptly.
+ */
+function raceTimeout<T>(p: Promise<T>, ms: number, signal?: AbortSignal): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => { cleanup(); reject((signal as any)?.reason ?? new Error("aborted")) }
+    const t = setTimeout(() => { cleanup(); reject(new Error("mcp connect/list timeout")) }, ms)
+    const cleanup = () => { clearTimeout(t); signal?.removeEventListener("abort", onAbort) }
+    if (signal) {
+      if (signal.aborted) return onAbort()
+      signal.addEventListener("abort", onAbort, { once: true })
+    }
+    p.then((v) => { cleanup(); resolve(v) }, (e) => { cleanup(); reject(e) })
+  })
+}
+
 async function paginateTools(client: Client, timeout: number): Promise<McpToolDef[]> {
   const result: McpToolDef[] = []
   const cursors = new Set<string>()
@@ -182,13 +222,59 @@ export interface McpSource {
   close(): Promise<void>
 }
 
-/** Connect to every enabled server, list + convert tools. Failures are isolated. */
-export async function loadMcp(input: string | object, opts?: { waitFor?: (request: Request) => Promise<Answer> }): Promise<McpSource> {
+/** Create a fresh (not-yet-connected) client, with the elicitation bridge attached if a waitFor
+ *  exists. Separated from connect so the caller ALWAYS holds a closeable reference — even if the
+ *  connect is later abandoned by a timeout/abort, `client.close()` still terminates any spawned
+ *  stdio child (no orphaned processes on cancellation). */
+function newMcpClient(waitFor?: (request: Request) => Promise<Answer>): Client {
+  const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: waitFor ? { elicitation: {} } : {} })
+  if (waitFor) {
+    client.setRequestHandler(ElicitRequestSchema, async (request) =>
+      answerToElicitResult(await waitFor(elicitationToRequest(request.params))),
+    )
+  }
+  return client
+}
+
+/** Connect an existing client's transport (remote streamable-HTTP with SSE fallback, or local stdio). */
+async function connectTransport(client: Client, cfg: ServerConfig): Promise<void> {
+  if (isRemote(cfg)) {
+    const url = new URL(cfg.url)
+    const expanded = expandEnvHeaders(cfg.headers)
+    const requestInit = expanded ? { headers: expanded } : undefined
+    try {
+      await client.connect(new StreamableHTTPClientTransport(url, { requestInit }))
+    } catch {
+      await client.connect(new SSEClientTransport(url, { requestInit }))
+    }
+  } else {
+    const local = cfg as LocalServer
+    const [cmd, ...args] = local.command
+    await client.connect(
+      new StdioClientTransport({
+        command: cmd,
+        args,
+        cwd: local.cwd,
+        env: { ...(process.env as Record<string, string>), ...(local.environment ?? local.env ?? {}) },
+        stderr: "pipe",
+      }),
+    )
+  }
+}
+
+/** Connect to every enabled server, list + convert tools. Failures are isolated.
+ *  §2 Gap 3: an optional `signal` bounds each connect/list by the server timeout and aborts the
+ *  whole load promptly on parent cancellation. */
+export async function loadMcp(
+  input: string | object,
+  opts?: { waitFor?: (request: Request) => Promise<Answer>; signal?: AbortSignal },
+): Promise<McpSource> {
   const config = parseMcpConfig(input)
   const tools: Tool[] = []
   const status: Record<string, McpStatus> = {}
   const clients: Client[] = []
   const waitFor = opts?.waitFor
+  const signal = opts?.signal
 
   await Promise.all(
     Object.entries(config).map(async ([name, cfg]) => {
@@ -197,45 +283,22 @@ export async function loadMcp(input: string | object, opts?: { waitFor?: (reques
         return
       }
       const timeout = cfg.timeout ?? DEFAULT_TIMEOUT
-      // Advertise elicitation + register the bridge ONLY when a waitFor exists to satisfy it —
-      // a waitFor-less host degrades cleanly (the server won't elicit). (§10 elicitation bridge)
-      const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: waitFor ? { elicitation: {} } : {} })
-      if (waitFor) {
-        client.setRequestHandler(ElicitRequestSchema, async (request) =>
-          answerToElicitResult(await waitFor(elicitationToRequest(request.params))),
-        )
-      }
+      // Create the client up front so a timed-out/aborted connect still has a closeable handle
+      // (its stdio child is killed by close() — never orphaned).
+      const client = newMcpClient(waitFor)
       try {
-        if (isRemote(cfg)) {
-          const url = new URL(cfg.url)
-          const expanded = expandEnvHeaders(cfg.headers)
-          const requestInit = expanded ? { headers: expanded } : undefined
-          try {
-            await client.connect(new StreamableHTTPClientTransport(url, { requestInit }))
-          } catch {
-            await client.connect(new SSEClientTransport(url, { requestInit }))
-          }
-        } else {
-          const local = cfg as LocalServer
-          const [cmd, ...args] = local.command
-          await client.connect(
-            new StdioClientTransport({
-              command: cmd,
-              args,
-              cwd: local.cwd,
-              env: { ...(process.env as Record<string, string>), ...(local.environment ?? local.env ?? {}) },
-              stderr: "pipe",
-            }),
-          )
-        }
-        const defs = await paginateTools(client, timeout)
-        for (const def of defs) tools.push(convertTool(name, def, client, timeout))
+        await raceTimeout(connectTransport(client, cfg), timeout, signal)
+        const defs = await raceTimeout(paginateTools(client, timeout), timeout, signal)
+        const kept = applyToolsFilter(name, defs, (cfg as { tools?: Record<string, boolean> }).tools)
+        for (const def of kept) tools.push(convertTool(name, def, client, timeout))
         clients.push(client)
         status[name] = "connected"
       } catch (e) {
         status[name] = "failed"
         await client.close().catch(() => {})
-        // one bad server never breaks the toolkit
+        // Parent cancellation/deadline aborts the whole load (§2 Gap 3, A1); a per-server timeout
+        // within budget isolates just this server.
+        if (signal?.aborted) throw e
         console.warn(`[toolnexus] MCP server "${name}" failed: ${e instanceof Error ? e.message : String(e)}`)
       }
     }),
@@ -249,3 +312,62 @@ export async function loadMcp(input: string | object, opts?: { waitFor?: (reques
     },
   }
 }
+
+/** §2 Gap 6. One listed tool definition (original, unprefixed name). */
+export interface ToolInfo {
+  name: string
+  description: string
+  inputSchema: JSONSchema
+}
+
+/** §2 Gap 6. Result of a list-only pass over an MCP config. */
+export interface McpInventory {
+  /** server → its full listed tool defs, UNFILTERED by ServerConfig.tools (authors the allowlist). */
+  tools: Record<string, ToolInfo[]>
+  status: Record<string, McpStatus>
+}
+
+/**
+ * §2 Gap 6. Connect to every enabled server, list tool definitions, and DISCONNECT before
+ * returning — no toolkit, no execute wiring, nothing left running. Failure isolation as in loadMcp.
+ */
+export async function listMcpTools(input: string | object, opts?: { signal?: AbortSignal }): Promise<McpInventory> {
+  const config = parseMcpConfig(input)
+  const toolsByServer: Record<string, ToolInfo[]> = {}
+  const status: Record<string, McpStatus> = {}
+  const signal = opts?.signal
+
+  await Promise.all(
+    Object.entries(config).map(async ([name, cfg]) => {
+      if (!isEnabled(cfg)) {
+        status[name] = "disabled"
+        return
+      }
+      const timeout = cfg.timeout ?? DEFAULT_TIMEOUT
+      // Client created up front so an aborted/timed-out connect is still closed (no orphaned child).
+      const client = newMcpClient()
+      try {
+        await raceTimeout(connectTransport(client, cfg), timeout, signal)
+        const defs = await raceTimeout(paginateTools(client, timeout), timeout, signal)
+        toolsByServer[name] = defs.map((d) => ({
+          name: d.name,
+          description: d.description ?? "",
+          inputSchema: {
+            ...(d.inputSchema as object),
+            type: "object",
+            properties: (d.inputSchema?.properties ?? {}) as Record<string, unknown>,
+          } as JSONSchema,
+        }))
+        status[name] = "connected"
+      } catch (e) {
+        status[name] = "failed"
+        if (signal?.aborted) { await client.close().catch(() => {}); throw e }
+        console.warn(`[toolnexus] MCP server "${name}" failed: ${e instanceof Error ? e.message : String(e)}`)
+      } finally {
+        await client.close().catch(() => {})
+      }
+    }),
+  )
+
+  return { tools: toolsByServer, status }
+}

package/src/toolkit.ts

@@ -35,6 +35,9 @@ export interface ToolkitOptions {
    * elicitation is not advertised.
    */
   waitFor?: (request: import("./types.js").Request) => Promise<import("./types.js").Answer>
+  /** §2 Gap 3. Bounds the MCP load: each connect/list is capped by the server timeout and the
+   * whole load aborts promptly if this signal fires. Omit ⇒ unbounded as before. */
+  signal?: AbortSignal
 }
 
 export class Toolkit {
@@ -66,7 +69,7 @@ export class Toolkit {
   }
 
   static async create(opts: ToolkitOptions): Promise<Toolkit> {
-    const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor }) : undefined
+    const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor, signal: opts.signal }) : undefined
     // Skills come from directories, in-memory data, and/or a lazy provider (§3,
     // S1). The provider is resolved here (create() is async) and merged with the
     // data list; a provider failure is isolated so other sources still load.