@interf/compiler 0.22.2 → 0.50.0

package/dist/cli/commands/mcp.js

@@ -1,52 +1,138 @@
 /**
- * `interf mcp` — Model Context Protocol server.
+ * Interf Model Context Protocol server.
  *
  * Wraps the local-service HTTP API as a typed agent surface so coding
  * agents can interact with Interf the same way they call other MCP tools
  * (instead of shelling out to the CLI).
  *
- *   interf mcp                              # stdio transport (default)
- *   interf mcp --transport=http --port=4889 # advanced: HTTP transport
+ * Packaged Desktop exposes this through `dist/bin-mcp.js`; the CLI subcommand
+ * is kept as a hidden developer entrypoint so tests and local hosts can launch
+ * the same adapter directly when needed.
  *
  * API-backed tools read `~/.interf/connection.json` (the same file every
- * other client uses) on each call. The MCP server can start before an
- * engine is connected so local plugin hosts such as Cowork can load the
- * tool surface first, then call `web_start` or `web_status`. The MCP
- * server itself holds no Interf runtime state. The transport options are
- * intentionally minimal — agents speaking MCP today are stdio-first.
+ * other client uses) on each call. In the default headless profile, the
+ * MCP server can start before a local service is connected so local plugin hosts
+ * can load the tool surface first, then call `runtime_start` or `runtime_status`.
+ * In the app profile, lifecycle, inventory, admin, and library-browsing tools
+ * are hidden because Interf Desktop owns the running service and the user flow
+ * should stay preparation-first: create a Project for the current Source,
+ * draft a Build Plan, build a Context Graph, then inspect graph evidence.
+ * The MCP server itself holds no Interf runtime state.
  *
  * Tool list:
- *   web_start           shell out to `interf web start`
- *   web_stop            shell out to `interf web stop`
- *   web_status          shell out to `interf web status`
- *   prep_list           GET /v1/preparations
- *   prep_create         POST /v1/preparations
- *   prep_show           GET /v1/preparations/{id}
- *   prep_select_build_plan PATCH /v1/preparations/{id}
- *   prep_remove         DELETE /v1/preparations/{id}
- *   prep_build          POST /v1/preparations/{id}/build-runs
- *   prep_test           POST /v1/preparations/{id}/verify-runs
- *   build_plan_list     GET /v1/build-plans
- *   build_plan_draft    POST /v1/preparations/{id}/build-plan-draft-runs
- *   build_plan_improve  POST /v1/preparations/{id}/build-plan-improvement-runs
- *   runs_status         GET /v1/runs/{run-id}
- *   runs_watch          GET /v1/build-runs/{run-id}/events  (snapshot, not SSE)
- *   runs_cancel         POST /v1/build-runs/{run-id}/cancel
- *   runs_fetch          GET /v1/build-runs/{run-id}/artifacts
- *   instance_status     GET /v1/instance
+ *   runtime_start       shell out to `interf runtime start`
+ *   runtime_stop        shell out to `interf runtime stop`
+ *   runtime_status      shell out to `interf runtime status`
+ * Desktop app profile tools:
+ *   create_project, prepare_build_plan, run_build
+ *   get_instance_status, get_project, get_run_status, get_run_events, get_run_artifacts
+ *   get_latest_context_graph, get_context_graph_entrypoint, read_context_graph_file
+ *   get_context_graph_traces, get_context_graph_sessions, get_context_graph_session,
+ *   get_build_evidence
+ *
+ * Headless developer profile additionally exposes runtime lifecycle,
+ * inventory, Build Plan library, benchmark, cancel, admin, full run event
+ * log (runs_events), and execution-session reads (context_graph_sessions,
+ * context_graph_session).
  */
 import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection, } from "../../packages/engine/connection-config.js";
-import { LOCAL_SERVICE_ROUTES, preparationResourcePath, preparationSubresourcePath, runResourcePath, } from "../../packages/engine/routes.js";
-import { BuildPlanAuthoringArtifactRequirementSchema, } from "../../packages/engine/lib/schema.js";
-import { RequestedArtifactSchema, SourceProfileSchema, } from "../../packages/project/lib/schema.js";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection, } from "../../packages/runtime/connection-config.js";
+import { readServiceRegistry, } from "../../packages/runtime/service/service-registry.js";
+import { callJson, } from "../lib/http-client.js";
+import { slugify } from "../../packages/contracts/utils/naming.js";
+import { LOCAL_SERVICE_ROUTES, buildPlanResourcePath, buildPlanSubresourcePath, projectResourcePath, projectSubresourcePath, runResourcePath, runSubresourcePath, } from "../../packages/runtime/service/routes.js";
+import { BuildPlanAuthoringArtifactRequirementSchema, BuildPlanContextCheckDraftSchema, RequestedArtifactSchema, } from "../../packages/runtime/schemas/index.js";
+import { ArtifactIdSchema, BuildPlanIdSchema, ProjectIdSchema, } from "../../packages/contracts/lib/schema.js";
+import { SourceContextSchema, } from "../../packages/projects/lib/schema.js";
+// ───────────────────────────────────────────────────────────────────────────
+// MCP id input schemas. These reuse the contract ID schemas so the MCP surface
+// accepts exactly the ids the runtime accepts — instead of a looser inline
+// `z.string().min(1)` that would let MCP pass ids the runtime then rejects.
+// `project_id`/`build_plan_id`/`artifact_id` carry the contract regex +
+// reserved-id rules; `run_id`s are opaque underscore-bearing tokens the runtime
+// mints (e.g. `build_<base36>_<base36>`), so there is no stricter contract
+// schema for them — they stay `z.string().min(1)`, defined once here.
+// ───────────────────────────────────────────────────────────────────────────
+const McpProjectIdSchema = ProjectIdSchema.describe("Project id (kebab-case).");
+const McpBuildPlanIdSchema = BuildPlanIdSchema.describe("Build Plan id (kebab-case).");
+const McpArtifactIdSchema = ArtifactIdSchema.describe("Requested output id (kebab-case).");
+const McpRunIdSchema = z.string().min(1).describe("Run id.");
+const INTERF_MCP_INSTRUCTIONS = [
+    "WHAT INTERF IS",
+    "Interf prepares data for agents. It builds a task-specific Context Graph from a Source (the user's files) — claim nodes, entities, comparison nodes, timelines, coverage indexes — that any agent can read to answer. Source-of-truth stays in the user's files. Interf does NOT answer the user's question; it prepares the structured graph the agent reasons over.",
+    "",
+    "WHAT YOU PASS, WHAT YOU GET",
+    "You pass: the user's intent (the task the graph is for) and optional graph areas you want prepared. You get: a Context Graph the agent reads — home.md as entrypoint, knowledge/ for drilldown, summaries/ as source coverage, source-backed traces for exact values.",
+    "",
+    "THE WORKFLOW",
+    "1. create_project — bind the Source + intent.",
+    "2. prepare_build_plan — name the graph areas to prepare (e.g. 'NY rent forecast claim nodes', 'cost comparison nodes', 'decision timeline'). Show the draft to the user. Stop for approval unless they granted end-to-end autonomy.",
+    "3. run_build — only after approval. Wait for terminal state; do not auto-retry.",
+    "4. get_latest_context_graph — read primary_metrics + home.md, follow traces for exact values, then answer.",
+    "",
+    "REQUESTED OUTPUTS ARE GRAPH AREAS, NOT ANSWERS",
+    "Each requested output is a region of the Context Graph the next agent will traverse (claim nodes, comparison nodes, a timeline, a coverage index). Never name an output 'the answer markdown', 'final report', 'forecast summary', or 'recommended decision' — those replace agent thinking. The agent still reasons; Interf only prepares.",
+    "",
+    "SOURCING",
+    "If the host/user already provides a Source locator, use the whole Source. Don't ask the user to pick files. Don't browse existing Projects like a corpus — create a fresh Project per task unless the user explicitly names one. Project ids are auto-generated.",
+    "",
+    "EXECUTORS VS MCP",
+    "Interf MCP is how this host talks to Interf. The agents listed inside Interf are EXECUTORS that run Build Plan stages; that is a separate setup from this MCP connection.",
+    "",
+    "FAILURE HANDLING",
+    "If any Run fails with 'executor preflight' in the error, the active execution agent CLI is broken on this machine. Tell the user to switch with `interf agents use claude-code` (or another available executor). Do not retry, do not create a new Project. For any other failure, report it and ask before starting another draft or Build.",
+].join("\n");
+const McpRequestedArtifactSchema = RequestedArtifactSchema.describe("A graph area Interf should prepare in the Context Graph — claim nodes, comparison nodes, a timeline, a coverage index. NOT the user's final answer and NOT a finished report. Each requested output is structured prepared data the NEXT agent will read and reason over. Good titles: 'NY rent forecast claims', 'Bristol vs London cost comparison nodes', 'Q3 decision-timeline signals'. Bad titles: 'NY rent growth answer', 'Final report', 'Forecast summary' — those replace agent thinking instead of preparing data for it. Source-of-truth stays in the user's files; Interf builds the task-specific Context Graph the agent reads.");
+function normalizeRequestedArtifacts(artifacts) {
+    if (!artifacts)
+        return undefined;
+    return artifacts.map((artifact) => RequestedArtifactSchema.parse(artifact));
+}
 function trimTrailingSlash(value) {
     return value.replace(/\/+$/, "");
 }
