one-code-extension 0.1.4 → 0.3.0

package/extensions/mcp/oauth/browser.ts

@@ -0,0 +1,26 @@
+/**
+ * Open a URL in the user's default browser (no dependency — platform command).
+ *
+ * Detached and unref'd so the auth flow never blocks on the browser process,
+ * and errors are swallowed to a boolean: a headless box has no browser, in which
+ * case the caller falls back to printing the URL for manual paste.
+ */
+
+import { spawn } from "node:child_process";
+
+export function openBrowser(url: string): boolean {
+	const [command, args] =
+		process.platform === "darwin"
+			? (["open", [url]] as const)
+			: process.platform === "win32"
+				? (["cmd", ["/c", "start", "", url]] as const)
+				: (["xdg-open", [url]] as const);
+	try {
+		const child = spawn(command, [...args], { stdio: "ignore", detached: true });
+		child.on("error", () => {});
+		child.unref();
+		return true;
+	} catch {
+		return false;
+	}
+}

package/extensions/mcp/oauth/callback.ts

@@ -0,0 +1,104 @@
+/**
+ * Loopback HTTP server that catches the OAuth authorization-code redirect.
+ *
+ * The MCP OAuth flow redirects the browser to `http://127.0.0.1:<port>/callback?code=…`
+ * after the user authorizes. This binds an ephemeral loopback port, hands its URL
+ * back as the redirect_uri, and resolves `waitForCode()` with the code (or rejects
+ * on an `error=` param / timeout). RFC 8252 §7.3 lets loopback redirects use any
+ * port, so a fresh port per flow is fine even against a previously-registered client.
+ */
+
+import { createServer, type Server } from "node:http";
+
+export interface CallbackServer {
+	/** The exact redirect_uri to register and hand to the authorization request. */
+	redirectUrl: string;
+	/** Resolves with the authorization code (and the echoed `state`, if any) once the browser is redirected back. */
+	waitForCode: (timeoutMs?: number) => Promise<{ code: string; state?: string }>;
+	close: () => void;
+}
+
+const DEFAULT_TIMEOUT_MS = 5 * 60_000;
+
+/** HTML the browser lands on after redirect — self-closes where the browser allows it. */
+function landingPage(message: string): string {
+	return `<!doctype html><meta charset="utf-8"><title>One Code</title><body style="font-family:system-ui;padding:3rem;text-align:center"><h2>${message}</h2><p>You can close this tab and return to the terminal.</p><script>setTimeout(()=>window.close(),1500)</script></body>`;
+}
+
+export async function startCallbackServer(): Promise<CallbackServer> {
+	// The result may arrive before waitForCode() installs its handlers (an IdP
+	// with a live session can redirect instantly), so buffer it: settle() records
+	// the outcome, and waitForCode() replays a buffered one immediately.
+	type Redirect = { code: string; state?: string };
+	let resolveCode: ((redirect: Redirect) => void) | undefined;
+	let rejectCode: ((error: Error) => void) | undefined;
+	let outcome: Redirect | { error: Error } | undefined;
+	const settle = (result: Redirect | { error: Error }) => {
+		if (outcome) return;
+		outcome = result;
+		if ("code" in result) resolveCode?.(result);
+		else rejectCode?.(result.error);
+	};
+
+	const server: Server = createServer((req, res) => {
+		const url = new URL(req.url ?? "/", "http://127.0.0.1");
+		if (url.pathname !== "/callback") {
+			res.writeHead(404).end();
+			return;
+		}
+		const error = url.searchParams.get("error");
+		const code = url.searchParams.get("code");
+		if (error) {
+			res.writeHead(400, { "content-type": "text/html" }).end(landingPage("Authorization failed"));
+			settle({ error: new Error(`authorization denied: ${url.searchParams.get("error_description") ?? error}`) });
+			return;
+		}
+		if (!code) {
+			res.writeHead(400, { "content-type": "text/html" }).end(landingPage("Missing authorization code"));
+			return;
+		}
+		res.writeHead(200, { "content-type": "text/html" }).end(landingPage("Authorization complete"));
+		settle({ code, state: url.searchParams.get("state") ?? undefined });
+	});
+
+	// Bind to loopback on an ephemeral port; the OS picks a free one.
+	await new Promise<void>((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(0, "127.0.0.1", resolve);
+	});
+	const address = server.address();
+	if (!address || typeof address === "string") {
+		server.close();
+		throw new Error("could not determine loopback callback port");
+	}
+	const redirectUrl = `http://127.0.0.1:${address.port}/callback`;
+
+	const waitForCode = (timeoutMs = DEFAULT_TIMEOUT_MS): Promise<Redirect> =>
+		new Promise<Redirect>((resolve, reject) => {
+			// Replay a result that already arrived before this call.
+			if (outcome) {
+				if ("code" in outcome) resolve(outcome);
+				else reject(outcome.error);
+				return;
+			}
+			resolveCode = resolve;
+			rejectCode = reject;
+			const timer = setTimeout(
+				() => settle({ error: new Error(`timed out after ${Math.round(timeoutMs / 1000)}s waiting for authorization`) }),
+				timeoutMs,
+			);
+			timer.unref?.();
+		});
+
+	return {
+		redirectUrl,
+		waitForCode,
+		close: () => {
+			try {
+				server.close();
+			} catch {
+				// already closing
+			}
+		},
+	};
+}

