one-code-extension 0.4.1 → 0.5.0

package/extensions/mcp/client.ts

@@ -5,9 +5,13 @@
 
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import { childProcessEnv } from "../lib/app-launch.mjs";
 import type { McpServer } from "./config.ts";
+import { collectPages } from "./discovery.ts";
+import { McpAuthenticationRequiredError } from "./oauth/provider.ts";
 
 /**
  * The MCP SDK costs ~70-80ms to load (findings §15), so it is imported on the
@@ -19,6 +23,7 @@ let sdkPromise:
 			Client: typeof import("@modelcontextprotocol/sdk/client/index.js").Client;
 			StdioClientTransport: typeof import("@modelcontextprotocol/sdk/client/stdio.js").StdioClientTransport;
 			StreamableHTTPClientTransport: typeof import("@modelcontextprotocol/sdk/client/streamableHttp.js").StreamableHTTPClientTransport;
+			SSEClientTransport: typeof import("@modelcontextprotocol/sdk/client/sse.js").SSEClientTransport;
 			UnauthorizedError: typeof import("@modelcontextprotocol/sdk/client/auth.js").UnauthorizedError;
 	  }>
 	| undefined;
@@ -27,6 +32,10 @@ let sdkPromise:
 // (the SDK's UnauthorizedError does not set `.name`, so a name/message check is
 // unreliable — a custom-message instance would be missed).
 let unauthorizedClass: typeof import("@modelcontextprotocol/sdk/client/auth.js").UnauthorizedError | undefined;
+let httpErrorClass: typeof import("@modelcontextprotocol/sdk/client/streamableHttp.js").StreamableHTTPError | undefined;
+let sseErrorClass: typeof import("@modelcontextprotocol/sdk/client/sse.js").SseError | undefined;
+
+type HttpTransport = StreamableHTTPClientTransport | SSEClientTransport;
 
 function loadSdk() {
 	sdkPromise ??= Promise.all([
@@ -34,12 +43,16 @@ function loadSdk() {
 		import("@modelcontextprotocol/sdk/client/stdio.js"),
 		import("@modelcontextprotocol/sdk/client/streamableHttp.js"),
 		import("@modelcontextprotocol/sdk/client/auth.js"),
-	]).then(([client, stdio, http, auth]) => {
+		import("@modelcontextprotocol/sdk/client/sse.js"),
+	]).then(([client, stdio, http, auth, sse]) => {
 		unauthorizedClass = auth.UnauthorizedError;
+		httpErrorClass = http.StreamableHTTPError;
+		sseErrorClass = sse.SseError;
 		return {
 			Client: client.Client,
 			StdioClientTransport: stdio.StdioClientTransport,
 			StreamableHTTPClientTransport: http.StreamableHTTPClientTransport,
+			SSEClientTransport: sse.SSEClientTransport,
 			UnauthorizedError: auth.UnauthorizedError,
 		};
 	});
@@ -62,11 +75,21 @@ export interface McpResource {
 	mimeType?: string;
 }
 
+export interface McpResourceTemplate {
+	uriTemplate: string;
+	name?: string;
+	description?: string;
+	mimeType?: string;
+}
+
 export interface Connection {
 	server: McpServer;
 	client: Client;
 	tools: McpTool[];
 	resources: McpResource[];
+	resourceTemplates?: McpResourceTemplate[];
+	/** Called after a tool-list refresh, or with its error while the last good list stays intact. */
+	onToolsChanged?: (error?: Error) => void;
 	/** The server's own usage instructions from its initialize result, if any. */
 	instructions?: string;
 	/** Non-fatal problems after a successful connect (e.g. listTools failed). */
@@ -126,8 +149,11 @@ function withTimeout<T>(promise: Promise<T>, ms: number, what: string): Promise<
 	});
 }
 
