feat(mcp): server prompts as /mcp__server__name slash commands

Finishes the MCP surface (tools + resources + prompts). Both transports
speak prompts/list + prompts/get; the manager aggregates prompts and,
after connect, each registers as a /mcp__<server>__<name> command that
expands the prompt (positional or key=value args) and submits it. /mcp
lists them.

Author: halfaipg

src/commands/builtins/mcp.ts

@@ -52,6 +52,11 @@ export const mcp: Command = {
 			ctx.emit("Resources (read via read_mcp_resource):");
 			for (const r of resources) ctx.emit(`  ${r.server} :: ${r.descriptor.uri}`);
 		}
+		const prompts = ctx.bundle.mcp.prompts();
+		if (prompts.length > 0) {
+			ctx.emit("Prompts (run as slash commands):");
+			for (const p of prompts) ctx.emit(`  /mcp__${p.server}__${p.descriptor.name}`);
+		}
 		return { handled: true };
 	},
 };

src/commands/mcp-prompt-commands.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { flattenPromptMessages, mcpPromptCommandName, parseArgs } from "./mcp-prompt-commands.js";
+
+describe("mcpPromptCommandName", () => {
+	it("namespaces server + prompt", () => {
+		expect(mcpPromptCommandName("git", "changelog")).toBe("mcp__git__changelog");
+	});
+});
+
+describe("parseArgs", () => {
+	const declared = [{ name: "topic" }, { name: "tone" }];
+
+	it("parses key=value pairs", () => {
+		expect(parseArgs("topic=auth tone=terse", declared)).toEqual({ topic: "auth", tone: "terse" });
+	});
+
+	it("maps positional args, last arg soaks the rest", () => {
+		expect(parseArgs("auth be very terse", declared)).toEqual({ topic: "auth", tone: "be very terse" });
+	});
+
+	it("puts a single arg in the first declared slot", () => {
+		expect(parseArgs("auth", declared)).toEqual({ topic: "auth" });
+	});
+
+	it("falls back to {input} when nothing is declared", () => {
+		expect(parseArgs("whatever they typed", undefined)).toEqual({ input: "whatever they typed" });
+	});
+
+	it("returns {} for empty args", () => {
+		expect(parseArgs("  ", declared)).toEqual({});
+	});
+});
+
+describe("flattenPromptMessages", () => {
+	it("joins user messages plainly and labels other roles", () => {
+		const text = flattenPromptMessages([
+			{ role: "user", content: "do the thing" },
+			{ role: "assistant", content: { type: "text", text: "context" } },
+		]);
+		expect(text).toBe("do the thing\n\n[assistant]\ncontext");
+	});
+
+	it("flattens content-block arrays", () => {
+		const text = flattenPromptMessages([
+			{
+				role: "user",
+				content: [
+					{ type: "text", text: "a" },
+					{ type: "text", text: "b" },
+				],
+			},
+		]);
+		expect(text).toBe("a\nb");
+	});
+
+	it("returns empty for missing messages", () => {
+		expect(flattenPromptMessages(undefined)).toBe("");
+	});
+});

src/commands/mcp-prompt-commands.ts

