@moor-sh/mcp 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moor-sh/mcp",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "MCP server for moor - lets AI agents (Claude Code, Cursor, etc.) manage your moor projects via the moor HTTP API.",
   "license": "MIT",
   "repository": {

package/src/index.ts

@@ -90,6 +90,17 @@ type Project = {
   domain: string | null;
   docker_image: string | null;
   github_url: string | null;
+  // #71: live_* fields are written by the API's status reconciler.
+  // status above is moor's RECORDED state (only changes on explicit
+  // start/stop/build/cancel). live_status reflects Docker's view at
+  // last successful inspect. Differences mean moor missed an external
+  // change (or the reconciler hasn't run yet). live_error non-null
+  // means the most recent inspect failed; the live_status / exit_code
+  // shown is the last successful snapshot.
+  live_status?: "running" | "stopped" | "error" | "missing" | null;
+  live_exit_code?: number | null;
+  live_checked_at?: string | null;
+  live_error?: string | null;
 };
 
 async function resolveProject(name: string): Promise<Project> {
@@ -166,9 +177,9 @@ function validateGithubRepoUrl(url: string): void {
   } catch {
     throw new Error(`github_url is not a valid URL: ${url}`);
   }
-  // The downstream build path (apps/api/docker.ts:buildImage) appends ".git" and a
-  // branch ref to whatever URL we forward, so a non-http protocol, query string, or
-  // fragment quietly mangles the resulting git remote. Reject those up front.
+  // The downstream build path (apps/api/docker.ts:buildImageStreaming) appends ".git"
+  // and a branch ref to whatever URL we forward, so a non-http protocol, query string,
+  // or fragment quietly mangles the resulting git remote. Reject those up front.
   if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
     throw new Error(`github_url must use http or https (got protocol "${parsed.protocol}")`);
   }
@@ -284,7 +295,8 @@ server.registerTool(
   "moor_status",
   {
     title: "List Projects",
-    description: "List all projects managed by Moor with their status, source, and domain.",
+    description:
+      "List all projects managed by Moor. `status` is moor's recorded state (only changes on explicit start/stop/build/cancel). `live_status` is Docker's view at last successful inspect; differences (e.g. recorded='running' live='error') mean moor missed an external change like a host docker stop, crash, or OOM kill. `live_error` non-null means the most recent inspect failed and the live_* values are the last successful snapshot, not necessarily current.",
   },
   async () => {
     const res = await apiGet("/api/projects");
@@ -293,6 +305,10 @@ server.registerTool(
     const summary = projects.map((p) => ({
       name: p.name,
       status: p.status,
+      live_status: p.live_status ?? null,
+      live_exit_code: p.live_exit_code ?? null,
+      live_checked_at: p.live_checked_at ?? null,
+      live_error: p.live_error ?? null,
       source: p.docker_image || p.github_url || null,
       domain: p.domain,
     }));
@@ -326,7 +342,7 @@ server.registerTool(
   {
     title: "Rebuild Project",
     description:
-      "Rebuild a project from source (git pull + docker build) and restart the container. Returns the build output.",
+      "Rebuild a project from source (git pull + docker build) and restart the container. Returns the build output when it finishes. While a build is in flight, the most recent moor_runs entry has finished_at=null — call moor_run_get on its id to tail the live output. Use moor_rebuild for code, Dockerfile, or base-image changes. For env vars / resource limits / port / volume / restart-policy changes, or to recover a crashed container from the existing image, use moor_restart — it skips the build and is much faster.",
     inputSchema: z.object({
       project: z.string().describe("Project name or ID"),
       no_cache: z.boolean().optional().default(false).describe("Build without Docker cache"),
@@ -346,7 +362,8 @@ server.registerTool(
   "moor_restart",
   {
     title: "Restart Project",
-    description: "Stop and start a project's container.",
+    description:
+      "Stop and recreate a project's container from its existing image. Does NOT pull from git or rebuild — uses the existing image_tag. Right tool for: applying changed env vars / resource limits / ports / volumes / restart policy, recovering a crashed container, or simply bouncing the process. Wrong tool for: code or Dockerfile changes (use moor_rebuild — those need a new image).",
     inputSchema: z.object({
       project: z.string().describe("Project name or ID"),
     }),
@@ -1264,7 +1281,7 @@ server.registerTool(
   {
     title: "List Project Run History",
     description:
-      "Paginated list of cron runs and build runs for a project. Returns one compact line per run (id, type, status, exit code, duration, output byte counts, timestamps) — stdout/stderr bodies are NOT included to avoid blowing token budgets on large build outputs. Use moor_run_get(run_id) to fetch the full output for a single run.",
+      "Paginated list of cron runs and build runs for a project. Returns one compact line per run (id, type, status, exit code, duration, output byte counts, timestamps) — stdout/stderr bodies are NOT included to avoid blowing token budgets on large build outputs. Use moor_run_get(run_id) to fetch the stored output for a single run (cron rows store full output; build/manual rows store at most a 64 KiB tail with the original total bytes recorded separately).",
     inputSchema: z.object({
       project: z.string().describe("Project name or ID"),
       page: z
@@ -1292,6 +1309,8 @@ server.registerTool(
         duration_ms: number | null;
         stdout_bytes: number;
         stderr_bytes: number;
+        stdout_total_bytes?: number;
+        stderr_total_bytes?: number;
       }>;
       total: number;
     };
@@ -1302,15 +1321,22 @@ server.registerTool(
     }
     const lines: string[] = [];
     lines.push(
-      `${p.name}: ${data.runs.length} run(s) on page ${page}, ${data.total} total. Use moor_run_get(run_id) for full output.`,
+      `${p.name}: ${data.runs.length} run(s) on page ${page}, ${data.total} total. Use moor_run_get(run_id) for stored output (build/manual rows are tail-truncated; total bytes shown below).`,
     );
     for (const r of data.runs) {
       const type = deriveRunType(r);
       const status = deriveRunStatus(r);
       const exit = r.exit_code != null ? ` exit=${r.exit_code}` : "";
       const cmd = r.cron_command ? ` cmd="${r.cron_command}"` : "";
+      // #65: surface "what was emitted" (total) per byte field. For live or
+      // already-truncated build runs total > stored; for crons and historical
+      // build rows they're equal. Showing total is the operationally useful
+      // number — "what did Docker actually produce" — and stays accurate as a
+      // build streams in. Fall back to stdout_bytes if the API is old.
+      const outTotal = r.stdout_total_bytes ?? r.stdout_bytes;
+      const errTotal = r.stderr_total_bytes ?? r.stderr_bytes;
       lines.push(
-        `id=${r.id} ${type} ${status}${exit} dur=${formatMsShort(r.duration_ms)} stdout=${r.stdout_bytes}B stderr=${r.stderr_bytes}B started=${r.started_at}${cmd}`,
+        `id=${r.id} ${type} ${status}${exit} dur=${formatMsShort(r.duration_ms)} stdout=${outTotal}B stderr=${errTotal}B started=${r.started_at}${cmd}`,
       );
     }
     return { content: [{ type: "text", text: lines.join("\n") }] };
@@ -1352,6 +1378,8 @@ server.registerTool(
       duration_ms: number | null;
       stdout: string | null;
       stderr: string | null;
+      stdout_total_bytes?: number | null;
+      stderr_total_bytes?: number | null;
     };
     const lines: string[] = [];
     const type = deriveRunType(r);
@@ -1361,18 +1389,55 @@ server.registerTool(
     if (r.cron_command) lines.push(`cron_command: ${r.cron_command}`);
     lines.push(`started_at: ${r.started_at}`);
     if (r.finished_at) lines.push(`finished_at: ${r.finished_at}`);
-    // runs.stdout/stderr is the full payload (no API-side truncation), so
-    // total bytes == stored bytes here. Using TextEncoder for byte length
-    // since JS String.length is UTF-16 code units, not UTF-8 bytes.
+    // #65: runs.stdout/stderr for build runs is a server-side 64 KiB tail
+    // (TAIL_CAP_BYTES). Use stdout_total_bytes / stderr_total_bytes when the
+    // API provides them so appendStream can honestly report "last X of Y".
+    // For cron rows the stored payload IS the full output, and total == stored.
+    // Fall back to encoded length for older APIs that don't return the totals.
     const stdoutStr = r.stdout ?? "";
     const stderrStr = r.stderr ?? "";
     const enc = new TextEncoder();
-    appendStream(lines, "stdout", stdoutStr, enc.encode(stdoutStr).length, cap);
-    appendStream(lines, "stderr", stderrStr, enc.encode(stderrStr).length, cap);
+    const stdoutTotal = r.stdout_total_bytes ?? enc.encode(stdoutStr).length;
+    const stderrTotal = r.stderr_total_bytes ?? enc.encode(stderrStr).length;
+    appendStream(lines, "stdout", stdoutStr, stdoutTotal, cap);
+    appendStream(lines, "stderr", stderrStr, stderrTotal, cap);
     return { content: [{ type: "text", text: lines.join("\n") }] };
   },
 );
 
+server.registerTool(
+  "moor_run_stop",
+  {
+    title: "Stop or Cancel a Run",
+    description:
+      "Stops an active cron run or cancels an active build/pull run (from moor_rebuild / moor_deploy). Closing the connection to the Docker build/pull endpoint aborts the daemon-side job. Cancellation is only valid during the build/pull streaming phase — once the build finishes and container start has begun, the call returns not_cancellable. Returns one of: cancelled, cancelled_cron, not_cancellable, already_finished, not_active, not_found. These are all expected outcomes, not errors — the tool throws only on unexpected server failures.",
+    inputSchema: z.object({
+      run_id: z.number().int().positive().describe("Run ID from moor_runs"),
+    }),
+  },
+  async ({ run_id }) => {
+    const res = await apiPost(`/api/runs/${run_id}/stop`);
+    // The /stop route returns 200 for cancelled/cancelled_cron and 4xx
+    // for the rest of the known result categories (with a result field
+    // either way). All of those are expected outcomes — render them as
+    // content so the agent can react without try/catch. Only surface as
+    // an error if the response doesn't fit the documented shape (server
+    // error, parse failure, etc).
+    let data: { ok?: boolean; result?: string; error?: string };
+    try {
+      data = (await res.json()) as { ok?: boolean; result?: string; error?: string };
+    } catch {
+      throw new Error(`run_id=${run_id} server error: ${res.status} ${res.statusText}`);
+    }
+    if (typeof data.result === "string") {
+      return { content: [{ type: "text", text: `run_id=${run_id} ${data.result}` }] };
+    }
+    throw new Error(
+      `run_id=${run_id} unexpected response: status=${res.status} body=${JSON.stringify(data)}`,
+    );
+  },
+);
+
 server.registerTool(
   "moor_deploy",
   {