diffing 0.4.1 → 0.5.1

package/dist/mcp-CFxcdEcJ.mjs

@@ -0,0 +1,733 @@
+import { o as parseDiffOptions, t as startServer } from "./server-CYSpLbdA.mjs";
+import { a as writeServerLock, n as isLockAlive, o as formatComments, r as readServerLock, t as diffScopeKey } from "./server-lock-Ddcat0HF.mjs";
+import { n as formatPlanReview } from "./plan-format-B6nbAw_c.mjs";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+//#region src/mcp.ts
+const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+function readPackageVersion() {
+	const packagePath = resolve(moduleDirectory, "..", "package.json");
+	const pkg = JSON.parse(readFileSync(packagePath, "utf-8"));
+	if (typeof pkg.version !== "string" || !pkg.version) throw new Error(`Invalid package version in ${packagePath}`);
+	return pkg.version;
+}
+const MCP_VERSION = readPackageVersion();
+const READ_ONLY = {
+	readOnlyHint: true,
+	destructiveHint: false,
+	idempotentHint: true,
+	openWorldHint: false
+};
+const MUTATING = {
+	readOnlyHint: false,
+	destructiveHint: false,
+	idempotentHint: false,
+	openWorldHint: false
+};
+const IDEMPOTENT_MUTATION = {
+	...MUTATING,
+	idempotentHint: true
+};
+const commentSchema = z.object({
+	id: z.string(),
+	filePath: z.string(),
+	side: z.enum(["deletions", "additions"]),
+	lineNumber: z.number(),
+	startLineNumber: z.number().optional(),
+	lineContent: z.string(),
+	body: z.string(),
+	status: z.enum(["open", "resolved"]),
+	createdAt: z.number(),
+	replies: z.array(z.object({
+		id: z.string(),
+		body: z.string(),
+		createdAt: z.number(),
+		role: z.enum(["user", "agent"]).optional(),
+		model: z.string().optional(),
+		createdAtPlanVersion: z.number().optional()
+	}))
+});
+function textResult(text, structuredContent) {
+	return {
+		content: [{
+			type: "text",
+			text
+		}],
+		structuredContent
+	};
+}
+/** Resolve and validate an immutable repository binding without invoking a shell. */
+function resolveMcpRepository(repoPath = process.cwd(), explicit = false) {
+	if (explicit && !isAbsolute(repoPath)) throw new Error("diffing mcp: --repo must be an absolute path");
+	let candidate;
+	try {
+		candidate = realpathSync(repoPath);
+		if (!statSync(candidate).isDirectory()) throw new Error("not a directory");
+	} catch {
+		throw new Error(`diffing mcp: repository path is not an accessible directory: ${repoPath}`);
+	}
+	try {
+		return execFileSync("git", [
+			"-C",
+			candidate,
+			"rev-parse",
+			"--show-toplevel"
+		], {
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		}).trim();
+	} catch {
+		throw new Error(`diffing mcp: path is not inside a Git repository: ${candidate}`);
+	}
+}
+function publicHost(host) {
+	return host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+}
+function lockUrl(lock) {
+	if ((lock.mode ?? "web") === "tui" || lock.port <= 0) return null;
+	return `http://${publicHost(lock.host)}:${lock.port}`;
+}
+async function requestJson(base, path, init) {
+	let response;
+	try {
+		response = await fetch(`${base}${path}`, init);
+	} catch (error) {
+		if (error instanceof Error && error.name === "AbortError") throw new Error(`Request to ${path} was cancelled. Retry the MCP tool when ready.`);
+		const detail = error instanceof Error ? error.message : String(error);
+		throw new Error(`Cannot reach the diffing review server at ${base}: ${detail}. Call review_session_status, then start_review_session if needed.`);
+	}
+	const raw = await response.text();
+	if (!response.ok) {
+		let detail = raw.trim();
+		try {
+			const parsed = JSON.parse(raw);
+			if (typeof parsed.error === "string") detail = parsed.error;
+		} catch {}
+		throw new Error(`diffing server rejected ${init?.method ?? "GET"} ${path} with HTTP ${response.status}` + (detail ? `: ${detail}` : "") + ".");
+	}
+	try {
+		return JSON.parse(raw);
+	} catch {
+		throw new Error(`diffing server returned malformed JSON for ${path}. Check that client and server versions match.`);
+	}
+}
+function sameScope(lock, requestedScope, requestedArgs) {
+	if (lock.scope) return lock.scope === requestedScope;
+	return requestedArgs.length === 0;
+}
+function createMcpServer(options) {
+	const repoRoot = resolveMcpRepository(options.repoRoot, true);
+	const startServerFn = options.startServerFn ?? startServer;
+	const now = options.now ?? Date.now;
+	const readLock = options.readLock ?? readServerLock;
+	const writeLock = options.writeLock ?? writeServerLock;
+	const lockIsAlive = options.lockIsAlive ?? isLockAlive;
+	const defaultClientDir = existsSync(resolve(moduleDirectory, "client")) ? resolve(moduleDirectory, "client") : resolve(repoRoot, "dist/client");
+	const clientDir = options.clientDir ?? defaultClientDir;
+	const instructions = `diffing is bound to ${repoRoot} for this connection. First call review_session_status. If no web session is running, call start_review_session; it is safe to retry and never replaces a user session. For code review, call get_diff, create_comment as needed, then await_review for the human handoff. For plan review, call submit_plan then await_plan_review. A changes-requested verdict means revise and resubmit the same planId; rejected means stop; approved means proceed. Wait tools return released or timeout with a mode; timeout is not failure and the same wait tool may be called again. All networking remains local.`;
+	const server = new McpServer({
+		name: "diffing",
+		version: MCP_VERSION
+	}, { instructions });
+	function liveLock() {
+		const lock = readLock(repoRoot);
+		return lock && lockIsAlive(lock, repoRoot) ? lock : null;
+	}
+	function requireBaseUrl() {
+		const lock = liveLock();
+		if (!lock) throw new Error(`No diffing web review session is running for ${repoRoot}. Call start_review_session, then retry this tool.`);
+		const url = lockUrl(lock);
+		if (!url) throw new Error("The active diffing session is TUI-only. Start a web review session before using MCP review tools.");
+		return url;
+	}
+	function sessionStatus() {
+		const lock = liveLock();
+		if (!lock) return {
+			repository: repoRoot,
+			serverState: "not-running",
+			mode: "none",
+			url: null,
+			managedBy: null,
+			diffArgs: [],
+			nextAction: "Call start_review_session, then get_diff."
+		};
+		const mode = lock.mode ?? "web";
+		return {
+			repository: repoRoot,
+			serverState: "running",
+			mode,
+			url: lockUrl(lock),
+			managedBy: lock.owner === "mcp" ? "mcp" : "user",
+			diffArgs: lock.diffArgs ?? [],
+			nextAction: mode === "tui" ? "A TUI session cannot serve MCP tools; stop it manually and call start_review_session." : mode === "gh-pr" ? "This is a GitHub PR session; use the GitHub review workflow or start a local session after it ends." : "Call get_diff to inspect changes, or use a plan-review tool."
+		};
+	}
+	server.registerTool("review_session_status", {
+		title: "Get review session status",
+		description: "Inspect the repository binding and active diffing session. Works when no web server is running; use its nextAction before other tools.",
+		inputSchema: {},
+		outputSchema: {
+			repository: z.string(),
+			serverState: z.enum(["running", "not-running"]),
+			mode: z.enum([
+				"none",
+				"web",
+				"gh-pr",
+				"tui"
+			]),
+			url: z.string().nullable(),
+			managedBy: z.enum(["mcp", "user"]).nullable(),
+			diffArgs: z.array(z.string()),
+			nextAction: z.string()
+		},
+		annotations: READ_ONLY
+	}, async () => {
+		const status = sessionStatus();
+		return textResult(status.serverState === "running" ? `diffing ${status.mode} session is running for ${repoRoot}${status.url ? ` at ${status.url}` : ""}. ${status.nextAction}` : `No diffing web session is running for ${repoRoot}. ${status.nextAction}`, { ...status });
+	});
+	let startingSession = null;
+	server.registerTool("start_review_session", {
+		title: "Start or reuse a local review session",
+		description: "Idempotently reuse a matching web review session or start a headless loopback-only session on an OS-selected port. diffArgs are passed directly to diff parsing, never to a shell. A live incompatible user session is reported, never stopped.",
+		inputSchema: { diffArgs: z.array(z.string()).optional().describe("Optional git-diff arguments, for example [\"--staged\"] or [\"main...HEAD\", \"--\", \"src/\"].") },
+		outputSchema: {
+			status: z.enum(["started", "reused"]),
+			repository: z.string(),
+			url: z.string(),
+			mode: z.literal("web"),
+			managedBy: z.enum(["mcp", "user"]),
+			diffArgs: z.array(z.string()),
+			nextAction: z.string()
+		},
+		annotations: IDEMPOTENT_MUTATION
+	}, async ({ diffArgs = [] }) => {
+		if (startingSession) {
+			const result = await startingSession;
+			return textResult(`Review session ready at ${result.url}.`, result);
+		}
+		startingSession = (async () => {
+			const parsed = parseDiffOptions(diffArgs);
+			if (parsed.help || parsed.version || parsed.tui || diffArgs.includes("--terminal")) throw new Error("start_review_session accepts git-diff scope arguments, not CLI help/version/terminal/TUI flags.");
+			parsed.outputMode = "web";
+			parsed.host = "127.0.0.1";
+			parsed.port = void 0;
+			parsed.noOpen = true;
+			const requestedScope = diffScopeKey(parsed);
+			const existing = liveLock();
+			if (existing) {
+				const mode = existing.mode ?? "web";
+				if (mode !== "web") throw new Error(`A live ${mode} diffing session already owns this repository. diffing will not replace or stop it; end that session manually before starting a local web review.`);
+				if (!sameScope(existing, requestedScope, diffArgs)) throw new Error(`A live diffing web session already shows a different diff scope. Requested arguments: ${JSON.stringify(diffArgs)}. Use the existing session or end it manually; diffing will not replace it.`);
+				const url = lockUrl(existing);
+				if (!url) throw new Error("The active diffing web session has no usable URL.");
+				return {
+					status: "reused",
+					repository: repoRoot,
+					url,
+					mode: "web",
+					managedBy: existing.owner === "mcp" ? "mcp" : "user",
+					diffArgs: existing.diffArgs ?? diffArgs,
+					nextAction: "Call get_diff to inspect the active diff."
+				};
+			}
+			const lock = {
+				port: (await startServerFn({
+					port: 0,
+					host: "127.0.0.1",
+					clientDir,
+					diffOpts: parsed
+				})).port,
+				host: "127.0.0.1",
+				pid: process.pid,
+				repoRoot,
+				startedAt: now(),
+				version: MCP_VERSION,
+				mode: "web",
+				scope: requestedScope,
+				diffArgs: [...diffArgs],
+				owner: "mcp"
+			};
+			writeLock(lock);
+			return {
+				status: "started",
+				repository: repoRoot,
+				url: lockUrl(lock),
+				mode: "web",
+				managedBy: "mcp",
+				diffArgs: [...diffArgs],
+				nextAction: "Call get_diff to inspect the active diff."
+			};
+		})();
+		try {
+			const result = await startingSession;
+			return textResult(`${result.status === "started" ? "Started" : "Reused"} review session at ${result.url}.`, result);
+		} finally {
+			startingSession = null;
+		}
+	});
+	server.registerTool("get_diff", {
+		title: "Get the active local diff",
+		description: "Fetch the complete patch and basic repository metadata from the active local web review. Start or locate the session first.",
+		inputSchema: {},
+		outputSchema: {
+			patch: z.string(),
+			repoName: z.string(),
+			branch: z.string(),
+			customMode: z.boolean(),
+			truncated: z.boolean().optional()
+		},
+		annotations: READ_ONLY
+	}, async () => {
+		const diff = await requestJson(requireBaseUrl(), "/api/diff");
+		const structured = {
+			patch: diff.patch,
+			repoName: diff.repoName,
+			branch: diff.branch,
+			customMode: diff.customMode,
+			...typeof diff.truncated === "boolean" ? { truncated: diff.truncated } : {}
+		};
+		return textResult(diff.patch || "(The active diff is empty.)", structured);
+	});
+	server.registerTool("create_comment", {
+		title: "Create an inline review comment",
+		description: "Create a local inline comment on an exact line from get_diff. side is additions for +/context in the new file and deletions for a removed line.",
+		inputSchema: {
+			filePath: z.string().min(1).describe("Repository-relative file path exactly as shown in the patch."),
+			side: z.enum(["deletions", "additions"]).describe("Which side of the patch contains the target line."),
+			lineNumber: z.number().int().positive().describe("Target line number on the selected side."),
+			startLineNumber: z.number().int().positive().optional().describe("Optional first line for a multiline comment."),
+			lineContent: z.string().describe("Target line text, used to preserve context in the review UI."),
+			body: z.string().min(1).describe("Actionable review comment in Markdown.")
+		},
+		outputSchema: {
+			status: z.literal("created"),
+			comment: commentSchema
+		},
+		annotations: MUTATING
+	}, async (input) => {
+		const comment = await requestJson(requireBaseUrl(), "/api/comments", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(input)
+		});
+		return textResult(`Created inline comment ${comment.id} on ${comment.filePath}:${comment.lineNumber}.`, {
+			status: "created",
+			comment
+		});
+	});
+	server.registerTool("await_review", {
+		title: "Wait for code review handoff",
+		description: "Wait for the human to send a code-review round. Returns status=released or status=timeout and always includes mode. Timeout is expected and safe to retry; progress notifications are sent between long polls.",
+		inputSchema: { timeoutSeconds: z.number().positive().max(3600).optional().describe("Total wait budget in seconds; defaults to 570.") },
+		outputSchema: {
+			status: z.enum(["released", "timeout"]),
+			mode: z.enum(["standard", "comment-only"]),
+			round: z.number(),
+			openCount: z.number().optional(),
+			decision: z.enum([
+				"approved",
+				"changes-requested",
+				"rejected",
+				"comment-only"
+			]).optional(),
+			comments: z.array(commentSchema).optional(),
+			nextAction: z.string()
+		},
+		annotations: READ_ONLY
+	}, async ({ timeoutSeconds }, extra) => {
+		const base = requireBaseUrl();
+		const budgetMs = (timeoutSeconds ?? 570) * 1e3;
+		const progressToken = extra?._meta?.progressToken;
+		let sinceRound = (await requestJson(base, "/api/review/status", { signal: extra?.signal })).round ?? 0;
+		const deadline = Date.now() + budgetMs;
+		let cycle = 0;
+		while (Date.now() < deadline) {
+			const remaining = Math.max(1, deadline - Date.now());
+			const result = await requestJson(base, `/api/review/await?timeoutMs=${Math.min(25e3, remaining)}&sinceRound=${sinceRound}`, { signal: extra?.signal });
+			if (result.status === "released") {
+				const payload = result.payload;
+				const structured = {
+					status: "released",
+					mode: payload.mode ?? "standard",
+					round: payload.round,
+					openCount: payload.openCount,
+					...payload.decision ? { decision: payload.decision } : {},
+					comments: payload.comments,
+					nextAction: payload.mode === "comment-only" ? "Reply to comments without editing files; resolve only comments the human considers addressed." : "Address open comments, reply with evidence, and resolve completed threads."
+				};
+				return textResult(payload.commentXml, structured);
+			}
+			sinceRound = result.round ?? sinceRound;
+			cycle += 1;
+			if (progressToken !== void 0) await extra.sendNotification({
+				method: "notifications/progress",
+				params: {
+					progressToken,
+					progress: cycle,
+					total: Math.max(cycle, Math.ceil(budgetMs / 25e3)),
+					message: "Still waiting for a code-review handoff; long poll completed and will retry."
+				}
+			}).catch(() => {});
+		}
+		const structured = {
+			status: "timeout",
+			mode: "standard",
+			round: sinceRound,
+			nextAction: "No review was sent within the wait budget. Call await_review again to keep waiting."
+		};
+		return textResult(structured.nextAction, structured);
+	});
+	server.registerTool("list_comments", {
+		title: "List code review comments",
+		description: "Fetch code-review comments as XML plus structured data. Use openOnly=true when addressing the current review round.",
+		inputSchema: { openOnly: z.boolean().optional().describe("Return only unresolved comments when true.") },
+		outputSchema: { comments: z.array(commentSchema) },
+		annotations: READ_ONLY
+	}, async ({ openOnly }) => {
+		const all = await requestJson(requireBaseUrl(), "/api/comments");
+		const comments = openOnly ? all.filter((comment) => comment.status === "open") : all;
+		return textResult(formatComments(comments), { comments });
+	});
+	server.registerTool("reply_to_comment", {
+		title: "Reply to a code review comment",
+		description: "Post an agent reply to an existing code-review thread. Include concise evidence of the answer or applied change.",
+		inputSchema: {
+			commentId: z.string().min(1).describe("Comment id from list_comments or await_review."),
+			body: z.string().min(1).describe("Reply body in Markdown."),
+			model: z.string().optional().describe("Optional agent/model identifier shown in the UI.")
+		},
+		outputSchema: {
+			status: z.literal("replied"),
+			commentId: z.string()
+		},
+		annotations: MUTATING
+	}, async ({ commentId, body, model }) => {
+		await requestJson(requireBaseUrl(), `/api/comments/${encodeURIComponent(commentId)}/replies`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				body,
+				role: "agent",
+				model
+			})
+		});
+		return textResult(`Replied to ${commentId}.`, {
+			status: "replied",
+			commentId
+		});
+	});
+	server.registerTool("resolve_comment", {
+		title: "Resolve a code review comment",
+		description: "Mark a code-review thread resolved after its request is fully addressed. Safe to retry.",
+		inputSchema: { commentId: z.string().min(1).describe("Comment id to resolve.") },
+		outputSchema: {
+			status: z.literal("resolved"),
+			commentId: z.string()
+		},
+		annotations: IDEMPOTENT_MUTATION
+	}, async ({ commentId }) => {
+		await requestJson(requireBaseUrl(), `/api/comments/${encodeURIComponent(commentId)}`, {
+			method: "PUT",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ status: "resolved" })
+		});
+		return textResult(`Resolved ${commentId}.`, {
+			status: "resolved",
+			commentId
+		});
+	});
+	server.registerTool("submit_plan", {
+		title: "Submit or resubmit a plan",
+		description: "Submit Markdown for human plan review. To revise after changes-requested, pass the same planId so a new version is created.",
+		inputSchema: {
+			title: z.string().optional().describe("Human-readable plan title."),
+			body: z.string().min(1).describe("Complete Markdown plan body."),
+			source: z.string().optional().describe("Optional source filename or workflow label."),
+			model: z.string().optional().describe("Optional agent/model identifier."),
+			planId: z.string().optional().describe("Existing plan id when resubmitting a revised version.")
+		},
+		outputSchema: {
+			status: z.literal("submitted"),
+			planId: z.string(),
+			version: z.number(),
+			url: z.string()
+		},
+		annotations: MUTATING
+	}, async ({ title, body, source, model, planId }) => {
+		const base = requireBaseUrl();
+		const plan = await requestJson(base, "/api/plans", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				id: planId,
+				title,
+				body,
+				source,
+				model
+			})
+		});
+		const url = `${base}/plan/${plan.id}`;
+		return textResult(`Submitted plan ${plan.id} (v${plan.version}) at ${url}. Call await_plan_review.`, {
+			status: "submitted",
+			planId: plan.id,
+			version: plan.version,
+			url
+		});
+	});
+	server.registerTool("await_plan_review", {
+		title: "Wait for plan review verdict",
+		description: "Wait for a plan verdict. Returns status=released or status=timeout and always includes mode. Timeout is expected and safe to retry; progress notifications are sent between long polls.",
+		inputSchema: { timeoutSeconds: z.number().positive().max(3600).optional().describe("Total wait budget in seconds; defaults to 570.") },
+		outputSchema: {
+			status: z.enum(["released", "timeout"]),
+			mode: z.enum(["standard", "comment-only"]),
+			round: z.number(),
+			planId: z.string().optional(),
+			decision: z.enum([
+				"pending",
+				"approved",
+				"changes-requested",
+				"rejected"
+			]).optional(),
+			decisionComment: z.string().optional(),
+			openCommentCount: z.number().optional(),
+			plan: z.unknown().optional(),
+			nextAction: z.string()
+		},
+		annotations: READ_ONLY
+	}, async ({ timeoutSeconds }, extra) => {
+		const base = requireBaseUrl();
+		const budgetMs = (timeoutSeconds ?? 570) * 1e3;
+		const progressToken = extra?._meta?.progressToken;
+		let sinceRound = (await requestJson(base, "/api/plan-review/status", { signal: extra?.signal })).round ?? 0;
+		const deadline = Date.now() + budgetMs;
+		let cycle = 0;
+		while (Date.now() < deadline) {
+			const remaining = Math.max(1, deadline - Date.now());
+			const result = await requestJson(base, `/api/plan-review/await?timeoutMs=${Math.min(25e3, remaining)}&sinceRound=${sinceRound}`, { signal: extra?.signal });
+			if (result.status === "released") {
+				const payload = result.payload;
+				const nextAction = payload.mode === "comment-only" ? "Reply to plan comments without changing implementation files." : payload.decision === "approved" ? "Proceed with the approved plan." : payload.decision === "changes-requested" ? "Revise the plan and call submit_plan with the same planId." : "Stop; the plan was rejected.";
+				const structured = {
+					status: "released",
+					mode: payload.mode ?? "standard",
+					round: payload.round,
+					planId: payload.planId,
+					decision: payload.decision,
+					...payload.decisionComment ? { decisionComment: payload.decisionComment } : {},
+					openCommentCount: payload.openCommentCount,
+					plan: payload.plan,
+					nextAction
+				};
+				return textResult(payload.reviewXml, structured);
+			}
+			sinceRound = result.round ?? sinceRound;
+			cycle += 1;
+			if (progressToken !== void 0) await extra.sendNotification({
+				method: "notifications/progress",
+				params: {
+					progressToken,
+					progress: cycle,
+					total: Math.max(cycle, Math.ceil(budgetMs / 25e3)),
+					message: "Still waiting for a plan verdict; long poll completed and will retry."
+				}
+			}).catch(() => {});
+		}
+		const structured = {
+			status: "timeout",
+			mode: "standard",
+			round: sinceRound,
+			nextAction: "No plan verdict arrived within the wait budget. Call await_plan_review again to keep waiting."
+		};
+		return textResult(structured.nextAction, structured);
+	});
+	server.registerTool("list_plans", {
+		title: "List submitted plans",
+		description: "List every submitted plan with its current verdict, version, and inline comments.",
+		inputSchema: {},
+		outputSchema: { plans: z.array(z.unknown()) },
+		annotations: READ_ONLY
+	}, async () => {
+		const plans = await requestJson(requireBaseUrl(), "/api/plans");
+		return textResult(plans.map((plan) => {
+			const open = (plan.comments ?? []).filter((comment) => comment.status === "open").length;
+			return `${plan.id} [${plan.decision}] v${plan.version} — ${open} open comment(s) — ${plan.title}`;
+		}).join("\n") || "No plans submitted yet.", { plans });
+	});
+	server.registerTool("get_plan", {
+		title: "Get a plan",
+		description: "Fetch one current plan as plan-review XML and structured data, including verdict and inline comments.",
+		inputSchema: { planId: z.string().min(1).describe("Plan id from submit_plan or list_plans.") },
+		outputSchema: { plan: z.unknown() },
+		annotations: READ_ONLY
+	}, async ({ planId }) => {
+		const plan = await requestJson(requireBaseUrl(), `/api/plans/${encodeURIComponent(planId)}`);
+		return textResult(formatPlanReview(plan), { plan });
+	});
+	server.registerTool("get_plan_versions", {
+		title: "List plan versions",
+		description: "List all submitted versions of a plan, oldest first.",
+		inputSchema: { planId: z.string().min(1).describe("Plan id to inspect.") },
+		outputSchema: { versions: z.array(z.unknown()) },
+		annotations: READ_ONLY
+	}, async ({ planId }) => {
+		const versions = await requestJson(requireBaseUrl(), `/api/plans/${encodeURIComponent(planId)}/versions`);
+		return textResult(versions.map((version) => {
+			const date = new Date(version.createdAt).toISOString().slice(0, 16).replace("T", " ");
+			return `v${version.version} — ${date} — ${version.title}`;
+		}).join("\n") || "No versions recorded.", { versions });
+	});
+	server.registerTool("get_plan_version", {
+		title: "Get a plan version",
+		description: "Fetch the current or a historical plan version as plan-review XML with version-anchored comments.",
+		inputSchema: {
+			planId: z.string().min(1).describe("Plan id to inspect."),
+			version: z.number().int().positive().optional().describe("Historical version number; omit for current.")
+		},
+		outputSchema: {
+			plan: z.unknown(),
+			version: z.unknown().optional(),
+			currentVersion: z.number().optional()
+		},
+		annotations: READ_ONLY
+	}, async ({ planId, version }) => {
+		const base = requireBaseUrl();
+		const encodedId = encodeURIComponent(planId);
+		const plan = await requestJson(base, `/api/plans/${encodedId}`);
+		if (version === void 0) return textResult(formatPlanReview(plan), { plan });
+		const data = await requestJson(base, `/api/plans/${encodedId}/versions/${version}`);
+		return textResult(formatPlanReview(plan, { viewingVersion: data.version.version }), {
+			plan,
+			version: data.version,
+			currentVersion: data.plan.currentVersion
+		});
+	});
+	async function findPlanForComment(base, commentId) {
+		return (await requestJson(base, "/api/plans")).find((plan) => (plan.comments ?? []).some((comment) => comment.id === commentId)) ?? null;
+	}
+	server.registerTool("reply_to_plan_comment", {
+		title: "Reply to a plan comment",
+		description: "Post an agent reply to an existing inline plan-review thread.",
+		inputSchema: {
+			commentId: z.string().min(1).describe("Plan comment id from get_plan or await_plan_review."),
+			body: z.string().min(1).describe("Reply body in Markdown."),
+			model: z.string().optional().describe("Optional agent/model identifier shown in the UI.")
+		},
+		outputSchema: {
+			status: z.literal("replied"),
+			commentId: z.string(),
+			planId: z.string()
+		},
+		annotations: MUTATING
+	}, async ({ commentId, body, model }) => {
+		const base = requireBaseUrl();
+		const plan = await findPlanForComment(base, commentId);
+		if (!plan) throw new Error(`Plan comment ${commentId} was not found. Refresh the plan before retrying.`);
+		await requestJson(base, `/api/plans/${encodeURIComponent(plan.id)}/comments/${encodeURIComponent(commentId)}/replies`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				body,
+				role: "agent",
+				model
+			})
+		});
+		return textResult(`Replied to plan comment ${commentId}.`, {
+			status: "replied",
+			commentId,
+			planId: plan.id
+		});
+	});
+	server.registerTool("resolve_plan_comment", {
+		title: "Resolve a plan comment",
+		description: "Mark an inline plan-review thread resolved after it is fully addressed. Safe to retry.",
+		inputSchema: { commentId: z.string().min(1).describe("Plan comment id to resolve.") },
+		outputSchema: {
+			status: z.literal("resolved"),
+			commentId: z.string(),
+			planId: z.string()
+		},
+		annotations: IDEMPOTENT_MUTATION
+	}, async ({ commentId }) => {
+		const base = requireBaseUrl();
+		const plan = await findPlanForComment(base, commentId);
+		if (!plan) throw new Error(`Plan comment ${commentId} was not found. Refresh the plan before retrying.`);
+		await requestJson(base, `/api/plans/${encodeURIComponent(plan.id)}/comments/${encodeURIComponent(commentId)}`, {
+			method: "PUT",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ status: "resolved" })
+		});
+		return textResult(`Resolved plan comment ${commentId}.`, {
+			status: "resolved",
+			commentId,
+			planId: plan.id
+		});
+	});
+	server.registerResource("agent-guide", "diffing://agent-guide", {
+		title: "diffing agent guide",
+		description: "Portable quick reference for the native code-review and plan-review workflows.",
+		mimeType: "text/markdown"
+	}, async () => ({ contents: [{
+		uri: "diffing://agent-guide",
+		mimeType: "text/markdown",
+		text: `# diffing agent guide
+
+This MCP connection is immutably bound to \`${repoRoot}\`.
+
+## Code review
+1. Call \`review_session_status\`; call \`start_review_session\` if needed.
+2. Call \`get_diff\` and inspect every changed file.
+3. Use \`create_comment\` for actionable inline findings.
+4. Use \`await_review\` for a human handoff; a timeout is safe to retry.
+5. In \`comment-only\` mode, reply without editing files.
+
+## Plan review
+1. Start or reuse a review session.
+2. Call \`submit_plan\`, then \`await_plan_review\`.
+3. On \`changes-requested\`, revise and resubmit with the same \`planId\`.
+4. On \`approved\`, proceed; on \`rejected\`, stop.
+
+All HTTP activity is loopback-only. MCP never terminates a user-owned session.`
+	}] }));
+	server.registerPrompt("review_local_changes", {
+		title: "Review local changes with diffing",
+		description: "Workflow prompt for inspecting a local diff and leaving inline review feedback.",
+		argsSchema: { focus: z.string().optional().describe("Optional review focus such as security, correctness, or tests.") }
+	}, async ({ focus }) => ({ messages: [{
+		role: "user",
+		content: {
+			type: "text",
+			text: `Use diffing to review the local changes in ${repoRoot}. Check review_session_status, start_review_session if needed, inspect get_diff, and create only actionable inline comments. Review every changed file${focus ? ` with special attention to ${focus}` : ""}.`
+		}
+	}] }));
+	server.registerPrompt("submit_plan_for_review", {
+		title: "Submit an implementation plan for review",
+		description: "Workflow prompt for submitting a plan and acting on the human verdict.",
+		argsSchema: { plan: z.string().describe("Complete Markdown implementation plan to submit.") }
+	}, async ({ plan }) => ({ messages: [{
+		role: "user",
+		content: {
+			type: "text",
+			text: `Use diffing for plan review in ${repoRoot}. Start or reuse a review session, submit this plan, and await the verdict. On changes-requested revise and resubmit the same planId; on rejected stop; on approved proceed.
+
+` + plan
+		}
+	}] }));
+	return server;
+}
+async function startMcpServer(options = {}) {
+	const repoRoot = resolveMcpRepository(options.repoPath ?? process.cwd(), options.repoPath !== void 0);
+	process.chdir(repoRoot);
+	await createMcpServer({ repoRoot }).connect(new StdioServerTransport());
+}
+//#endregion
+export { startMcpServer };