@danwahl/antigravity-mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan Wahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# antigravity-mcp
+
+A minimal MCP server that exposes [Antigravity CLI](https://antigravity.google/) (`agy`) as a single tool callable from Claude Code (or any MCP client).
+
+This project started as `gemini-cli-mcp`, wrapping Gemini CLI. Gemini CLI is deprecated in favor of Antigravity, so the server now spawns `agy` instead. The tool interface is the same shape; see [Migrating from gemini-cli-mcp](#migrating-from-gemini-cli-mcp).
+
+## How it works
+
+Claude Code sends prompts to this server via MCP. The server spawns `agy -p "..."` in headless mode and returns the response. Antigravity inherits your Google sign-in, so no API key is required.
+
+```
+Claude Code ──MCP/stdio──▶ antigravity-mcp ──spawn──▶ agy -p "..." --output-format json --add-dir <cwd>
+```
+
+## Prerequisites
+
+- Antigravity CLI installed, on your `PATH` as `agy`, and signed in (run `agy` once interactively to complete login). Requires a version with headless JSON output (1.1.8 or later; tested against 1.2.7).
+
+## Installation
+
+### From source
+
+```sh
+git clone https://github.com/danwahl/antigravity-mcp
+cd antigravity-mcp
+npm install
+npm run build
+```
+
+## Configuration
+
+**User install** (available across all projects):
+
+```sh
+claude mcp add agy -s user -- npx -y @danwahl/antigravity-mcp
+```
+
+**Project install** (shared with your team via `.mcp.json`):
+
+```sh
+claude mcp add agy -s project -- npx -y @danwahl/antigravity-mcp
+```
+
+Or from source, replace `npx -y @danwahl/antigravity-mcp` with `node /absolute/path/to/antigravity-mcp/dist/index.js`.
+
+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. |
+
+### Structured output
+
+Each call returns structured content alongside the text response:
+
+```json
+{
+  "conversationId": "dc381a74-...",
+  "response": "Antigravity's answer...",
+  "status": "SUCCESS",
+  "usage": {
+    "inputTokens": 12447,
+    "outputTokens": 122,
+    "thinkingTokens": 121,
+    "cacheReadTokens": 0,
+    "totalTokens": 12569
+  }
+}
+```
+
+`agy`'s JSON output does not include per-tool call counts or a per-model breakdown, so those fields from the Gemini CLI version are gone.
+
+### 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.
+
+### Errors
+
+On a model or API failure `agy` prints an `AGY_ERROR: {...}` line to stderr and exits with code 3. The server surfaces the status and message from that line as the tool error.
+
+## Migrating from gemini-cli-mcp
+
+- `sessionId` is now `conversationId` (both the input parameter and the output field).
+- `models` and `tools` in the structured output are replaced by a single `usage` object.
+- Gemini CLI model aliases (`auto`, `pro`, `flash`, `flash-lite`) are not recognized; use a name from `agy models`.
+- Re-add the server under the new package name: `claude mcp remove gemini-cli` then the `claude mcp add` command above.
+
+## Development
+
+```sh
+npm run build   # compile with tsc
+npm test        # run unit tests
+```
+
+### Smoke test
+
+```sh
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js
+```
+
+## Design
+
+One tool, no prompt wrappers. Claude Code is the orchestrator: it decides what to ask Antigravity and how to phrase it. This server is a thin, reliable pipe between MCP and `agy -p`.
+
+See [CLAUDE.md](./CLAUDE.md) for project conventions.

package/dist/index.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createRequire } from "node:module";
+import { z } from "zod";
+import { runAgy } from "./lib.js";
+const { version } = createRequire(import.meta.url)("../package.json");
+const server = new McpServer({
+    name: "antigravity-mcp",
+    version,
+});
+const usageSchema = z.object({
+    inputTokens: z.number(),
+    outputTokens: z.number(),
+    thinkingTokens: z.number(),
+    cacheReadTokens: z.number(),
+    totalTokens: z.number(),
+});
+server.registerTool("cli", {
+    description: "Send a task to Antigravity CLI (agy) and return the response. " +
+        "Antigravity runs headlessly with full tool access (file read/write, web search, shell commands) " +
+        "and operates in the working directory you specify via `cwd`.\n\n" +
+        "When to use this tool:\n" +
+        "- Delegating rote coding tasks: boilerplate generation, repetitive refactors, bulk edits across many files\n" +
+        "- Getting a second opinion: code review, architecture feedback, sanity-checking an approach\n" +
+        "- 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" +
+        "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" +
+        "Keep prompts self-contained: include all necessary context in the `prompt` since " +
+        "Antigravity has no access to your conversation history or MCP state.",
+    inputSchema: {
+        prompt: z
+            .string()
+            .describe("The task or question to send to Antigravity CLI"),
+        cwd: z
+            .string()
+            .describe("Absolute path to the working directory (workspace) for Antigravity to operate in"),
+        model: z
+            .string()
+            .optional()
+            .describe("Model to use. Omit to use Antigravity's default. " +
+            "Run `agy models` to list available model names."),
+        conversationId: z
+            .string()
+            .optional()
+            .describe("Resume a previous conversation by ID. The ID is returned in the structured output of each call. " +
+            "Conversations are scoped to a workspace, so pass the same `cwd` as the original call."),
+        timeout: z
+            .number()
+            .optional()
+            .default(120)
+            .describe("Timeout in seconds. Default: 120. Increase for complex multi-step tasks."),
+    },
+    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"),
+    },
+    annotations: {
+        readOnlyHint: false,
+        openWorldHint: true,
+    },
+}, async ({ prompt, cwd, model, conversationId, timeout }) => {
+    const timeoutMs = (timeout ?? 120) * 1000;
+    const result = await runAgy(prompt, cwd, model, timeoutMs, conversationId);
+    if (result.isError) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: result.errorMessage ?? "Unknown error" }],
+            structuredContent: result.output,
+        };
+    }
+    return {
+        content: [{ type: "text", text: result.output.response }],
+        structuredContent: result.output,
+    };
+});
+async function runServer() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+runServer().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/lib.js