+function normalizeConnectionUrl(value) {
+    return trimTrailingSlash(value.trim());
+}
+function registryTokenForUrl(url) {
+    const normalized = normalizeConnectionUrl(url);
+    for (const service of readServiceRegistry()) {
+        if (normalizeConnectionUrl(service.url) === normalized && service.auth_token) {
+            return service.auth_token;
+        }
+    }
+    return null;
+}
+function connectionTokenForUrl(url) {
+    const normalized = normalizeConnectionUrl(url);
+    const active = readActiveConnection();
+    if (!active)
+        return null;
+    return normalizeConnectionUrl(active.url) === normalized ? active.auth_token : null;
+}
+function encodeRelativePath(value) {
+    return value
+        .split("/")
+        .filter((segment) => segment.length > 0)
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+}
+function contextGraphFilePath(projectId, filePath) {
+    return `${projectSubresourcePath(projectId, "contextGraphFile")}?path=${encodeURIComponent(filePath)}`;
+}
+// Exported for the slugify-equivalence regression test. The 18-char clamp keeps
+// the generated base well inside `slugify`'s own 80-char cap, so swapping the
+// former local `slugifyMcpId` (48-char cap) for the shared `slugify` is
+// behavior-preserving for every input.
+export function generatedMcpId(prefix) {
+    const base = slugify(prefix).slice(0, 18) || "item";
+    const suffix = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+    return `${base}-${suffix}`;
+}
 function packageVersionFromManifest() {
     try {
         const url = new URL("../../../package.json", import.meta.url);
@@ -58,15 +144,28 @@ function packageVersionFromManifest() {
         return "0.0.0";
     }
 }
+// MCP intentionally does NOT use http-client's `resolveConnection`. That helper
+// is the CLI contract: it `process.exit(1)`s when no connection is found, which
+// is correct for a one-shot CLI command but fatal for a long-lived MCP server
+// that must instead return a structured `CONNECT_OR_ERROR_HINT` tool error and
+// stay up. MCP also adds a `--url`-override token discovery step (services.json
+// registry, then the active connection) that the plain CLI override path does
+// not perform. Until http-client exports a shared null-returning variant, this
+// resolution stays here; the underlying `readActiveConnection` precedence is
+// still single-sourced in connection-config.
 function resolveConnectionOrNull(args) {
+    const urlOverride = args.url?.trim();
+    const currentLocalToken = urlOverride
+        ? registryTokenForUrl(urlOverride) ?? connectionTokenForUrl(urlOverride)
+        : null;
     const conn = readActiveConnection({
-        urlOverride: args.url ?? null,
-        authTokenOverride: args.token ?? null,
+        urlOverride: urlOverride ?? null,
+        authTokenOverride: currentLocalToken ?? args.token ?? null,
     });
     if (!conn)
         return null;
     return {
-        url: trimTrailingSlash(conn.url),
+        url: normalizeConnectionUrl(conn.url),
         token: conn.auth_token ?? null,
     };
 }
@@ -108,25 +207,12 @@ function runInterfCli(args) {
         });
     });
 }