package/extensions/mcp/oauth/flow.ts

@@ -0,0 +1,68 @@
+/**
+ * Interactive OAuth orchestration for an http MCP server.
+ *
+ * Ties together the loopback callback catcher (callback.ts), the browser opener
+ * (browser.ts), the SDK-backed provider (provider.ts), and the transport-level
+ * auth entry points (client.ts): start a callback server, let the SDK register +
+ * redirect the user to authorize, catch the returned code, finish the exchange,
+ * then reconnect with the freshly stored tokens. The result is a live
+ * Connection the caller registers exactly like any other.
+ */
+
+import type { HttpServer } from "../config.ts";
+import { beginInteractiveAuth, type Connection, connect } from "../client.ts";
+import { openBrowser } from "./browser.ts";
+import { startCallbackServer } from "./callback.ts";
+import { McpOAuthProvider } from "./provider.ts";
+
+export interface AuthenticateOptions {
+	server: HttpServer;
+	home?: string;
+	env?: NodeJS.ProcessEnv;
+	/** Progress/URL messages for the caller to surface (browser opened, or manual URL). */
+	onPrompt?: (message: string) => void;
+	timeoutMs?: number;
+}
+
+/** A provider for a silent (non-interactive) connect using already-stored tokens. */
+export function silentProvider(serverName: string, home?: string, env?: NodeJS.ProcessEnv): McpOAuthProvider {
+	return new McpOAuthProvider({ serverName, home, env });
+}
+
+export async function authenticate(options: AuthenticateOptions): Promise<Connection> {
+	const { server, home, env, onPrompt, timeoutMs } = options;
+	const callback = await startCallbackServer();
+	try {
+		const provider = new McpOAuthProvider({
+			serverName: server.name,
+			redirectUrl: callback.redirectUrl,
+			openAuthorization: (url) => {
+				const opened = openBrowser(url.toString());
+				onPrompt?.(
+					opened
+						? `Opened your browser to authorize "${server.name}". If it didn't open, visit:\n${url}`
+						: `Open this URL to authorize "${server.name}":\n${url}`,
+				);
+			},
+			home,
+			env,
+		});
+
+		const started = await beginInteractiveAuth(server, provider);
+		if ("connection" in started) return started.connection; // valid tokens already present
+
+		const { code, state } = await callback.waitForCode(timeoutMs);
+		// Login-CSRF guard (RFC 8252 §8.9): the redirect must echo the state this
+		// provider issued, or an attacker-planted code could bind their account.
+		const expected = provider.expectedState();
+		if (expected !== undefined && state !== expected) {
+			throw new Error(`authorization response state mismatch for "${server.name}" — the redirect did not come from this authorization request`);
+		}
+		await started.transport.finishAuth(code);
+
+		// Reconnect fresh: the provider now has stored tokens, so this is silent.
+		return await connect(server, silentProvider(server.name, home, env));
+	} finally {
+		callback.close();
+	}
+}