-/** True when the error is the SDK's "authorization required" signal (an HTTP 401). */
+/** True when the server requires authentication, including an expired stored grant. */
 export function isUnauthorized(error: unknown): boolean {
+	if (error instanceof McpAuthenticationRequiredError) return true;
+	if (httpErrorClass && error instanceof httpErrorClass && error.code === 401) return true;
+	if (sseErrorClass && error instanceof sseErrorClass && error.code === 401) return true;
 	// The class is captured on the first loadSdk(); every caller runs after a
 	// connect (which awaits it), so it is set. The message fallback only covers
 	// the impossible pre-load case.
@@ -140,61 +166,140 @@ function buildTransport(
 	server: McpServer,
 	sdk: Awaited<ReturnType<typeof loadSdk>>,
 	authProvider?: OAuthClientProvider,
+	keepOAuthOpen?: () => boolean,
 ): { transport: Transport; stderrTail: () => string } {
 	const tail = createTailBuffer();
 	if (server.kind === "stdio") {
 		const transport = new sdk.StdioClientTransport({
 			command: server.command,
 			args: server.args,
-			env: { ...(process.env as Record<string, string>), ...(server.env ?? {}) },
+			// The user's own environment under the bundled app (lib/app-launch.mjs), then the server's.
+			env: { ...(childProcessEnv(process.env) as Record<string, string>), ...(server.env ?? {}) },
+			...(server.cwd ? { cwd: server.cwd } : {}),
 			stderr: "pipe",
 		});
 		// The PassThrough exists before start(); drain it from the first byte.
 		transport.stderr?.on("data", (chunk: string | Uint8Array) => tail.push(chunk));
 		return { transport, stderrTail: tail.text };
 	}
-	const transport = new sdk.StreamableHTTPClientTransport(new URL(server.url), {
+	const lifetime = new AbortController();
+	const RemoteTransport = server.transport === "sse" ? sdk.SSEClientTransport : sdk.StreamableHTTPClientTransport;
+	const transport = new RemoteTransport(new URL(server.url), {
 		authProvider,
 		requestInit: server.headers ? { headers: server.headers } : undefined,
+		// The SDK's close signal covers MCP requests, but not the discovery and
+		// token fetches it starts during OAuth. Those must stop with the client too.
+		fetch: (input, init) => fetch(input, {
+			...init,
+			signal: init?.signal ? AbortSignal.any([lifetime.signal, init.signal]) : lifetime.signal,
+		}),
 	});
+	const closeTransport = transport.close.bind(transport);
+	transport.close = async () => {
+		if (!keepOAuthOpen?.()) lifetime.abort();
+		await closeTransport();
+	};
 	return { transport, stderrTail: tail.text };
 }
 
-/** List a connected client's tools and resources into a Connection. */
+/** Bound the complete list, not each page, and cancel its last request on timeout. */
+async function discoverPages<T>(
+	fetchPage: (cursor: string | undefined, signal: AbortSignal) => Promise<{ items: T[]; nextCursor?: string }>,
+	what: string,
+): Promise<T[]> {
+	const controller = new AbortController();
+	try {
+		return await withTimeout(collectPages((cursor) => fetchPage(cursor, controller.signal), controller.signal), CONNECT_TIMEOUT_MS, what);
+	} catch (error) {
+		controller.abort();
+		throw error;
+	}
+}
+
+/** A fresh, complete tool snapshot. */
+export function discoverTools(client: Client, serverName: string): Promise<McpTool[]> {
+	return discoverPages(async (cursor, signal) => {
+		const result = await client.listTools(cursor === undefined ? undefined : { cursor }, { signal });
+		return { items: result.tools, nextCursor: result.nextCursor };
+	}, `listing tools of "${serverName}"`);
+}
+
+/** List a connected client's tools, resources and URI templates into a Connection. */
 async function finalizeConnection(client: Client, server: McpServer, stderrTail: () => string = () => ""): Promise<Connection> {
 	const warnings: string[] = [];
 
-	// Each list call can take up to CONNECT_TIMEOUT_MS on a slow server; run
-	// them concurrently instead of stacking their worst-case latencies.
-	const [toolsResult, resourcesResult] = await Promise.allSettled([
-		withTimeout(client.listTools(), CONNECT_TIMEOUT_MS, `listing tools of "${server.name}"`),
-		withTimeout(client.listResources(), CONNECT_TIMEOUT_MS, `listing resources of "${server.name}"`),
+	// Each complete list has one deadline; run them concurrently instead of
+	// stacking their worst-case latencies or granting each page a fresh timeout.
+	const [toolsResult, resourcesResult, templatesResult] = await Promise.allSettled([
+		discoverTools(client, server.name),
+		discoverPages(async (cursor, signal) => {
+			const result = await client.listResources(cursor === undefined ? undefined : { cursor }, { signal });
+			return { items: result.resources, nextCursor: result.nextCursor };
+		}, `listing resources of "${server.name}"`),
+		discoverPages(async (cursor, signal) => {
+			const result = await client.listResourceTemplates(cursor === undefined ? undefined : { cursor }, { signal });
+			return { items: result.resourceTemplates, nextCursor: result.nextCursor };
+		}, `listing resource templates of "${server.name}"`),
 	]);
 
 	let tools: McpTool[] = [];
 	if (toolsResult.status === "fulfilled") {
-		tools = (toolsResult.value.tools ?? []) as McpTool[];
+		tools = toolsResult.value;
 	} else {
 		// A server that connects but fails listTools would otherwise register
 		// zero tools with no signal anywhere — surface it as a warning.
 		warnings.push(`connected, but listing tools failed: ${(toolsResult.reason as Error).message}`);
 	}
 
-	let resources: McpResource[] = [];
-	if (resourcesResult.status === "fulfilled") {
-		resources = (resourcesResult.value.resources ?? []) as McpResource[];
-	} else {
-		// Resources are optional in MCP; "method not found" is normal. Anything
-		// else (a timeout, a protocol error) is worth a warning.
-		const message = (resourcesResult.reason as Error).message;
-		if (!/method not found|-32601/i.test(message)) {
-			warnings.push(`connected, but listing resources failed: ${message}`);
-		}
-	}
-
+	// Resources and templates are optional in MCP; "method not found" is
+	// normal. A timeout or protocol error must still surface as a warning.
+	const optionalList = <T>(result: PromiseSettledResult<T[]>, label: string): T[] => {
+		if (result.status === "fulfilled") return result.value;
+		const message = (result.reason as Error).message;
+		if (!/method not found|-32601/i.test(message)) warnings.push(`connected, but listing ${label} failed: ${message}`);
+		return [];
+	};
+	const resources = optionalList(resourcesResult, "resources");
+	const resourceTemplates = optionalList(templatesResult, "resource templates");
 	const instructions = client.getInstructions()?.trim() || undefined;
 
-	return { server, client, tools, resources, instructions, warnings, stderrTail };
+	const connection: Connection = { server, client, tools, resources, resourceTemplates, instructions, warnings, stderrTail };
+	const { ToolListChangedNotificationSchema } = await import("@modelcontextprotocol/sdk/types.js");
+	let refreshing = false;
+	let pending = false;
+	client.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+		if (connection.closing) return;
+		pending = true;
+		if (refreshing) return;
+		refreshing = true;
+		try {
+			// A burst during an in-flight list gets one follow-up refresh, never
+			// concurrent snapshots that could overwrite a newer list with an old one.
+			while (pending && !connection.closing) {
+				pending = false;
+				let refreshed: McpTool[];
+				try {
+					refreshed = await discoverTools(client, server.name);
+				} catch (cause) {
+					if (connection.closing) return;
+					const error = cause instanceof Error ? cause : new Error(String(cause));
+					const warning = `connected, but refreshing tools failed: ${error.message}`;
+					if (!connection.warnings.includes(warning)) connection.warnings.push(warning);
+					connection.onToolsChanged?.(error);
+					continue;
+				}
+				if (connection.closing) return;
+				connection.tools = refreshed;
+				connection.onToolsChanged?.();
+			}
+		} finally {
+			refreshing = false;
+		}
+	});
+	// A server can exit after initialize but before discovery finishes. Its
+	// onclose already fired, before index.ts can adopt the connection.
+	if (!client.transport) throw new Error(withStderr(`connection to "${server.name}" closed during discovery`, stderrTail()));
+	return connection;
 }
 
 /**
@@ -208,10 +313,11 @@ async function finalizeConnection(client: Client, server: McpServer, stderrTail:
 async function openClient(
 	server: McpServer,
 	authProvider?: OAuthClientProvider,
+	keepOAuthOpen?: () => boolean,
 ): Promise<{ client: Client; transport: Transport; stderrTail: () => string }> {
 	const sdk = await loadSdk();
 	const client = new sdk.Client({ name: "one-code", version: "0.1.0" }, { capabilities: {} });
-	return { client, ...buildTransport(server, sdk, authProvider) };
+	return { client, ...buildTransport(server, sdk, authProvider, keepOAuthOpen) };
 }
 
 /**
@@ -254,22 +360,35 @@ export async function connect(server: McpServer, authProvider?: OAuthClientProvi
 export async function beginInteractiveAuth(
 	server: McpServer,
 	authProvider: OAuthClientProvider,
-): Promise<{ transport: StreamableHTTPClientTransport } | { connection: Connection }> {
+): Promise<{ transport: HttpTransport } | { connection: Connection }> {
 	if (server.kind !== "http") throw new Error(`OAuth is only available for http MCP servers; "${server.name}" is stdio.`);
-	const { client, transport: baseTransport, stderrTail } = await openClient(server, authProvider);
-	const transport = baseTransport as StreamableHTTPClientTransport;
+	// Client.connect closes the transport after the expected UnauthorizedError.
+	// Keep OAuth fetches usable until the redirect has been handed to the caller.
+	let awaitingRedirect = true;
+	const { client, transport: baseTransport, stderrTail } = await openClient(server, authProvider, () => awaitingRedirect);
+	const transport = baseTransport as HttpTransport;
 	try {
 		// Not connectOrClose: on a 401 the transport must stay open — it carries
 		// the OAuth flow state the caller finishes with finishAuth(code).
 		await withTimeout(client.connect(transport), CONNECT_TIMEOUT_MS, `connecting to "${server.name}"`);
 		return { connection: await finalizeConnection(client, server, stderrTail) };
 	} catch (error) {
-		if (isUnauthorized(error)) return { transport };
+		// Only the SDK's redirect signal means a browser callback is coming.
+		// A raw 401 after refreshing tokens is an auth failure, not a redirect.
+		if (unauthorizedClass && error instanceof unauthorizedClass) return { transport };
+		awaitingRedirect = false;
 		await transport.close().catch(() => {});
 		throw error;
+	} finally {
+		awaitingRedirect = false;
 	}
 }
 
+/** Bound the token exchange too; the callback deadline only covers waiting for the browser. */
+export async function finishInteractiveAuth(transport: HttpTransport, code: string): Promise<void> {
+	await withTimeout(transport.finishAuth(code), CONNECT_TIMEOUT_MS, "exchanging the authorization code");
+}
+
 const INSTRUCTIONS_CAP = 3000;
 
 /**
@@ -322,21 +441,15 @@ export async function callTool(
 	connection: Connection,
 	toolName: string,
 	args: Record<string, unknown>,
-): Promise<{ content?: unknown[]; isError?: boolean }> {
-	const result = await withTimeout(
-		connection.client.callTool({ name: toolName, arguments: args }),
-		CALL_TIMEOUT_MS,
-		`calling "${toolName}"`,
-	);
-	return result as { content?: unknown[]; isError?: boolean };
+	signal?: AbortSignal,
+): Promise<{ content?: unknown[]; isError?: boolean; structuredContent?: Record<string, unknown> }> {
+	return await connection.client.callTool({ name: toolName, arguments: args }, undefined, { signal, timeout: CALL_TIMEOUT_MS }) as {
+		content?: unknown[]; isError?: boolean; structuredContent?: Record<string, unknown>;
+	};
 }
 
-export async function readResource(connection: Connection, uri: string): Promise<{ contents?: unknown[] }> {
-	return (await withTimeout(
-		connection.client.readResource({ uri }),
-		CALL_TIMEOUT_MS,
-		`reading resource "${uri}"`,
-	)) as { contents?: unknown[] };
+export async function readResource(connection: Connection, uri: string, signal?: AbortSignal): Promise<{ contents?: unknown[] }> {
+	return await connection.client.readResource({ uri }, { signal, timeout: CALL_TIMEOUT_MS });
 }
 
 /**
@@ -345,13 +458,13 @@ export async function readResource(connection: Connection, uri: string): Promise
  * The SDK only calls `safeParse` on the result schema, and the response shape is
  * server-defined, so a passthrough schema beats pinning one the spec hasn't settled.
  */
-export async function readResourceDir(connection: Connection, uri: string): Promise<Record<string, unknown>> {
+export async function readResourceDir(connection: Connection, uri: string, signal?: AbortSignal): Promise<Record<string, unknown>> {
 	const passthrough = { safeParse: (data: unknown) => ({ success: true as const, data }) };
-	return (await withTimeout(
-		connection.client.request({ method: "resources/directory/read", params: { uri } }, passthrough as never),
-		CALL_TIMEOUT_MS,
-		`listing directory "${uri}"`,
-	)) as Record<string, unknown>;
+	return await connection.client.request(
+		{ method: "resources/directory/read", params: { uri } },
+		passthrough as never,
+		{ signal, timeout: CALL_TIMEOUT_MS },
+	) as Record<string, unknown>;
 }
 
 export async function close(connection: Connection): Promise<void> {

package/extensions/mcp/config.ts

@@ -2,17 +2,36 @@
  * MCP server configuration in Claude Code's format (pure).
  *
  * Sources, lowest to highest precedence:
+ *   plugins' .mcp.json                (bare server maps)
+ *   pi.registerMcpServer()            (servers other pi extensions register, pi 0.99+)
+ *   <agentDir>/mcp.json               (pi's own user file, ~/.pi/agent/mcp.json)
+ *   <cwd>/.pi/mcp.json                (pi's own project file)
  *   ~/.claude.json                    (user, global)
  *   <cwd>/.mcp.json                   (project, checked in — walked up to the repo root)
  *   <cwd>/.claude/settings.local.json (project, personal)
  *
+ * Independent mode (lib/config-mode.ts) reads none of the three Claude Code
+ * files: plugins, registered servers and pi's two files only.
+ *
  * Every file holds an `mcpServers` object. A stdio server has `command` (plus
  * optional `args`, `env`); a remote one has `url` and optional `type`/`headers`.
+ *
+ * pi's two files are read because One Code's `/mcp` replaces pi 0.99's
+ * built-in MCP, which would otherwise have read them (decisions/mcp.md). Their
+ * format is pi's: `enabled: false` turns a server off, a stdio server may set
+ * `cwd` (relative to the session directory), and a leading `~/` in `command`,
+ * an argument or `cwd` names the home directory. A server with a `!command`
+ * value in `env` or `headers` is skipped with a note: running a shell command
+ * from a config file to build a credential is not supported. pi's
+ * `oauth`/`auth` settings, `exposure`, `timeout` and `description` are
+ * ignored. A Claude Code file's server of the same name wins, with a note.
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { claudeJsonPath } from "../lib/paths.ts";
+import { dirname, join, resolve } from "node:path";
+import { claudeSourcesOn } from "../lib/config-mode.ts";
+import { claudeJsonPath, expandTilde } from "../lib/paths.ts";
+import { hashServerConfig } from "./trust.ts";
 
 export interface StdioServer {
 	kind: "stdio";
@@ -20,7 +39,11 @@ export interface StdioServer {
 	command: string;
 	args: string[];
 	env?: Record<string, string>;
+	/** Working directory (pi's `mcp.json` only); the session's directory when absent. */
+	cwd?: string;
 	source: string;
+	/** Set for a server read in pi's format: which of pi's sources defined it. */
+	piOrigin?: PiOrigin;
 	/** Config referenced these environment variables and they are not set. */
 	missingEnv?: string[];
 	/** Every env var the config references (set or not), for the consent dialog — values are expanded away by parse time. */
@@ -29,10 +52,13 @@ export interface StdioServer {
 
 export interface HttpServer {
 	kind: "http";
+	/** Legacy HTTP+SSE when explicitly configured; otherwise Streamable HTTP. */
+	transport?: "sse";
 	name: string;
 	url: string;
 	headers?: Record<string, string>;
 	source: string;
+	piOrigin?: PiOrigin;
 	/** Config referenced these environment variables and they are not set. */
 	missingEnv?: string[];
 	/** Every env var the config references (set or not), for the consent dialog — values are expanded away by parse time. */
@@ -41,6 +67,9 @@ export interface HttpServer {
 
 export type McpServer = StdioServer | HttpServer;
 
+/** pi's user `mcp.json`, its project `mcp.json`, or an extension's `pi.registerMcpServer()`. */
+export type PiOrigin = "user" | "project" | "extension";
+
 interface RawServer {
 	command?: unknown;
 	args?: unknown;
@@ -49,6 +78,26 @@ interface RawServer {
 	type?: unknown;
 	headers?: unknown;
 	disabled?: unknown;
+	/** pi's `mcp.json`: `false` keeps the entry without connecting. */
+	enabled?: unknown;
+	/** pi's `mcp.json`: a stdio server's working directory. */
+	cwd?: unknown;
+}
+
+/** How to read a server from one of pi's own `mcp.json` files. */
+export interface PiFormat {
+	home: string;
+	/** The session directory a relative `cwd` resolves against. */
+	cwd: string;
+}
+
+/**
+ * Why a pi-format server cannot be loaded, or undefined: a `!command` value
+ * in `env` or `headers` (pi runs it in a shell to build the value).
+ */
+export function piFormatProblem(raw: RawServer): string | undefined {
+	const values = [...Object.values(asStringRecord(raw.env) ?? {}), ...Object.values(asStringRecord(raw.headers) ?? {})];
+	return values.some((value) => value.startsWith("!")) ? "a `!command` value in env or headers is not supported" : undefined;
 }
 
 function asStringRecord(value: unknown): Record<string, string> | undefined {
@@ -100,8 +149,11 @@ export function parseServer(
 	raw: RawServer,
 	source: string,
 	env: Record<string, string | undefined>,
+	pi?: PiFormat,
 ): McpServer | undefined {
 	if (raw.disabled === true) return undefined;
+	if (pi && raw.enabled === false) return undefined;
+	const home = (value: string) => (pi ? expandTilde(value, pi.home) : value);
 
 	if (typeof raw.url === "string" && raw.url.trim()) {
 		const headers = asStringRecord(raw.headers);
@@ -112,6 +164,7 @@ export function parseServer(
 		const referenced = referencedEnvVars(raw.url, ...Object.values(headers ?? {}));
 		return {
 			kind: "http",
+			...(raw.type === "sse" ? { transport: "sse" as const } : {}),
 			name,
 			url: expandEnv(raw.url, env),
 			headers: headers
@@ -125,11 +178,14 @@ export function parseServer(
 
 	if (typeof raw.command === "string" && raw.command.trim()) {
 		const args = Array.isArray(raw.args)
-			? raw.args.filter((a): a is string => typeof a === "string").map((a) => expandEnv(a, env))
+			? raw.args.filter((a): a is string => typeof a === "string").map((a) => home(expandEnv(a, env)))
 			: [];
+		const rawCwd = pi && typeof raw.cwd === "string" && raw.cwd.trim() ? raw.cwd : undefined;
+		const cwd = rawCwd && pi ? resolve(pi.cwd, home(expandEnv(rawCwd, env))) : undefined;
 		const rawEnv = asStringRecord(raw.env);
 		const missing = [
 			...missingEnvVars(raw.command, env),
+			...missingEnvVars(rawCwd ?? "", env),
 			...(Array.isArray(raw.args) ? raw.args : [])
 				.filter((a): a is string => typeof a === "string")
 				.flatMap((a) => missingEnvVars(a, env)),
@@ -137,15 +193,17 @@ export function parseServer(
 		];
 		const referenced = referencedEnvVars(
 			raw.command,
+			rawCwd ?? "",
 			...(Array.isArray(raw.args) ? raw.args.filter((a): a is string => typeof a === "string") : []),
 			...Object.values(rawEnv ?? {}),
 		);
 		return {
 			kind: "stdio",
 			name,
-			command: expandEnv(raw.command, env),
+			command: home(expandEnv(raw.command, env)),
 			args,
 			env: rawEnv ? Object.fromEntries(Object.entries(rawEnv).map(([k, v]) => [k, expandEnv(v, env)])) : undefined,
+			...(cwd ? { cwd } : {}),
 			source,
 			missingEnv: missing.length > 0 ? [...new Set(missing)] : undefined,
 			referencedEnv: referenced.length > 0 ? referenced : undefined,
@@ -171,7 +229,29 @@ export function findProjectConfigs(cwd: string): string[] {
 	return found.reverse();
 }
 
+/**
+ * `/mcp` with no servers: where to look when that is unexpected (`/doctor`
+ * lists config files that failed validation) and where servers go, by mode.
+ * Claude Code names its own CLI and docs here; One Code names its own.
+ */
+export const MCP_GUIDE_URL = "https://github.com/IsuruMaduranga/one-code/blob/master/docs/guide/skills-plugins-and-mcp.md#mcp-servers";
+export function noMcpServersMessage(claudeSources: boolean): string {
+	const where = claudeSources ? ".mcp.json in the project, ~/.claude.json, .pi/mcp.json or the agent dir's mcp.json" : ".pi/mcp.json or the agent dir's mcp.json";
+	return `No MCP servers configured. Run /doctor if this is unexpected — it lists MCP config files that failed validation. Otherwise, add servers to ${where}; see ${MCP_GUIDE_URL} to learn more.`;
+}
+
+/**
+ * pi's own `mcp.json` files: the agent dir's and the project's. `configDirName`
+ * is pi's `CONFIG_DIR_NAME` (`.pi` unless pi itself is rebranded); callers
+ * that import pi pass it.
+ */
+export function piMcpConfigPaths(agentDir: string, cwd: string, configDirName = ".pi"): { user: string; project: string } {
+	return { user: join(agentDir, "mcp.json"), project: join(cwd, configDirName, "mcp.json") };
+}
+
+/** Claude Code's MCP files; none in independent mode (lib/config-mode.ts), where pi's two `mcp.json` files remain. */
 export function configPaths(cwd: string, home: string): string[] {
+	if (!claudeSourcesOn()) return [];
 	return [claudeJsonPath(home), ...findProjectConfigs(cwd), join(cwd, ".claude", "settings.local.json")];
 }
 
@@ -196,6 +276,25 @@ export interface LoadServersOptions {
 	pluginNames?: ReadonlyMap<string, string>;
 	/** Called for a config file that exists but is not valid JSON (review M11: a silent drop read as "no servers configured"). */
 	onError?: (path: string, message: string) => void;
+	/** pi's own `mcp.json` files (user, then project): read in pi's format, below every Claude Code file. */
+	piConfigs?: { user: string; project: string };
+	/** Called for a pi-format server that is skipped, or overridden by a Claude Code file's server of the same name. */
+	onNote?: (message: string) => void;
+	/** Servers other pi extensions registered (`pi.getMcpServers()`): pi's format, below every file; `source` is the extension's path. */
+	registered?: readonly RegisteredServer[];
+}
+
+/** One `pi.getMcpServers()` entry, structurally (pi 0.99's `RegisteredMcpServer`). */
+export interface RegisteredServer {
+	name: string;
+	config: unknown;
+	extensionPath: string;
+}
+
+/** The servers other extensions registered (`pi.getMcpServers()`, pi 0.99+); none on an older pi. */
+export function registeredMcpServers(pi: object): RegisteredServer[] {
+	const host = pi as { getMcpServers?: () => RegisteredServer[] };
+	return typeof host.getMcpServers === "function" ? host.getMcpServers() : [];
 }
 
 export function loadServers(
@@ -206,8 +305,21 @@ export function loadServers(
 	options: LoadServersOptions = {},
 ): McpServer[] {
 	const byName = new Map<string, McpServer>();
-	// Plugin configs come first so project and user files can override them.
-	for (const path of [...extraPaths, ...configPaths(cwd, home)]) {
+	const piPaths = options.piConfigs ? [options.piConfigs.user, options.piConfigs.project] : [];
+	const piFormat: PiFormat = { home, cwd };
+	for (const { name, config, extensionPath } of options.registered ?? []) {
+		const raw = (config && typeof config === "object" ? config : {}) as RawServer;
+		const problem = piFormatProblem(raw);
+		if (problem) {
+			options.onNote?.(`MCP server "${name}" registered by ${extensionPath} is skipped: ${problem}.`);
+			continue;
+		}
+		const server = parseServer(name, raw, extensionPath, env, piFormat);
+		if (server) byName.set(name, { ...server, piOrigin: "extension" });
+	}
+	// Plugin configs come first so project and user files can override them,
+	// then pi's own files, then Claude Code's.
+	for (const path of [...extraPaths, ...piPaths, ...configPaths(cwd, home)]) {
 		if (!existsSync(path)) continue;
 		let file: Record<string, unknown> | undefined;
 		try {
@@ -219,10 +331,22 @@ export function loadServers(
 		const servers = serverMapOf(file);
 		if (!servers) continue;
 		const plugin = options.pluginNames?.get(path);
+		const piOrigin: PiOrigin | undefined =
+			path === options.piConfigs?.user ? "user" : path === options.piConfigs?.project ? "project" : undefined;
 		for (const [rawName, raw] of Object.entries(servers)) {
 			const name = plugin ? `plugin:${plugin}:${rawName}` : rawName;
-			const server = parseServer(name, raw ?? {}, path, env);
-			if (server) byName.set(name, server);
+			const problem = piOrigin ? piFormatProblem(raw ?? {}) : undefined;
+			if (problem) {
+				options.onNote?.(`MCP server "${name}" in ${path} is skipped: ${problem}.`);
+				continue;
+			}
+			const server = parseServer(name, raw ?? {}, path, env, piOrigin ? piFormat : undefined);
+			const inherited = byName.get(name);
+			// The same server kept in both (common while moving between the two) is not worth a warning.
+			if (!piOrigin && server && inherited?.piOrigin && hashServerConfig(server) !== hashServerConfig(inherited)) {
+				options.onNote?.(`MCP server "${name}" in ${inherited.source} is overridden by the one in ${path}.`);
+			}
+			if (server) byName.set(name, piOrigin ? { ...server, piOrigin } : server);
 			else byName.delete(name); // an explicit `disabled` entry removes an inherited one
 		}
 	}

package/extensions/mcp/discovery.ts

@@ -0,0 +1,19 @@
+/** Collect an MCP list response's cursor pages without silently dropping later entries. */
+export async function collectPages<T>(
+	fetchPage: (cursor?: string) => Promise<{ items: T[]; nextCursor?: string }>,
+	signal?: AbortSignal,
+): Promise<T[]> {
+	const items: T[] = [];
+	const seen = new Set<string>();
+	let cursor: string | undefined;
+	while (true) {
+		signal?.throwIfAborted();
+		const page = await fetchPage(cursor);
+		signal?.throwIfAborted();
+		for (const item of page.items) items.push(item);
+		if (page.nextCursor === undefined) return items;
+		if (seen.has(page.nextCursor)) throw new Error("MCP server repeated a pagination cursor; check the server's list implementation.");
+		seen.add(page.nextCursor);
+		cursor = page.nextCursor;
+	}
+}