@sigrun/ext-mcp 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-13
+### Added
+- Renamed to `@sigrun/ext-mcp` for the 0.1.0 release (repo stays
+  `sigrun-ai/sigrun-ext-mcp`): published package metadata
+  (`publishConfig` access/provenance), host modules moved to
+  `peerDependencies` mirrored in `devDependencies` at exact pins
+  (`typebox` now declared — it was an undeclared host import),
+  CHANGELOG.md joined the files whitelist, and a manifest hygiene check
+  wired into `npm test`.
+- MCP client over stdio: server discovery, tool registration (`<server>/<tool>`
+  naming), OAuth (PKCE paste-the-URL flow) with a durable token store.
+- The MCP exposure model on pi-durable 1.2.0: per-server
+  `exposure: codemode|deferred|direct|hidden` (default `codemode`),
+  per-tool `toolExposure` overrides (exact over patterns, first wins),
+  `enabled`, and per-request `timeout` with progress-notification reset.
+- The `mcp_servers` prompt section: live-rendered, 4KB whole-line-truncated,
+  gated on the discovery tool being model-offered, with an honest
+  enable-notice line for unreachable servers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael MacLeod
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# @sigrun/ext-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Register MCP server tools as pi-durable tools, named `<server>/<tool>`.
+
+Config: `~/.config/sigrun/mcp.json` (or the `SIGRUN_MCP_CONFIG` env override
+pointing at any path). Each entry under `"servers"` names a stdio MCP server:
+
+```json
+{
+	"servers": {
+		"github": {
+			"command": "npx",
+			"args": ["-y", "@modelcontextprotocol/server-github"],
+			"exposure": "codemode",
+			"timeout": 120
+		}
+	}
+}
+```
+
+## Server fields
+
+- `command`, `args` (required) — how to spawn the server.
+- `env` — extra environment variables for the child process.
+- `enabled` (default `true`) / `disabled` — skip the server entirely. Set one,
+  never both: a server that is simultaneously on and off is a config error and
+  fails loudly.
+- `timeout` — per-request wire timeout in seconds (default `60`). A request
+  that gets no reply by its deadline rejects. A server that keeps sending
+  `notifications/progress` for a pending request never dies at the deadline
+  while it keeps reporting work — progress resets the deadline.
+- `exposure` — how the server's tools register (see below). Default `"codemode"`.
+- `toolExposure` — per-tool overrides of `exposure`: an object mapping tool
+  names (exact) or `*`-globs (e.g. `"get-*"`) to exposure words. An exact name
+  always wins; among matching patterns the FIRST one in config order wins.
+- `oauth` — the authorization-code (PKCE) flow block; see `sigrun-ext-mcp oauth
+  <server>` (the CLI mints and stores a token; the spawn injects it).
+
+## Exposure: how tools reach callers
+
+On pi-durable 1.2.0 semantics, `"exposure"` decides who can call a server's
+tools:
+
+| exposure    | registration              | who can call                          |
+| ----------- | ------------------------- | ------------------------------------- |
+| `codemode`  | `callers: ["tools"]`      | scripts only (never model-offered)    |
+| `deferred`  | `deferred: true`          | the model, once `tool_search` loads it |
+| `direct`    | normal                    | the model (offered when in the set)   |
+| `hidden`    | not registered            | nobody (config entry kept)            |
+
+The `codemode-deferred` word is kept as an alias for `codemode` (pi compat).
+
+### The default flip — a breaking change
+
+**Before 1.2.0, an `mcp.json` server entry with no `exposure` field had its
+tools offered to the model. Now the default is `"codemode"`:** a
+default-exposure server's tools are callable by scripts (codemode), never
+offered to the model directly. To restore the old behavior, set the server
+(or the tool, via `toolExposure`) to `"exposure": "direct"`:
+
+```json
+{ "exposure": "direct" }
+```
+
+The `mcp_servers` system-prompt section lists codemode/deferred servers when
+their discovery tool (`codemode`, `tool_search`) is offered in the request;
+when such servers exist but their tools are unreachable, it appends one
+notice line naming the count and the Settings → default tools fix.
+
+## Tool naming: `<server>/<tool>` (decision)
+
+Tools keep the existing `<server>/<tool>` shape rather than upstream pi's
+`mcp__<server>__<tool>`:
+
+- The upstream codemode section groups tools by `CodemodeNamespace.prefix`
+  (longest match wins), and the namespaces are **config-side** — the host
+  passes the groups, so any naming can namespace trivially: ours groups as
+  `prefix: "<server>/"` with no rename at all.
+- The name-addressed surface makes per-tool replacement and `toolExposure`
+  patterns readable (`"github/*"`), and the existing wire name is already
+  deployed in configs and scripts.
+
+No section-rendering compat requires the upstream spelling; the decision is
+recorded here per the spec's open item.
+
+## Replacement semantics
+
+Replacement works by not installing ours and installing yours: the
+name-addressed tool surface (`<server>/<tool>`) makes per-name replacement
+trivial. Co-installing this package with another that registers the same
+tool names shadows silently (pi-durable resolves cross-extension duplicates
+last-selected-wins) — **do not co-install**. Sigrun's extension loader
+(made the shadowing visible at boot: it `console.warn`s once per duplicate
+tool name, naming the extensions and the last-wins resolution) but the
+warning changes nothing: last-wins stands. Replace, don't co-install.