package/extensions/mcp/oauth/provider.ts

@@ -0,0 +1,147 @@
+/**
+ * An OAuthClientProvider for the MCP SDK, backed by the on-disk token store.
+ *
+ * The SDK's StreamableHTTPClientTransport drives the whole OAuth 2.1 flow
+ * (discovery, dynamic client registration, PKCE, token exchange and refresh) and
+ * calls into this provider for the three things only the host knows: where to
+ * persist credentials (the store), where the redirect lands (the loopback URL),
+ * and how to send the user to the authorization page (open a browser).
+ *
+ * One instance is scoped to one server for one flow; `redirectUrl` is fixed from
+ * the loopback callback server. A non-interactive instance (startup reconnect
+ * using stored tokens) is constructed without an opener and refuses to redirect.
+ */
+
+import type {
+	OAuthClientInformationFull,
+	OAuthClientInformationMixed,
+	OAuthClientMetadata,
+	OAuthTokens,
+} from "@modelcontextprotocol/sdk/shared/auth.js";
+import { randomBytes } from "node:crypto";
+import type { OAuthClientProvider, OAuthDiscoveryState } from "@modelcontextprotocol/sdk/client/auth.js";
+import { readAuth, type StoredAuth, writeAuth } from "./store.ts";
+
+export interface McpOAuthProviderOptions {
+	serverName: string;
+	/** Loopback redirect_uri; required for an interactive flow, omitted for silent reconnect. */
+	redirectUrl?: string;
+	/** Sends the user to the authorization URL (opens a browser). Interactive flows only. */
+	openAuthorization?: (url: URL) => void;
+	home?: string;
+	env?: NodeJS.ProcessEnv;
+}
+
+export class McpOAuthProvider implements OAuthClientProvider {
+	private readonly serverName: string;
+	private readonly _redirectUrl?: string;
+	private readonly openAuthorization?: (url: URL) => void;
+	private readonly home?: string;
+	private readonly env?: NodeJS.ProcessEnv;
+
+	// The SDK calls tokens() on every request it sends, so the parsed store is
+	// cached in-instance and re-read only after this provider's own writes,
+	// instead of a readFileSync + JSON.parse per getter.
+	private cache?: StoredAuth;
+	/** The `state` issued for this flow's authorization request; the callback must echo it (RFC 8252 §8.9). */
+	private issuedState?: string;
+
+	constructor(options: McpOAuthProviderOptions) {
+		this.serverName = options.serverName;
+		this._redirectUrl = options.redirectUrl;
+		this.openAuthorization = options.openAuthorization;
+		this.home = options.home;
+		this.env = options.env;
+	}
+
+	private load(): StoredAuth {
+		return (this.cache ??= readAuth(this.serverName, this.home, this.env));
+	}
+
+	/** Merge a patch into the cached store and persist it. */
+	private save(patch: Partial<StoredAuth>): void {
+		this.cache = { ...this.load(), ...patch };
+		writeAuth(this.serverName, this.cache, this.home, this.env);
+	}
+
+	get redirectUrl(): string | URL | undefined {
+		return this._redirectUrl;
+	}
+
+	get clientMetadata(): OAuthClientMetadata {
+		// A persisted metadata block keeps a re-registered client stable across
+		// sessions; otherwise register as a public client using the loopback
+		// redirect with the PKCE authorization-code grant.
+		const stored = this.load().clientMetadata;
+		if (stored) return stored;
+		return {
+			client_name: "One Code",
+			redirect_uris: this._redirectUrl ? [this._redirectUrl] : [],
+			grant_types: ["authorization_code", "refresh_token"],
+			response_types: ["code"],
+			token_endpoint_auth_method: "none",
+		};
+	}
+
+	clientInformation(): OAuthClientInformationMixed | undefined {
+		return this.load().clientInformation;
+	}
+
+	saveClientInformation(clientInformation: OAuthClientInformationMixed): void {
+		this.save({ clientInformation: clientInformation as OAuthClientInformationFull, clientMetadata: this.clientMetadata });
+	}
+
+	tokens(): OAuthTokens | undefined {
+		return this.load().tokens;
+	}
+
+	saveTokens(tokens: OAuthTokens): void {
+		this.save({ tokens });
+	}
+
+	/** Fresh per flow; the SDK puts it on the authorization URL. */
+	state(): string {
+		const issued = this.issuedState ?? randomBytes(16).toString("hex");
+		this.issuedState = issued;
+		return issued;
+	}
+
+	/** The state the loopback callback must carry back, or undefined before an authorization was started. */
+	expectedState(): string | undefined {
+		return this.issuedState;
+	}
+
+	redirectToAuthorization(authorizationUrl: URL): void {
+		if (!this.openAuthorization) {
+			throw new Error(`MCP server "${this.serverName}" needs authentication; run /mcp and choose Authenticate.`);
+		}
+		this.openAuthorization(authorizationUrl);
+	}
+
+	saveCodeVerifier(codeVerifier: string): void {
+		this.save({ codeVerifier });
+	}
+
+	codeVerifier(): string {
+		const verifier = this.load().codeVerifier;
+		if (!verifier) throw new Error("no PKCE code verifier saved for this authorization");
+		return verifier;
+	}
+
+	saveDiscoveryState(state: OAuthDiscoveryState): void {
+		this.save({ discoveryState: state });
+	}
+
+	discoveryState(): OAuthDiscoveryState | undefined {
+		return this.load().discoveryState;
+	}
+
+	invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier" | "discovery"): void {
+		this.save({
+			clientInformation: scope === "all" || scope === "client" ? undefined : this.load().clientInformation,
+			tokens: scope === "all" || scope === "tokens" ? undefined : this.load().tokens,
+			codeVerifier: scope === "all" || scope === "verifier" ? undefined : this.load().codeVerifier,
+			discoveryState: scope === "all" || scope === "discovery" ? undefined : this.load().discoveryState,
+		});
+	}
+}

