@danwahl/antigravity-mcp 0.2.0 → 0.3.0

package/README.md

@@ -47,13 +47,18 @@ Verify with `claude mcp list`.
 
 ## Tool: `cli`
 
-| Parameter        | Type   | Required | Description |
-|------------------|--------|----------|-------------|
-| `prompt`         | string | yes      | Task or question to send to Antigravity |
-| `cwd`            | string | yes      | Absolute path to the working directory (agy's workspace) |
-| `model`          | string | no       | Model name. Omit for agy's default. `agy models` lists the options. |
-| `conversationId` | string | no       | Resume a previous conversation. Returned in the structured output of each call. Pass the same `cwd`, since conversations are workspace-scoped. |
-| `timeout`        | number | no       | Seconds before the run is killed. Default 120. |
+| Parameter        | Type    | Required | Description |
+|------------------|---------|----------|-------------|
+| `prompt`         | string  | yes      | Task or question to send to Antigravity |
+| `cwd`            | string  | yes      | Absolute path to the working directory (agy's workspace) |
+| `model`          | string  | no       | Model name, e.g. `gemini-3.1-pro-high`, `gemini-3.8-flash-medium`, `claude-sonnet-4-6`. Omit for agy's default. `agy models` lists the options. |
+| `effort`         | string  | no       | Reasoning effort: `low`, `medium`, or `high`. Omit for agy's default. |
+| `sandbox`        | boolean | no       | Default `true`. Shell commands can read anywhere but write only under `/tmp`; agy's file edit tools are unaffected. Set `false` for builds, installs, git commits, or tests that write to the workspace. |
+| `mode`           | string  | no       | `plan` or `accept-edits`. In headless mode plan review is auto-approved, so `plan` shapes the workflow but does not block edits. |
+| `agent`          | string  | no       | Custom agent name, defined at `.agents/agents/<name>.md` in the workspace or `~/.gemini/config/agents/`. |
+| `jsonSchema`     | object  | no       | JSON Schema enforced on the final answer. The parsed object comes back in `structuredOutput`. |
+| `conversationId` | string  | no       | Resume a previous conversation. Returned in the structured output of each call. Pass the same `cwd`, since conversations are workspace-scoped. |
+| `timeout`        | number  | no       | Seconds before the run is stopped. Default 120. On expiry the call returns an error; any partial response is in the structured output. |
 
 ### Structured output
 
@@ -70,7 +75,11 @@ Each call returns structured content alongside the text response:
     "thinkingTokens": 121,
     "cacheReadTokens": 0,
     "totalTokens": 12569
-  }
+  },
+  "structuredOutput": null,
+  "durationSeconds": 2.6,
+  "numTurns": 1,
+  "deniedActions": []
 }
 ```
 
@@ -78,7 +87,15 @@ Each call returns structured content alongside the text response:
 
 ### What Antigravity can do
 
-`agy` runs with `--dangerously-skip-permissions`, giving it full tool access: read/write files, run shell commands, web search, and more. The `cwd` you specify is passed as `--add-dir` so it becomes the agent's workspace; the spawn working directory alone is not enough in headless mode. Persisted `settings.json` permission rules still apply.
+`agy` runs with `--dangerously-skip-permissions`, giving it full tool access: read/write files, run shell commands, web search, and more. Headless agy cannot prompt for permission, so without this flag any tool needing approval is silently denied and the turn ends early. Deny rules in agy's own `settings.json` still apply; when one fires the call returns an error listing `deniedActions`.
+
+The `cwd` you specify is passed as `--add-dir` so it becomes the agent's workspace; the spawn working directory alone is not enough in headless mode.
+
+`--sandbox` is on by default as a check against the permission bypass. It restricts shell commands only: they can read anywhere but write only under `/tmp`. agy's file edit tools can still modify the workspace.
+
+### Timeouts and cancellation
+
+The `timeout` is passed to agy as `--print-timeout`, so agy stops its own turn at the deadline and returns whatever it has. The server reports that as an error with the partial response in the structured output. If agy fails to exit within a few seconds after that, its process group is killed. Cancelling the MCP call (for example, interrupting Claude Code) kills the agy process group immediately.
 
 ### Errors
 

package/dist/index.js

@@ -26,6 +26,9 @@ server.registerTool("cli", {
         "- Research and brainstorming: Antigravity has web search and a large context window, useful for exploring options or summarizing docs\n" +
         "- Large file analysis: processing files that would be expensive to handle directly\n" +
         "- Parallel workstreams: offloading independent subtasks while you continue other work\n\n" +
+        "Sandbox: on by default. Antigravity's file tools can still edit the workspace, but shell commands " +
+        "can only write under /tmp. Set `sandbox: false` for tasks whose shell commands must write to the " +
+        "workspace (builds, installs, git commits, test runs that produce files).\n\n" +
         "Conversation resumption: each response includes a `conversationId`. " +
         "Pass it back via the `conversationId` parameter (with the same `cwd`) to continue a conversation " +
         "without re-sending context — useful for multi-step tasks or follow-up questions.\n\n" +
@@ -42,7 +45,32 @@ server.registerTool("cli", {
             .string()
             .optional()
             .describe("Model to use. Omit to use Antigravity's default. " +
-            "Run `agy models` to list available model names."),
+            "Examples: \"gemini-3.1-pro-high\", \"gemini-3.1-pro-low\", \"gemini-3.8-flash-medium\", " +
+            "\"claude-sonnet-4-6\", \"claude-opus-4-6-thinking\". Run `agy models` for the full list."),
+        effort: z
+            .enum(["low", "medium", "high"])
+            .optional()
+            .describe("Reasoning effort for the session. Omit to use Antigravity's default."),
+        sandbox: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Run shell commands in a sandbox where they can read anywhere but write only under /tmp. " +
+            "File edit tools are unaffected. Default: true."),
+        mode: z
+            .enum(["accept-edits", "plan"])
+            .optional()
+            .describe("Agent execution mode. \"plan\" drafts an implementation plan before acting; in headless mode " +
+            "the plan is auto-approved, so this shapes the workflow but does not prevent edits."),
+        agent: z
+            .string()
+            .optional()
+            .describe("Name of a custom agent to run, defined at .agents/agents/<name>.md in the workspace " +
+            "or ~/.gemini/config/agents/. Omit for the default agent."),
+        jsonSchema: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("JSON Schema to enforce on the final answer. The parsed object is returned in `structuredOutput`."),
         conversationId: z
             .string()
             .optional()
@@ -52,31 +80,40 @@ server.registerTool("cli", {
             .number()
             .optional()
             .default(120)
-            .describe("Timeout in seconds. Default: 120. Increase for complex multi-step tasks."),
+            .describe("Timeout in seconds. Default: 120. Increase for complex multi-step tasks. " +
+            "On expiry the call returns an error with any partial response in the structured output."),
     },
     outputSchema: {
         conversationId: z.string().nullable().describe("Antigravity conversation ID"),
         response: z.string().describe("Antigravity's text response"),
         status: z.string().nullable().describe("Run status reported by agy (e.g. SUCCESS)"),
         usage: usageSchema.nullable().describe("Token usage for this turn"),
+        structuredOutput: z
+            .record(z.string(), z.unknown())
+            .nullable()
+            .describe("Parsed answer when `jsonSchema` was given"),
+        durationSeconds: z.number().nullable().describe("Wall-clock time of the run"),
+        numTurns: z.number().nullable().describe("Number of agent turns in the conversation"),
+        deniedActions: z.array(z.string()).describe("Tools agy was denied permission to use"),
     },
     annotations: {
         readOnlyHint: false,
         openWorldHint: true,
     },
-}, async ({ prompt, cwd, model, conversationId, timeout }) => {
+}, async ({ prompt, cwd, model, effort, sandbox, mode, agent, jsonSchema, conversationId, timeout }, extra) => {
     const timeoutMs = (timeout ?? 120) * 1000;
-    const result = await runAgy(prompt, cwd, model, timeoutMs, conversationId);
+    const result = await runAgy(prompt, cwd, timeoutMs, { model, effort, sandbox, mode, agent, jsonSchema, conversationId }, extra.signal);
+    const structuredContent = result.output;
     if (result.isError) {
         return {
             isError: true,
             content: [{ type: "text", text: result.errorMessage ?? "Unknown error" }],
-            structuredContent: result.output,
+            structuredContent,
         };
     }
     return {
         content: [{ type: "text", text: result.output.response }],
-        structuredContent: result.output,
+        structuredContent,
     };
 });
 async function runServer() {

package/dist/lib.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-export function buildAgyArgs(prompt, cwd, model, conversationId) {
+export function buildAgyArgs(prompt, cwd, opts = {}) {
     // The spawn cwd alone does not register a workspace in headless mode; without
     // --add-dir the agent is told it has no active workspace and works in its
     // own scratch directory.
@@ -10,34 +10,75 @@ export function buildAgyArgs(prompt, cwd, model, conversationId) {
         "--dangerously-skip-permissions",
         "--add-dir", cwd,
     ];
-    if (model) {
-        args.push("--model", model);
+    if (opts.sandbox ?? true) {
+        args.push("--sandbox");
     }
-    if (conversationId) {
-        args.push("--conversation", conversationId);
+    if (opts.model) {
+        args.push("--model", opts.model);
+    }
+    if (opts.effort) {
+        args.push("--effort", opts.effort);
+    }
+    if (opts.mode) {
+        args.push("--mode", opts.mode);
+    }
+    if (opts.agent) {
+        args.push("--agent", opts.agent);
+    }
+    if (opts.jsonSchema) {
+        args.push("--json-schema", JSON.stringify(opts.jsonSchema));
+    }
+    if (opts.conversationId) {
+        args.push("--conversation", opts.conversationId);
+    }
+    if (opts.timeoutMs) {
+        // Let agy wind down on its own at the deadline and return partial output;
+        // the caller's kill timer is only a backstop.
+        args.push("--print-timeout", `${Math.ceil(opts.timeoutMs / 1000)}s`);
     }
     return args;
 }
-const EMPTY_OUTPUT = { conversationId: null, response: "", status: null, usage: null };
+export const EMPTY_OUTPUT = {
+    conversationId: null,
+    response: "",
+    status: null,
+    usage: null,
+    structuredOutput: null,
+    durationSeconds: null,
+    numTurns: null,
+    deniedActions: [],
+};
 function numberOr(value, fallback) {
     return typeof value === "number" ? value : fallback;
 }
+function numberOrNull(value) {
+    return typeof value === "number" ? value : null;
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 function parseUsage(value) {
-    if (value === null || typeof value !== "object")
+    if (!isObject(value))
         return null;
-    const u = value;
     return {
-        inputTokens: numberOr(u.input_tokens, 0),
-        outputTokens: numberOr(u.output_tokens, 0),
-        thinkingTokens: numberOr(u.thinking_tokens, 0),
-        cacheReadTokens: numberOr(u.cache_read_tokens, 0),
-        totalTokens: numberOr(u.total_tokens, 0),
+        inputTokens: numberOr(value.input_tokens, 0),
+        outputTokens: numberOr(value.output_tokens, 0),
+        thinkingTokens: numberOr(value.thinking_tokens, 0),
+        cacheReadTokens: numberOr(value.cache_read_tokens, 0),
+        totalTokens: numberOr(value.total_tokens, 0),
     };
 }
+function parseDeniedActions(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((d) => (isObject(d) && typeof d.action === "string" ? d.action : null))
+        .filter((a) => a !== null);
+}
 export function parseAgyOutput(stdout) {
     const trimmed = stdout.trim();
     if (!trimmed) {
-        return EMPTY_OUTPUT;
+        return { ...EMPTY_OUTPUT };
     }
     let parsed;
     try {
@@ -46,18 +87,18 @@ export function parseAgyOutput(stdout) {
     catch {
         return { ...EMPTY_OUTPUT, response: trimmed };
     }
-    if (parsed === null || typeof parsed !== "object") {
-        return { ...EMPTY_OUTPUT, response: trimmed };
-    }
-    const obj = parsed;
-    if (typeof obj.response !== "string") {
+    if (!isObject(parsed) || typeof parsed.response !== "string") {
         return { ...EMPTY_OUTPUT, response: trimmed };
     }
     return {
-        conversationId: typeof obj.conversation_id === "string" ? obj.conversation_id : null,
-        response: obj.response,
-        status: typeof obj.status === "string" ? obj.status : null,
-        usage: parseUsage(obj.usage),
+        conversationId: typeof parsed.conversation_id === "string" ? parsed.conversation_id : null,
+        response: parsed.response,
+        status: typeof parsed.status === "string" ? parsed.status : null,
+        usage: parseUsage(parsed.usage),
+        structuredOutput: isObject(parsed.structured_output) ? parsed.structured_output : null,
+        durationSeconds: numberOrNull(parsed.duration_seconds),
+        numTurns: numberOrNull(parsed.num_turns),
+        deniedActions: parseDeniedActions(parsed.denied_actions),
     };
 }
 // agy prints a structured `AGY_ERROR: {...}` line on stderr for model/API failures.
@@ -76,15 +117,31 @@ export function extractAgyError(stderr) {
         return json;
     }
 }
-function errorResult(errorMessage) {
-    return { output: EMPTY_OUTPUT, isError: true, errorMessage };
+// On --print-timeout expiry agy exits 0 with status SUCCESS and a stderr notice.
+export function hitPrintTimeout(stderr) {
+    return /print timeout after .* with turn in progress/.test(stderr);
 }
-export function runAgy(prompt, cwd, model, timeoutMs, conversationId) {
+function errorResult(errorMessage, output = { ...EMPTY_OUTPUT }) {
+    return { output, isError: true, errorMessage };
+}
+// Classify a completed (exit 0) run. Exposed for testing.
+export function classifyRun(output, stderr, timeoutMs) {
+    if (hitPrintTimeout(stderr)) {
+        return errorResult(`agy timed out after ${timeoutMs / 1000}s; partial response returned in structured output`, output);
+    }
+    if (output.deniedActions.length > 0) {
+        return errorResult(`agy was denied permission for: ${output.deniedActions.join(", ")}. ` +
+            "Check permissions.deny rules in agy's settings.json.", output);
+    }
+    return { output, isError: false };
+}
+const KILL_GRACE_MS = 5000;
+export function runAgy(prompt, cwd, timeoutMs, opts = {}, signal) {
     if (!existsSync(cwd)) {
         return Promise.resolve(errorResult(`Working directory does not exist: ${cwd}`));
     }
     return new Promise((resolve) => {
-        const args = buildAgyArgs(prompt, cwd, model, conversationId);
+        const args = buildAgyArgs(prompt, cwd, { ...opts, timeoutMs });
         let child;
         try {
             child = spawn("agy", args, { cwd, env: process.env, detached: true });
@@ -111,20 +168,34 @@ export function runAgy(prompt, cwd, model, timeoutMs, conversationId) {
                 // group already gone
             }
         };
+        const terminate = () => {
+            killGroup("SIGTERM");
+            setTimeout(() => killGroup("SIGKILL"), KILL_GRACE_MS).unref();
+        };
         const finish = (r) => {
             if (settled)
                 return;
             settled = true;
             clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
             resolve(r);
         };
+        // Backstop: agy should exit on its own via --print-timeout, but if it doesn't
+        // (or grandchildren keep pipes open), kill the group and resolve without
+        // waiting for `close`.
         const timer = setTimeout(() => {
-            killGroup("SIGTERM");
-            setTimeout(() => killGroup("SIGKILL"), 5000).unref();
-            // Resolve immediately — don't wait for `close`, which may never fire
-            // if grandchildren keep stdio pipes open.
-            finish(errorResult(`agy timed out after ${timeoutMs / 1000}s`));
-        }, timeoutMs);
+            terminate();
+            finish(errorResult(`agy timed out after ${timeoutMs / 1000}s and was killed`));
+        }, timeoutMs + KILL_GRACE_MS);
+        const onAbort = () => {
+            terminate();
+            finish(errorResult("agy call was cancelled"));
+        };
+        if (signal?.aborted) {
+            onAbort();
+            return;
+        }
+        signal?.addEventListener("abort", onAbort, { once: true });
         child.stdout?.on("data", (chunk) => {
             stdout += chunk;
         });
@@ -138,14 +209,14 @@ export function runAgy(prompt, cwd, model, timeoutMs, conversationId) {
                 ? "agy binary not found. Install Antigravity CLI and make sure `agy` is on PATH."
                 : `Failed to spawn agy: ${err.message}`));
         });
-        child.on("close", (code, signal) => {
+        child.on("close", (code, sig) => {
             if (code !== 0) {
-                const how = code === null ? `signal ${signal}` : `code ${code}`;
+                const how = code === null ? `signal ${sig}` : `code ${code}`;
                 const detail = extractAgyError(stderr) || stderr.trim() || stdout.trim() || how;
                 finish(errorResult(`agy exited with ${how}: ${detail}`));
                 return;
             }
-            finish({ output: parseAgyOutput(stdout), isError: false });
+            finish(classifyRun(parseAgyOutput(stdout), stderr, timeoutMs));
         });
     });
 }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@danwahl/antigravity-mcp",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server that exposes Antigravity CLI (agy) as a single tool for Claude Code",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/danwahl/antigravity-mcp.git"
+    "url": "git+https://github.com/danwahl/antigravity-mcp.git"
   },
   "keywords": [
     "mcp",
@@ -24,12 +24,13 @@
     "antigravity-mcp": "dist/index.js"
   },
   "scripts": {
-    "build": "tsc && shx chmod +x dist/*.js",
+    "build": "rm -rf dist && tsc && shx chmod +x dist/*.js",
     "test": "node --import tsx/esm --test src/lib.test.ts",
     "prepublishOnly": "npm run build"
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/*.test.js"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.21.0",

package/dist/lib.test.js

@@ -1,145 +0,0 @@
-import { describe, it } from "node:test";
-import assert from "node:assert/strict";
-import { buildGeminiArgs, parseGeminiOutput, extractStructuredOutput, } from "./lib.ts";
-describe("buildGeminiArgs", () => {
-    it("omits --model when not provided", () => {
-        const args = buildGeminiArgs("hello", undefined);
-        assert.ok(!args.includes("--model"));
-    });
-    it("includes --model when provided", () => {
-        const args = buildGeminiArgs("hello", "gemini-2.5-pro");
-        const idx = args.indexOf("--model");
-        assert.ok(idx !== -1);
-        assert.equal(args[idx + 1], "gemini-2.5-pro");
-    });
-    it("passes model string through unchanged", () => {
-        const args = buildGeminiArgs("hello", "gemini-1.5-flash-001");
-        assert.equal(args[args.indexOf("--model") + 1], "gemini-1.5-flash-001");
-    });
-    it("includes --resume when sessionId provided", () => {
-        const args = buildGeminiArgs("x", undefined, "my-session-id");
-        const idx = args.indexOf("--resume");
-        assert.ok(idx !== -1);
-        assert.equal(args[idx + 1], "my-session-id");
-    });
-    it("omits --resume when sessionId not provided", () => {
-        const args = buildGeminiArgs("x", undefined);
-        assert.ok(!args.includes("--resume"));
-    });
-    it("includes --approval-mode yolo", () => {
-        const args = buildGeminiArgs("x", undefined);
-        const idx = args.indexOf("--approval-mode");
-        assert.ok(idx !== -1);
-        assert.equal(args[idx + 1], "yolo");
-    });
-    it("includes --output-format json", () => {
-        const args = buildGeminiArgs("x", undefined);
-        const idx = args.indexOf("--output-format");
-        assert.ok(idx !== -1);
-        assert.equal(args[idx + 1], "json");
-    });
-});
-describe("parseGeminiOutput", () => {
-    it("parses valid JSON response", () => {
-        const result = parseGeminiOutput(JSON.stringify({ response: "Hello, world!" }));
-        assert.equal(result.response, "Hello, world!");
-        assert.equal(result.sessionId, null);
-        assert.equal(result.stats, undefined);
-    });
-    it("extracts session_id", () => {
-        const result = parseGeminiOutput(JSON.stringify({ session_id: "abc-123", response: "ok" }));
-        assert.equal(result.sessionId, "abc-123");
-    });
-    it("extracts stats field", () => {
-        const stats = { models: {}, tools: {} };
-        const result = parseGeminiOutput(JSON.stringify({ response: "ok", stats }));
-        assert.deepEqual(result.stats, stats);
-    });
-    it("handles missing stats gracefully", () => {
-        const result = parseGeminiOutput(JSON.stringify({ response: "ok" }));
-        assert.equal(result.stats, undefined);
-    });
-    it("returns raw stdout when JSON parsing fails", () => {
-        const raw = "this is not json";
-        const result = parseGeminiOutput(raw);
-        assert.equal(result.response, raw);
-        assert.equal(result.sessionId, null);
-    });
-    it("returns raw stdout for JSON without response field", () => {
-        const raw = JSON.stringify({ message: "unexpected shape" });
-        const result = parseGeminiOutput(raw);
-        assert.equal(result.response, raw);
-    });
-    it("handles empty stdout", () => {
-        const result = parseGeminiOutput("");
-        assert.equal(result.response, "");
-    });
-    it("trims surrounding whitespace before parsing", () => {
-        const result = parseGeminiOutput("  " + JSON.stringify({ response: "trimmed" }) + "\n");
-        assert.equal(result.response, "trimmed");
-    });
-});
-describe("extractStructuredOutput", () => {
-    it("passes through sessionId and response", () => {
-        const output = { sessionId: "abc", response: "hello" };
-        const result = extractStructuredOutput(output);
-        assert.equal(result.sessionId, "abc");
-        assert.equal(result.response, "hello");
-    });
-    it("returns empty records when no stats", () => {
-        const output = { sessionId: null, response: "hi" };
-        const result = extractStructuredOutput(output);
-        assert.deepEqual(result.models, {});
-        assert.deepEqual(result.tools, {});
-    });
-    it("extracts model token totals", () => {
-        const output = {
-            sessionId: null,
-            response: "hi",
-            stats: {
-                models: {
-                    "gemini-2.5-pro": { tokens: { total: 100 } },
-                    "gemini-2.0-flash": { tokens: { total: 50 } },
-                },
-            },
-        };
-        assert.deepEqual(extractStructuredOutput(output).models, {
-            "gemini-2.5-pro": 100,
-            "gemini-2.0-flash": 50,
-        });
-    });
-    it("omits models with no token data", () => {
-        const output = {
-            sessionId: null,
-            response: "hi",
-            stats: { models: { "gemini-2.5-pro": {} } },
-        };
-        assert.deepEqual(extractStructuredOutput(output).models, {});
-    });
-    it("extracts tool call counts from byName", () => {
-        const output = {
-            sessionId: null,
-            response: "hi",
-            stats: {
-                tools: {
-                    byName: {
-                        list_directory: { count: 2 },
-                        web_fetch: { count: 1 },
-                    },
-                },
-            },
-        };
-        assert.deepEqual(extractStructuredOutput(output).tools, {
-            list_directory: 2,
-            web_fetch: 1,
-        });
-    });
-    it("returns empty tools when no tool calls", () => {
-        const output = {
-            sessionId: null,
-            response: "hi",
-            stats: { tools: { totalCalls: 0, byName: {} } },
-        };
-        assert.deepEqual(extractStructuredOutput(output).tools, {});
-    });
-});