@interf/compiler 0.22.2 → 0.33.0

package/dist/cli/commands/mcp.js

@@ -1,52 +1,114 @@
 /**
- * `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_artifacts
+ *   get_latest_context_graph, read_context_graph_file
+ *   get_context_graph_traces, get_build_evidence
+ *
+ * Headless developer profile additionally exposes runtime lifecycle,
+ * inventory, Build Plan library, benchmark, cancel, and admin tools.
  */
 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 { 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 { SourceContextSchema, } from "../../packages/projects/lib/schema.js";
+const INTERF_MCP_INSTRUCTIONS = [
+    "Interf prepares data for agents. It is not a search engine and not a general RAG index.",
+    "Interf MCP is how this host talks to Interf. Agents listed inside Interf are executors that run Build Plan stages. Do not treat MCP setup as executor setup.",
+    "App MCP exposes three core workflow tools: create_project, prepare_build_plan, and run_build. Other tools are read-only inspection helpers.",
+    "Default workflow for a user question over files: create a fresh Project for the current Source, propose Context Checks and requested Artifacts, prepare the Build Plan after the user approves those checks and Artifacts, stop for Build Plan approval, run_build only after that approval, then answer from the prepared Context Graph and its source-backed traces.",
+    "Source scope default: if Interf Desktop, the MCP host, or the user context already provides a Source locator or file set, use that whole Source. Do not ask the user to choose individual files or a subset unless they explicitly ask to narrow scope.",
+    "Do not answer by browsing existing Projects as if they were a corpus. In the Desktop app profile, always create a fresh Project for the current Source unless the user explicitly names an existing Project id.",
+    "Use existing Projects or Context Graphs only when the user explicitly selected or named them and they bind the same Source and task.",
+    "If no usable Source locator is available, ask for one Source locator. In the local Desktop path this may be a folder path. Do not present a file-selection menu or ask which files inside the Source to use.",
+    "Project creation is allowed when the user asks Interf to use a Source. Project ids are generated internally. Do not ask for existing Project ids. Approval gates are for Build Plan preparation and Build execution.",
+    "Before building, show the user the Context Checks, requested Artifacts, and drafted Build Plan in chat. Wait for approval unless the user has explicitly granted end-to-end autonomy.",
+    "No automatic retries: if prepare_build_plan, run_build, or a polled Run reaches failed/cancelled, report the failure and ask the user before starting another draft or Build run.",
+    "After a Build succeeds, read the task handoff under artifacts/ first. Treat home.md as a graph index, summaries/ as source coverage proof, and knowledge/ as navigation/drilldown.",
+    "A Context Graph is a knowledge map over the Source, not the answer source. Use it to understand what exists and where evidence lives; follow source references and traces when exact values, chart reads, tables, or provenance matter.",
+    "If a Context Graph artifact is too coarse or missing the needed evidence, improve the Build Plan and rebuild instead of giving a weak answer.",
+].join("\n");
+const McpRequestedArtifactSchema = RequestedArtifactSchema.describe("Requested Artifact the user approved. Use a short title, optional id, description/purpose, and plain-English checks.");
+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)}`;
+}
+function slugifyMcpId(input) {
+    return input
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+}
+function generatedMcpId(prefix) {
+    const base = slugifyMcpId(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);
@@ -59,14 +121,18 @@ function packageVersionFromManifest() {
     }
 }
 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,
     };
 }
@@ -164,262 +230,712 @@ async function callAndReturn(args, path, init = {}) {
     }
     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.",
+async function callAndProject(args, path, project, init = {}) {
+    const conn = resolveConnectionOrNull(args);
+    if (!conn)
+        return toolErrorJson(CONNECT_OR_ERROR_HINT);
+    const response = await callApi(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 callApi(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 callApi(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 response = await callApi(conn, LOCAL_SERVICE_ROUTES.projects, {
+        method: "POST",
+        body: JSON.stringify({
+            id,
+            source: { kind: "local-folder", locator: sourcePath },
+        }),
+    });
+    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: "Core step 1. Create a fresh Project for this task and the whole current Source. The Project id is generated internally; do not ask for or provide one.",
         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."),
+            source_path: z.string().min(1).optional().describe("Fallback Source locator. In the local Desktop path this is an absolute folder path. Use only when Interf does not expose a current Source; do not pass individual files or a subset selection."),
         },
-    }, 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.",
+    }, async (args) => callAppCreateProject(connectionArgs, args));
+    server.registerTool("prepare_build_plan", {
+        title: "Prepare Build Plan",
+        description: "Core step 2. Draft the approved Build Plan for the Project. Use after the user approves checks and requested Artifacts. Stop after this tool and ask for Build Plan approval before building. If it fails, report the failure; do not retry without explicit user approval.",
         inputSchema: {
-            url: z.string().url().optional().describe("Optional engine URL to stop."),
-            token: z.string().min(1).optional().describe("Optional bearer token."),
+            project_id: z.string().min(1).describe("Project id from create_project."),
+            build_plan_id: z.string().min(1).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).describe("Question/task the Context Graph must support."),
+            context_checks: z.array(BuildPlanContextCheckDraftSchema).optional().describe("Plain-English checks the user approved."),
+            requested_artifacts: z.array(McpRequestedArtifactSchema).optional().describe("Requested Artifacts the user approved."),
+            source_context: SourceContextSchema.nullable().optional(),
         },
-    }, 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.",
+    }, 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,
+                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: "Core step 3. Run the selected Build Plan and create the Context Graph. Never call immediately after prepare_build_plan; use only after explicit Build Plan approval or explicit end-to-end autonomy. If it fails, report the failure; do not retry without explicit user approval.",
         inputSchema: {
-            url: z.string().url().optional().describe("Optional engine URL."),
-            token: z.string().min(1).optional().describe("Optional bearer token."),
+            project_id: z.string().min(1).describe("Project id from create_project."),
         },
-    }, 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));
-    });
-    // ── 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.",
+    }, 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([
+            callApi(conn, LOCAL_SERVICE_ROUTES.health),
+            callApi(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 -> ask user to approve checks/Artifacts -> prepare_build_plan -> ask user to approve the Build Plan -> run_build. 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: {
+            project_id: z.string().min(1).describe("Project id."),
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectResourcePath(args.project_id)));
+    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: z.string().min(1).describe("Run id."),
+        },
+    }, async (args) => callAndProject(connectionArgs, runSubresourcePath(args.run_id, "status"), compactRunStatus));
+    server.registerTool("get_run_artifacts", {
+        title: "Get Run Artifacts",
+        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: z.string().min(1).describe("Run id."),
+        },
+    }, 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 for a Project. This is a locator/status read, not the answer surface; read artifacts/ handoff files next.",
+        inputSchema: {
+            project_id: z.string().min(1).describe("Project id."),
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "contextGraph")));
+    server.registerTool("read_context_graph_file", {
+        title: "Read Context Graph File",
+        description: "Read one prepared Context Graph file by relative path. Start with artifacts/ task handoffs; use summaries/ for coverage and knowledge/ for drilldown.",
+        inputSchema: {
+            project_id: z.string().min(1).describe("Project id."),
+            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: z.string().min(1).describe("Project id."),
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "traces")));
+    server.registerTool("get_build_evidence", {
+        title: "Get Build Evidence",
+        description: "Read-only helper. Read checks, Artifact diagnostics, and readiness evidence.",
         inputSchema: {
-            id: z.string().min(1).describe("Preparation id (kebab-case)."),
+            project_id: z.string().min(1).describe("Project id."),
+        },
+    }, 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: z.string().min(1).describe("Project id (kebab-case)."),
             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: z.string().min(1).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,
             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("Project id."),
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectResourcePath(args.id)));
+    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: z.string().min(1).describe("Project id."),
+                build_plan_id: z.string().min(1).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: z.string().min(1).describe("Project id."),
+            },
+        }, 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 checks/requested Artifacts and Build Plan, "
+            + "unless they explicitly granted autonomy. Returns immediately; poll with runs_status.",
         inputSchema: {
-            id: z.string().min(1).describe("Preparation id."),
+            id: z.string().min(1).describe("Project id."),
         },
-    }, 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, 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: z.string().min(1).describe("Project id."),
+            },
+        }, 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."),
-            build_plan_id: z.string().min(1).describe("Build Plan id to use."),
+            id: z.string().min(1).describe("Project id."),
         },
-    }, 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, "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-relevant checks/artifacts; otherwise improve or draft a Build Plan and rebuild. Read artifacts/ handoffs before answering.",
         inputSchema: {
-            id: z.string().min(1).describe("Preparation id."),
+            project_id: z.string().min(1).describe("Project id."),
         },
-    }, 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.project_id, "contextGraph")));
+    server.registerTool("context_graph_file_read", {
+        title: "Read a Context Graph file",
+        description: "Read one prepared Context Graph file by relative path. Start with artifacts/ task handoffs, "
+            + "then use summaries/ for coverage and knowledge/ for drilldown. Do not use this to search unrelated Projects for answers.",
         inputSchema: {
-            id: z.string().min(1).describe("Preparation id."),
+            project_id: z.string().min(1).describe("Project id."),
+            path: z.string().min(1).describe("Relative path inside the Context Graph root."),
         },
-    }, 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, 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: {
-            id: z.string().min(1).describe("Preparation id."),
+            project_id: z.string().min(1).describe("Project id."),
         },
-    }, async (args) => callAndReturn(connectionArgs, preparationSubresourcePath(args.id, "verifyRuns"), {
-        method: "POST",
-        body: JSON.stringify({}),
-    }));
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "traces")));
+    server.registerTool("project_build_evidence", {
+        title: "Read Build evidence",
+        description: "Read the latest Build evidence resource for a Project: check rows, Artifact diagnostics, "
+            + "and readiness backing. If evidence is weak or missing, improve the Build Plan instead of answering.",
+        inputSchema: {
+            project_id: z.string().min(1).describe("Project id."),
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "buildEvidence")));
+    server.registerTool("project_artifact_show", {
+        title: "Show Project Artifact",
+        description: "Return latest status and contributing evidence for one Build Plan-declared Artifact.",
+        inputSchema: {
+            project_id: z.string().min(1).describe("Project id."),
+            artifact_id: z.string().min(1).describe("Artifact 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 Artifacts, stages, and checks.",
+            inputSchema: {
+                build_plan_id: z.string().min(1).describe("Build Plan id."),
+            },
+        }, 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: z.string().min(1).describe("Build Plan id."),
+                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 after the user approves the proposed Context Checks "
+            + "and requested Artifacts. 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."),
+            project_id: z.string().min(1).describe("Project id."),
             build_plan_id: z.string().min(1).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).describe("Agent task this Build Plan should support."),
+            context_checks: z.array(BuildPlanContextCheckDraftSchema).optional().describe("Plain-English Context Checks the user approved before drafting."),
+            requested_artifacts: z.array(McpRequestedArtifactSchema).optional().describe("Requested Artifacts the user approved before drafting. Use simple titles, descriptions, and plain-English checks."),
+            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 } : {}),
+            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 an Artifact 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."),
+            project_id: z.string().min(1).describe("Project id."),
             build_plan_id: z.string().min(1).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).describe("Change request or improvement goal."),
+            context_checks: z.array(BuildPlanContextCheckDraftSchema).optional().describe("Plain-English Context Checks the improved Plan must satisfy."),
+            requested_artifacts: z.array(McpRequestedArtifactSchema).optional().describe("Requested Artifacts for the improved Plan. Use simple titles, descriptions, and plain-English checks."),
+            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 } : {}),
+            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."),
         },
-    }, 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.",
-        inputSchema: {
-            run_id: z.string().min(1).describe("Run id."),
-        },
-    }, 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.",
+        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."),
+            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)}/cancel`, { method: "POST", body: "{}" }));
+    }, 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: z.string().min(1).describe("Run id."),
+            },
+        }, async (args) => callAndReturn(connectionArgs, `${LOCAL_SERVICE_ROUTES.runs}/${encodeURIComponent(args.run_id)}/cancel`, { method: "POST", body: "{}" }));
+    }
     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."),
         },
-    }, 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 +946,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);
     },
 };