package/extensions/mcp/oauth/store.ts

@@ -0,0 +1,86 @@
+/**
+ * On-disk OAuth credential store for MCP servers.
+ *
+ * One JSON file per server under `~/.onecode/mcp-auth/<slug>.json`, holding the
+ * dynamically-registered client info, the tokens (access + refresh), the PKCE
+ * verifier mid-flow, and the cached discovery state. The MCP SDK's OAuth
+ * provider (oauth/provider.ts) reads and writes through this; refresh happens
+ * automatically once a refresh token is stored, so a one-time Authenticate keeps
+ * the server connected across sessions.
+ *
+ * Kept in ~/.onecode (never ~/.claude) like all One Code state, and separate
+ * from settings.json because tokens are secrets, not configuration.
+ */
+
+import { mkdirSync, chmodSync } from "node:fs";
+import os from "node:os";
+import { join } from "node:path";
+import type { OAuthClientInformationFull, OAuthClientMetadata, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+import type { OAuthDiscoveryState } from "@modelcontextprotocol/sdk/client/auth.js";
+import { readJsonFile, writeJsonAtomic } from "../../lib/atomic-write.ts";
+import { oneCodeStateDir } from "../../lib/paths.ts";
+
+export interface StoredAuth {
+	clientInformation?: OAuthClientInformationFull;
+	clientMetadata?: OAuthClientMetadata;
+	tokens?: OAuthTokens;
+	codeVerifier?: string;
+	discoveryState?: OAuthDiscoveryState;
+}
+
+/**
+ * Filesystem-safe, collision-free file name for a server: a readable sanitized
+ * stem plus a short hash of the raw name, so two names that sanitize alike
+ * (e.g. "a/b" and "a_b") still get distinct files.
+ */
+function slug(serverName: string): string {
+	let hash = 5381;
+	for (let i = 0; i < serverName.length; i++) hash = ((hash << 5) + hash + serverName.charCodeAt(i)) >>> 0;
+	const safe = serverName.replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 48);
+	return `${safe || "server"}-${hash.toString(16).padStart(8, "0")}.json`;
+}
+
+export function authStoreDir(home: string = os.homedir(), env: NodeJS.ProcessEnv = process.env): string {
+	return join(oneCodeStateDir(env, home), "mcp-auth");
+}
+
+function authFilePath(serverName: string, home: string, env: NodeJS.ProcessEnv): string {
+	return join(authStoreDir(home, env), slug(serverName));
+}
+
+export function readAuth(serverName: string, home: string = os.homedir(), env: NodeJS.ProcessEnv = process.env): StoredAuth {
+	return readJsonFile<StoredAuth>(authFilePath(serverName, home, env)) ?? {};
+}
+
+export function writeAuth(
+	serverName: string,
+	auth: StoredAuth,
+	home: string = os.homedir(),
+	env: NodeJS.ProcessEnv = process.env,
+): void {
+	// Bearer tokens: owner-only file and directory (review M10). mkdir's mode
+	// applies only on creation, so an existing dir is tightened explicitly.
+	const dir = authStoreDir(home, env);
+	mkdirSync(dir, { recursive: true, mode: 0o700 });
+	try {
+		chmodSync(dir, 0o700);
+	} catch {
+		// Not fatal (a filesystem without modes); the file mode below still applies where it can.
+	}
+	writeJsonAtomic(authFilePath(serverName, home, env), auth, { mode: 0o600 });
+}
+
+/** Merge a partial update into the stored record. */
+export function updateAuth(
+	serverName: string,
+	patch: Partial<StoredAuth>,
+	home: string = os.homedir(),
+	env: NodeJS.ProcessEnv = process.env,
+): void {
+	writeAuth(serverName, { ...readAuth(serverName, home, env), ...patch }, home, env);
+}
+
+/** True when a usable (non-empty) access token is stored. */
+export function hasStoredTokens(serverName: string, home: string = os.homedir(), env: NodeJS.ProcessEnv = process.env): boolean {
+	return Boolean(readAuth(serverName, home, env).tokens?.access_token);
+}

