@moor-sh/mcp 0.4.1 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moor-sh/mcp",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "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

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 import { McpServer, StdioServerTransport } from "@modelcontextprotocol/server";
 import { z } from "zod";
+import { tailUtf8 } from "./tail-utf8";
 
 // --- Config ---
 
@@ -1042,6 +1043,172 @@ server.registerTool(
   },
 );
 
+// --- Async exec (#34 Phase B) ---
+
+server.registerTool(
+  "moor_exec_async",
+  {
+    title: "Start Async Exec",
+    description:
+      "Run a long-lived command inside a project's container, returning immediately with a run_id. Use moor_exec_status to poll for output and exit code; moor_exec_stop to terminate. Bounded by an optional timeout_ms (default 86400000 = 24h; min 60000 = 1 min; max 86400000). The recorded output is tail-truncated to the last 64 KiB per stream; stdout_total_bytes and stderr_total_bytes report the full pre-truncation byte count.",
+    inputSchema: z.object({
+      project: z.string().describe("Project name or ID"),
+      command: z.string().min(1).describe("Shell command to execute"),
+      timeout_ms: z
+        .number()
+        .int()
+        .min(60_000)
+        .max(86_400_000)
+        .optional()
+        .describe(
+          "Safety timeout in milliseconds. When exceeded, the process tree is terminated and the run is marked timed_out. Default 86400000 (24h). Min 60000. Max 86400000.",
+        ),
+    }),
+  },
+  async ({ project, command, timeout_ms }) => {
+    const p = await resolveProject(project);
+    const body: Record<string, unknown> = { command };
+    if (timeout_ms !== undefined) body.timeout_ms = timeout_ms;
+    const res = await apiPost(`/api/projects/${p.id}/exec/async`, body);
+    if (!res.ok) throw new Error(`Failed: ${await res.text()}`);
+    const data = (await res.json()) as { run_id: number };
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Started async exec on ${p.name}. run_id=${data.run_id}. Use moor_exec_status to poll; moor_exec_stop to terminate.`,
+        },
+      ],
+    };
+  },
+);
+
+server.registerTool(
+  "moor_exec_status",
+  {
+    title: "Get Async Exec Status",
+    description:
+      "Return the current state of an async exec run: state, exit code (when finished), running tail of stdout/stderr (default 8 KiB each inline; the API stores up to 64 KiB), total bytes seen, duration, and any error message. State is one of: running, exited, stopped, timed_out, error. Pass tail_bytes to control how many bytes of each stream are returned inline (0 to 65536; default 8192). The API's 64 KiB-per-stream storage cap is unchanged — tail_bytes only controls what the MCP tool returns to keep responses under typical agent token limits.",
+    inputSchema: z.object({
+      run_id: z.number().int().positive().describe("Run ID returned by moor_exec_async"),
+      tail_bytes: z
+        .number()
+        .int()
+        .min(0)
+        .max(65_536)
+        .optional()
+        .describe(
+          "Max bytes of each stream (stdout, stderr) returned inline. Default 8192. Max 65536 (the API storage cap). Set to 0 for metadata-only.",
+        ),
+    }),
+  },
+  async ({ run_id, tail_bytes }) => {
+    const cap = tail_bytes ?? 8192;
+    const res = await apiGet(`/api/exec/${run_id}`);
+    if (res.status === 404) throw new Error(`run_id ${run_id} not found`);
+    if (!res.ok) throw new Error(`Failed: ${await res.text()}`);
+    const data = (await res.json()) as {
+      id: number;
+      state: string;
+      exit_code: number | null;
+      stdout: string;
+      stderr: string;
+      stdout_total_bytes: number;
+      stderr_total_bytes: number;
+      duration_ms: number;
+      command: string;
+      killed_pid: string | null;
+      error_message: string | null;
+      started_at: string;
+      finished_at: string | null;
+    };
+    const lines: string[] = [];
+    lines.push(
+      `run_id=${data.id} state=${data.state} duration=${formatMs(data.duration_ms)}` +
+        (data.exit_code !== null ? ` exit_code=${data.exit_code}` : ""),
+    );
+    lines.push(`command: ${data.command}`);
+    if (data.killed_pid) lines.push(`killed_pid: ${data.killed_pid}`);
+    if (data.error_message) lines.push(`error: ${data.error_message}`);
+    appendStream(lines, "stdout", data.stdout, data.stdout_total_bytes, cap);
+    appendStream(lines, "stderr", data.stderr, data.stderr_total_bytes, cap);
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  },
+);
+
+function appendStream(
+  lines: string[],
+  name: string,
+  raw: string,
+  totalBytes: number,
+  cap: number,
+): void {
+  if (!raw && totalBytes === 0) return;
+  if (!raw) {
+    // API returned an empty string but the stream did emit data (totalBytes > 0
+    // is possible when no bytes survived API-side tail cap, though unlikely).
+    lines.push(`${name}_total_bytes=${totalBytes}`);
+    return;
+  }
+  const { tail, storedBytes, trimmed: mcpTrimmed } = tailUtf8(raw, cap);
+  const apiTrimmed = totalBytes > storedBytes;
+  let header: string;
+  if (mcpTrimmed && apiTrimmed) {
+    header = `${name} (showing last ${tail.length} chars of ${storedBytes} stored bytes; ${totalBytes} total bytes seen):`;
+  } else if (mcpTrimmed) {
+    header = `${name} (showing last ${tail.length} chars of ${storedBytes} total bytes):`;
+  } else if (apiTrimmed) {
+    header = `${name} (tail of ${storedBytes} stored from ${totalBytes} total bytes seen):`;
+  } else {
+    header = `${name}:`;
+  }
+  lines.push(header);
+  if (cap > 0) lines.push(tail);
+}
+
+server.registerTool(
+  "moor_exec_stop",
+  {
+    title: "Stop Async Exec",
+    description:
+      "Terminate a running async exec by run_id. Walks the descendant process tree inside the container and sends SIGTERM then SIGKILL. Always transitions the run to a terminal state: state=stopped on clean termination (all descendants gone), state=error if any descendant survived OR if the kill handle was lost (moor restart, missing pidfile). Stop is NOT retry-safe — the kill script removes the pidfile after every attempt, and reparented survivors are unreachable from the original PID.",
+    inputSchema: z.object({
+      run_id: z.number().int().positive().describe("Run ID returned by moor_exec_async"),
+    }),
+  },
+  async ({ run_id }) => {
+    const res = await apiPost(`/api/exec/${run_id}/stop`);
+    if (res.status === 404) throw new Error(`run_id ${run_id} not found`);
+    const data = (await res.json()) as {
+      ok: boolean;
+      state: string;
+      killed_pid: string | null;
+      live_remaining: number;
+      message: string;
+    };
+    return {
+      content: [
+        {
+          type: "text",
+          text: `run_id=${run_id} state=${data.state} ${data.message}`,
+        },
+      ],
+    };
+  },
+);
+
+function formatMs(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  const rs = s % 60;
+  if (m < 60) return `${m}m${rs}s`;
+  const h = Math.floor(m / 60);
+  const rm = m % 60;
+  return `${h}h${rm}m${rs}s`;
+}
+
 // --- Start ---
 
 const transport = new StdioServerTransport();

package/src/tail-utf8.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import { tailUtf8 } from "./tail-utf8";
+
+describe("tailUtf8", () => {
+  test("returns the string unchanged when under maxBytes", () => {
+    const r = tailUtf8("hello", 100);
+    expect(r.tail).toBe("hello");
+    expect(r.storedBytes).toBe(5);
+    expect(r.trimmed).toBe(false);
+  });
+
+  test("returns the last maxBytes bytes for ASCII input", () => {
+    const r = tailUtf8("0123456789", 4);
+    expect(r.tail).toBe("6789");
+    expect(r.storedBytes).toBe(10);
+    expect(r.trimmed).toBe(true);
+  });
+
+  test("returns an empty string when maxBytes is 0", () => {
+    const r = tailUtf8("hello", 0);
+    expect(r.tail).toBe("");
+    expect(r.storedBytes).toBe(5);
+    expect(r.trimmed).toBe(true);
+  });
+
+  test("preserves complete trailing multi-byte codepoints", () => {
+    // "café" = c(1) a(1) f(1) é(2) = 5 bytes. Cap at 4 → trim "c", landing
+    // on "a" boundary; result "afé" (4 bytes).
+    const r = tailUtf8("café", 4);
+    expect(r.tail).toBe("afé");
+    expect(r.storedBytes).toBe(5);
+    expect(r.trimmed).toBe(true);
+    expect(r.tail).not.toContain("\ufffd");
+  });
+
+  test("aligns to a codepoint boundary when the cut falls inside a 2-byte sequence", () => {
+    // "héllo" = h(1) é(2) l(1) l(1) o(1) = 6 bytes. Cap at 4 → start at
+    // byte 2, which is the continuation of é. Align forward to "llo" (3 bytes).
+    const r = tailUtf8("héllo", 4);
+    expect(r.tail).toBe("llo");
+    expect(r.storedBytes).toBe(6);
+    expect(r.tail).not.toContain("\ufffd");
+  });
+
+  test("aligns to a codepoint boundary inside a 3-byte sequence", () => {
+    // "€€€" = 9 bytes (each € = 3 bytes). Cap at 4 → start at byte 5, which
+    // is a continuation. Align forward to start of last € → "€" (3 bytes).
+    const r = tailUtf8("€€€", 4);
+    expect(r.tail).toBe("€");
+    expect(r.storedBytes).toBe(9);
+    expect(r.tail).not.toContain("\ufffd");
+  });
+
+  test("aligns inside a 4-byte sequence (surrogate pair codepoint)", () => {
+    // "🌍🌍" = 8 bytes (each emoji = 4 bytes). Cap at 5 → start at byte 3,
+    // continuation. Align forward to start of last emoji → "🌍" (4 bytes).
+    const r = tailUtf8("🌍🌍", 5);
+    expect(r.tail).toBe("🌍");
+    expect(r.storedBytes).toBe(8);
+    expect(r.tail).not.toContain("\ufffd");
+  });
+
+  test("reports storedBytes as the original UTF-8 byte length, not JS char length", () => {
+    // "🌍" is 1 codepoint but 4 UTF-8 bytes (and 2 UTF-16 code units in JS).
+    const r = tailUtf8("🌍", 100);
+    expect(r.storedBytes).toBe(4);
+    expect(r.tail.length).toBe(2); // JS string length counts UTF-16 code units
+  });
+});

package/src/tail-utf8.ts

@@ -0,0 +1,25 @@
+// Byte-aware UTF-8 tail-trim used by moor_exec_status (#44). The MCP tool
+// can't return the full API tail (up to 64 KiB per stream) inline because
+// large responses blow agent token budgets. Caller picks how many bytes per
+// stream they want; the trim is UTF-8 safe — the result never starts mid-
+// codepoint, which would cause TextDecoder to emit U+FFFD at the head.
+
+export function tailUtf8(
+  s: string,
+  maxBytes: number,
+): { tail: string; storedBytes: number; trimmed: boolean } {
+  const bytes = new TextEncoder().encode(s);
+  const storedBytes = bytes.length;
+  if (storedBytes <= maxBytes) return { tail: s, storedBytes, trimmed: false };
+  if (maxBytes === 0) return { tail: "", storedBytes, trimmed: true };
+  // Start at the offset that leaves maxBytes bytes; walk forward past any
+  // UTF-8 continuation bytes (10xxxxxx) so the decoded tail begins on a
+  // codepoint boundary.
+  let start = storedBytes - maxBytes;
+  while (start < storedBytes && (bytes[start] & 0xc0) === 0x80) start++;
+  return {
+    tail: new TextDecoder("utf-8", { fatal: false }).decode(bytes.subarray(start)),
+    storedBytes,
+    trimmed: true,
+  };
+}