package/dist/bin.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The package bin entry (`sigrun-ext-mcp` → dist/bin.js): parse-and-run the
+ * CLI, mapping the result to the process exit code. The body lives in
+ * ./cli.ts so tests can exercise it without spawning a process.
+ */
+export {};

package/dist/bin.js

@@ -0,0 +1,9 @@
+/**
+ * The package bin entry (`sigrun-ext-mcp` → dist/bin.js): parse-and-run the
+ * CLI, mapping the result to the process exit code. The body lives in
+ * ./cli.ts so tests can exercise it without spawning a process.
+ */
+import { runCli } from "./cli.js";
+void runCli(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+});

package/dist/cli.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The `sigrun-ext-mcp` CLI bin (ruling 4): `sigrun-ext-mcp oauth <server>`
+ * runs the paste-the-URL OAuth flow for one configured server.
+ *
+ * argv surface (parsed minimally — no new deps):
+ *   sigrun-ext-mcp oauth <server> [--paste]
+ *
+ * Default mode: the loopback listener runs AND stdin is read (paste
+ * fallback) — first arrival wins. `--paste` is accepted for hosts that want
+ * the semantics explicit; the flow is identical either way.
+ *
+ * Prints to stdout:
+ *   - the authorize URL (open this in a browser)
+ *   - the redirect_uri (what the AS will redirect to)
+ *   - a paste prompt
+ * Exits 0 with the token stored, or 1 with a clear error (usage / config /
+ * flow / 5-minute timeout).
+ */
+/** Parse argv minimally: `oauth <server> [--paste]`. */
+export declare function parseCliArgs(argv: readonly string[]): {
+    readonly command: "oauth";
+    readonly server: string;
+    readonly paste: boolean;
+};
+/** The CLI body (exported for tests); returns the process exit code. */
+export declare function runCli(argv: readonly string[], io?: {
+    readonly stdout: NodeJS.WriteStream;
+    readonly stderr: NodeJS.WriteStream;
+}): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,109 @@
+/**
+ * The `sigrun-ext-mcp` CLI bin (ruling 4): `sigrun-ext-mcp oauth <server>`
+ * runs the paste-the-URL OAuth flow for one configured server.
+ *
+ * argv surface (parsed minimally — no new deps):
+ *   sigrun-ext-mcp oauth <server> [--paste]
+ *
+ * Default mode: the loopback listener runs AND stdin is read (paste
+ * fallback) — first arrival wins. `--paste` is accepted for hosts that want
+ * the semantics explicit; the flow is identical either way.
+ *
+ * Prints to stdout:
+ *   - the authorize URL (open this in a browser)
+ *   - the redirect_uri (what the AS will redirect to)
+ *   - a paste prompt
+ * Exits 0 with the token stored, or 1 with a clear error (usage / config /
+ * flow / 5-minute timeout).
+ */
+import { createInterface } from "node:readline";
+import { loadMcpConfig, MCP_CONFIG_ENV } from "./config.js";
+import { startOauth } from "./oauth.js";
+import { resolveMcpTokenPath } from "./tokens.js";
+/** The flow timeout (matches startOauth's default; explicit so the user's
+ * error message is deterministic). */
+const TIMEOUT_MS = 5 * 60_000;
+/** Print the usage banner. */
+function usage(out) {
+    out.write("usage: sigrun-ext-mcp oauth <server> [--paste]\n");
+    out.write(`reads the MCP config (env ${MCP_CONFIG_ENV} or ~/.config/sigrun/mcp.json);\n` +
+        `the named server needs an oauth block; the token is stored beside the\n` +
+        `config as mcp-tokens.json (0600)\n`);
+}
+/** Parse argv minimally: `oauth <server> [--paste]`. */
+export function parseCliArgs(argv) {
+    const args = [...argv];
+    const head = args.shift();
+    if (head !== "oauth") {
+        throw new Error(`unknown command: ${String(head)}`);
+    }
+    const paste = args.includes("--paste");
+    const positional = args.filter((arg) => arg !== "--paste");
+    if (positional.length !== 1) {
+        throw new Error("expected exactly one server name");
+    }
+    return { command: "oauth", server: positional[0], paste };
+}
+/** Load the config, turning a malformed config into exit-1 (not a crash). */
+function loadMcpConfigSafe(stderr) {
+    try {
+        return loadMcpConfig();
+    }
+    catch (cause) {
+        stderr.write(`error: ${cause instanceof Error ? cause.message : String(cause)}\n`);
+        process.exit(1);
+    }
+}
+/** The CLI body (exported for tests); returns the process exit code. */
+export async function runCli(argv, io = { stdout: process.stdout, stderr: process.stderr }) {
+    let parsed;
+    try {
+        parsed = parseCliArgs(argv);
+    }
+    catch (cause) {
+        usage(io.stderr);
+        io.stderr.write(`error: ${cause instanceof Error ? cause.message : String(cause)}\n`);
+        return 1;
+    }
+    const config = loadMcpConfigSafe(io.stderr);
+    const server = config.servers[parsed.server];
+    if (server === undefined) {
+        io.stderr.write(`error: no server named "${parsed.server}" in the MCP config\n`);
+        return 1;
+    }
+    if (server.oauth === undefined) {
+        io.stderr.write(`error: server "${parsed.server}" has no oauth block in the MCP config\n`);
+        return 1;
+    }
+    const flow = await startOauth(parsed.server, server.oauth, {
+        timeoutMs: TIMEOUT_MS,
+    });
+    io.stdout.write(`Authorize URL:\n  ${flow.authorizeUrl}\n`);
+    io.stdout.write(`Redirect URI:\n  ${flow.redirectUri}\n`);
+    io.stdout.write("Open the Authorize URL in a browser and approve. If the redirect does\n" +
+        "not reach this machine, paste the FULL redirected URL here instead:\n");
+    // The paste fallback: every stdin line is fed to the flow; first arrival
+    // wins (the loopback listener or the paste settles the code). pasteUrl
+    // never throws (lines with no code are ignored), so the readline handler
+    // cannot crash the bin.
+    const lines = createInterface({ input: process.stdin });
+    lines.on("line", (line) => {
+        const trimmed = line.trim();
+        if (trimmed !== "")
+            flow.pasteUrl(trimmed);
+    });
+    try {
+        await flow.done;
+        lines.close();
+        io.stdout.write(`Token stored for "${parsed.server}" in:\n  ${resolveMcpTokenPath()}\n`);
+        return 0;
+    }
+    catch (cause) {
+        lines.close();
+        flow.stop();
+        io.stderr.write(`error: ${cause instanceof Error ? cause.message : String(cause)}\n`);
+        return 1;
+    }
+}
+// This module is the CLI body only (pure exports; importable for tests).
+// The bin entry lives in ./bin.ts — dist/bin.js is the package.json "bin".