package/extensions/mcp/panel/keys.ts

@@ -0,0 +1,34 @@
+/**
+ * Raw-byte key decoding for the /mcp panel (pure).
+ *
+ * The panel is a two-level menu (server list → server detail with a numbered
+ * action list), navigated with the arrows and Enter, Esc to go back/close. A
+ * digit selects an action directly in the detail view. No text field, so any
+ * other printable input is ignored.
+ */
+
+export type McpKey =
+	| { kind: "up" | "down" | "enter" | "back" | "close" }
+	| { kind: "digit"; value: number };
+
+export function decodeMcpKey(data: string): McpKey | undefined {
+	switch (data) {
+		case "\x1b[A":
+		case "\x1bOA":
+			return { kind: "up" };
+		case "\x1b[B":
+		case "\x1bOB":
+			return { kind: "down" };
+		case "\r":
+		case "\n":
+			return { kind: "enter" };
+		case "\x1b":
+			return { kind: "back" };
+		case "\x03": // ctrl+c
+			return { kind: "close" };
+		default:
+			break;
+	}
+	if (data.length === 1 && data >= "1" && data <= "9") return { kind: "digit", value: Number(data) };
+	return undefined;
+}

package/extensions/mcp/panel/model.ts

@@ -0,0 +1,62 @@
+/**
+ * /mcp panel data model (pure — no pi, no fs).
+ *
+ * The mcp extension builds an `McpEntry[]` from its live connection state each
+ * repaint; this module owns the shared vocabulary the state machine and the
+ * renderer agree on: the status/auth glyphs and the per-entry action list. The
+ * list view groups entries under a heading (computed by the wiring, e.g. "User
+ * MCPs (~/.claude.json)"); the detail view shows one entry's fields and actions.
+ */
+
+export type McpEntryStatus = "connected" | "failed" | "authNeeded" | "connecting" | "disabled";
+
+export interface McpEntry {
+	name: string;
+	/** Heading this entry sits under in the grouped list. */
+	group: string;
+	status: McpEntryStatus;
+	toolCount?: number;
+	/** Failure reason, shown as the detail view's "Issue" line. */
+	issue?: string;
+	/** http server url, shown as the detail view's "URL" line. */
+	url?: string;
+	/** Where the server was configured, shown as "Config location". */
+	configLocation: string;
+	/** Present when auth state is known; drives the "Auth" line. */
+	authState?: "authenticated" | "notAuthenticated";
+	/** True only for an OAuth-capable http server (Authenticate can actually help). */
+	canAuthenticate: boolean;
+}
+
+export type McpAction = "reconnect" | "authenticate" | "disable" | "enable";
+
+export interface McpActionItem {
+	key: McpAction;
+	label: string;
+}
+
+/** The numbered action list for an entry, matching Claude Code's detail view. */
+export function actionsFor(entry: McpEntry): McpActionItem[] {
+	if (entry.status === "disabled") return [{ key: "enable", label: "Enable" }];
+	const primary: McpActionItem =
+		entry.status === "authNeeded" && entry.canAuthenticate
+			? { key: "authenticate", label: "Authenticate" }
+			: { key: "reconnect", label: "Reconnect" };
+	return [primary, { key: "disable", label: "Disable" }];
+}
+
+/** Glyph + label for a status; the wiring paints the glyph in the status colour. */
+export function statusText(entry: McpEntry): { glyph: string; label: string; color: string } {
+	switch (entry.status) {
+		case "connected":
+			return { glyph: "✔", label: "connected", color: "success" };
+		case "authNeeded":
+			return { glyph: "⚠", label: "needs authentication", color: "warning" };
+		case "connecting":
+			return { glyph: "…", label: "connecting", color: "dim" };
+		case "disabled":
+			return { glyph: "○", label: "disabled", color: "dim" };
+		case "failed":
+			return { glyph: "✘", label: "failed", color: "error" };
+	}
+}