@@ -0,0 +1,114 @@
+import type { McpManager, McpPromptRef } from "../mcp/manager.js";
+import type { McpContentBlock } from "../mcp/protocol.js";
+import type { CommandRegistry } from "./registry.js";
+import type { Command } from "./types.js";
+
+/** MCP prompt → slash command name: `mcp__<server>__<prompt>`, mirroring tool naming. */
+export function mcpPromptCommandName(server: string, prompt: string): string {
+	return `mcp__${server}__${prompt}`;
+}
+
+const VALID = /^[a-z0-9][a-z0-9_-]*$/i;
+
+/**
+ * Bridge connected MCP prompts into slash commands. `/mcp__<server>__<name>
+ * [args]` calls prompts/get on the server, flattens the returned messages
+ * into a single prompt, and submits it to the agent. Arguments are parsed
+ * positionally against the prompt's declared `arguments`, or as
+ * `key=value` pairs. Names that collide with a built-in or are unsafe for
+ * a command are skipped.
+ */
+export function buildMcpPromptCommands(
+	prompts: readonly McpPromptRef[],
+	mcp: McpManager,
+	registry: CommandRegistry,
+): Command[] {
+	const out: Command[] = [];
+	for (const { server, descriptor } of prompts) {
+		const name = mcpPromptCommandName(server, descriptor.name);
+		if (!VALID.test(name) || registry.get(name)) continue;
+		out.push({
+			name,
+			description: descriptor.description
+				? `${descriptor.description} (MCP prompt)`
+				: `MCP prompt ${descriptor.name}.`,
+			handler: (args, ctx) => {
+				if (ctx.state.status !== "idle" && ctx.state.status !== "error" && ctx.state.status !== "aborted") {
+					ctx.emit(`agent is busy — run /${name} after this turn settles.`);
+					return { handled: true };
+				}
+				const parsed = parseArgs(args, descriptor.arguments);
+				void mcp
+					.getPrompt(server, descriptor.name, parsed)
+					.then((result) => {
+						const text = flattenPromptMessages(result.messages);
+						if (!text.trim()) {
+							ctx.emit(`MCP prompt "${descriptor.name}" returned nothing.`);
+							return;
+						}
+						return ctx.bundle.submitUserPrompt(text).then((r) => {
+							if (!r.submitted) ctx.emit(`prompt blocked: ${r.reason ?? "refused by hook"}`);
+							else if (r.error) ctx.emit(`agent error: ${r.error}`);
+						});
+					})
+					.catch((err) => ctx.emit(`MCP prompt failed: ${err instanceof Error ? err.message : String(err)}`));
+				return { handled: true };
+			},
+		});
+	}
+	return out;
+}
+
+/** Map user args to the prompt's declared arguments — `key=value` pairs first, else positional. */
+export function parseArgs(raw: string, declared: McpPromptRef["descriptor"]["arguments"]): Record<string, string> {
+	const trimmed = raw.trim();
+	if (!trimmed) return {};
+	const tokens = trimmed.split(/\s+/);
+	const names = (declared ?? []).map((a) => a.name);
+
+	// All tokens look like key=value → keyed.
+	if (tokens.every((t) => /^[^=\s]+=/.test(t))) {
+		const out: Record<string, string> = {};
+		for (const t of tokens) {
+			const eq = t.indexOf("=");
+			out[t.slice(0, eq)] = t.slice(eq + 1);
+		}
+		return out;
+	}
+
+	// Positional against declared names; a single undeclared arg → first slot.
+	if (names.length === 0) return { input: trimmed };
+	const out: Record<string, string> = {};
+	names.forEach((n, i) => {
+		if (i < names.length - 1) {
+			if (tokens[i] !== undefined) out[n] = tokens[i];
+		} else {
+			// Last declared arg soaks up the remaining tokens.
+			const rest = tokens.slice(i).join(" ");
+			if (rest) out[n] = rest;
+		}
+	});
+	return out;
+}
+
+/** Flatten prompt messages into a single text prompt; non-user roles are labeled. */
+export function flattenPromptMessages(
+	messages: Array<{ role: string; content: string | McpContentBlock | McpContentBlock[] }> | undefined,
+): string {
+	if (!Array.isArray(messages)) return "";
+	const parts: string[] = [];
+	for (const m of messages) {
+		const text = contentToText(m.content);
+		if (!text) continue;
+		parts.push(m.role === "user" ? text : `[${m.role}]\n${text}`);
+	}
+	return parts.join("\n\n");
+}
+
+function contentToText(content: string | McpContentBlock | McpContentBlock[]): string {
+	if (typeof content === "string") return content;
+	const blocks = Array.isArray(content) ? content : [content];
+	return blocks
+		.map((b) => (b.type === "text" && typeof b.text === "string" ? b.text : `[${b.type} content]`))
+		.join("\n");
+}

src/mcp/__test__/mock-server.mjs

@@ -23,7 +23,7 @@ rl.on("line", (line) => {
 			id: msg.id,
 			result: {
 				protocolVersion: "2025-06-18",
-				capabilities: { tools: {}, resources: {} },
+				capabilities: { tools: {}, resources: {}, prompts: {} },
 				serverInfo: { name: "mock", version: "0" },
 			},
 		});