package/dist/client.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Minimal hand-rolled MCP stdio client (ruling 3): JSON-RPC 2.0 over
+ * newline-delimited stdio, no pi-mcp dependency.
+ *
+ * Lifecycle: spawn → `initialize` handshake (protocolVersion "2025-06-18",
+ * clientInfo, capabilities) → `notifications/initialized` → `tools/list`
+ * (discovery) → `tools/call` (execution). Requests correlate by id; the
+ * response frame's `id` must match a pending request (a notification is
+ * never a reply). A spawn failure or handshake failure rejects `connect`,
+ * never affecting any other server (per-server isolation).
+ *
+ * Per-request timeout (codemode parity, spec slice 3): every request REJECTS
+ * at its deadline (default 60s; config `timeout` per server) instead of
+ * awaiting a hung server forever. A `notifications/progress` frame naming a
+ * pending request's id (sent as the request's `progressToken`) RESETS that
+ * request's deadline — a server that keeps reporting progress stays alive
+ * as long as it works. A timeout rejects the call but never kills the child
+ * (per-server isolation: the next request gets a fresh chance).
+ */
+import { type ChildProcess } from "node:child_process";
+import type { McpServerConfig, McpToolDefinition, McpToolResult } from "./types.js";
+/** One connected MCP server: a live child process speaking JSON-RPC. */
+export declare class McpClient {
+    #private;
+    /** @internal constructed by {@link connectMcpServer}. */
+    constructor(name: string, child: ChildProcess);
+    /**
+     * The MCP handshake: `initialize` then `notifications/initialized`.
+     * The initialize reply is validated to carry the protocol version.
+     */
+    handshake(): Promise<void>;
+    /** Discover the server's tools (`tools/list`). */
+    listTools(): Promise<McpToolDefinition[]>;
+    /** Execute one tool (`tools/call`); an `isError` result resolves (it is a
+     * valid tool outcome, not a protocol failure). `timeoutSeconds` caps the
+     * wait per request (default 60; progress notifications reset it). */
+    callTool(name: string, args: Record<string, unknown>, timeoutSeconds?: number): Promise<McpToolResult>;
+    /** Wait for the child to exit (used by tests / shutdown checks). */
+    exited(): Promise<Error | undefined>;
+    /** Kill the child and tear down (idempotent). */
+    close(): void;
+}
+/**
+ * Spawn and connect one configured MCP server. Throws on spawn failure or a
+ * failed handshake — per-server isolation is the CALLER's policy (the
+ * extension connects all servers with `.catch` per server).
+ */
+export declare function connectMcpServer(name: string, config: McpServerConfig): Promise<McpClient>;