package/extensions/mcp/panel/render.ts

@@ -0,0 +1,141 @@
+/**
+ * /mcp panel rendering (pure).
+ *
+ * Returns plain lines already cut to width; the wiring wraps them in a memoized
+ * component and applies a final ANSI-aware truncate. Mirrors Claude Code's MCP
+ * manager: a grouped server list ("Manage MCP servers") and a per-server detail
+ * view (Status / Issue / Auth / URL / Config location + a numbered action list).
+ * Only width-1 glyphs are used so cutPlainText's code-point count stays exact.
+ */
+
+import { cutPlainText, padPlainText, panelTopRule, type RenderBlock as Block, windowBlocks } from "../../lib/tui-render.ts";
+import { actionsFor, type McpEntry, statusText } from "./model.ts";
+import { clampMcpCursor, detailEntry, type McpPanelState } from "./state.ts";
+
+export interface McpPaint {
+	fg: (color: string, text: string) => string;
+	bold: (text: string) => string;
+}
+
+export interface McpRenderInput {
+	state: McpPanelState;
+	entries: McpEntry[];
+	width: number;
+	height: number;
+	/** Transient messages (auth in progress / URL / errors). */
+	notices: string[];
+	settled: boolean;
+}
+
+function statusFragment(entry: McpEntry, paint: McpPaint): string {
+	const { glyph, label, color } = statusText(entry);
+	const tools = entry.status === "connected" && entry.toolCount !== undefined ? ` · ${entry.toolCount} tools` : "";
+	return `${paint.fg(color, glyph)} ${label}${tools}`;
+}
+
+function listBlocks(input: McpRenderInput, paint: McpPaint): Block[] {
+	const { state, entries, width } = input;
+	const blocks: Block[] = [];
+	let lastGroup: string | undefined;
+	entries.forEach((entry, i) => {
+		if (entry.group !== lastGroup) {
+			lastGroup = entry.group;
+			blocks.push({ lines: ["", paint.bold(cutPlainText(`  ${entry.group}`, width - 1))], selectable: false });
+		}
+		const isCursor = i === state.cursor;
+		const marker = isCursor ? "❯ " : "  ";
+		if (isCursor) {
+			// Cursor row is one flat accent highlight, so build it from plain text.
+			const { glyph, label } = statusText(entry);
+			const tools = entry.status === "connected" && entry.toolCount !== undefined ? ` · ${entry.toolCount} tools` : "";
+			const plain = `${marker}${entry.name} · ${glyph} ${label}${tools}`;
+			blocks.push({ lines: [paint.fg("accent", cutPlainText(plain, width - 1))], selectable: true });
+		} else {
+			blocks.push({ lines: [`${marker}${entry.name} · ${statusFragment(entry, paint)}`], selectable: true });
+		}
+	});
+	return blocks;
+}
+
+/** Aligns the detail view's value column past the longest label ("Config location:"). */
+const LABEL_WIDTH = 18;
+
+function detailLines(input: McpRenderInput, paint: McpPaint): { lines: string[]; footer: string } {
+	const { state, entries, width } = input;
+	const entry = detailEntry(state, entries);
+	if (!entry) return { lines: [paint.fg("dim", "  (server no longer available)")], footer: "Esc to go back" };
+
+	const lines: string[] = [];
+	// The value may already carry paint escapes, so it isn't cut here (cutPlainText
+	// counts code points, escapes included) — the caller's ANSI-aware truncateLine
+	// trims to the real width. Long plain values are pre-cut before painting below.
+	const field = (label: string, value: string) => {
+		lines.push(` ${paint.bold(padPlainText(`${label}:`, LABEL_WIDTH))}${value}`);
+	};
+
+	lines.push(` ${paint.bold(cutPlainText(`${entry.name} MCP Server`, width - 1))}`);
+	lines.push("");
+	const status = statusText(entry);
+	field("Status", `${paint.fg(status.color, status.glyph)} ${status.label}`);
+	if (entry.issue) field("Issue", paint.fg("dim", cutPlainText(entry.issue, width - LABEL_WIDTH - 2)));
+	if (entry.authState) {
+		field(
+			"Auth",
+			entry.authState === "authenticated"
+				? paint.fg("success", "✔ authenticated")
+				: paint.fg("error", "✘ not authenticated"),
+		);
+	}
+	if (entry.url) field("URL", paint.fg("dim", entry.url));
+	field("Config location", paint.fg("dim", entry.configLocation));
+	lines.push("");
+
+	const actions = actionsFor(entry);
+	const actionCursor = state.detail?.actionCursor ?? 0;
+	actions.forEach((action, i) => {
+		const isCursor = i === actionCursor;
+		const line = `${isCursor ? "❯ " : "  "}${i + 1}. ${action.label}`;
+		lines.push(isCursor ? paint.fg("accent", line) : line);
+	});
+
+	return { lines, footer: "↑/↓ to navigate · Enter to select · Esc to back" };
+}
+
+export function renderMcpPanel(input: McpRenderInput, paint: McpPaint): string[] {
+	const { state, entries, width, height } = input;
+	clampMcpCursor(state, entries);
+
+	const out: string[] = [panelTopRule(paint.fg, width)];
+	let footer: string;
+
+	if (state.detail) {
+		out.push("");
+		const detail = detailLines(input, paint);
+		out.push(...detail.lines);
+		footer = detail.footer;
+	} else {
+		out.push(` ${paint.bold("Manage MCP servers")}`);
+		const count = `${entries.length} server${entries.length === 1 ? "" : "s"}${input.settled ? "" : " · connecting…"}`;
+		out.push(paint.fg("dim", cutPlainText(` ${count}`, width - 1)));
+
+		const footerReserve = 3 + input.notices.length + 1;
+		const budget = Math.max(1, height - out.length - footerReserve);
+		if (entries.length === 0) {
+			out.push("", paint.fg("dim", "  No MCP servers configured. Add them to .mcp.json or ~/.claude.json."));
+		} else {
+			const windowed = windowBlocks(listBlocks(input, paint), state.cursor, budget);
+			out.push(...windowed.lines);
+			if (windowed.more > 0) out.push(paint.fg("dim", `  ↓ ${windowed.more} more`));
+		}
+		out.push("");
+		out.push(paint.fg("dim", cutPlainText("  Servers are configured in .mcp.json or ~/.claude.json.", width - 1)));
+		footer = "↑/↓ to navigate · Enter to confirm · Esc to cancel";
+	}
+
+	for (const notice of input.notices) {
+		for (const line of notice.split("\n")) out.push(paint.fg("warning", cutPlainText(`  ${line}`, width - 1)));
+	}
+	out.push("");
+	out.push(paint.fg("dim", cutPlainText(` ${footer}`, width - 1)));
+	return out;
+}