agent-from-zero 0.32.4 → 0.34.0

package/dist/mcp.js

@@ -1,7 +1,12 @@
 import { spawn } from "node:child_process"; // stdio servers are subprocesses
+import { createServer } from "node:http"; // the OAuth callback listener
+import crypto from "node:crypto"; // PKCE + state nonces
+import os from "node:os"; // home directory for token persistence
+import path from "node:path"; // path joining
+import fs from "node:fs"; // token file persistence
 import chalk from "chalk"; // status lines
 import { CONFIG } from "./config.js"; // configured servers
-import { registerExternalTool } from "./tools.js"; // expose discovered tools
+import { registerExternalTool, unregisterExternalTool } from "./tools.js"; // expose discovered tools
 import { emit } from "./telemetry.js"; // observability
 // MCP (Model Context Protocol) lets the agent borrow tools from external
 // servers — a filesystem server, a GitHub server, a database server, anything.
@@ -16,8 +21,44 @@ import { emit } from "./telemetry.js"; // observability
 //
 // Discovered tools are named mcp__<server>__<tool> so they never collide with
 // built-ins and the user can see (and gate) exactly where each came from.
+//
+// Since this file also drives the /mcp command, it keeps a REGISTRY of every
+// configured server and its live connection state (connected / failed /
+// needs-auth / disabled) so the UI can list them and reconnect/authenticate one
+// at a time — the way Claude Code's /mcp does.
+//
+// Remote servers (Linear, Slack, GitHub…) are OAuth-protected. The flow is the
+// MCP authorization spec end to end: the 401 challenge points at the resource
+// metadata (RFC 9728), which names the authorization server (RFC 8414); we
+// register a client dynamically (RFC 7591) unless the config carries a
+// pre-registered one; then authorization-code + PKCE with a loopback redirect,
+// the `resource` indicator (RFC 8707) on every token request, and refresh
+// tokens so a session survives token expiry without another browser round.
 const INIT_TIMEOUT_MS = 15_000; // a server that doesn't initialize in 15s is skipped
 const CALL_TIMEOUT_MS = 60_000; // a single tool call may take this long