package/dist/client.js

@@ -0,0 +1,279 @@
+/**
+ * Minimal hand-rolled MCP stdio client (ruling 3): JSON-RPC 2.0 over
+ * newline-delimited stdio, no pi-mcp dependency.
+ *
+ * Lifecycle: spawn → `initialize` handshake (protocolVersion "2025-06-18",
+ * clientInfo, capabilities) → `notifications/initialized` → `tools/list`
+ * (discovery) → `tools/call` (execution). Requests correlate by id; the
+ * response frame's `id` must match a pending request (a notification is
+ * never a reply). A spawn failure or handshake failure rejects `connect`,
+ * never affecting any other server (per-server isolation).
+ *
+ * Per-request timeout (codemode parity, spec slice 3): every request REJECTS
+ * at its deadline (default 60s; config `timeout` per server) instead of
+ * awaiting a hung server forever. A `notifications/progress` frame naming a
+ * pending request's id (sent as the request's `progressToken`) RESETS that
+ * request's deadline — a server that keeps reporting progress stays alive
+ * as long as it works. A timeout rejects the call but never kills the child
+ * (per-server isolation: the next request gets a fresh chance).
+ */
+import { spawn } from "node:child_process";
+import { spawnEnvWithToken } from "./tokens.js";
+import { DEFAULT_TIMEOUT_SECONDS } from "./config.js";
+const MCP_PROTOCOL_VERSION = "2025-06-18";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** One connected MCP server: a live child process speaking JSON-RPC. */
+export class McpClient {
+    #process;
+    #stdin;
+    #stdout;
+    #name;
+    #nextId = 1;
+    #buffer = "";
+    #pending = new Map();
+    #exitError;
+    /** True when the child exited through an intentional close(). */
+    #exitClean = false;
+    #exitWaiters = [];
+    #closed = false;
+    /** @internal constructed by {@link connectMcpServer}. */
+    constructor(name, child) {
+        this.#name = name;
+        this.#process = child;
+        if (child.stdin === null || child.stdout === null) {
+            throw new Error(`mcp server "${name}" spawned without stdio`);
+        }
+        this.#stdin = child.stdin;
+        this.#stdout = child.stdout;
+        this.#stdout.setEncoding("utf8");
+        this.#stdout.on("data", (chunk) => this.#onData(chunk));
+        this.#stdout.on("error", () => this.#failExits()); // closed pipe: ignore
+        // A broken stdin pipe (server died) must not crash the host with an
+        // unhandled stream error; surface it as the exit error instead.
+        this.#stdin.on("error", () => this.#failExits());
+        this.#process.on("error", (error) => this.#setExitError(error));
+        this.#process.on("exit", () => this.#setExitError(undefined));
+    }
+    #onData(chunk) {
+        this.#buffer += chunk;
+        for (;;) {
+            const newline = this.#buffer.indexOf("\n");
+            if (newline < 0)
+                return;
+            const line = this.#buffer.slice(0, newline).trim();
+            this.#buffer = this.#buffer.slice(newline + 1);
+            if (line === "")
+                continue;
+            this.#onLine(line);
+        }
+    }
+    #onLine(line) {
+        let frame;
+        try {
+            frame = JSON.parse(line);
+        }
+        catch {
+            return; // a non-JSON line (server chatter) is not a protocol reply
+        }
+        if (frame.id === undefined || frame.id === null) {
+            // A frame with no id is a server-initiated NOTIFICATION (a reply
+            // always carries the request's id). A `notifications/progress`
+            // frame whose `progressToken` names a PENDING request resets that
+            // request's deadline — the server is alive and still working, so
+            // a long job must not die at the deadline while it keeps
+            // reporting progress. Every other notification is ignored.
+            if (frame.method === "notifications/progress" &&
+                isRecord(frame.params) &&
+                typeof frame.params.progressToken === "number") {
+                this.#pending.get(frame.params.progressToken)?.resetTimeout();
+            }
+            return;
+        }
+        // A reply: its id must be one of ours (a notification is never a
+        // reply, and a non-numeric id is not one of our requests).
+        if (typeof frame.id !== "number")
+            return;
+        const pending = this.#pending.get(frame.id);
+        if (pending === undefined)
+            return;
+        this.#pending.delete(frame.id);
+        pending.clearTimeout();
+        if (frame.error !== undefined) {
+            pending.reject(new Error(`mcp server "${this.#name}" ${frame.error.message} (code ${frame.error.code})`));
+        }
+        else {
+            pending.resolve(frame.result);
+        }
+    }
+    #setExitError(error) {
+        if (this.#exitError !== undefined)
+            return;
+        // An INTENTIONAL close() is a clean shutdown: resolve waiters with no
+        // error (a close is a shutdown, never a failure).
+        if (this.#closed)
+            this.#exitClean = true;
+        const waiters = this.#exitWaiters;
+        this.#exitWaiters = [];
+        if (!this.#exitClean) {
+            this.#exitError =
+                error ??
+                    new Error(`mcp server "${this.#name}" exited early (code ${this.#process.exitCode ?? "?"})`);
+        }
+        for (const waiter of waiters)
+            waiter(this.#exitError);
+        this.#rejectPending();
+    }
+    #failExits() {
+        // stdout closed: surface as an exit error if the process has not yet
+        // reported one, so a hung `tools/call` unwinds.
+        this.#setExitError(undefined);
+    }
+    #rejectPending() {
+        const pending = [...this.#pending.values()];
+        this.#pending.clear();
+        for (const entry of pending) {
+            entry.clearTimeout();
+            entry.reject(this.#exitError ?? new Error("mcp server closed"));
+        }
+    }
+    /** Write one frame as a single newline-terminated line. */
+    #write(frame) {
+        if (this.#closed)
+            throw new Error(`mcp server "${this.#name}" is closed`);
+        this.#stdin.write(JSON.stringify(frame) + "\n");
+    }
+    /**
+     * Send a request and await its reply (id-correlated) under a per-request
+     * deadline. `timeoutSeconds` defaults to 60; the request's id doubles as
+     * the `progressToken` it advertises (in `params._meta`, per the MCP
+     * convention), so progress notifications can name it.
+     */
+    #request(method, params, timeoutSeconds) {
+        const id = this.#nextId++;
+        const seconds = timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
+        return new Promise((resolve, reject) => {
+            let timer;
+            const entry = {
+                resolve,
+                reject,
+                // A progress notification naming this request id restarts the
+                // deadline wait (the server is alive and still working).
+                resetTimeout: () => {
+                    clearTimeout(timer);
+                    timer = setTimeout(deadline, seconds * 1000);
+                },
+                clearTimeout: () => {
+                    clearTimeout(timer);
+                    timer = undefined;
+                },
+            };
+            const fail = (error) => {
+                this.#pending.delete(id);
+                entry.clearTimeout();
+                reject(error);
+            };
+            const deadline = () => fail(new Error(`mcp server "${this.#name}" ${method} timed out after ${seconds}s`));
+            this.#pending.set(id, entry);
+            try {
+                // MCP convention: the progressToken rides in params._meta (a
+                // spec-conforming server reads/echoes it from there). params is
+                // merged (never mutated) so an object request keeps its fields;
+                // a null-params request (tools/list) gets params just for _meta.
+                const requestParams = isRecord(params)
+                    ? { ...params, _meta: { progressToken: id } }
+                    : { _meta: { progressToken: id } };
+                this.#write({
+                    jsonrpc: "2.0",
+                    id,
+                    method,
+                    params: requestParams,
+                });
+            }
+            catch (error) {
+                fail(error instanceof Error ? error : new Error(String(error)));
+                return;
+            }
+            timer = setTimeout(deadline, seconds * 1000);
+            if (this.#exitError !== undefined) {
+                // The server already died: unwind this request too.
+                fail(this.#exitError);
+            }
+        });
+    }
+    /**
+     * The MCP handshake: `initialize` then `notifications/initialized`.
+     * The initialize reply is validated to carry the protocol version.
+     */
+    async handshake() {
+        const result = (await this.#request("initialize", {
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: "sigrun-ext-mcp", version: "0.1.0" },
+        }, undefined));
+        if (typeof result?.protocolVersion !== "string") {
+            throw new Error(`mcp server "${this.#name}" handshake reply lacks protocolVersion`);
+        }
+        this.#write({ jsonrpc: "2.0", method: "notifications/initialized" });
+    }
+    /** Discover the server's tools (`tools/list`). */
+    async listTools() {
+        const result = (await this.#request("tools/list", undefined, undefined));
+        return result?.tools ?? [];
+    }
+    /** Execute one tool (`tools/call`); an `isError` result resolves (it is a
+     * valid tool outcome, not a protocol failure). `timeoutSeconds` caps the
+     * wait per request (default 60; progress notifications reset it). */
+    async callTool(name, args, timeoutSeconds) {
+        const result = (await this.#request("tools/call", { name, arguments: args }, timeoutSeconds));
+        if (result === undefined) {
+            throw new Error(`mcp server "${this.#name}" tools/call "${name}" returned no result`);
+        }
+        return result;
+    }
+    /** Wait for the child to exit (used by tests / shutdown checks). */
+    async exited() {
+        if (this.#exitError !== undefined)
+            return this.#exitError;
+        if (this.#process.exitCode !== null || this.#process.signalCode !== null) {
+            return undefined; // exited cleanly; already unwound pending
+        }
+        return new Promise((resolve) => {
+            this.#exitWaiters.push(resolve);
+        });
+    }
+    /** Kill the child and tear down (idempotent). */
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#process.kill("SIGTERM");
+        this.#rejectPending();
+    }
+}
+/**
+ * Spawn and connect one configured MCP server. Throws on spawn failure or a
+ * failed handshake — per-server isolation is the CALLER's policy (the
+ * extension connects all servers with `.catch` per server).
+ */
+export async function connectMcpServer(name, config) {
+    const child = spawn(config.command, [...config.args], {
+        stdio: ["pipe", "pipe", "pipe"],
+        // Token injection (ruling 3): a server with an oauth block AND a stored
+        // token gets it as MCP_ACCESS_TOKEN, merged over the server's own env.
+        env: { ...process.env, ...spawnEnvWithToken(name, config) },
+    });
+    const client = new McpClient(name, child);
+    try {
+        await client.handshake();
+    }
+    catch (cause) {
+        client.close();
+        child.kill("SIGKILL");
+        throw cause instanceof Error
+            ? cause
+            : new Error(`mcp server "${name}" handshake failed`);
+    }
+    return client;
+}