@interf/compiler 0.16.0 → 0.21.0

package/dist/cli/commands/mcp.js

@@ -1,25 +1,113 @@
+/**
+ * `interf mcp` — 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
+ *
+ * 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.
+ *
+ * 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_set_method     PATCH /v1/preparations/{id}
+ *   prep_remove         DELETE /v1/preparations/{id}
+ *   prep_compile        POST /v1/preparations/{id}/compile-runs
+ *   prep_test           POST /v1/preparations/{id}/verify-runs
+ *   method_list         GET /v1/methods
+ *   method_draft        POST /v1/preparations/{id}/method-authoring-runs
+ *   method_improve      POST /v1/preparations/{id}/method-improvement-runs
+ *   runs_status         GET /v1/runs/{run-id}
+ *   runs_watch          GET /v1/runs/{run-id}/events  (snapshot, not SSE)
+ *   runs_cancel         POST /v1/runs/{run-id}/cancel
+ *   runs_fetch          GET /v1/runs/{run-id}/artifacts
+ *   instance_status     GET /v1/instance
+ */
+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, runSubresourcePath, } from "../../packages/engine/routes.js";
+import { MethodAuthoringArtifactRequirementSchema, } from "../../packages/engine/lib/schema.js";
+import { RequestedArtifactSchema, SourceProfileSchema, } from "../../packages/project/lib/schema.js";
 function trimTrailingSlash(value) {
     return value.replace(/\/+$/, "");
 }
-function resolveConnection(args) {
+function packageVersionFromManifest() {
+    try {
+        const url = new URL("../../../package.json", import.meta.url);
+        const raw = readFileSync(url, "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function resolveConnectionOrNull(args) {
     const conn = readActiveConnection({
         urlOverride: args.url ?? null,
         authTokenOverride: args.token ?? null,
     });
-    if (!conn) {
-        process.stderr.write(`${CONNECT_OR_ERROR_HINT}\n`);
-        process.exit(1);
-    }
+    if (!conn)
+        return null;
     return {
         url: trimTrailingSlash(conn.url),
         token: conn.auth_token ?? null,
     };
 }
+function runInterfCli(args) {
+    const binPath = process.argv[1];
+    if (!binPath) {
+        return Promise.resolve({
+            code: 1,
+            signal: null,
+            stdout: "",
+            stderr: "Cannot locate the Interf CLI entrypoint.",
+        });
+    }
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [binPath, ...args], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: process.env,
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", (error) => {
+            resolve({
+                code: 1,
+                signal: null,
+                stdout,
+                stderr: stderr || error.message,
+            });
+        });
+        child.on("close", (code, signal) => {
+            resolve({ code, signal, stdout, stderr });
+        });
+    });
+}
 async function callApi(conn, path, init = {}) {
     const headers = new Headers(init.headers ?? {});
     if (conn.token)
@@ -57,38 +145,109 @@ function toolErrorJson(message, payload) {
         isError: true,
     };
 }
-async function callAndReturn(conn, path, init = {}) {
+function cliToolResult(result) {
+    const output = [
+        result.stdout.trim(),
+        result.stderr.trim(),
+    ].filter(Boolean).join("\n");
+    if (result.code === 0)
+        return toolResultJson(output || "OK");
+    return toolErrorJson(`interf command exited with ${result.signal ?? result.code ?? "unknown"}.`, output);
+}
+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);
     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, conn) {
+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));
+    });
     // ── Preparations ────────────────────────────────────────────────────────
     server.registerTool("prep_list", {
         title: "List preparations",
         description: "List every Preparation registered on the connected Interf instance, "
-            + "with source binding, Method id, and current readiness.",
+            + "with source binding, Build Plan / Method package id, and current readiness.",
         inputSchema: {},
-    }, async () => callAndReturn(conn, LOCAL_SERVICE_ROUTES.preparations));
+    }, 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 Folder "
-            + "to an optional Method and is the saved unit of work for compile runs.",
+        description: "Create a new Preparation. The Preparation binds a Source, "
+            + "agent intent, requested Artifacts, and optional Build Plan.",
         inputSchema: {
             id: z.string().min(1).describe("Preparation id (kebab-case)."),
-            source_path: z.string().min(1).describe("Absolute or workspace-relative Source Folder path."),
-            method_id: z.string().min(1).optional().describe("Optional Method id to bind. Bind later with prep_set_method if omitted."),
+            source_path: z.string().min(1).describe("Source path visible to the connected instance."),
+            method_id: z.string().min(1).optional().describe("Optional Build Plan / Method id to select. Select later with prep_set_method 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 compile."),
         },