@@ -80,6 +80,25 @@ rl.on("line", (line) => {
 		});
 		return;
 	}
+	if (msg.method === "prompts/list") {
+		send({
+			jsonrpc: "2.0",
+			id: msg.id,
+			result: {
+				prompts: [{ name: "greet", description: "Greet someone", arguments: [{ name: "who", required: true }] }],
+			},
+		});
+		return;
+	}
+	if (msg.method === "prompts/get") {
+		const who = msg.params?.arguments?.who ?? "world";
+		send({
+			jsonrpc: "2.0",
+			id: msg.id,
+			result: { messages: [{ role: "user", content: { type: "text", text: `Say hello to ${who}.` } }] },
+		});
+		return;
+	}
 	// Unknown method → error response.
 	if (typeof msg.id === "number") {
 		send({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: `unknown method: ${msg.method}` } });

src/mcp/client.ts

@@ -1,4 +1,11 @@
-import type { McpCallToolResult, McpReadResourceResult, McpResourceDescriptor, McpToolDescriptor } from "./protocol.js";
+import type {
+	McpCallToolResult,
+	McpGetPromptResult,
+	McpPromptDescriptor,
+	McpReadResourceResult,
+	McpResourceDescriptor,
+	McpToolDescriptor,
+} from "./protocol.js";
 
 /** What every MCP client speaks to, regardless of transport (stdio | http). */
 export const CLIENT_INFO = { name: "codebase-cli", version: "1" } as const;
@@ -23,6 +30,10 @@ export interface McpClient {
 	listResources(): Promise<McpResourceDescriptor[]>;
 	/** Read one resource by URI. */
 	readResource(uri: string): Promise<McpReadResourceResult>;
+	/** List the server's prompts. Returns [] when the server has no prompts capability. */
+	listPrompts(): Promise<McpPromptDescriptor[]>;
+	/** Expand a prompt by name with arguments. */
+	getPrompt(name: string, args: Record<string, string>): Promise<McpGetPromptResult>;
 	/** Tear down the transport and reject any in-flight requests. */
 	close(): void;
 }

src/mcp/http-client.ts