@@ -0,0 +1,151 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+export function buildAgyArgs(prompt, cwd, model, conversationId) {
+    // 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.
+    const args = [
+        "-p", prompt,
+        "--output-format", "json",
+        "--dangerously-skip-permissions",
+        "--add-dir", cwd,
+    ];
+    if (model) {
+        args.push("--model", model);
+    }
+    if (conversationId) {
+        args.push("--conversation", conversationId);
+    }
+    return args;
+}
+const EMPTY_OUTPUT = { conversationId: null, response: "", status: null, usage: null };
+function numberOr(value, fallback) {
+    return typeof value === "number" ? value : fallback;
+}
+function parseUsage(value) {
+    if (value === null || typeof value !== "object")
+        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),
+    };
+}
+export function parseAgyOutput(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed) {
+        return EMPTY_OUTPUT;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    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") {
+        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),
+    };
+}
+// agy prints a structured `AGY_ERROR: {...}` line on stderr for model/API failures.
+export function extractAgyError(stderr) {
+    const line = stderr.split("\n").find((l) => l.startsWith("AGY_ERROR:"));
+    if (!line)
+        return null;
+    const json = line.slice("AGY_ERROR:".length).trim();
+    try {
+        const parsed = JSON.parse(json);
+        const message = typeof parsed.message === "string" ? parsed.message : json;
+        const status = typeof parsed.status === "string" ? `${parsed.status}: ` : "";
+        return `${status}${message}`;
+    }
+    catch {
+        return json;
+    }
+}
+function errorResult(errorMessage) {
+    return { output: EMPTY_OUTPUT, isError: true, errorMessage };
+}
+export function runAgy(prompt, cwd, model, timeoutMs, conversationId) {
+    if (!existsSync(cwd)) {
+        return Promise.resolve(errorResult(`Working directory does not exist: ${cwd}`));
+    }
+    return new Promise((resolve) => {
+        const args = buildAgyArgs(prompt, cwd, model, conversationId);
+        let child;
+        try {
+            child = spawn("agy", args, { cwd, env: process.env, detached: true });
+        }
+        catch (err) {
+            resolve(errorResult(`Failed to spawn agy: ${String(err)}. Is Antigravity CLI installed?`));
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        // Decode as UTF-8 streams so multi-byte characters split across chunks survive.
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        // Kill the entire process group (agy + tool grandchildren).
+        // Without this, grandchildren can keep stdio pipes open and `close` never fires.
+        const killGroup = (sig) => {
+            if (child.pid === undefined)
+                return;
+            try {
+                process.kill(-child.pid, sig);
+            }
+            catch {
+                // group already gone
+            }
+        };
+        const finish = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(r);
+        };
+        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);
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", (err) => {
+            const isNotFound = err.code === "ENOENT" ||
+                err.message.includes("ENOENT");
+            finish(errorResult(isNotFound
+                ? "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) => {
+            if (code !== 0) {
+                const how = code === null ? `signal ${signal}` : `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 });
+        });
+    });
+}

package/dist/lib.test.js

@@ -0,0 +1,145 @@
+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, {});
+    });
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@danwahl/antigravity-mcp",
+  "type": "module",
+  "version": "0.2.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"
+  },
+  "keywords": [
+    "mcp",
+    "antigravity",
+    "agy",
+    "gemini",
+    "claude",
+    "llm",
+    "ai"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "antigravity-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/*.js",
+    "test": "node --import tsx/esm --test src/lib.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.21.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "shx": "^0.3.4",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.0"
+  }
+}