+const OAUTH_CALLBACK_TIMEOUT_MS = 5 * 60_000; // how long the local callback waits for the browser
+const PROTOCOL_VERSION = "2024-11-05"; // the MCP revision we speak in the handshake
+const CLIENT_INFO = { name: "mini-agent", version: "0" }; // who we say we are in the handshake
+// Thrown when an HTTP MCP server answers 401 — the caller marks the server as
+// "needs auth" instead of "failed". The challenge header is parsed and kept:
+// it is the AUTHORITATIVE pointer to the OAuth metadata. Guessing well-known
+// paths is what breaks on servers like Slack, whose metadata sits at the origin
+// root rather than under the /mcp path.
+export class NeedsAuthError extends Error {
+    resourceMetadataUrl;
+    scope;
+    constructor(message, wwwAuthenticate) {
+        super(message);
+        this.name = "NeedsAuthError";
+        // The challenge is `Bearer key="value", key="value"…` — pull out the pairs we use.
+        for (const m of (wwwAuthenticate ?? "").matchAll(/(\w+)="([^"]*)"/g)) {
+            if (m[1] === "resource_metadata")
+                this.resourceMetadataUrl = m[2];
+            if (m[1] === "scope")
+                this.scope = m[2];
+        }
+    }
+}
 // ---- stdio transport: one JSON object per line, to a subprocess --------------
 class StdioTransport {
     child;
@@ -100,9 +141,11 @@ class HttpTransport {
     url;
     headers;
     sessionId; // assigned by the server on initialize, echoed on every later request
-    constructor(def) {
+    constructor(def, token) {
         this.url = def.url;
         this.headers = { ...def.headers };
+        if (token)
+            this.headers["authorization"] = `Bearer ${token}`; // OAuth access token
     }
     // The response to a POST may come back as a single JSON object OR as an SSE
     // stream carrying it. Either way we want the JSON-RPC message matching our id.
@@ -118,6 +161,9 @@ class HttpTransport {
             body: JSON.stringify(body),
             signal: AbortSignal.timeout(timeoutMs),
         });
+        if (res.status === 401) {
+            throw new NeedsAuthError(`MCP server at ${this.url} requires authentication`, res.headers.get("www-authenticate"));
+        }
         const sid = res.headers.get("mcp-session-id"); // initialize hands us a session to keep
         if (sid)
             this.sessionId = sid;
@@ -143,6 +189,8 @@ class HttpTransport {
             return msg ?? { id: payload.id, error: { message: `MCP request '${payload.method}' returned no response` } };
         }
         catch (err) {
+            if (err instanceof NeedsAuthError)
+                throw err; // propagate so the registry can mark needs-auth
             return { id: payload.id, error: { message: `MCP HTTP request '${payload.method}' failed: ${err.message}` } };
         }
     }
@@ -150,6 +198,9 @@ class HttpTransport {
         // Fire-and-forget; errors on a notification are not worth surfacing.
         void this.post({ jsonrpc: "2.0", method, params }, INIT_TIMEOUT_MS, false).catch(() => { });
     }
+    setToken(token) {
+        this.headers["authorization"] = `Bearer ${token}`; // a refreshed token; the session id stays valid
+    }
     close() {
         // Best-effort: tell the server to drop the session. No await, no error care.
         if (this.sessionId) {
@@ -158,23 +209,23 @@ class HttpTransport {
     }
 }
 // Choose the pipe from the config: a url means HTTP, otherwise spawn over stdio.
-function makeTransport(def) {
-    return def.url ? new HttpTransport(def) : new StdioTransport(def);
+function makeTransport(def, token) {
+    return def.url ? new HttpTransport(def, token) : new StdioTransport(def);
 }
 // The protocol layer: handshake, request ids, tool flattening. It talks to a
 // Transport and is blind to whether that's a subprocess or an HTTP endpoint.
 class McpClient {
     transport;
     nextId = 1; // JSON-RPC request id counter
-    constructor(def) {
-        this.transport = makeTransport(def);
+    constructor(def, token) {
+        this.transport = makeTransport(def, token);
     }
     request(method, params, timeoutMs) {
         return this.transport.request({ jsonrpc: "2.0", id: this.nextId++, method, params }, timeoutMs);
     }
     // The MCP startup dance: initialize → initialized → list tools.
     async start() {
-        const init = await this.request("initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "mini-agent", version: "0" } }, INIT_TIMEOUT_MS);
+        const init = await this.request("initialize", { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: CLIENT_INFO }, INIT_TIMEOUT_MS);
         if (init.error)
             throw new Error(init.error.message); // server refused to initialize
         this.transport.notify("notifications/initialized", {}); // tell the server we're ready
@@ -192,46 +243,548 @@ class McpClient {
         const body = text || "(no output)";
         return res.result?.isError ? `[error] ${body}` : body; // MCP can flag a logical error in a successful response
     }
+    // Swap the bearer token after a refresh (a no-op for stdio).
+    setToken(token) {
+        this.transport.setToken?.(token);
+    }
     kill() {
         this.transport.close();
     }
 }
+const registry = new Map();
+// OAuth tokens persist to the global config dir so a reconnect across sessions
+// doesn't force the browser flow again. Plain JSON (self-hosted CLI, not a
+// hardened credential store — Claude Code uses the OS keychain); tokens are
+// bearer secrets — treat accordingly. Next to the tokens we keep everything a
+// refresh needs (token endpoint, client, resource) so it never rediscovers.
+// MINI_AGENT_OAUTH_STORE relocates the file (the test suite points it at a
+// scratch path so a fake server's tokens never land in the real store).
+const OAUTH_STORE_PATH = process.env.MINI_AGENT_OAUTH_STORE || path.join(os.homedir(), ".config", "mini-agent", "mcp-oauth.json");
+const expiryFrom = (t) => (typeof t.expires_in === "number" ? Date.now() + t.expires_in * 1000 : undefined);
+function readOAuthStore() {
+    try {
+        return JSON.parse(fs.readFileSync(OAUTH_STORE_PATH, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeOAuthStore(store) {
+    fs.mkdirSync(path.dirname(OAUTH_STORE_PATH), { recursive: true });
+    fs.writeFileSync(OAUTH_STORE_PATH, JSON.stringify(store, null, 2) + "\n");
+}
+const oauthStore = readOAuthStore();
+function base64url(input) {
+    return Buffer.from(input).toString("base64url");
+}
+function pkcePair() {
+    const verifier = base64url(crypto.randomBytes(32));
+    const challenge = base64url(crypto.createHash("sha256").update(verifier).digest());
+    return { verifier, challenge };
+}
+// Try to open a URL in the user's browser. Best-effort: if it fails, the caller
+// has already printed the link so the user can click it themselves. Set
+// MINI_AGENT_NO_BROWSER=1 to only print it (an SSH session, a test).
+function openBrowser(url) {
+    if (process.env.MINI_AGENT_NO_BROWSER)
+        return;
+    const platform = process.platform;
+    const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+    const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        /* ignore — the printed URL is the fallback */
+    }
+}
+async function fetchJson(url) {
+    try {
+        const res = await fetch(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(INIT_TIMEOUT_MS) });
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+// Ask the server for its 401 challenge without a token — the cheapest way to
+// learn where the metadata lives when no 401 was recorded this session (a
+// re-authenticate while still connected). Empty when the server doesn't 401.
+async function probeChallenge(serverUrl) {
+    try {
+        const res = await fetch(serverUrl, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+            body: JSON.stringify({ jsonrpc: "2.0", id: 0, method: "initialize", params: { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: CLIENT_INFO } }),
+            signal: AbortSignal.timeout(INIT_TIMEOUT_MS),
+        });
+        if (res.status === 401)
+            return new NeedsAuthError("", res.headers.get("www-authenticate"));
+    }
+    catch {
+        /* unreachable server — discovery falls back to the well-known paths */
+    }
+    return {};
+}
+// Discover the OAuth endpoints for an MCP server: protected-resource metadata
+// (RFC 9728) → authorization-server metadata (RFC 8414). The 401 challenge says
+// exactly where the resource metadata lives; the well-known paths under the
+// server's origin are a fallback for servers that don't send one. Exported so
+// the discovery step can be exercised on its own. Returns null when the server
+// has no OAuth metadata at all.
+export async function discoverOAuth(serverUrl, challenge = {}) {
+    const base = new URL(serverUrl);
+    const rsPath = base.pathname === "/" ? "" : base.pathname.replace(/\/$/, "");
+    const candidates = [
+        challenge.resourceMetadataUrl, // what the server told us — authoritative
+        `${base.origin}/.well-known/oauth-protected-resource${rsPath}`, // RFC 9728 path-scoped (Linear)
+        `${base.origin}/.well-known/oauth-protected-resource`, // RFC 9728 origin-wide (Slack)
+    ].filter((u) => Boolean(u));
+    let prm = null;
+    for (const url of new Set(candidates)) {
+        prm = await fetchJson(url);
+        if (prm)
+            break;
+    }
+    // The resource names its authorization server(s); default to the origin. A
+    // server with a path component would need the RFC 8414 path insertion — none
+    // of the servers we target has one, so keep it simple.
+    const authServers = Array.isArray(prm?.authorization_servers) ? prm.authorization_servers : [];
+    const authServer = (authServers[0] ?? base.origin).replace(/\/$/, "");
+    // RFC 8414 first, then the OpenID Connect location some servers use instead.
+    const metadata = (await fetchJson(`${authServer}/.well-known/oauth-authorization-server`)) ?? (await fetchJson(`${authServer}/.well-known/openid-configuration`));
+    if (!metadata)
+        return null;
+    const str = (v) => (typeof v === "string" ? v : undefined);
+    const list = (v) => (Array.isArray(v) && v.length ? v : undefined);
+    const authorizationEndpoint = str(metadata.authorization_endpoint);
+    const tokenEndpoint = str(metadata.token_endpoint);
+    if (!authorizationEndpoint || !tokenEndpoint)
+        return null;
+    return {
+        authorizationEndpoint,
+        tokenEndpoint,
+        registrationEndpoint: str(metadata.registration_endpoint),
+        scopes: challenge.scope?.split(/\s+/).filter(Boolean) ?? list(prm?.scopes_supported) ?? list(metadata.scopes_supported),
+        resource: str(prm?.resource) ?? serverUrl,
+    };
+}
+// Bind the loopback listener for the authorization-code redirect. The browser
+// is sent to http://localhost:<port>/callback (the redirect URI Claude Code
+// registers too, so a pre-registered Slack client id works unchanged), and
+// "localhost" may resolve to 127.0.0.1 or ::1 depending on browser and OS — so
+// listen on both; the IPv6 bind is best-effort. `port` 0 = any free port (the
+// DCR case, where we register whatever we got); a fixed port is what a
+// pre-registered client demands. The code promise is armed on creation, BEFORE
+// the browser opens, so a fast callback can't race us.
+async function listenForCallback(port, state) {
+    let settle;
+    const handler = (req, res) => {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        res.setHeader("connection", "close"); // one-shot listener: a kept-alive socket would deliver a LATER flow's callback (same fixed port) to this dead handler
+        if (url.pathname !== "/callback" || url.searchParams.get("state") !== state)
+            return void res.writeHead(404).end(); // not ours (favicon, a stale tab…)
+        res.setHeader("content-type", "text/html");
+        res.end("<h1>Connected</h1><p>You can close this window and return to the terminal.</p>");
+        // Settle only once the page has been flushed: settling tears the servers
+        // down, and tearing down before the write lands would blank the browser tab.
+        res.once("finish", () => {
+            const code = url.searchParams.get("code");
+            if (code)
+                settle?.resolve(code);
+            else
+                settle?.reject(new Error(`OAuth callback did not include a code: ${url.searchParams.get("error_description") ?? url.searchParams.get("error") ?? "unknown error"}`));
+        });
+    };
+    const v4 = createServer(handler);
+    const bound = await new Promise((resolve, reject) => {
+        v4.once("error", (err) => reject(new Error(`Could not bind the OAuth callback on port ${port || "(any)"}: ${err.message}`)));
+        v4.listen(port, "127.0.0.1", () => {
+            const addr = v4.address();
+            resolve(addr && typeof addr === "object" ? addr.port : port);
+        });
+    });
+    const v6 = createServer(handler);
+    await new Promise((resolve) => {
+        v6.once("error", () => resolve()); // no IPv6 loopback here — the v4 listener carries it
+        v6.listen(bound, "::1", () => resolve());
+    });
+    const close = () => {
+        // Release the port for real: close() alone leaves open sockets alive, and a
+        // pre-registered client's next flow needs the SAME port back immediately.
+        for (const s of [v4, v6]) {
+            s.closeAllConnections();
+            s.close();
+        }
+    };
+    const code = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            close();
+            reject(new Error("Timed out waiting for OAuth authorization in the browser"));
+        }, OAUTH_CALLBACK_TIMEOUT_MS);
+        settle = {
+            resolve: (c) => (clearTimeout(timer), close(), resolve(c)),
+            reject: (e) => (clearTimeout(timer), close(), reject(e)),
+        };
+    });
+    return { port: bound, close, code };
+}
+// Run the OAuth authorization-code flow for an HTTP server: PKCE always;
+// dynamic client registration (RFC 7591) unless the config carries a
+// pre-registered client; a loopback redirect; then the code → token exchange
+// with the `resource` indicator (RFC 8707). When onUrl is provided, the
+// authorization URL is handed back so the UI can print it in case the browser
+// doesn't open. Resolves with everything the store needs to reconnect + refresh.
+async function runOAuthFlow(def, challenge, onUrl) {
+    if (!def.url)
+        throw new Error("OAuth is only available for http MCP servers");
+    const discovery = await discoverOAuth(def.url, challenge);
+    if (!discovery)
+        throw new Error(`No OAuth metadata found for ${def.url}`);
+    const pkce = pkcePair();
+    const state = base64url(crypto.randomBytes(16));
+    // The redirect URI must match what the client registered: for DCR we register
+    // whatever port we were given; a pre-registered client (Slack) fixes the port.
+    const listener = await listenForCallback(def.oauth?.callbackPort ?? 0, state);
+    listener.code.catch(() => { }); // settled later; never an unhandled rejection if we throw before awaiting it
+    const redirectUri = `http://localhost:${listener.port}/callback`;
+    let clientId = def.oauth?.clientId ?? ""; // a pre-registered client skips DCR
+    let clientSecret = def.oauth?.clientSecret;
+    if (!clientId && discovery.registrationEndpoint) {
+        // Dynamic client registration — most MCP servers register a public client on the spot.
+        const regRes = await fetch(discovery.registrationEndpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                redirect_uris: [redirectUri],
+                token_endpoint_auth_method: "none",
+                grant_types: ["authorization_code", "refresh_token"],
+                response_types: ["code"],
+                client_name: "mini-agent",
+            }),
+            signal: AbortSignal.timeout(INIT_TIMEOUT_MS),
+        }).catch((err) => {
+            throw new Error(`OAuth client registration failed for ${def.url}: ${err.message}`);
+        });
+        if (regRes.ok) {
+            const reg = (await regRes.json());
+            clientId = reg.client_id ?? "";
+            clientSecret = reg.client_secret;
+        }
+    }
+    if (!clientId) {
+        listener.close();
+        throw new Error(discovery.registrationEndpoint
+            ? `OAuth client registration failed for ${def.url}`
+            : `${def.url} offers no dynamic client registration — set mcpServers.<name>.oauth.clientId (and callbackPort) to a pre-registered client`);
+    }
+    const authUrl = new URL(discovery.authorizationEndpoint);
+    authUrl.searchParams.set("response_type", "code");
+    authUrl.searchParams.set("client_id", clientId);
+    authUrl.searchParams.set("code_challenge", pkce.challenge);
+    authUrl.searchParams.set("code_challenge_method", "S256");
+    authUrl.searchParams.set("redirect_uri", redirectUri);
+    authUrl.searchParams.set("state", state);
+    authUrl.searchParams.set("resource", discovery.resource); // RFC 8707: bind the token to THIS server
+    const scopes = def.oauth?.scopes ?? discovery.scopes; // an explicit config list wins over what the server advertises
+    if (scopes?.length)
+        authUrl.searchParams.set("scope", scopes.join(" "));
+    onUrl?.(authUrl.href);
+    openBrowser(authUrl.href);
+    const code = await listener.code; // the listener closes itself once settled
+    const params = new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        code_verifier: pkce.verifier,
+        redirect_uri: redirectUri,
+        client_id: clientId,
+        resource: discovery.resource,
+    });
+    if (clientSecret)
+        params.set("client_secret", clientSecret);
+    const tokenRes = await fetch(discovery.tokenEndpoint, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+        body: params.toString(),
+        signal: AbortSignal.timeout(INIT_TIMEOUT_MS),
+    });
+    if (!tokenRes.ok) {
+        throw new Error(`OAuth token exchange failed: HTTP ${tokenRes.status} ${(await tokenRes.text()).slice(0, 200)}`);
+    }
+    const tokens = (await tokenRes.json());
+    if (!tokens.access_token)
+        throw new Error(`OAuth token exchange returned no access_token: ${tokens.error_description ?? tokens.error ?? "unknown error"}`);
+    return {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresAt: expiryFrom(tokens),
+        clientId,
+        clientSecret,
+        tokenEndpoint: discovery.tokenEndpoint,
+        resource: discovery.resource,
+    };
+}
+function entryFor(name) {
+    let entry = registry.get(name);
+    if (!entry) {
+        const def = CONFIG.mcpServers[name];
+        if (!def)
+            throw new Error(`No MCP server named "${name}"`);
+        entry = { def, status: "failed", tools: 0, toolNames: [] };
+        registry.set(name, entry);
+    }
+    return entry;
+}
+function registerTools(name, specs, client) {
+    for (const spec of specs) {
+        const toolName = `mcp__${name}__${spec.name}`; // namespaced, collision-proof
+        const tool = {
+            definition: {
+                type: "function",
+                function: {
+                    name: toolName,
+                    description: `[MCP:${name}] ${spec.description ?? spec.name}`, // mark the origin in the manual
+                    parameters: spec.inputSchema ?? { type: "object", properties: {} }, // pass the server's schema straight through
+                },
+            },
+            // dispatch routes here; the permission gate ran first. A 401 mid-session
+            // (the access token expired or was revoked) gets ONE silent refresh and a
+            // retry; if that fails the server is flagged needs-auth and the model gets
+            // a readable error pointing at /mcp auth — a tool result never throws.
+            run: async (args) => {
+                try {
+                    return await client.callTool(spec.name, args);
+                }
+                catch (err) {
+                    if (!(err instanceof NeedsAuthError))
+                        throw err; // dispatch turns any other crash into text
+                    const fresh = await refreshAccessToken(name);
+                    if (fresh) {
+                        client.setToken(fresh);
+                        try {
+                            return await client.callTool(spec.name, args);
+                        }
+                        catch (again) {
+                            if (!(again instanceof NeedsAuthError))
+                                throw again;
+                        }
+                    }
+                    markNeedsAuth(name, err);
+                    return `[error] MCP server "${name}" needs authentication — run /mcp auth ${name}`;
+                }
+            },
+        };
+        registerExternalTool(tool); // now indistinguishable from a built-in to the rest of the system
+    }
+    return specs.length;
+}
+// Flag a server as needing the browser flow and remember the challenge so
+// /mcp auth knows where the OAuth metadata lives. Its tools stay registered:
+// they answer with the readable error until the user authenticates.
+function markNeedsAuth(name, challenge) {
+    const entry = entryFor(name);
+    entry.status = "needs-auth";
+    entry.error = challenge.message;
+    entry.challenge = challenge;
+}
+// Connect a single configured server and register its tools. Updates the
+// registry with the live status. Used by connectMcpServers() at startup and by
+// /mcp reconnect / enable / auth.
+async function connectOne(name, retried = false) {
+    const entry = entryFor(name);
+    // Unregister any stale tools from a previous connection.
+    for (const n of entry.toolNames)
+        unregisterExternalTool(n);
+    entry.toolNames = [];
+    entry.client?.kill();
+    entry.client = undefined;
+    // A stored token we KNOW is expired is refreshed before connecting rather
+    // than burning a 401 round trip on it.
+    let stored = oauthStore[name];
+    if (stored?.refreshToken && stored.expiresAt && stored.expiresAt <= Date.now()) {
+        await refreshAccessToken(name);
+        stored = oauthStore[name];
+    }
+    const client = new McpClient(entry.def, stored?.accessToken);
+    try {
+        const specs = await client.start(); // handshake + discover
+        entry.client = client;
+        entry.tools = registerTools(name, specs, client);
+        entry.toolNames = specs.map((s) => `mcp__${name}__${s.name}`);
+        entry.status = "connected";
+        entry.error = undefined;
+        emit("agent_mcp_connected", { server: name, tools: specs.length, transport: entry.def.url ? "http" : "stdio" });
+        console.log(chalk.dim(`(mcp: ${name} — ${specs.length} tools${entry.def.url ? " over http" : ""})`)); // visible at startup / on reconnect
+    }
+    catch (err) {
+        client.kill(); // don't leak the process/session
+        if (err instanceof NeedsAuthError) {
+            // A stale token (expired early, revoked): one refresh + retry before giving up.
+            if (!retried && stored?.refreshToken && (await refreshAccessToken(name)))
+                return connectOne(name, true);
+            markNeedsAuth(name, err);
+        }
+        else {
+            entry.status = "failed";
+            entry.error = err.message;
+        }
+        emit("agent_mcp_failed", { server: name });
+        console.error(chalk.yellow(`  [mcp] ${name} ${entry.status === "needs-auth" ? `needs authentication (run /mcp auth ${name})` : "failed to start"}: ${err.message}`));
+    }
+}
 // Connect to every configured MCP server, register their tools, and return a
 // cleanup function. Failures are isolated: a server that won't start is logged
 // and skipped — it never stops the agent or the other servers.
 export async function connectMcpServers() {
-    const entries = Object.entries(CONFIG.mcpServers); // [name, def] pairs
-    if (!entries.length)
-        return () => { }; // the common case: nothing configured
-    const clients = []; // for cleanup
-    for (const [serverName, def] of entries) {
-        const client = new McpClient(def);
-        try {
-            const specs = await client.start(); // handshake + discover
-            clients.push(client);
-            for (const spec of specs) {
-                const toolName = `mcp__${serverName}__${spec.name}`; // namespaced, collision-proof
-                const tool = {
-                    definition: {
-                        type: "function",
-                        function: {
-                            name: toolName,
-                            description: `[MCP:${serverName}] ${spec.description ?? spec.name}`, // mark the origin in the manual
-                            parameters: spec.inputSchema ?? { type: "object", properties: {} }, // pass the server's schema straight through
-                        },
-                    },
-                    run: async (args) => client.callTool(spec.name, args), // dispatch routes here; the permission gate ran first
-                };
-                registerExternalTool(tool); // now indistinguishable from a built-in to the rest of the system
-            }
-            emit("agent_mcp_connected", { server: serverName, tools: specs.length, transport: def.url ? "http" : "stdio" });
-            console.log(chalk.dim(`(mcp: ${serverName} — ${specs.length} tools${def.url ? " over http" : ""})`)); // visible at startup
-        }
-        catch (err) {
-            client.kill(); // don't leak the process/session
-            emit("agent_mcp_failed", { server: serverName });
-            console.error(chalk.yellow(`  [mcp] ${serverName} failed to start (skipped): ${err.message}`)); // loud, but not fatal
-        }
+    const entries = Object.keys(CONFIG.mcpServers); // configured server names
+    for (const name of entries) {
+        await connectOne(name); // sequential: a slow start doesn't starve the next one
+    }
+    return () => {
+        for (const entry of registry.values())
+            entry.client?.kill(); // cleanup on exit
+    };
+}
+// ---- /mcp command support ----------------------------------------------------
+export function listMcpServers() {
+    // Include every CONFIGURED server, even ones never attempted this session.
+    return Object.entries(CONFIG.mcpServers).map(([name, def]) => {
+        const entry = registry.get(name);
+        return {
+            name,
+            transport: def.url ? "http" : "stdio",
+            status: entry?.status ?? "failed",
+            tools: entry?.tools ?? 0,
+            error: entry?.error,
+            authenticated: Boolean(oauthStore[name]?.accessToken),
+            url: def.url,
+        };
+    });
+}
+// Which actions make sense for a server in a given state. Mirrors Claude Code's
+// per-server menu: authenticate when it needs auth, reconnect when it isn't,
+// enable/disable to toggle it off/on.
+export function mcpActionsFor(info) {
+    if (info.status === "disabled") {
+        return [{ label: "Enable", action: "enable" }];
+    }
+    const out = [];
+    if (info.transport === "http") {
+        out.push({ label: info.authenticated ? "Re-authenticate" : "Authenticate", action: "authenticate" });
+    }
+    out.push({ label: "Reconnect", action: "reconnect" });
+    out.push({ label: "Disable", action: "disable" });
+    return out;
+}
+// Trade the stored refresh token for a new access token, at the token endpoint
+// recorded when the user authenticated — no rediscovery. A definitive rejection
+// (400/401: the refresh token itself is dead) wipes the record so the UI tells
+// the truth: the user has to authenticate again. Network trouble keeps it.
+// Returns the new access token, or undefined when there is none to be had.
+async function refreshAccessToken(name) {
+    const stored = oauthStore[name];
+    if (!stored?.refreshToken || !stored.tokenEndpoint)
+        return undefined;
+    const params = new URLSearchParams({ grant_type: "refresh_token", refresh_token: stored.refreshToken });
+    if (stored.clientId)
+        params.set("client_id", stored.clientId);
+    if (stored.clientSecret)
+        params.set("client_secret", stored.clientSecret);
+    if (stored.resource)
+        params.set("resource", stored.resource);
+    let res;
+    try {
+        res = await fetch(stored.tokenEndpoint, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+            body: params.toString(),
+            signal: AbortSignal.timeout(INIT_TIMEOUT_MS),
+        });
+    }
+    catch {
+        return undefined; // offline / timeout — keep the record, it may work next time
+    }
+    if (res.status === 400 || res.status === 401) {
+        delete oauthStore[name]; // invalid_grant: the refresh token is gone for good
+        writeOAuthStore(oauthStore);
+        return undefined;
+    }
+    if (!res.ok)
+        return undefined; // a server hiccup — keep the record
+    const tokens = (await res.json().catch(() => ({})));
+    if (!tokens.access_token)
+        return undefined;
+    oauthStore[name] = { ...stored, accessToken: tokens.access_token, refreshToken: tokens.refresh_token ?? stored.refreshToken, expiresAt: expiryFrom(tokens) };
+    writeOAuthStore(oauthStore);
+    return tokens.access_token;
+}
+// Authenticate a server via browser OAuth and store the tokens. Returns a
+// human-readable result for the UI.
+export async function authenticateMcpServer(name, onUrl) {
+    const def = CONFIG.mcpServers[name];
+    if (!def)
+        return `No MCP server named "${name}"`;
+    if (!def.url)
+        return `${name} is a stdio server — it needs no OAuth authentication`;
+    // Where the OAuth metadata lives: the last 401 told us; if none was seen this
+    // session (re-authenticating while connected), ask the server now.
+    const entry = entryFor(name);
+    const challenge = entry.challenge ?? (await probeChallenge(def.url));
+    oauthStore[name] = await runOAuthFlow(def, challenge, onUrl);
+    writeOAuthStore(oauthStore);
+    // Immediately reconnect with the fresh token so the server shows connected.
+    await connectOne(name);
+    const status = entry.status;
+    return status === "connected"
+        ? `Authentication successful. Connected to ${name}.`
+        : `Authentication done, but ${name} is ${status} — use /mcp reconnect ${name} to retry.`;
+}
+// Disconnect and reconnect a single server (re-registering its tools). A stale
+// stored token is refreshed inside connectOne, so this is just: connect again.
+export async function reconnectMcpServer(name) {
+    const def = CONFIG.mcpServers[name];
+    if (!def)
+        return `No MCP server named "${name}"`;
+    await connectOne(name);
+    const info = listMcpServers().find((s) => s.name === name);
+    return info.status === "connected"
+        ? `Connected to ${name} (${info.tools} tool${info.tools === 1 ? "" : "s"}).`
+        : `${name} is ${info.status}: ${info.error ?? "unknown error"}`;
+}
+// Toggle a server off/on (session-only — the config file is not rewritten).
+export async function disableMcpServer(name) {
+    const entry = entryFor(name);
+    for (const n of entry.toolNames)
+        unregisterExternalTool(n);
+    entry.toolNames = [];
+    entry.client?.kill();
+    entry.client = undefined;
+    entry.status = "disabled";
+    entry.error = undefined;
+    return `Disabled ${name}.`;
+}
+export async function enableMcpServer(name) {
+    const entry = entryFor(name);
+    if (entry.status !== "disabled")
+        return `${name} is not disabled.`;
+    await connectOne(name);
+    const info = listMcpServers().find((s) => s.name === name);
+    return info.status === "connected" ? `Enabled ${name}.` : `${name} is ${info.status}: ${info.error ?? "unknown error"}`;
+}
+// Run one action from mcpActionsFor and return the note to display.
+export async function runMcpAction(name, action, onUrl) {
+    switch (action) {
+        case "authenticate":
+            return authenticateMcpServer(name, onUrl);
+        case "reconnect":
+            return reconnectMcpServer(name);
+        case "disable":
+            return disableMcpServer(name);
+        case "enable":
+            return enableMcpServer(name);
     }
-    return () => clients.forEach((c) => c.kill()); // the caller calls this on exit
 }