-    }, async (args) => callAndReturn(conn, LOCAL_SERVICE_ROUTES.preparations, {
+    }, async (args) => callAndReturn(connectionArgs, LOCAL_SERVICE_ROUTES.preparations, {
         method: "POST",
         body: JSON.stringify({
             id: args.id,
             source: { kind: "local-folder", locator: args.source_path },
             ...(args.method_id ? { method_id: args.method_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", {
@@ -97,16 +256,16 @@ function registerTools(server, conn) {
         inputSchema: {
             id: z.string().min(1).describe("Preparation id."),
         },
-    }, async (args) => callAndReturn(conn, preparationResourcePath(args.id)));
+    }, async (args) => callAndReturn(connectionArgs, preparationResourcePath(args.id)));
     server.registerTool("prep_set_method", {
-        title: "Bind a Method to a preparation",
-        description: "Update the Method binding on a Preparation. Use this to swap "
-            + "Methods between compile runs without rebuilding the Preparation.",
+        title: "Select a Build Plan for a Preparation",
+        description: "Update the Build Plan / Method-package binding on a Preparation. Use this to swap "
+            + "Build Plans between compile runs without rebuilding the Preparation.",
         inputSchema: {
             id: z.string().min(1).describe("Preparation id."),
-            method_id: z.string().min(1).describe("Method id to bind."),
+            method_id: z.string().min(1).describe("Build Plan / Method id to use."),
         },
-    }, async (args) => callAndReturn(conn, preparationResourcePath(args.id), {
+    }, async (args) => callAndReturn(connectionArgs, preparationResourcePath(args.id), {
         method: "PATCH",
         body: JSON.stringify({ method_id: args.method_id }),
     }));
@@ -116,10 +275,10 @@ function registerTools(server, conn) {
         inputSchema: {
             id: z.string().min(1).describe("Preparation id."),
         },
-    }, async (args) => callAndReturn(conn, preparationResourcePath(args.id), {
+    }, async (args) => callAndReturn(connectionArgs, preparationResourcePath(args.id), {
         method: "DELETE",
     }));
-    // ── Compile + verify runs ──────────────────────────────────────────────
+    // ── Compile + readiness-check runs ─────────────────────────────────────
     server.registerTool("prep_compile", {
         title: "Start a compile run",
         description: "Kick off a compile run for a Preparation. Returns the new run "
@@ -128,41 +287,84 @@ function registerTools(server, conn) {
         inputSchema: {
             id: z.string().min(1).describe("Preparation id."),
         },
-    }, async (args) => callAndReturn(conn, preparationSubresourcePath(args.id, "compileRuns"), { method: "POST", body: "{}" }));
-    server.registerTool("prep_verify", {
+    }, async (args) => callAndReturn(connectionArgs, preparationSubresourcePath(args.id, "compileRuns"), { method: "POST", body: "{}" }));
+    server.registerTool("prep_test", {
         title: "Run readiness checks",
         description: "Run the Preparation's readiness checks against the latest portable "
-            + "context. Verify runs always judge against the compiled output in 0.15+.",
+            + "context.",
         inputSchema: {
             id: z.string().min(1).describe("Preparation id."),
         },
-    }, async (args) => callAndReturn(conn, preparationSubresourcePath(args.id, "verifyRuns"), {
+    }, async (args) => callAndReturn(connectionArgs, preparationSubresourcePath(args.id, "verifyRuns"), {
         method: "POST",
         body: JSON.stringify({}),
     }));
     // ── Methods ─────────────────────────────────────────────────────────────
     server.registerTool("method_list", {
         title: "List Methods",
-        description: "List every Method visible to the connected instance: workspace "
-            + "drafts, the user library at ~/.interf/methods/, and bundled Methods.",
+        description: "List every Method visible to the connected instance: user-authored "
+            + "Methods, the user library at ~/.interf/methods/, and bundled Methods.",
         inputSchema: {},
-    }, async () => callAndReturn(conn, LOCAL_SERVICE_ROUTES.methods));
+    }, async () => callAndReturn(connectionArgs, LOCAL_SERVICE_ROUTES.methods));
     server.registerTool("method_draft", {
-        title: "Author a new Method draft",
-        description: "Run the Method-authoring agent for a Preparation. Produces a new "
-            + "Method package draft under <workspace>/methods/<id>/.",
+        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.",
         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."),
+            method_id: z.string().min(1).describe("Build Plan / Method 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(MethodAuthoringArtifactRequirementSchema).optional(),
         },
-    }, async (args) => callAndReturn(conn, preparationSubresourcePath(args.prep_id, "methodAuthoringRuns"), { method: "POST", body: "{}" }));
+    }, async (args) => callAndReturn(connectionArgs, preparationSubresourcePath(args.prep_id, "methodAuthoringRuns"), {
+        method: "POST",
+        body: JSON.stringify({
+            preparation: args.prep_id,
+            source_folder_path: args.source_folder_path,
+            method_id: args.method_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 } : {}),
+        }),
+    }));
     server.registerTool("method_improve", {
-        title: "Run Method improvement",
-        description: "Run the Method-improvement agent for a Preparation. Iterates on "
-            + "the bound Method based on the latest readiness-check results.",
+        title: "Improve a Build Plan",
+        description: "Run the Build Plan improvement agent for a Preparation. Iterates on "
+            + "the selected Method package based on requested Artifacts and latest readiness evidence.",
         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."),
+            method_id: z.string().min(1).describe("Selected Build Plan / Method 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(MethodAuthoringArtifactRequirementSchema).optional(),
         },
-    }, async (args) => callAndReturn(conn, preparationSubresourcePath(args.prep_id, "methodImprovementRuns"), { method: "POST", body: "{}" }));
+    }, async (args) => callAndReturn(connectionArgs, preparationSubresourcePath(args.prep_id, "methodImprovementRuns"), {
+        method: "POST",
+        body: JSON.stringify({
+            preparation: args.prep_id,
+            source_folder_path: args.source_folder_path,
+            method_id: args.method_id,
+            reference_method_id: args.method_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 } : {}),
+        }),
+    }));
     // ── Runs ────────────────────────────────────────────────────────────────
     server.registerTool("runs_status", {
         title: "Get run status",
@@ -170,7 +372,7 @@ function registerTools(server, conn) {
         inputSchema: {
             run_id: z.string().min(1).describe("Run id."),
         },
-    }, async (args) => callAndReturn(conn, runResourcePath(args.run_id)));
+    }, async (args) => callAndReturn(connectionArgs, runResourcePath(args.run_id)));
     server.registerTool("runs_watch", {
         title: "Read run events",
         description: "Read the events log for one run as a snapshot. Returns the same "
@@ -179,14 +381,14 @@ function registerTools(server, conn) {
         inputSchema: {
             run_id: z.string().min(1).describe("Run id."),
         },
-    }, async (args) => callAndReturn(conn, runSubresourcePath(args.run_id, "events")));
+    }, async (args) => callAndReturn(connectionArgs, runSubresourcePath(args.run_id, "events")));
     server.registerTool("runs_cancel", {
         title: "Cancel a run",
         description: "Request cancellation of an in-flight run.",
         inputSchema: {
             run_id: z.string().min(1).describe("Run id."),
         },
-    }, async (args) => callAndReturn(conn, runSubresourcePath(args.run_id, "cancel"), { method: "POST", body: "{}" }));
+    }, async (args) => callAndReturn(connectionArgs, runSubresourcePath(args.run_id, "cancel"), { method: "POST", body: "{}" }));
     server.registerTool("runs_fetch", {
         title: "Fetch run artifacts",
         description: "Return the artifact manifest for a finished run (portable context, "
@@ -194,19 +396,18 @@ function registerTools(server, conn) {
         inputSchema: {
             run_id: z.string().min(1).describe("Run id."),
         },
-    }, async (args) => callAndReturn(conn, runSubresourcePath(args.run_id, "artifacts")));
+    }, async (args) => callAndReturn(connectionArgs, runSubresourcePath(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.",
         inputSchema: {},
-    }, async () => callAndReturn(conn, LOCAL_SERVICE_ROUTES.instance));
+    }, async () => callAndReturn(connectionArgs, LOCAL_SERVICE_ROUTES.instance));
 }
 async function startStdioServer(args) {
-    const conn = resolveConnection(args);
-    const server = new McpServer({ name: "interf", version: "0.14.0" }, { capabilities: { tools: {} } });
-    registerTools(server, conn);
+    const server = new McpServer({ name: "interf", version: packageVersionFromManifest() }, { capabilities: { tools: {} } });
+    registerTools(server, args);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }