one-code-extension 0.4.1 → 0.6.0

package/extensions/mcp/index.ts

@@ -16,11 +16,13 @@
  */
 
 import os from "node:os";
-import { getAgentDir, type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { isDeepStrictEqual } from "node:util";
+import { CONFIG_DIR_NAME, getAgentDir, type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { DEFER_CHANNEL } from "../lib/deferred.ts";
 import { MCP_TOOLS_CHANNEL } from "../lib/mcp-share.ts";
 import { persistIfLarge, sessionResultsDir } from "../lib/persisted-output.ts";
+import { emptyToolResultContent } from "../lib/empty-tool-result.ts";
 import { ccToolRenderers } from "../lib/tui-render.ts";
 import {
 	callTool,
@@ -34,7 +36,7 @@ import {
 	readResource,
 	readResourceDir,
 } from "./client.ts";
-import { CONTEXT_ORDER, REMINDER_CHANNEL } from "../lib/reminders.ts";
+import { CONTEXT_ORDER, REMINDER_CHANNEL, RENDER_CHANNEL, type RenderRequest } from "../lib/reminders.ts";
 import { join } from "node:path";
 import {
 	MCP_STATUS_CHANNEL,
@@ -47,14 +49,14 @@ import { readDisabledMcpServers, setMcpServerDisabled } from "../lib/mcp-overrid
 import { boundedDockHeight, safeThemeBold, safeThemePaint, truncateLine } from "../lib/tui-render.ts";
 import { authenticate as runOAuthFlow, silentProvider } from "./oauth/flow.ts";
 import { hasStoredTokens } from "./oauth/store.ts";
-import { announcedFrom, applyMcpDelta, emptyAnnounced, mcpChangeNotices, mcpDelta, type McpSnapshot } from "./announce.ts";
+import { mcpChangeNotices, mcpDelta, mcpFacts, type McpSnapshot, mcpStartupNotices } from "./announce.ts";
 import { decodeMcpKey } from "./panel/keys.ts";
 import { type McpEntry, type McpEntryStatus } from "./panel/model.ts";
 import { renderMcpPanel, type McpPaint } from "./panel/render.ts";
 import { applyMcpKey, initialMcpState, type McpEffect } from "./panel/state.ts";
 import { sessionAlive } from "../lib/session-lifecycle.ts";
-import { loadServers, type McpServer } from "./config.ts";
-import { approveMcpServers, persistApproval, projectRootOf } from "./trust.ts";
+import { loadServers, type McpServer, noMcpServersMessage, piMcpConfigPaths, registeredMcpServers } from "./config.ts";
+import { approveMcpServers, type McpTrustDeps, persistApproval, projectRootOf, reconnectRefusal } from "./trust.ts";
 import {
 	capDescription,
 	describeContent,
@@ -65,6 +67,11 @@ import {
 	namespacedToolName,
 } from "./schema.ts";
 import { registerLocalCommand } from "../lib/local-command.ts";
+import { canShowCustomUi, notifyRpcReadOnly } from "../lib/headless-output.ts";
+import { claudeSourcesOn } from "../lib/config-mode.ts";
+import { claudeJsonPath } from "../lib/paths.ts";
+import { consentDialog, startupConsentReady } from "../lib/consent-dialogs.ts";
+import { panelUi } from "../lib/panel-focus.ts";
 
 /** Anthropic's hard limit on a tool name; a longer one fails the whole request. */
 const MAX_TOOL_NAME_LENGTH = 128;
@@ -78,10 +85,13 @@ function unknownServerError(name: string) {
 	};
 }
 
+/** pi's own `mcp.json` files, read because our `/mcp` replaces pi 0.99's built-in MCP (config.ts). */
+const piMcpConfigs = (cwd: string) => piMcpConfigPaths(getAgentDir(), cwd, CONFIG_DIR_NAME);
+
 export default function mcpExtension(pi: ExtensionAPI) {
 	const connections = new Map<string, Connection>();
 	let failures: FailedConnection[] = [];
-	const registered = new Set<string>();
+	const registered = new Map<string, { server: string; tool: string }>();
 	let servers: McpServer[] = [];
 	// http servers that returned a 401 with no stored tokens — authNeeded via OAuth,
 	// distinct from a missing-env authNeeded (which Authenticate cannot fix).
@@ -93,18 +103,17 @@ export default function mcpExtension(pi: ExtensionAPI) {
 	const withheldNames = new Map<string, string>();
 	// Config file paths contributed by plugins, so the panel can group them.
 	let pluginConfigPaths = new Set<string>();
+	// pi 0.99's registry of servers other extensions register; absent on older pi.
+	// Registered after the session started: our servers are read once per session.
+	pi.on("mcp_servers_change", (_event, ctx) => {
+		const text = "An extension changed its MCP servers; run /reload to connect the change.";
+		if (ctx.hasUI) ctx.ui.notify(text, "info");
+		else process.stderr.write(`${text}\n`);
+	});
 	const home = os.homedir();
 	// Live tool definitions, shared with in-process subagents so they reach MCP
 	// through these same open connections instead of connecting their own.
 	const sharedTools: ToolDefinition[] = [];
-	// Message 1 carries the MCP instructions and failed-servers reminders. Once a
-	// request has gone out it is part of every later request's cached prefix, so
-	// those blocks are frozen and later changes ride one-shot notices (./announce.ts).
-	let requestSent = false;
-	let announced = emptyAnnounced();
-	pi.on("context", () => {
-		requestSent = true;
-	});
 
 	/**
 	 * Where oversized results are persisted — the session dir, matching Claude
@@ -114,6 +123,8 @@ export default function mcpExtension(pi: ExtensionAPI) {
 	const resultsDir = (ctx: ExtensionContext | undefined): string => sessionResultsDir(ctx);
 
 	const registerToolsFor = (connection: Connection) => {
+		// Names other extensions own, read once per batch (getAllTools builds every definition).
+		let taken: Set<string> | undefined;
 		for (const tool of connection.tools) {
 			const name = namespacedToolName(connection.server.name, tool.name);
 			// Anthropic caps a tool name at 128 characters and rejects the whole
@@ -128,8 +139,12 @@ export default function mcpExtension(pi: ExtensionAPI) {
 				});
 				continue;
 			}
-			if (registered.has(name)) {
-				// Two tools sanitise to one name (`a-b` and `a_b`, or a server
+			const owner = registered.get(name);
+			// An unchanged tool on reconnect keeps its exact definition and loaded
+			// state. Only a different raw server/tool pair is a name collision.
+			if (owner?.server === connection.server.name && owner.tool === tool.name) continue;
+			if (owner || (taken ??= new Set(pi.getAllTools().map((existing) => existing.name))).has(name)) {
+				// Two tools sanitise to one name (`a.b` and `a_b`, or a server
 				// reconnecting under a stale registration). Skipping silently would
 				// make the second tool unreachable with no trace; record it where
 				// the connection summary reports it.
@@ -139,7 +154,7 @@ export default function mcpExtension(pi: ExtensionAPI) {
 				});
 				continue;
 			}
-			registered.add(name);
+			registered.set(name, { server: connection.server.name, tool: tool.name });
 
 			const def: ToolDefinition = {
 				name,
@@ -147,7 +162,7 @@ export default function mcpExtension(pi: ExtensionAPI) {
 				...ccToolRenderers(`${connection.server.name}: ${tool.name}`),
 				description: capDescription(tool.description) ?? `MCP tool "${tool.name}" from server "${connection.server.name}".`,
 				parameters: jsonSchemaToTypeBox(tool.inputSchema),
-				async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+				async execute(toolCallId, params, signal, _onUpdate, ctx) {
 					const live = connections.get(connection.server.name);
 					if (!live) {
 						return {
@@ -156,17 +171,27 @@ export default function mcpExtension(pi: ExtensionAPI) {
 							isError: true,
 						};
 					}
+					const current = live.tools.find((candidate) => candidate.name === tool.name);
+					if (!current || !isDeepStrictEqual(current.inputSchema, tool.inputSchema)) {
+						return {
+							content: [{ type: "text", text: !current
+								? `MCP server "${connection.server.name}" no longer exposes tool "${tool.name}".`
+								: `MCP tool "${name}" changed its input schema. Run /reload to load the new definition; this call was not sent.` }],
+							details: {} as Record<string, unknown>,
+							isError: true,
+						};
+					}
 					try {
-						const result = await callTool(live, tool.name, (params ?? {}) as Record<string, unknown>);
-						const { text, images } = describeContent(result.content as McpContentBlock[] | undefined, connection.server.name);
+						const result = await callTool(live, tool.name, (params ?? {}) as Record<string, unknown>, signal);
+						const { text: contentText, images } = describeContent(result.content as McpContentBlock[] | undefined, connection.server.name);
+						const structuredText = result.structuredContent !== undefined ? JSON.stringify(result.structuredContent, null, 2) : "";
+						const text = [contentText, structuredText].filter(Boolean).join("\n");
+						const content = [
+							...(text ? [{ type: "text" as const, text: persistIfLarge(text, { dir: resultsDir(ctx), id: toolCallId }) }] : []),
+							...images.map((image) => ({ type: "image" as const, data: image.data, mimeType: image.mimeType })),
+						];
 						return {
-							content: [
-								{
-									type: "text",
-									text: text ? persistIfLarge(text, { dir: resultsDir(ctx), id: toolCallId }) : "(no output)",
-								},
-								...images.map((image) => ({ type: "image" as const, data: image.data, mimeType: image.mimeType })),
-							],
+							content: emptyToolResultContent(content, name) ?? content,
 							details: { server: connection.server.name, tool: tool.name } as Record<string, unknown>,
 							isError: result.isError === true,
 						};
@@ -232,15 +257,38 @@ export default function mcpExtension(pi: ExtensionAPI) {
 			});
 			emitInstructions();
 		};
+		let previousTools = connection.tools;
+		connection.onToolsChanged = (error) => {
+			if (!alive() || connection.closing || connections.get(server.name) !== connection) return;
+			if (error) {
+				failures.push({ server, error: error.message });
+				pi.events.emit(REMINDER_CHANNEL, { text: `MCP server "${server.name}" could not refresh its tool list: ${error.message}` });
+				return;
+			}
+			const unavailable = previousTools.filter((old) => {
+				const current = connection.tools.find((tool) => tool.name === old.name);
+				return !current || !isDeepStrictEqual(current.inputSchema, old.inputSchema);
+			});
+			previousTools = connection.tools;
+			registerToolsFor(connection);
+			if (unavailable.length > 0) {
+				pi.events.emit(REMINDER_CHANNEL, {
+					text: `MCP server "${server.name}" removed or changed these tools: ${unavailable.map((tool) => namespacedToolName(server.name, tool.name)).join(", ")}. Their old definitions cannot be used. Run /reload to refresh changed schemas.`,
+				});
+			}
+		};
 		registerToolsFor(connection);
 		for (const warning of connection.warnings) failures.push({ server, error: warning });
-		if (connection.resources.length > 0) registerResourceTools();
+		if (connection.resources.length > 0 || connection.resourceTemplates?.length) registerResourceTools();
 	};
 
+	/** Servers with a connect in flight (startup, a reconnect, an authenticate): not dropped while it runs. */
+	const connectingNames = new Set<string>();
 	const connectOne = async (server: McpServer): Promise<void> => {
 		failures = failures.filter((f) => f.server.name !== server.name);
 		oauthNeeded.delete(server.name);
-		const provider = server.kind === "http" && hasStoredTokens(server.name) ? silentProvider(server.name) : undefined;
+		const provider = server.kind === "http" && hasStoredTokens(server) ? silentProvider(server) : undefined;
+		connectingNames.add(server.name);
 		try {
 			const connection = await connect(server, provider);
 			if (!alive()) {
@@ -252,6 +300,8 @@ export default function mcpExtension(pi: ExtensionAPI) {
 			if (!alive()) return;
 			if (server.kind === "http" && isUnauthorized(error)) oauthNeeded.add(server.name);
 			else failures.push({ server, error: (error as Error).message });
+		} finally {
+			connectingNames.delete(server.name);
 		}
 	};
 
@@ -261,73 +311,94 @@ export default function mcpExtension(pi: ExtensionAPI) {
 	 * which servers failed — otherwise it concludes the tools do not exist or the
 	 * user has no access instead of reporting a connection failure the user can
 	 * fix (review M4). Re-run on every connect, close, reconnect, authenticate,
-	 * enable and disable. Before the first request the two first-prepend blocks on
-	 * message 1 are (re)written; after it they are frozen and only the changes are
-	 * announced (./announce.ts).
+	 * enable and disable. The two first-prepend blocks are live state: what an
+	 * epoch's message 1 says. Inside an epoch the render step below announces
+	 * only what changed since the epoch told it (./announce.ts).
 	 */
+	const liveSnapshot = (): McpSnapshot => ({
+		connected: [...connections.values()].map((c) => ({ name: c.server.name, instructions: c.instructions })),
+		failed: failures.filter((f) => !connections.has(f.server.name)).map((f) => ({ name: f.server.name, error: f.error })),
+	});
 	const emitInstructions = () => {
 		const live = [...connections.values()];
-		const snapshot: McpSnapshot = {
-			connected: live.map((c) => ({ name: c.server.name, instructions: c.instructions })),
-			failed: failures.filter((f) => !connections.has(f.server.name)).map((f) => ({ name: f.server.name, error: f.error })),
-		};
-
-		if (!requestSent) {
-			// Nothing is cached yet: (re)write the standing message-1 blocks.
-			if (snapshot.failed.length === 0) {
-				pi.events.emit(REMINDER_CHANNEL, { scope: "every-turn", key: "mcp-failures", text: "", remove: true });
-			} else {
-				pi.events.emit(REMINDER_CHANNEL, {
-					scope: "every-turn",
-					key: "mcp-failures",
-					text: mcpFailuresReminder(snapshot.failed),
-					placement: "first-prepend",
-					order: CONTEXT_ORDER.mcp + 1,
-				});
-			}
-			const instructions = mcpInstructionsReminder(live);
-			if (instructions) {
-				pi.events.emit(REMINDER_CHANNEL, {
-					scope: "every-turn",
-					key: "mcp-instructions",
-					text: instructions,
-					placement: "first-prepend",
-					order: CONTEXT_ORDER.mcp,
-				});
-			} else {
-				// No server has instructions anymore (e.g. the last one was disabled or
-				// disconnected) — drop the stale every-turn reminder so the model stops
-				// being told to use tools that are gone.
-				pi.events.emit(REMINDER_CHANNEL, { scope: "every-turn", key: "mcp-instructions", text: "", remove: true });
-			}
-			announced = announcedFrom(snapshot);
-			return;
+		const snapshot = liveSnapshot();
+		if (snapshot.failed.length === 0) {
+			pi.events.emit(REMINDER_CHANNEL, { key: "mcp-failures", text: "", remove: true });
+		} else {
+			pi.events.emit(REMINDER_CHANNEL, {
+				key: "mcp-failures",
+				text: mcpFailuresReminder(snapshot.failed),
+				placement: "first-prepend",
+				order: CONTEXT_ORDER.mcp + 1,
+				facts: mcpFacts({ connected: [], failed: snapshot.failed }),
+			});
+		}
+		const instructions = mcpInstructionsReminder(live);
+		if (instructions) {
+			pi.events.emit(REMINDER_CHANNEL, {
+				key: "mcp-instructions",
+				text: instructions,
+				placement: "first-prepend",
+				order: CONTEXT_ORDER.mcp,
+				facts: mcpFacts({ connected: snapshot.connected, failed: [] }),
+			});
+		} else {
+			// No server has instructions anymore (e.g. the last one was disabled or
+			// disconnected) — drop the stale block so an epoch does not tell the
+			// model to use tools that are gone.
+			pi.events.emit(REMINDER_CHANNEL, { key: "mcp-instructions", text: "", remove: true });
 		}
-
-		// Message 1 is frozen (rewriting it would re-cache the whole conversation):
-		// tell the model only what changed, as one-shots where it reads next.
-		const delta = mcpDelta(announced, snapshot);
-		for (const text of mcpChangeNotices(delta)) pi.events.emit(REMINDER_CHANNEL, { text });
-		applyMcpDelta(announced, delta);
 	};
+	// Inside an epoch, what changed since message 1 (or the last notice) rides
+	// the request's tail, decided when the request goes out.
+	pi.events.on(RENDER_CHANNEL, (data) => {
+		const request = data as RenderRequest;
+		if (request.epoch) return;
+		const delta = mcpDelta(request.toldBlocks, liveSnapshot(), !connectSettled, connectingNames);
+		const notices = mcpChangeNotices(delta);
+		notices.forEach((text, i) => request.blocks.push({ text, ...(i === 0 ? { facts: delta.facts } : {}) }));
+	});
 
 	/** Config files that exist but failed to parse (review M11) — shown at startup and in /mcp. */
 	let configErrors: string[] = [];
 
+	/** How the consent check asks, tells and records a "No", for startup and for Reconnect alike. */
+	const consentDeps = (ctx: ExtensionContext): McpTrustDeps => ({
+		hasUI: ctx.hasUI,
+		select: (title, options) => consentDialog(pi.events, (signal) => ctx.ui.select(title, options, { signal })),
+		notify: (message) => {
+			if (ctx.hasUI) ctx.ui.notify(message, "warning");
+			else process.stderr.write(`${message}\n`);
+		},
+		disable: (server) => {
+			setMcpServerDisabled(server.name, true, "project", ctx.cwd, home);
+			disabledNames.add(server.name);
+		},
+	});
+
 	const connectAll = async (ctx: ExtensionContext) => {
 		const plugins = discoverPlugins(defaultDiscoverRoots(getAgentDir(), ctx.cwd));
 		pluginConfigPaths = new Set(plugins.mcpConfigs);
 		configErrors = [];
+		const configNotes: string[] = [];
 		servers = loadServers(ctx.cwd, home, process.env, [...pluginConfigPaths], {
 			pluginNames: plugins.mcpConfigPlugins,
 			onError: (path, message) => configErrors.push(`${path}: ${message}`),
+			piConfigs: piMcpConfigs(ctx.cwd),
+			onNote: (message) => configNotes.push(message),
+			registered: registeredMcpServers(pi),
 		});
-		if (configErrors.length > 0) {
-			const text = `MCP config could not be parsed (ignored): ${configErrors.join("; ")}`;
+		const configWarnings = [
+			...(configErrors.length > 0 ? [`MCP config could not be parsed (ignored): ${configErrors.join("; ")}`] : []),
+			...configNotes,
+		];
+		for (const text of configWarnings) {
 			if (ctx.hasUI) ctx.ui.notify(text, "warning");
 			else process.stderr.write(`${text}\n`);
 		}
 		disabledNames = readDisabledMcpServers(ctx.cwd, home);
+		// With no server configured there is nothing to connect; a resumed epoch
+		// that told the model about one hears that it dropped at render time.
 		if (servers.length === 0) return;
 
 		// Disabled servers are listed but never connected; a server with an unset
@@ -336,19 +407,13 @@ export default function mcpExtension(pi: ExtensionAPI) {
 		// server needs the user's consent first (trust.ts — a cloned repo must not
 		// run commands at startup). Everything else connects.
 		const candidates = servers.filter((server) => !disabledNames.has(server.name) && !server.missingEnv?.length);
-		const consent = await approveMcpServers(candidates, pluginConfigPaths, ctx.cwd, home, {
-			hasUI: ctx.hasUI,
-			select: (title, options) => ctx.ui.select(title, options),
-			notify: (message) => {
-				if (ctx.hasUI) ctx.ui.notify(message, "warning");
-				else process.stderr.write(`${message}\n`);
-			},
-			disable: (server) => {
-				setMcpServerDisabled(server.name, true, "project", ctx.cwd, home);
-				disabledNames.add(server.name);
-			},
-		});
-		if (!alive()) return;
+		// Reserve the modal position before the asynchronous policy read, so the
+		// external-includes dialog cannot jump ahead of MCP's startup consent.
+		const consent = await consentDialog(pi.events, (signal) => approveMcpServers(candidates, pluginConfigPaths, ctx.cwd, home, {
+			...consentDeps(ctx),
+			select: (title, options) => ctx.ui.select(title, options, { signal }),
+		}));
+		if (!consent || !alive()) return;
 		withheldNames.clear();
 		for (const { server, reason } of consent.withheld) {
 			withheldNames.set(
@@ -364,16 +429,15 @@ export default function mcpExtension(pi: ExtensionAPI) {
 
 		if (!alive()) return;
 
-		if (failures.length > 0) {
-			const text = failures.map((f) => `MCP server "${f.server.name}" failed: ${f.error}`).join("\n") + " (/mcp for status)";
-			if (ctx.hasUI) ctx.ui.notify(text, "warning");
-			else process.stderr.write(`${text}\n`);
-		}
-		if (oauthNeeded.size > 0 && ctx.hasUI) {
-			ctx.ui.notify(
-				`${oauthNeeded.size} MCP server${oauthNeeded.size === 1 ? "" : "s"} need authentication — run /mcp to authenticate.`,
-				"warning",
-			);
+		// Warnings from servers that did connect are shown in /mcp, not as failures.
+		const failed = failures.filter((f) => !connections.has(f.server.name));
+		if (ctx.hasUI) {
+			// Needs auth: an OAuth sign-in, or a credential variable that is not set (never attempted).
+			const needsAuth = new Set([...oauthNeeded, ...servers.filter((server) => !disabledNames.has(server.name) && server.missingEnv?.length).map((server) => server.name)]).size;
+			for (const text of mcpStartupNotices(new Set(failed.map((f) => f.server.name)).size, needsAuth)) ctx.ui.notify(text, "warning");
+		} else if (failed.length > 0) {
+			// Headless runs have no /mcp, so they keep each server's error on stderr.
+			process.stderr.write(`${failed.map((f) => `MCP server "${f.server.name}" failed: ${f.error}`).join("\n")}\n`);
 		}
 
 		emitInstructions();
@@ -384,12 +448,17 @@ export default function mcpExtension(pi: ExtensionAPI) {
 		if (resourceToolsRegistered) return;
 		resourceToolsRegistered = true;
 
-		pi.registerTool({
+		const registerResourceTool: ExtensionAPI["registerTool"] = (definition) => {
+			pi.registerTool(definition);
+			sharedTools.push(definition as ToolDefinition);
+		};
+
+		registerResourceTool({
 			name: "list_mcp_resources",
 			label: "MCP Resources",
 			...ccToolRenderers("MCP Resources"),
 			description:
-				"List resources exposed by connected MCP servers. Resources are readable documents or data the server offers, addressed by uri.",
+				"List resources and URI templates exposed by connected MCP servers. Resources are readable documents or data the server offers, addressed by uri. Substitute template variables to construct a resource uri.",
 			parameters: Type.Object({
 				server: Type.Optional(Type.String({ description: "Limit to one server by name" })),
 			}),
@@ -417,12 +486,15 @@ export default function mcpExtension(pi: ExtensionAPI) {
 							`${connection.server.name} ${resource.uri}${resource.name ? ` — ${resource.name}` : ""}${resource.description ? `: ${resource.description}` : ""}`,
 						);
 					}
+					for (const template of connection.resourceTemplates ?? []) {
+						lines.push(`${connection.server.name} ${template.uriTemplate} (URI template)${template.name ? ` — ${template.name}` : ""}${template.description ? `: ${template.description}` : ""}`);
+					}
 				}
 				return {
 					content: [
 						{
 							type: "text",
-							text: lines.length ? persistIfLarge(lines.join("\n"), { dir: resultsDir(ctx), id: toolCallId }) : "No MCP resources available.",
+							text: lines.length ? persistIfLarge(lines.join("\n"), { dir: resultsDir(ctx), id: toolCallId }) : "No resources found. MCP servers may still provide tools even if they have no resources.",
 						},
 					],
 					details: { count: lines.length },
@@ -430,7 +502,7 @@ export default function mcpExtension(pi: ExtensionAPI) {
 			},
 		});
 
-		pi.registerTool({
+		registerResourceTool({
 			name: "read_mcp_resource",
 			label: "Read MCP Resource",
 			...ccToolRenderers("Read MCP Resource"),
@@ -439,17 +511,17 @@ export default function mcpExtension(pi: ExtensionAPI) {
 				server: Type.String({ description: "Server name that owns the resource" }),
 				uri: Type.String({ description: "Resource uri" }),
 			}),
-			async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+			async execute(toolCallId, params, signal, _onUpdate, ctx) {
 				const connection = connections.get(params.server);
 				if (!connection) return unknownServerError(params.server);
 				try {
-					const result = await readResource(connection, params.uri);
-					const text = describeResourceContents(result.contents as McpResourceContents[] | undefined);
+					const result = await readResource(connection, params.uri, signal);
+					const text = describeResourceContents(result.contents as McpResourceContents[] | undefined) || JSON.stringify({ contents: result.contents ?? [] });
 					return {
 						content: [
 							{
 								type: "text",
-								text: text ? persistIfLarge(text, { dir: resultsDir(ctx), id: toolCallId }) : "(empty resource)",
+								text: persistIfLarge(text, { dir: resultsDir(ctx), id: toolCallId }),
 							},
 						],
 						details: { server: params.server, uri: params.uri },
@@ -464,7 +536,7 @@ export default function mcpExtension(pi: ExtensionAPI) {
 			},
 		});
 
-		pi.registerTool({
+		registerResourceTool({
 			name: "read_mcp_resource_dir",
 			label: "List MCP Resource Directory",
 			...ccToolRenderers("List MCP Resource Directory"),
@@ -474,18 +546,18 @@ export default function mcpExtension(pi: ExtensionAPI) {
 				server: Type.String({ description: "Server name that owns the directory" }),
 				uri: Type.String({ description: "The directory resource uri to list" }),
 			}),
-			async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+			async execute(toolCallId, params, signal, _onUpdate, ctx) {
 				const connection = connections.get(params.server);
 				if (!connection) return unknownServerError(params.server);
 				try {
-					const result = await readResourceDir(connection, params.uri);
+					const result = await readResourceDir(connection, params.uri, signal);
 					const entries = (result.resources ?? result.entries ?? []) as Array<{ uri?: string; name?: string; mimeType?: string }>;
 					const lines = entries.map((e) => `${e.uri ?? "(no uri)"}${e.name ? ` — ${e.name}` : ""}${e.mimeType ? ` (${e.mimeType})` : ""}`);
 					return {
 						content: [
 							{
 								type: "text",
-								text: lines.length ? persistIfLarge(lines.join("\n"), { dir: resultsDir(ctx), id: toolCallId }) : "(empty directory)",
+								text: lines.length ? persistIfLarge(lines.join("\n"), { dir: resultsDir(ctx), id: toolCallId }) : 'Directory is empty.\n{"resources":[]}',
 							},
 						],
 						details: { server: params.server, uri: params.uri },
@@ -503,13 +575,10 @@ export default function mcpExtension(pi: ExtensionAPI) {
 		for (const name of ["list_mcp_resources", "read_mcp_resource", "read_mcp_resource_dir"]) {
 			pi.events.emit(DEFER_CHANNEL, { name, keywords: ["mcp", "resource", "document", "uri", "directory"] });
 		}
+		pi.events.emit(MCP_TOOLS_CHANNEL, { tools: [...sharedTools] });
 	};
 
 	pi.on("session_start", async (_event, ctx) => {
-		// A new session (/clear, resume in a new process) has no cached prefix yet:
-		// its message-1 blocks are written fresh (same reset as tool-search).
-		requestSent = false;
-		announced = emptyAnnounced();
 		// pi awaits session_start handlers serially before the prompt opens, and
 		// remote servers take seconds to answer — awaiting here was the entire
 		// "slow startup" (4.9s → 0.24s measured, findings §15). In the interactive
@@ -524,6 +593,9 @@ export default function mcpExtension(pi: ExtensionAPI) {
 			// `failures`, so this only catches setup bugs — surface them loud.
 			if (ctx.hasUI) ctx.ui.notify(`MCP startup failed: ${(error as Error).message}`, "error");
 		});
+		// The external-includes question follows the startup hooks/MCP consent,
+		// but does not wait for slow server connections.
+		startupConsentReady(pi.events);
 		connecting.finally(() => {
 			connectSettled = true;
 			// The session may be gone by now (/clear while a remote server was still
@@ -600,12 +672,18 @@ export default function mcpExtension(pi: ExtensionAPI) {
 		if (pluginConfigPaths.has(server.source)) {
 			return { rank: 3, group: "Plugin MCPs", configLocation: "Plugin configuration", scope: "project" };
 		}
-		if (server.source === join(home, ".claude.json")) {
+		if (server.source === claudeJsonPath(home) || server.piOrigin === "user") {
 			return { rank: 0, group: `User MCPs (${shorten(server.source)})`, configLocation: shorten(server.source), scope: "user" };
 		}
 		if (server.source.endsWith(join(".claude", "settings.local.json"))) {
 			return { rank: 2, group: "Project MCPs (.claude/settings.local.json)", configLocation: shorten(server.source), scope: "project" };
 		}
+		if (server.piOrigin === "extension") {
+			return { rank: 3, group: "Extension MCPs", configLocation: shorten(server.source), scope: "user" };
+		}
+		if (server.piOrigin === "project") {
+			return { rank: 1, group: `Project MCPs (${join(CONFIG_DIR_NAME, "mcp.json")})`, configLocation: shorten(server.source), scope: "project" };
+		}
 		return { rank: 1, group: `Project MCPs (${shorten(server.source)})`, configLocation: shorten(server.source), scope: "project" };
 	};
 
@@ -626,7 +704,7 @@ export default function mcpExtension(pi: ExtensionAPI) {
 				// honestly from whether tokens are stored — not just "failed http".
 				const authState =
 					status === "failed" && server.kind === "http"
-						? hasStoredTokens(server.name)
+						? hasStoredTokens(server)
 							? ("authenticated" as const)
 							: ("notAuthenticated" as const)
 						: undefined;
@@ -656,7 +734,7 @@ export default function mcpExtension(pi: ExtensionAPI) {
 	const MCP_PANEL_MAX_HEIGHT = 22;
 
 	const openMcpPanel = async (ctx: ExtensionContext): Promise<void> => {
-		await ctx.ui.custom<null>((tui, theme, _keybindings, done) => {
+		await panelUi(pi.events, ctx.ui).custom<null>((tui, theme, _keybindings, done) => {
 			const paint: McpPaint = { fg: safeThemePaint(theme), bold: safeThemeBold(theme) };
 			const state = initialMcpState();
 			let notices: string[] = [];
@@ -692,7 +770,24 @@ export default function mcpExtension(pi: ExtensionAPI) {
 			const runReconnect = async (entry: McpEntry) => {
 				const server = servers.find((s) => s.name === entry.name);
 				if (!server || busy.has(entry.name)) return;
+				const refusal = reconnectRefusal(server);
+				if (refusal) {
+					notices = [refusal];
+					syncRepaint();
+					return;
+				}
 				busy.add(entry.name);
+				// Reconnect spawns the command again, so a project server needs the
+				// same consent startup asked for (a stored or session approval
+				// passes without a prompt).
+				const consent = await approveMcpServers([server], pluginConfigPaths, ctx.cwd, home, consentDeps(ctx));
+				if (consent.approved.length === 0) {
+					busy.delete(entry.name);
+					if (!alive()) return;
+					notices = [`"${entry.name}" was not approved, so it was not reconnected.`];
+					syncRepaint();
+					return;
+				}
 				notices = [`Reconnecting to "${entry.name}"…`];
 				syncRepaint();
 				const existing = connections.get(entry.name);
@@ -844,16 +939,19 @@ export default function mcpExtension(pi: ExtensionAPI) {
 	};
 
 	registerLocalCommand(pi, "mcp", {
+		reportsResult: true,
 		description: "Manage MCP servers (status, reconnect, authenticate, enable/disable)",
 		handler: async (args, ctx) => {
 			if (servers.length === 0) {
-				ctx.ui.notify("No MCP servers configured. Add them to .mcp.json or ~/.claude.json.", "info");
-				return;
+				const stdout = noMcpServersMessage(claudeSourcesOn());
+				ctx.ui.notify(stdout, "info");
+				return stdout;
 			}
-			if (ctx.hasUI) {
+			if (canShowCustomUi(ctx)) {
 				await openMcpPanel(ctx);
-				return;
+				return "MCP dialog dismissed";
 			}
+			const readOnly = notifyRpcReadOnly(ctx, "/mcp", "reconnect, authenticate, enable or disable servers");
 			// Non-interactive fallback: a flat status listing, with tool/resource
 			// counts and any warning for connected servers.
 			const lines = servers.map((server) => {
@@ -869,6 +967,7 @@ export default function mcpExtension(pi: ExtensionAPI) {
 				return `${status.padEnd(12)} ${server.name}${suffix} (${server.source})`;
 			});
 			ctx.ui.notify(lines.join("\n"), "info");
+			return [readOnly, ...lines].filter(Boolean).join("\n");
 		},
 	});
 }