@@ -5,6 +5,8 @@ import {
 	type JsonRpcResponse,
 	MCP_PROTOCOL_VERSION,
 	type McpCallToolResult,
+	type McpGetPromptResult,
+	type McpPromptDescriptor,
 	type McpReadResourceResult,
 	type McpResourceDescriptor,
 	type McpToolDescriptor,
@@ -84,6 +86,21 @@ export class HttpMcpClient implements McpClient {
 		return (res.result as McpReadResourceResult) ?? {};
 	}
 
+	async listPrompts(): Promise<McpPromptDescriptor[]> {
+		try {
+			const res = await this.request("prompts/list", {});
+			const result = res.result as { prompts?: McpPromptDescriptor[] } | undefined;
+			return Array.isArray(result?.prompts) ? result.prompts : [];
+		} catch {
+			return [];
+		}
+	}
+
+	async getPrompt(name: string, args: Record<string, string>): Promise<McpGetPromptResult> {
+		const res = await this.request("prompts/get", { name, arguments: args });
+		return (res.result as McpGetPromptResult) ?? {};
+	}
+
 	close(): void {
 		if (this.closed) return;
 		this.closed = true;

src/mcp/manager.test.ts

@@ -93,6 +93,19 @@ describe("McpManager (against the mock server)", () => {
 		expect(read.contents?.[0]).toMatchObject({ text: "hello from mock" });
 	});
 
+	it("aggregates prompts and expands one with arguments", async () => {
+		writeConfig({ demo: { command: process.execPath, args: [MOCK] } });
+		manager = new McpManager();
+		await manager.connectAll({ home, cwd });
+
+		const prompts = manager.prompts();
+		expect(prompts).toHaveLength(1);
+		expect(prompts[0]).toMatchObject({ server: "demo", descriptor: { name: "greet" } });
+
+		const got = await manager.getPrompt("demo", "greet", { who: "Ada" });
+		expect(got.messages?.[0]).toMatchObject({ role: "user", content: { text: "Say hello to Ada." } });
+	});
+
 	it("connects a remote (url) server over HTTP and bridges its tools", async () => {
 		const server = await startHttpMock();
 		try {

src/mcp/manager.ts

@@ -5,7 +5,12 @@ import { HttpMcpClient } from "./http-client.js";
 import type { AuthorizeDeps } from "./oauth/flow.js";
 import { McpOAuthProvider } from "./oauth/provider.js";
 import { McpOAuthStore } from "./oauth/store.js";
-import type { McpReadResourceResult, McpResourceDescriptor } from "./protocol.js";
+import type {
+	McpGetPromptResult,
+	McpPromptDescriptor,
+	McpReadResourceResult,
+	McpResourceDescriptor,
+} from "./protocol.js";
 import { StdioMcpClient } from "./stdio-client.js";
 import { mcpToAgentTool } from "./to-agent-tool.js";
 
@@ -22,6 +27,12 @@ export interface McpResourceRef {
 	descriptor: McpResourceDescriptor;
 }
 
+/** A prompt plus the server that exposes it. */
+export interface McpPromptRef {
+	server: string;
+	descriptor: McpPromptDescriptor;
+}
+
 export interface McpManagerOptions {
 	/** Persisted OAuth sessions for remote servers. Defaults to ~/.codebase/mcp-credentials.json. */
 	oauthStore?: McpOAuthStore;
@@ -45,6 +56,7 @@ export class McpManager {
 	private readonly statuses: McpServerStatus[] = [];
 	private readonly toolList: AgentTool<any>[] = [];
 	private readonly resourceList: McpResourceRef[] = [];
+	private readonly promptList: McpPromptRef[] = [];
 	private readonly oauthStore: McpOAuthStore;
 	private readonly authDeps: AuthorizeDeps;
 
@@ -72,10 +84,12 @@ export class McpManager {
 					for (const desc of descriptors) {
 						this.toolList.push(mcpToAgentTool(name, client, desc));
 					}
-					// Resources are best-effort — a server without the capability
-					// returns [], and a failure here never blocks its tools.
+					// Resources + prompts are best-effort — a server without the
+					// capability returns [], and a failure never blocks its tools.
 					const resources = await client.listResources().catch(() => []);
 					for (const r of resources) this.resourceList.push({ server: name, descriptor: r });
+					const prompts = await client.listPrompts().catch(() => []);
+					for (const p of prompts) this.promptList.push({ server: name, descriptor: p });
 					this.statuses.push({ name, connected: true, toolCount: descriptors.length });
 				} catch (err) {
 					client.close();
@@ -112,6 +126,18 @@ export class McpManager {
 		return client.readResource(uri);
 	}
 
+	/** Every prompt discovered across connected servers. */
+	prompts(): readonly McpPromptRef[] {
+		return this.promptList;
+	}
+
+	/** Expand a prompt by server + name with arguments. Throws if the server isn't connected. */
+	async getPrompt(server: string, name: string, args: Record<string, string>): Promise<McpGetPromptResult> {
+		const client = this.clientsByName.get(server);
+		if (!client) throw new Error(`MCP server "${server}" is not connected`);
+		return client.getPrompt(name, args);
+	}
+
 	/** Terminate every server connection. Idempotent. */
 	dispose(): void {
 		for (const client of this.clients) client.close();

src/mcp/protocol.ts

@@ -75,6 +75,25 @@ export interface McpReadResourceResult {
 	[key: string]: unknown;
 }
 
+/** A prompt as described by a server's prompts/list response. */
+export interface McpPromptDescriptor {
+	name: string;
+	description?: string;
+	arguments?: Array<{ name: string; description?: string; required?: boolean }>;
+}
+
+/** One message of a prompts/get result. Content is text or a content-block array. */
+export interface McpPromptMessage {
+	role: string;
+	content: string | McpContentBlock | McpContentBlock[];
+}
+
+export interface McpGetPromptResult {
+	description?: string;
+	messages?: McpPromptMessage[];
+	[key: string]: unknown;
+}
+
 /** Parse one line of stdio output into a JSON-RPC message, or null if unparseable. */
 export function parseRpcLine(line: string): JsonRpcResponse | JsonRpcNotification | null {
 	const trimmed = line.trim();