-async function callApi(conn, path, init = {}) {
-    const headers = new Headers(init.headers ?? {});
-    if (conn.token)
-        headers.set("authorization", `Bearer ${conn.token}`);
-    if (init.body && !headers.has("content-type")) {
-        headers.set("content-type", "application/json");
-    }
-    const response = await fetch(`${conn.url}${path}`, { ...init, headers });
-    const raw = await response.text();
-    let body = null;
-    if (raw.length > 0) {
-        try {
-            body = JSON.parse(raw);
-        }
-        catch {
-            body = raw;
-        }
-    }
-    return { status: response.status, body, raw };
+// MCP issues every API call through the shared CLI `callJson` (header-setting +
+// JSON parsing live solely in http-client). `callJson` yields `body: null` on a
+// non-JSON body (vs the former local `callApi`'s `body = raw`); every read site
+// goes through `body ?? raw` or an `isRecord(body)` guard, so behavior holds.
+function mcpApi(conn, path, init = {}) {
+    return callJson(`${conn.url}${path}`, conn.token, init);
 }
 function toolResultJson(payload) {
     const text = typeof payload === "string"
@@ -158,268 +244,795 @@ async function callAndReturn(args, path, init = {}) {
     const conn = resolveConnectionOrNull(args);
     if (!conn)
         return toolErrorJson(CONNECT_OR_ERROR_HINT);
-    const response = await callApi(conn, path, init);
+    const response = await mcpApi(conn, path, init);
     if (response.status >= 200 && response.status < 300) {
         return toolResultJson(response.body ?? response.raw);
     }
     return toolErrorJson(`Local service responded with HTTP ${response.status}.`, response.body ?? response.raw);
 }
-function registerTools(server, connectionArgs) {
-    // ── Local engine lifecycle ─────────────────────────────────────────────
-    server.registerTool("web_start", {
-        title: "Start local Interf engine",
-        description: "Start the Interf engine in the background on the user's machine. "
-            + "Use this when no Interf instance is connected yet.",
-        inputSchema: {
-            host: z.string().min(1).optional().describe("Host to bind. Defaults to 127.0.0.1."),
-            port: z.number().int().positive().optional().describe("Port to bind. Defaults to 4873."),
-            timeout_ms: z.number().int().positive().optional().describe("Startup timeout in milliseconds."),
-            log: z.string().min(1).optional().describe("Optional path for background engine logs."),
-        },
-    }, async (args) => {
-        const cliArgs = ["web", "start"];
-        if (args.host)
-            cliArgs.push("--host", args.host);
-        if (args.port)
-            cliArgs.push("--port", String(args.port));
-        if (args.timeout_ms)
-            cliArgs.push("--timeout-ms", String(args.timeout_ms));
-        if (args.log)
-            cliArgs.push("--log", args.log);
-        return cliToolResult(await runInterfCli(cliArgs));
-    });
-    server.registerTool("web_stop", {
-        title: "Stop local Interf engine",
-        description: "Stop the connected Interf engine or the live engine recorded in the "
-            + "local service registry.",
-        inputSchema: {
-            url: z.string().url().optional().describe("Optional engine URL to stop."),
-            token: z.string().min(1).optional().describe("Optional bearer token."),
-        },
-    }, async (args) => {
-        const cliArgs = ["web", "stop"];
-        if (args.url)
-            cliArgs.push("--url", args.url);
-        if (args.token)
-            cliArgs.push("--token", args.token);
-        return cliToolResult(await runInterfCli(cliArgs));
-    });
-    server.registerTool("web_status", {
-        title: "Show local Interf engine status",
-        description: "Return the connected engine status using the same connection record "
-            + "as the CLI.",
-        inputSchema: {
-            url: z.string().url().optional().describe("Optional engine URL."),
-            token: z.string().min(1).optional().describe("Optional bearer token."),
-        },
-    }, async (args) => {
-        const cliArgs = ["web", "status"];
-        if (args.url)
-            cliArgs.push("--url", args.url);
-        if (args.token)
-            cliArgs.push("--token", args.token);
-        return cliToolResult(await runInterfCli(cliArgs));
+async function callAndProject(args, path, project, init = {}) {
+    const conn = resolveConnectionOrNull(args);
+    if (!conn)
+        return toolErrorJson(CONNECT_OR_ERROR_HINT);
+    const response = await mcpApi(conn, path, init);
+    if (response.status >= 200 && response.status < 300) {
+        return toolResultJson(project(response.body, response.raw));
+    }
+    return toolErrorJson(`Local service responded with HTTP ${response.status}.`, response.body ?? response.raw);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString(record, key) {
+    const value = record[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function readNumber(record, key) {
+    const value = record[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function readArray(record, key) {
+    const value = record[key];
+    return Array.isArray(value) ? value : [];
+}
+function truncateText(value, max = 360) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, Math.max(0, max - 1))}…`;
+}
+function summarizeMetrics(metrics) {
+    return metrics
+        .filter(isRecord)
+        .map((metric) => ({
+        label: readString(metric, "label") ?? "",
+        value: String(metric.value ?? ""),
+    }))
+        .filter((metric) => metric.label.length > 0 && metric.value.length > 0)
+        .slice(0, 12);
+}
+function summarizeCollection(items) {
+    const statuses = {};
+    for (const item of items) {
+        if (!isRecord(item))
+            continue;
+        const status = readString(item, "status");
+        if (status)
+            statuses[status] = (statuses[status] ?? 0) + 1;
+    }
+    return {
+        total: items.length,
+        ...(Object.keys(statuses).length > 0 ? { statuses } : {}),
+    };
+}
+function summarizeReadiness(value) {
+    if (!isRecord(value))
+        return null;
+    return {
+        status: readString(value, "status"),
+        ready: value.ready === true ? true : value.ready === false ? false : undefined,
+        checks_passed: readNumber(value, "checks_passed"),
+        checks_total: readNumber(value, "checks_total"),
+    };
+}
+function summarizeTraceEvent(event) {
+    if (!isRecord(event))
+        return null;
+    const eventData = isRecord(event.eventData) ? event.eventData : {};
+    const result = isRecord(eventData.result) ? eventData.result : {};
+    const error = isRecord(eventData.error) ? eventData.error : {};
+    return {
+        event_id: readString(event, "eventId"),
+        type: readString(event, "eventType"),
+        correlation_id: readString(event, "correlationId"),
+        created_at: readString(event, "createdAt"),
+        message: readString(eventData, "message") ?? readString(result, "summary") ?? readString(error, "message"),
+    };
+}
+function compactTraceStream(stream) {
+    if (!isRecord(stream))
+        return null;
+    const text = readString(stream, "text");
+    if (!text)
+        return null;
+    return {
+        stream_id: readString(stream, "streamId"),
+        chunk_id: readString(stream, "chunkId"),
+        index: readNumber(stream, "index"),
+        created_at: readString(stream, "createdAt"),
+        text: truncateText(text),
+    };
+}
+function latestTraceStream(streams) {
+    for (let index = streams.length - 1; index >= 0; index -= 1) {
+        const compact = compactTraceStream(streams[index]);
+        if (compact)
+            return compact;
+    }
+    return null;
+}
+function compactRunStatus(payload) {
+    if (!isRecord(payload))
+        return payload;
+    const trace = isRecord(payload.trace) ? payload.trace : {};
+    const events = readArray(trace, "events");
+    const streams = readArray(trace, "streams");
+    return {
+        kind: "interf-run-status",
+        version: 1,
+        run_id: readString(payload, "run_id"),
+        run_type: readString(payload, "run_type"),
+        title: readString(payload, "title"),
+        status: readString(payload, "status"),
+        project: readString(payload, "project"),
+        build_plan: readString(payload, "build_plan"),
+        created_at: readString(payload, "created_at"),
+        started_at: readString(payload, "started_at"),
+        finished_at: readString(payload, "finished_at"),
+        metrics: summarizeMetrics(readArray(payload, "metrics")),
+        artifacts: summarizeCollection(readArray(payload, "artifacts")),
+        checks: summarizeCollection(readArray(payload, "checks")),
+        context_checks: summarizeCollection(readArray(payload, "context_checks")),
+        readiness: summarizeReadiness(payload.readiness),
+        latest_event: events.length > 0 ? summarizeTraceEvent(events[events.length - 1]) : null,
+        latest_log: latestTraceStream(streams),
+        detail_hint: "Poll this compact status until terminal. If status is failed or cancelled, report it and ask before retrying; use event/log and artifact tools only when debugging or reading finished outputs.",
+    };
+}
+function compactRunEvents(payload, options) {
+    if (!isRecord(payload))
+        return payload;
+    const trace = isRecord(payload.trace) ? payload.trace : {};
+    const events = readArray(trace, "events");
+    const streams = readArray(trace, "streams");
+    const recentEvents = events
+        .slice(Math.max(0, events.length - options.eventLimit))
+        .map(summarizeTraceEvent)
+        .filter((event) => event !== null);
+    const recentStreams = options.includeStreams
+        ? streams
+            .slice(Math.max(0, streams.length - options.streamLimit))
+            .map(compactTraceStream)
+            .filter((stream) => stream !== null)
+        : undefined;
+    return {
+        kind: "interf-run-events",
+        version: 1,
+        run_id: readString(payload, "run_id"),
+        status: readString(payload, "status"),
+        event_count: events.length,
+        stream_count: streams.length,
+        events: recentEvents,
+        ...(recentStreams ? { streams: recentStreams } : {}),
+        detail_hint: "This is a bounded tail. Use a larger limit only when debugging; use compact run status for polling.",
+    };
+}
+async function currentSourcePathForApp(conn) {
+    const response = await mcpApi(conn, LOCAL_SERVICE_ROUTES.health);
+    if (response.status >= 200 && response.status < 300 && isRecord(response.body)) {
+        const sourcePath = readString(response.body, "source_folder_path");
+        if (sourcePath)
+            return sourcePath;
+    }
+    const sourceCandidates = await sourceCandidatesForApp(conn);
+    return sourceCandidates.length === 1 ? sourceCandidates[0]?.source_path ?? null : null;
+}
+async function sourceCandidatesForApp(conn) {
+    const response = await mcpApi(conn, LOCAL_SERVICE_ROUTES.projects);
+    if (response.status < 200 || response.status >= 300 || !isRecord(response.body))
+        return [];
+    const bySource = new Map();
+    for (const project of readArray(response.body, "projects").filter(isRecord)) {
+        const source = isRecord(project.source) ? project.source : {};
+        const sourcePath = readString(source, "locator");
+        if (!sourcePath)
+            continue;
+        const entry = bySource.get(sourcePath) ?? { count: 0, buildPlanIds: new Set() };
+        entry.count += 1;
+        const buildPlanId = readString(project, "build_plan_id");
+        if (buildPlanId)
+            entry.buildPlanIds.add(buildPlanId);
+        bySource.set(sourcePath, entry);
+    }
+    return [...bySource.entries()]
+        .map(([sourcePath, entry]) => ({
+        source_path: sourcePath,
+        project_count: entry.count,
+        build_plan_ids: [...entry.buildPlanIds].slice(0, 4),
+    }))
+        .slice(0, 8);
+}
+async function callAppCreateProject(args, request) {
+    const conn = resolveConnectionOrNull(args);
+    if (!conn)
+        return toolErrorJson(CONNECT_OR_ERROR_HINT);
+    const sourcePath = request.source_path?.trim() || await currentSourcePathForApp(conn);
+    if (!sourcePath) {
+        const sourceCandidates = await sourceCandidatesForApp(conn);
+        return toolErrorJson("No unambiguous current Source locator is exposed by Interf. If source_candidates contains a Source that clearly matches the user's task, call create_project again with that source_path. Otherwise ask for one Source locator. Do not ask for an existing Project id or ask the user to choose individual files.", { source_candidates: sourceCandidates });
+    }
+    const id = generatedMcpId("project");
+    const intent = request.intent.trim();
+    const response = await mcpApi(conn, LOCAL_SERVICE_ROUTES.projects, {
+        method: "POST",
+        body: JSON.stringify({
+            id,
+            intent,
+            source: { kind: "local-folder", locator: sourcePath },
+        }),
     });
-    // ── Preparations ────────────────────────────────────────────────────────
-    server.registerTool("prep_list", {
-        title: "List preparations",
-        description: "List every Preparation registered on the connected Interf instance, "
-            + "with source binding, Build Plan id, and current readiness.",
+    if (response.status >= 200 && response.status < 300) {
+        return toolResultJson(response.body ?? response.raw);
+    }
+    return toolErrorJson(`Local service responded with HTTP ${response.status}.`, response.body ?? response.raw);
+}
+function registerAppProfileTools(server, connectionArgs) {
+    server.registerTool("create_project", {
+        title: "Create Project",
+        description: "Workflow step 1. Bind the current Source + the user's intent (the task the Context Graph is for). Project id is auto-generated.",
+        inputSchema: {
+            intent: z.string().min(1).describe("The task the Context Graph must support — e.g. 'compare NY effective vs blended rent growth for 2026'."),
+            source_path: z.string().min(1).optional().describe("Fallback Source locator (absolute folder path on local Desktop). Pass only when Interf does not expose a current Source."),
+        },
+    }, async (args) => callAppCreateProject(connectionArgs, args));
+    server.registerTool("prepare_build_plan", {
+        title: "Prepare Build Plan",
+        description: "Workflow step 2. Draft the Build Plan from the Project intent + requested graph areas. Stop after this tool and show the draft for user approval (see top-level instructions for failure handling).",
+        inputSchema: {
+            project_id: McpProjectIdSchema.describe("Project id from create_project."),
+            build_plan_id: McpBuildPlanIdSchema.optional().describe("Optional Build Plan id. Omit to auto-generate."),
+            label: z.string().min(1).optional().describe("Optional short human label."),
+            hint: z.string().min(1).optional().describe("Optional one-line plan hint."),
+            intent: z.string().min(1).optional().describe("Question/task the Context Graph must support. Omit to use the Project intent."),
+            context_checks: z.array(BuildPlanContextCheckDraftSchema).optional().describe("Optional legacy plain-English checks. Prefer Project intent plus requested outputs and coverage expectations."),
+            requested_artifacts: z.array(McpRequestedArtifactSchema).optional().describe("Requested outputs the user approved."),
+            source_context: SourceContextSchema.nullable().optional(),
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "buildPlanDraftRuns"), {
+        method: "POST",
+        body: JSON.stringify((() => {
+            const intent = args.intent?.trim();
+            const buildPlanId = args.build_plan_id?.trim() || generatedMcpId("plan");
+            return {
+                build_plan_id: buildPlanId,
+                label: args.label?.trim() || buildPlanId,
+                hint: args.hint?.trim() || intent || `Build Plan for Project ${args.project_id}`,
+                ...(intent ? { intent } : {}),
+                ...(args.context_checks ? { checks: args.context_checks } : {}),
+                ...(args.requested_artifacts ? { requested_artifacts: normalizeRequestedArtifacts(args.requested_artifacts) } : {}),
+                ...(args.source_context !== undefined ? { source_context: args.source_context } : {}),
+            };
+        })()),
+    }));
+    server.registerTool("run_build", {
+        title: "Run Build",
+        description: "Workflow step 3. Run the approved Build Plan and build the Context Graph. Only call after explicit Build Plan approval or explicit end-to-end autonomy. See top-level instructions for failure handling.",
+        inputSchema: {
+            project_id: McpProjectIdSchema.describe("Project id from create_project."),
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "buildRuns"), { method: "POST", body: "{}" }));
+    server.registerTool("get_instance_status", {
+        title: "Get Instance Status",
+        description: "Read-only helper. Check service health, current Source, active runs, and instance metadata. Not for Project search.",
         inputSchema: {},
-    }, async () => callAndReturn(connectionArgs, LOCAL_SERVICE_ROUTES.preparations));
-    server.registerTool("prep_create", {
-        title: "Create a preparation",
-        description: "Create a new Preparation. The Preparation binds a Source, "
-            + "agent intent, requested Artifacts, and optional Build Plan.",
+    }, async () => {
+        const conn = resolveConnectionOrNull(connectionArgs);
+        if (!conn)
+            return toolErrorJson(CONNECT_OR_ERROR_HINT);
+        const [health, instance, sourceCandidates] = await Promise.all([
+            mcpApi(conn, LOCAL_SERVICE_ROUTES.health),
+            mcpApi(conn, LOCAL_SERVICE_ROUTES.instance),
+            sourceCandidatesForApp(conn),
+        ]);
+        if (health.status < 200 || health.status >= 300) {
+            return toolErrorJson(`Health responded with HTTP ${health.status}.`, health.body ?? health.raw);
+        }
+        if (instance.status < 200 || instance.status >= 300) {
+            return toolErrorJson(`Instance responded with HTTP ${instance.status}.`, instance.body ?? instance.raw);
+        }
+        const healthBody = isRecord(health.body) ? health.body : {};
+        const instanceBody = isRecord(instance.body) ? instance.body : {};
+        const healthSource = readString(healthBody, "source_folder_path");
+        const sourcePath = healthSource ?? (sourceCandidates.length === 1 ? sourceCandidates[0]?.source_path ?? null : null);
+        return toolResultJson({
+            kind: "interf-mcp-status",
+            version: 1,
+            service_url: readString(healthBody, "service_url") ?? readString(instanceBody, "url"),
+            source_path: sourcePath,
+            project_count: readNumber(instanceBody, "project_count"),
+            active_run_count: readNumber(instanceBody, "active_run_count"),
+            agent_count: readNumber(instanceBody, "agent_count"),
+            default_agent: readString(instanceBody, "default_agent"),
+            source_candidates: sourceCandidates,
+            instruction: "For a new file question: use the whole current Source, create_project -> prepare_build_plan -> ask user to review/approve the Build Plan -> run_build -> get_latest_context_graph. If source_path is null but source_candidates has a Source that clearly matches the user's task, pass that source_path to create_project. Do not ask which files inside the Source to use unless the user explicitly narrows scope.",
+        });
+    });
+    server.registerTool("get_project", {
+        title: "Get Project",
+        description: "Read-only helper. Confirm one Project's Source binding, selected Build Plan, readiness, and latest Context Graph.",
         inputSchema: {
-            id: z.string().min(1).describe("Preparation id (kebab-case)."),
+            project_id: McpProjectIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectResourcePath(args.project_id)));
+    server.registerTool("get_project_readiness", {
+        title: "Get Project Readiness",
+        description: "Read-only helper. Return ready/not ready for the latest Context Graph against the Project intent.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "readiness")));
+    server.registerTool("get_run_status", {
+        title: "Get Run Status",
+        description: "Read-only helper. Compact polling receipt for one Run. Use this for repeated status checks.",
+        inputSchema: {
+            run_id: McpRunIdSchema,
+        },
+    }, async (args) => callAndProject(connectionArgs, runSubresourcePath(args.run_id, "status"), compactRunStatus));
+    server.registerTool("get_run_artifacts", {
+        title: "Get Run Outputs",
+        description: "Read-only helper. Fetch a finished Run's artifact manifest only when status is terminal or when reviewing a completed Build Plan draft.",
+        inputSchema: {
+            run_id: McpRunIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, `${LOCAL_SERVICE_ROUTES.runs}/${encodeURIComponent(args.run_id)}/artifacts`));
+    server.registerTool("get_latest_context_graph", {
+        title: "Get Latest Context Graph",
+        description: "Read-only helper. Show the latest Context Graph locator, GraphManifest, primary metrics, entrypoints, and readiness for a Project. Start from home.md next.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "contextGraph")));
+    server.registerTool("get_context_graph_entrypoint", {
+        title: "Get Graph Entrypoint",
+        description: "Read-only helper. Return the downstream agent entrypoint for the latest Context Graph. Start from home.md, then follow entrypoint links when useful.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "contextGraphEntrypoint")));
+    server.registerTool("read_context_graph_file", {
+        title: "Read Context Graph File",
+        description: "Read one prepared Context Graph file by relative path. Start with home.md; use summaries/ for coverage and knowledge/ for drilldown.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+            path: z.string().min(1).describe("Relative path inside the Context Graph."),
+        },
+    }, async (args) => callAndReturn(connectionArgs, contextGraphFilePath(args.project_id, args.path)));
+    server.registerTool("get_context_graph_traces", {
+        title: "Get Context Graph Traces",
+        description: "Read-only helper. Read source-backed traces for exact values and provenance.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "traces")));
+    server.registerTool("get_context_graph_sessions", {
+        title: "Get Context Graph Execution Sessions",
+        description: "Read-only helper. List the per-stage execution shell sessions for the latest Build run — executor + model, status, attempt, validation attempts, and replay readiness. Pull these to drive the next self-improvement iteration when a stage was weak or failed.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "contextGraphSessions")));
+    server.registerTool("get_context_graph_session", {
+        title: "Get One Context Graph Execution Session",
+        description: "Read-only helper. Return one preserved execution shell session by stage_run_id — prompt, event/status log paths, runtime files, artifact mounts, validation attempts, and the terminal verdict. Use it to inspect or replay exactly what a stage attempt did.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+            stage_run_id: z.string().min(1).describe("Stage execution session id (stage_run_id) from get_context_graph_sessions."),
+        },
+    }, async (args) => callAndReturn(connectionArgs, `${projectSubresourcePath(args.project_id, "contextGraphSessions")}/${encodeURIComponent(args.stage_run_id)}`));
+    server.registerTool("get_run_events", {
+        title: "Get Run Events",
+        description: "Read-only helper. Read the durable event log for a Build run: stage start/pass/fail, files processed, artifacts written, evidence, checks, and readiness. Poll get_run_status for progress; read events to inspect or replay what happened.",
+        inputSchema: {
+            run_id: McpRunIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, runSubresourcePath(args.run_id, "events")));
+    server.registerTool("get_build_evidence", {
+        title: "Get Supplemental Build Diagnostics",
+        description: "Read-only helper. Read supplemental diagnostics. Prefer get_latest_context_graph for primary coverage metrics and readiness.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "buildEvidence")));
+}
+function registerTools(server, connectionArgs) {
+    const appProfile = (connectionArgs.profile ?? "headless") === "app";
+    if (appProfile) {
+        registerAppProfileTools(server, connectionArgs);
+        return;
+    }
+    // ── Local service lifecycle ────────────────────────────────────────────
+    if (!appProfile) {
+        server.registerTool("runtime_start", {
+            title: "Start local Interf service",
+            description: "Start the Interf local service in the background on the user's machine. "
+                + "Use this when no Interf instance is connected yet.",
+            inputSchema: {
+                host: z.string().min(1).optional().describe("Host to bind. Defaults to 127.0.0.1."),
+                port: z.number().int().positive().optional().describe("Port to bind. Defaults to 4873."),
+                timeout_ms: z.number().int().positive().optional().describe("Startup timeout in milliseconds."),
+                log: z.string().min(1).optional().describe("Optional path for background service logs."),
+            },
+        }, async (args) => {
+            const cliArgs = ["runtime", "start"];
+            if (args.host)
+                cliArgs.push("--host", args.host);
+            if (args.port)
+                cliArgs.push("--port", String(args.port));
+            if (args.timeout_ms)
+                cliArgs.push("--timeout-ms", String(args.timeout_ms));
+            if (args.log)
+                cliArgs.push("--log", args.log);
+            return cliToolResult(await runInterfCli(cliArgs));
+        });
+        server.registerTool("runtime_stop", {
+            title: "Stop local Interf service",
+            description: "Stop the connected Interf local service or the live service recorded in the "
+                + "local service registry.",
+            inputSchema: {
+                url: z.string().url().optional().describe("Optional service URL to stop."),
+                token: z.string().min(1).optional().describe("Optional bearer token."),
+            },
+        }, async (args) => {
+            const cliArgs = ["runtime", "stop"];
+            if (args.url)
+                cliArgs.push("--url", args.url);
+            if (args.token)
+                cliArgs.push("--token", args.token);
+            return cliToolResult(await runInterfCli(cliArgs));
+        });
+        server.registerTool("runtime_status", {
+            title: "Show local Interf service status",
+            description: "Return the connected service status using the same connection record "
+                + "as the CLI.",
+            inputSchema: {
+                url: z.string().url().optional().describe("Optional service URL."),
+                token: z.string().min(1).optional().describe("Optional bearer token."),
+            },
+        }, async (args) => {
+            const cliArgs = ["runtime", "status"];
+            if (args.url)
+                cliArgs.push("--url", args.url);
+            if (args.token)
+                cliArgs.push("--token", args.token);
+            return cliToolResult(await runInterfCli(cliArgs));
+        });
+    }
+    // ── Projects ────────────────────────────────────────────────────────────
+    if (!appProfile) {
+        server.registerTool("project_list", {
+            title: "List Projects",
+            description: "Developer inventory tool. Do not use this as search over a corpus. "
+                + "For user questions over files, create a Project for the current Source unless the user names an existing Project.",
+            inputSchema: {},
+        }, async () => callAndReturn(connectionArgs, LOCAL_SERVICE_ROUTES.projects));
+    }
+    server.registerTool("project_create", {
+        title: "Create a Project",
+        description: "Create a Project for the user's current Source. In the Desktop app profile, this is normally "
+            + "the first Interf action for a new user question over files.",
+        inputSchema: {
+            id: McpProjectIdSchema,
+            intent: z.string().min(1).describe("Agent task this Project's Context Graph should support."),
             source_path: z.string().min(1).describe("Source path visible to the connected instance."),
-            build_plan_id: z.string().min(1).optional().describe("Optional Build Plan id to select. Select later with prep_select_build_plan if omitted."),
-            about: z.string().min(1).optional().describe("Optional human-readable description."),
-            requested_artifacts: z.array(RequestedArtifactSchema).optional().describe("Requested Artifacts the agent/user confirmed for this Preparation."),
-            source_profile: SourceProfileSchema.optional().describe("Advisory source profile from the agent's inspection before build."),
+            ...(!appProfile
+                ? {
+                    build_plan_id: McpBuildPlanIdSchema.optional().describe("Optional Build Plan id to select."),
+                }
+                : {}),
         },
-    }, async (args) => callAndReturn(connectionArgs, LOCAL_SERVICE_ROUTES.preparations, {
+    }, async (args) => callAndReturn(connectionArgs, LOCAL_SERVICE_ROUTES.projects, {
         method: "POST",
         body: JSON.stringify({
             id: args.id,
+            intent: args.intent,
             source: { kind: "local-folder", locator: args.source_path },
             ...(args.build_plan_id ? { build_plan_id: args.build_plan_id } : {}),
-            ...(args.about ? { about: args.about } : {}),
-            ...(args.requested_artifacts ? { requested_artifacts: args.requested_artifacts } : {}),
-            ...(args.source_profile ? { source_profile: args.source_profile } : {}),
         }),
     }));
-    server.registerTool("prep_show", {
-        title: "Show one preparation",
-        description: "Return the full resource for one Preparation by id.",
+    server.registerTool("project_show", {
+        title: "Show one Project",
+        description: "Return one Project resource to confirm its Source binding, selected Build Plan, readiness, "
+            + "and latest Context Graph before deciding whether it matches the current task.",
         inputSchema: {
-            id: z.string().min(1).describe("Preparation id."),
+            id: McpProjectIdSchema,
         },
-    }, async (args) => callAndReturn(connectionArgs, preparationResourcePath(args.id)));
-    server.registerTool("prep_select_build_plan", {
-        title: "Select a Build Plan for a Preparation",
-        description: "Update the selected Build Plan on a Preparation. Use this to swap "
-            + "Build Plans between Build runs without rebuilding the Preparation.",
+    }, async (args) => callAndReturn(connectionArgs, projectResourcePath(args.id)));
+    server.registerTool("project_readiness", {
+        title: "Read Project readiness",
+        description: "Return the ready/not ready status for this Project's latest Context Graph against the Project intent.",
         inputSchema: {
-            id: z.string().min(1).describe("Preparation id."),
-            build_plan_id: z.string().min(1).describe("Build Plan id to use."),
+            id: McpProjectIdSchema,
         },
-    }, async (args) => callAndReturn(connectionArgs, preparationResourcePath(args.id), {
-        method: "PATCH",
-        body: JSON.stringify({ build_plan_id: args.build_plan_id }),
-    }));
-    server.registerTool("prep_remove", {
-        title: "Remove a preparation",
-        description: "Delete a Preparation. Verifiable context is removed too.",
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.id, "readiness")));
+    if (!appProfile) {
+        server.registerTool("project_select_build_plan", {
+            title: "Select a Build Plan for a Project",
+            description: "Developer/admin tool. Update the selected Build Plan on a Project. "
+                + "Build Plan draft/improve runs select their resulting Plan automatically.",
+            inputSchema: {
+                id: McpProjectIdSchema,
+                build_plan_id: McpBuildPlanIdSchema.describe("Build Plan id to use."),
+            },
+        }, async (args) => callAndReturn(connectionArgs, projectResourcePath(args.id), {
+            method: "PATCH",
+            body: JSON.stringify({ build_plan_id: args.build_plan_id }),
+        }));
+        server.registerTool("project_remove", {
+            title: "Remove a Project",
+            description: "Developer/admin tool. Delete a Project and its Context Graph.",
+            inputSchema: {
+                id: McpProjectIdSchema,
+            },
+        }, async (args) => callAndReturn(connectionArgs, projectResourcePath(args.id), {
+            method: "DELETE",
+        }));
+    }
+    // ── Build + benchmark/evaluation runs ────────────────────────────
+    server.registerTool("project_build", {
+        title: "Build Context Graph",
+        description: "Run the selected Build Plan for a Project and write a task-specific Context Graph. "
+            + "Use this only after the user has approved the coverage expectations, requested outputs, and Build Plan, "
+            + "unless they explicitly granted autonomy. Returns immediately; poll with runs_status.",
         inputSchema: {
-            id: z.string().min(1).describe("Preparation id."),
+            id: McpProjectIdSchema,
         },
-    }, async (args) => callAndReturn(connectionArgs, preparationResourcePath(args.id), {
-        method: "DELETE",
-    }));
-    // ── Build + readiness-check runs ───────────────────────────────────────
-    server.registerTool("prep_build", {
-        title: "Start a Build run",
-        description: "Run the selected Build Plan for a Preparation. Returns the new Build run "
-            + "resource immediately; use runs_status to poll progress and "
-            + "runs_fetch when the run finishes.",
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.id, "buildRuns"), { method: "POST", body: "{}" }));
+    if (!appProfile) {
+        server.registerTool("project_benchmark", {
+            title: "Run benchmark/evaluation",
+            description: "Developer/evaluation tool. Run the Project's Q&A / fact-check benchmark against the latest Context Graph.",
+            inputSchema: {
+                id: McpProjectIdSchema,
+            },
+        }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.id, "verifyRuns"), {
+            method: "POST",
+            body: JSON.stringify({}),
+        }));
+    }
+    server.registerTool("project_source_files", {
+        title: "List Project source files",
+        description: "List the Source files bound to a Project to confirm coverage scope. "
+            + "This is not an answer source by itself; prepare or inspect a Context Graph before answering.",
         inputSchema: {
-            id: z.string().min(1).describe("Preparation id."),
+            id: McpProjectIdSchema,
         },
-    }, async (args) => callAndReturn(connectionArgs, preparationSubresourcePath(args.id, "buildRuns"), { method: "POST", body: "{}" }));
-    server.registerTool("prep_test", {
-        title: "Run readiness checks",
-        description: "Run the Preparation's readiness checks against the latest verifiable "
-            + "context.",
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.id, "sourceFiles")));
+    server.registerTool("context_graph_show", {
+        title: "Show latest Context Graph",
+        description: "Inspect the latest Context Graph locator/status for a Project. Reuse it only if it was built for the same Source "
+            + "and task intent; otherwise improve or draft a Build Plan and rebuild. Read home.md before answering.",
         inputSchema: {
-            id: z.string().min(1).describe("Preparation id."),
+            project_id: McpProjectIdSchema,
         },
-    }, async (args) => callAndReturn(connectionArgs, preparationSubresourcePath(args.id, "verifyRuns"), {
-        method: "POST",
-        body: JSON.stringify({}),
-    }));
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "contextGraph")));
+    server.registerTool("context_graph_entrypoint", {
+        title: "Read Context Graph entrypoint",
+        description: "Return the downstream entrypoint for the latest Context Graph. Start from home.md before summaries/ or knowledge/.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "contextGraphEntrypoint")));
+    server.registerTool("context_graph_file_read", {
+        title: "Read a Context Graph file",
+        description: "Read one prepared Context Graph file by relative path. Start with home.md, "
+            + "then use summaries/ for coverage and knowledge/ for drilldown. Do not use this to search unrelated Projects for answers.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+            path: z.string().min(1).describe("Relative path inside the Context Graph root."),
+        },
+    }, async (args) => callAndReturn(connectionArgs, contextGraphFilePath(args.project_id, args.path)));
+    server.registerTool("project_traces", {
+        title: "Read Project traces",
+        description: "Read source-backed traces for the latest Context Graph. Use traces to follow prepared context "
+            + "back to the Source for exact values, chart reads, tables, and provenance-sensitive claims.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "traces")));
+    server.registerTool("context_graph_sessions", {
+        title: "List Context Graph execution sessions",
+        description: "List the per-stage execution shell sessions for the latest Build run — executor + model, status, attempt, validation attempts, and replay readiness. Pull these to drive the next self-improvement iteration when a stage was weak or failed.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "contextGraphSessions")));
+    server.registerTool("context_graph_session", {
+        title: "Get one Context Graph execution session",
+        description: "Return one preserved execution shell session by stage_run_id — prompt, event/status log paths, runtime files, artifact mounts, validation attempts, and terminal verdict. Use it to inspect or replay exactly what a stage attempt did.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+            stage_run_id: z.string().min(1).describe("Stage execution session id (stage_run_id) from context_graph_sessions."),
+        },
+    }, async (args) => callAndReturn(connectionArgs, `${projectSubresourcePath(args.project_id, "contextGraphSessions")}/${encodeURIComponent(args.stage_run_id)}`));
+    server.registerTool("project_build_evidence", {
+        title: "Read Supplemental Build Diagnostics",
+        description: "Read the latest supplemental diagnostics resource for a Project. Prefer context_graph_show for primary metrics; if coverage is weak or missing, improve the Build Plan instead of answering.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "buildEvidence")));
+    server.registerTool("project_artifact_show", {
+        title: "Show Requested Output",
+        description: "Return latest status and contributing evidence for one Build Plan-declared requested output.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+            artifact_id: McpArtifactIdSchema.describe("Requested output id."),
+        },
+    }, async (args) => callAndReturn(connectionArgs, `${projectSubresourcePath(args.project_id, "artifacts")}/${encodeURIComponent(args.artifact_id)}`));
     // ── Build Plans ────────────────────────────────────────────────────────
-    server.registerTool("build_plan_list", {
-        title: "List Build Plans",
-        description: "List every Build Plan visible to the connected instance: Preparation drafts, "
-            + "saved Build Plans, and bundled Build Plans.",
-        inputSchema: {},
-    }, async () => callAndReturn(connectionArgs, LOCAL_SERVICE_ROUTES.buildPlans));
+    if (!appProfile) {
+        server.registerTool("build_plan_list", {
+            title: "List Build Plans",
+            description: "Developer/library tool. Do not treat the Build Plan library as an answer source.",
+            inputSchema: {},
+        }, async () => callAndReturn(connectionArgs, LOCAL_SERVICE_ROUTES.buildPlans));
+        server.registerTool("build_plan_show", {
+            title: "Show one Build Plan",
+            description: "Developer/library tool. Return one Build Plan resource, including requested outputs, stages, and coverage checks.",
+            inputSchema: {
+                build_plan_id: McpBuildPlanIdSchema,
+            },
+        }, async (args) => callAndReturn(connectionArgs, buildPlanResourcePath(args.build_plan_id)));
+        server.registerTool("build_plan_file_read", {
+            title: "Read a Build Plan file",
+            description: "Developer/library tool. Read one file inside a Build Plan package by relative path, such as "
+                + "build-plan.json, build-plan.schema.json, or a stage SKILL.md.",
+            inputSchema: {
+                build_plan_id: McpBuildPlanIdSchema,
+                path: z.string().min(1).describe("Relative path inside the Build Plan package."),
+            },
+        }, async (args) => callAndReturn(connectionArgs, `${buildPlanSubresourcePath(args.build_plan_id, "files")}/${encodeRelativePath(args.path)}`));
+    }
     server.registerTool("build_plan_draft", {
         title: "Draft a Build Plan",
-        description: "Run the Build Plan authoring agent for a Preparation. Saved requested "
-            + "Artifacts are used automatically when omitted from the request.",
+        description: "Draft the task-specific Build Plan from the Project intent, requested outputs, and optional coverage expectations. This is the main Interf preparation action before building.",
         inputSchema: {
-            prep_id: z.string().min(1).describe("Preparation id."),
-            source_folder_path: z.string().min(1).describe("Source folder path visible to the connected instance."),
-            build_plan_id: z.string().min(1).describe("Build Plan id to create."),
+            project_id: McpProjectIdSchema,
+            build_plan_id: McpBuildPlanIdSchema.describe("Build Plan id to create."),
             label: z.string().min(1).describe("Human-readable Build Plan label."),
             hint: z.string().min(1).describe("Short Build Plan hint."),
-            task_prompt: z.string().min(1).describe("Agent job this Build Plan should support."),
-            requested_artifacts: z.array(RequestedArtifactSchema).optional(),
-            source_profile: SourceProfileSchema.nullable().optional(),
-            artifact_requirements: z.array(BuildPlanAuthoringArtifactRequirementSchema).optional(),
+            intent: z.string().min(1).optional().describe("Agent task this Build Plan should support. Omit to use the Project intent."),
+            context_checks: z.array(BuildPlanContextCheckDraftSchema).optional().describe("Optional legacy plain-English checks. Prefer Project intent plus requested outputs and coverage expectations."),
+            requested_artifacts: z.array(McpRequestedArtifactSchema).optional().describe("Requested outputs the user approved before drafting. Use simple titles, descriptions, and coverage expectations."),
+            source_context: SourceContextSchema.nullable().optional(),
+            ...(!appProfile
+                ? {
+                    artifact_requirements: z.array(BuildPlanAuthoringArtifactRequirementSchema).optional(),
+                }
+                : {}),
         },
-    }, async (args) => callAndReturn(connectionArgs, preparationSubresourcePath(args.prep_id, "buildPlanDraftRuns"), {
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "buildPlanDraftRuns"), {
         method: "POST",
         body: JSON.stringify({
-            preparation: args.prep_id,
-            source_folder_path: args.source_folder_path,
+            project: args.project_id,
             build_plan_id: args.build_plan_id,
             label: args.label,
             hint: args.hint,
-            task_prompt: args.task_prompt,
-            ...(args.requested_artifacts ? { requested_artifacts: args.requested_artifacts } : {}),
-            ...(args.source_profile !== undefined ? { source_profile: args.source_profile } : {}),
-            ...(args.artifact_requirements ? { artifact_requirements: args.artifact_requirements } : {}),
+            ...(args.intent ? { intent: args.intent } : {}),
+            ...(args.context_checks ? { checks: args.context_checks } : {}),
+            ...(args.requested_artifacts ? { requested_artifacts: normalizeRequestedArtifacts(args.requested_artifacts) } : {}),
+            ...(args.source_context !== undefined ? { source_context: args.source_context } : {}),
+            ...(!appProfile && args.artifact_requirements ? { artifact_requirements: args.artifact_requirements } : {}),
         }),
     }));
     server.registerTool("build_plan_improve", {
         title: "Improve a Build Plan",
-        description: "Run the Build Plan improvement agent for a Preparation. Iterates on "
-            + "the selected Build Plan based on requested Artifacts and latest readiness evidence.",
+        description: "Improve the selected Build Plan when the current Context Graph is not ready for the user's task, "
+            + "for example when coverage is missing, an entrypoint is too coarse, a chart/table was under-extracted, or evidence is missing.",
         inputSchema: {
-            prep_id: z.string().min(1).describe("Preparation id."),
-            source_folder_path: z.string().min(1).describe("Source folder path visible to the connected instance."),
-            build_plan_id: z.string().min(1).describe("Selected Build Plan id to improve."),
+            project_id: McpProjectIdSchema,
+            build_plan_id: McpBuildPlanIdSchema.describe("Selected Build Plan id to improve."),
             label: z.string().min(1).describe("Human-readable Build Plan label."),
             hint: z.string().min(1).describe("Short Build Plan hint."),
-            task_prompt: z.string().min(1).describe("Change request or improvement goal."),
-            requested_artifacts: z.array(RequestedArtifactSchema).optional(),
-            source_profile: SourceProfileSchema.nullable().optional(),
-            artifact_requirements: z.array(BuildPlanAuthoringArtifactRequirementSchema).optional(),
+            intent: z.string().min(1).optional().describe("Change request or improvement goal. Omit to use the Project intent."),
+            context_checks: z.array(BuildPlanContextCheckDraftSchema).optional().describe("Optional legacy plain-English checks. Prefer missing coverage and requested output changes."),
+            requested_artifacts: z.array(McpRequestedArtifactSchema).optional().describe("Requested outputs for the improved Plan. Use simple titles, descriptions, and coverage expectations."),
+            source_context: SourceContextSchema.nullable().optional(),
+            ...(!appProfile
+                ? {
+                    artifact_requirements: z.array(BuildPlanAuthoringArtifactRequirementSchema).optional(),
+                }
+                : {}),
         },
-    }, async (args) => callAndReturn(connectionArgs, preparationSubresourcePath(args.prep_id, "buildPlanImprovementRuns"), {
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "buildPlanImprovementRuns"), {
         method: "POST",
         body: JSON.stringify({
-            preparation: args.prep_id,
-            source_folder_path: args.source_folder_path,
+            project: args.project_id,
             build_plan_id: args.build_plan_id,
             reference_build_plan_id: args.build_plan_id,
             label: args.label,
             hint: args.hint,
-            task_prompt: args.task_prompt,
-            ...(args.requested_artifacts ? { requested_artifacts: args.requested_artifacts } : {}),
-            ...(args.source_profile !== undefined ? { source_profile: args.source_profile } : {}),
-            ...(args.artifact_requirements ? { artifact_requirements: args.artifact_requirements } : {}),
+            ...(args.intent ? { intent: args.intent } : {}),
+            ...(args.context_checks ? { checks: args.context_checks } : {}),
+            ...(args.requested_artifacts ? { requested_artifacts: normalizeRequestedArtifacts(args.requested_artifacts) } : {}),
+            ...(args.source_context !== undefined ? { source_context: args.source_context } : {}),
+            ...(!appProfile && args.artifact_requirements ? { artifact_requirements: args.artifact_requirements } : {}),
         }),
     }));
     // ── Runs ────────────────────────────────────────────────────────────────
     server.registerTool("runs_status", {
         title: "Get run status",
-        description: "Return the run record for one observable run.",
+        description: "Return a compact run-status receipt for polling. This intentionally omits full trace events, "
+            + "stream logs, and artifact manifests so repeated polls do not fill the agent context window.",
         inputSchema: {
-            run_id: z.string().min(1).describe("Run id."),
+            run_id: McpRunIdSchema,
         },
-    }, async (args) => callAndReturn(connectionArgs, runResourcePath(args.run_id)));
+    }, async (args) => callAndProject(connectionArgs, runSubresourcePath(args.run_id, "status"), compactRunStatus));
     server.registerTool("runs_watch", {
-        title: "Read run events",
-        description: "Read the events log for one run as a snapshot. Returns the same "
-            + "stream the UI consumes via SSE; agents that need live progress "
-            + "should poll runs_status until the run reaches a terminal state.",
+        title: "Read recent run events",
+        description: "Read a bounded tail of run events for debugging or progress detail. Do not use this for polling; "
+            + "poll runs_status until the run reaches a terminal state.",
         inputSchema: {
-            run_id: z.string().min(1).describe("Run id."),
+            run_id: McpRunIdSchema,
+            limit: z.number().int().min(1).max(50).default(10).describe("Maximum recent events to return. Defaults to 10; max 50."),
+            include_streams: z.boolean().default(false).describe("Include recent log stream chunks. Defaults to false because logs can be verbose."),
+            stream_limit: z.number().int().min(1).max(20).default(5).describe("Maximum recent log stream chunks to return when include_streams is true. Defaults to 5; max 20."),
         },
-    }, async (args) => callAndReturn(connectionArgs, `${LOCAL_SERVICE_ROUTES.buildRuns}/${encodeURIComponent(args.run_id)}/events`));
-    server.registerTool("runs_cancel", {
-        title: "Cancel a run",
-        description: "Request cancellation of an in-flight run.",
+    }, async (args) => callAndProject(connectionArgs, runResourcePath(args.run_id), (body) => compactRunEvents(body, {
+        eventLimit: args.limit,
+        includeStreams: args.include_streams,
+        streamLimit: args.stream_limit,
+    })));
+    if (!appProfile) {
+        server.registerTool("runs_cancel", {
+            title: "Cancel a run",
+            description: "Developer/admin tool. Request cancellation of an in-flight run.",
+            inputSchema: {
+                run_id: McpRunIdSchema,
+            },
+        }, async (args) => callAndReturn(connectionArgs, `${LOCAL_SERVICE_ROUTES.runs}/${encodeURIComponent(args.run_id)}/cancel`, { method: "POST", body: "{}" }));
+    }
+    server.registerTool("runs_events", {
+        title: "Read full run event log",
+        description: "Return the full durable event log for a Build run: stage start/pass/fail, files processed, "
+            + "artifacts written, evidence, checks, and readiness. Use runs_status for polling and runs_watch "
+            + "for a bounded tail; use this to inspect or replay the complete sequence.",
         inputSchema: {
-            run_id: z.string().min(1).describe("Run id."),
+            run_id: McpRunIdSchema,
         },
-    }, async (args) => callAndReturn(connectionArgs, `${LOCAL_SERVICE_ROUTES.buildRuns}/${encodeURIComponent(args.run_id)}/cancel`, { method: "POST", body: "{}" }));
+    }, async (args) => callAndReturn(connectionArgs, runSubresourcePath(args.run_id, "events")));
     server.registerTool("runs_fetch", {
         title: "Fetch run artifacts",
-        description: "Return the artifact manifest for a finished run (verifiable context, "
-            + "proof records, logs, run-scoped audit trail).",
+        description: "Return the artifact manifest for a finished run (Context Graph, "
+            + "evidence records, logs, run-scoped audit trail).",
         inputSchema: {
-            run_id: z.string().min(1).describe("Run id."),
+            run_id: McpRunIdSchema,
         },
-    }, async (args) => callAndReturn(connectionArgs, `${LOCAL_SERVICE_ROUTES.buildRuns}/${encodeURIComponent(args.run_id)}/artifacts`));
+    }, async (args) => callAndReturn(connectionArgs, `${LOCAL_SERVICE_ROUTES.runs}/${encodeURIComponent(args.run_id)}/artifacts`));
     // ── Instance ────────────────────────────────────────────────────────────
     server.registerTool("instance_status", {
         title: "Show instance status",
-        description: "Return the engine's instance resource: started_at, package "
-            + "version, registered preparations, active runs, idle seconds.",
+        description: "Return the local service instance resource: started_at, registered "
+            + "Projects, active runs, idle seconds.",
         inputSchema: {},
     }, async () => callAndReturn(connectionArgs, LOCAL_SERVICE_ROUTES.instance));
 }
-async function startStdioServer(args) {
-    const server = new McpServer({ name: "interf", version: packageVersionFromManifest() }, { capabilities: { tools: {} } });
+export async function startInterfMcpServer(args) {
+    if (args.transport && args.transport !== "stdio") {
+        throw new Error("Only the MCP stdio transport is implemented for the local Interf MCP server.");
+    }
+    const server = new McpServer({ name: "interf", version: packageVersionFromManifest() }, {
+        capabilities: { tools: {} },
+        instructions: INTERF_MCP_INSTRUCTIONS,
+    });
     registerTools(server, args);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
 export const mcpCommand = {
     command: "mcp",
-    describe: "Run the Interf Model Context Protocol server (stdio by default).",
+    describe: false,
     builder: (yargs) => yargs
         .option("transport", {
         type: "string",
-        choices: ["stdio", "http"],
+        choices: ["stdio"],
         default: "stdio",
         describe: "Transport for the MCP server.",
+    })
+        .option("profile", {
+        type: "string",
+        choices: ["headless", "app"],
+        default: "headless",
+        describe: "Tool profile. App profile hides lifecycle tools because Desktop owns the local service.",
     })
         .option("url", {
         type: "string",
@@ -430,11 +1043,12 @@ export const mcpCommand = {
         describe: "Override the active bearer token.",
     }),
     handler: async (args) => {
-        if (args.transport && args.transport !== "stdio") {
-            process.stderr.write("interf mcp: only the stdio transport is implemented today. "
-                + "Open an issue if you need --transport=http.\n");
+        try {
+            await startInterfMcpServer(args);
+        }
+        catch (error) {
+            process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
             process.exit(2);
         }
-        await startStdioServer(args);
     },
 };