内容
```text
____ _ _
/ ___| | __ _ _ _ __| | ___
| | | |/ _` | | | |/ _` |/ _ \
| |___| | (_| | |_| | (_| | __/
\____|_|\__,_|\__,_|\__,_|\___|
|
+----+----+
| MCP |
+----+----+
|
_ _ _ _ _
/ \ _ __ | |_(_) __ _ _ __ __ ___ _(_) |_ _ _
/ _ \ | '_ \| __| |/ _` | '__/ _` \ \ / / | __| | | |
/ ___ \| | | | |_| | (_| | | | (_| |\ V /| | |_| |_| |
/_/ \_\_| |_|\__|_|\__, |_| \__,_| \_/ |_|\__|\__, |
|___/ |___/
```
<div align="center">
**让 Claude（或任何 MCP 客户端）将其繁重的工作交给谷歌反重力（Google Antigravity）的 `agy` 代理。**
-4285F4?logo=google&logoColor=white)
</div>
---
## 什么是本项目？
**antigravity-mcp** 是一个小型 [MCP](https://modelcontextprotocol.io) （模型上下文协议）服务器。它公开了 **谷歌反重力（Google Antigravity）** —— 谷歌的终端编码代理，由 `agy` 命令行界面驱动（底层使用 Gemini）—— 作为一组工具，任何 MCP 客户端都可以调用。
其理念是：您的主要模型（Claude Desktop，Claude Code，Codex 等）保持轻量，并将 **繁重的工作** —— 网络搜索、整个仓库分析、脚手架文件、长时间运行的编辑等 —— 委托给在后台运行的第二个代理。任务是 **异步且无限制的**：您发送一个任务，立即获得一个 `jobId`，然后在调用者继续工作的同时轮询结果。
```
Claude / Codex 此 MCP 服务器 反重力
+---------------+ 工具 +----------------+ 启动 +--------------+
| "分析整个 | -----> | 使用反重力 | ------> | agy --print |
| 仓库" | | -> jobId(异步) | | （Gemini） |
+---------------+ <----- +----------------+ <------ +--------------+
继续工作 轮询结果 / 日志 执行工作
```
---
## 要求
| 需要 | 为什么 |
|------|-----|
| **Node.js 18+** | 运行此服务器（自带 `npx`/`npm`）。检查：`node --version` |
| **反重力 CLI（`agy`）** | 此服务器驱动的代理。以下安装。 |
| 一个 **MCP 客户端** | Claude Desktop，Claude Code，或任何支持 MCP 的客户端 |
---
## 步骤 1 — 安装反重力 CLI（`agy`）
> 从未使用过 `agy`？从这里开始。只需一个命令。首次启动使用 Google 登录。
**macOS / Linux**
```bash
curl -fsSL https://antigravity.google/cli/install.sh | bash
```
**Windows (PowerShell)**
```powershell
irm https://antigravity.google/cli/install.ps1 | iex
```
**Windows (CMD)**
```cmd
curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd
```
**它所在的位置（记住它 — 您可能需要它来设置 `AGY_PATH`）：**
| 操作系统 | 默认 `agy` 位置 |
|----|------------------------|
| macOS / Linux | `~/.local/bin/agy` |
| Windows | `C:\Users\<您>\AppData\Local\agy\bin\agy.exe` |
**登录和验证：**
```bash
agy # 首次运行会在浏览器中打开 Google 登录页面（凭证缓存在您的 OS 密钥环中）
agy --version # 应该打印版本号，例如 1.1.1
agy models # 列出可用的模型（Gemini 3.5 Flash，Gemini 3.1 Pro，...）
```
如果安装后找不到 `agy`，请打开一个新的终端（以重新加载 `PATH`）或运行 `agy install` 以修复 shell 路径。
---
## 步骤 2 — 获取此 MCP 服务器
**选项 A — npx（推荐，无需安装）：** 直接跳到步骤 3 并使用 `npx` 配置。npm 按需下载并运行它。
**选项 B — 从源代码（用于修改）：**
```bash
git clone https://github.com/TurkerYakup/mcp-server-google-antigravity.git
cd mcp-server-google-antigravity
npm install
npm test # 语法检查 + 启动烟雾测试
```
> `node-pty`（仅用于 Windows 上的干净输出）是一个 **可选** 依赖项 — 如果它在 macOS/Linux 上无法构建，安装仍将成功，服务器将自动回退。无需编译器。
---
## 步骤 3 — 在您的 MCP 客户端中注册它
<details open>
<summary><b>Claude Desktop</b></summary>
编辑您的 `claude_desktop_config.json`:
| 操作系统 | 配置文件 |
|----|-------------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
**使用 npx（选项 A）— 推荐：**
```json
{
"mcpServers": {
"antigravity": {
"command": "npx",
"args": ["-y", "antigravity-mcp"],
"env": {
"AGY_MODEL": "Gemini 3.5 Flash (Medium)",
"AGY_AUTO_APPROVE": "true"
},
"timeout": 900000
}
}
}
```
**从源代码（选项 B）：** 设置 `"command": "node"` 和 `"args": ["/绝对路径/到/mcp-server-google-antigravity/index.js"]` 代替。在 **Windows** 上使用正斜杠，例如 `"C:/Dev/Repos/mcp/index.js"`。
在编辑完成后完全重启应用程序（从托盘/菜单栏退出，而不是关闭窗口）。
</details>
<details>
<summary><b>Claude Code（CLI）</b> — 支持 macOS、Windows、Linux</summary>
```bash
# npx（选项 A）
claude mcp add antigravity -- npx -y antigravity-mcp
# 从源代码（选项 B）
claude mcp add antigravity -- node /绝对路径/到/mcp-server-google-antigravity/index.js
```
</details>
就这样。您的客户端现在拥有 `use_antigravity`、`antigravity_continue` 等工具。
---
## 配置（环境变量）
所有配置项均为可选 — 默认情况下有合理的默认值。
| 变量 | 默认值 | 功能 |
|-----|---------|--------------|
| `AGY_PATH` | 自动检测 | `agy` 二进制文件的完整路径。只有当它不在 `PATH` 中时才需要。 在 Windows 上，路径会自动折叠为 8.3 短路径，因此非 ASCII 用户名不再破坏任何内容。 |
| `AGY_MODEL` | agy 的默认值 | 调用未省略 `model` 时的默认模型。使用 `agy models` 中的确切名称，例如 `Gemini 3.5 Flash (Medium)`。 |
| `AGY_AUTO_APPROVE` | `true` | 传递 `--dangerously-skip-permissions` 以使无头作业不会因提示而挂起。设置为 `false` 以进行只读操作。 |
| `AGY_SANDBOX` | `false` | 使用 `--sandbox`（终端限制）运行每个作业。对于不受信任的提示，廉价且更安全。每个调用的 `sandbox` 覆盖。 |
| `AGY_PRINT_TIMEOUT` | `10m` | agy 的 `--print-timeout`。 |
| `AGY_HEARTBEAT_MS` | `15000` | “作业正在运行”的进度通知间隔。`0` 禁用。 |
| `AGY_MODEL_TTL_MS` | `300000` | 缓存的 `agy models` 列表的信任时间。 |
---
## 工具
| 工具 | 功能 |
|------|--------------|
| `use_antigravity` | 委托任务（异步）。立即返回 `jobId`。参数：`prompt`、`thinking_depth`（低/高）、`add_dirs`（agy 可以读取/写入的文件夹）、`auto_approve`、`new_project`、`model`、`mode`（计划/接受编辑）、`agent`、`project`、`sandbox`、`write_to_file`。 |
| `antigravity_continue` | 使用新提示继续上一次对话（或特定的 `conversation_id`）。 |
| `antigravity_result` | 通过 `jobId` 获取作业的结果 — 状态 `running` / `done` / `error` / `not_found`。 |
| `antigravity_jobs` | 列出最近的作业和状态。 |
| `antigravity_cancel` | 通过 `jobId` 终止正在运行的作业。 |
| `antigravity_cleanup` | 按年龄删除旧作业文件（`older_than_hours`）。 |
| `antigravity_create_folder` | 创建文件夹（递归），由服务器直接执行。 |
| `antigravity_create_file` | 创建/写入文本文件（创建父目录）；`overwrite:false` 以保护现有文件。 |
| `antigravity_create_tree` | 从 JSON 规范构建整个文件夹/文件树。 |
| `antigravity_read_file` | 读取 UTF-8 文本文件（即时）；可选 `max_bytes` 限制。 |
| `antigravity_list_dir` | 列出文件夹的条目。 |
| `antigravity_models` | 列出可用的模型（`agy models`）。 |
| `antigravity_agents` | 列出可用的代理配置文件（`agy agents`）。 |
| `antigravity_health` | 检查 `agy` 是否可达 + 报告有效默认值。**出现问题时首先运行此命令。** |
服务器端文件系统工具直接使用 Node 的 `fs` — 即时且不会因权限提示而阻塞。
---
## 实时进度通知
由于作业立即返回 `jobId`，服务器会推送 MCP **日志通知** (`notifications/message`，日志记录器 `antigravity`)，以便客户端无需轮询即可看到活动：
- `job started` — jobId、类型、提示片段
- `job running` — 每 `AGY_HEARTBEAT_MS`（默认为 15 秒）发送一次心跳，并附上当前部分输出的尾部
- `job done` / `job failed` — 最终状态、字节数 / 错误
最佳努力：如果客户端未协商 `logging` 功能，则会静默丢弃。轮询 `antigravity_result` 两种方式都有效。
---
## 工作原理（设计笔记）
`agy` CLI 运行单个提示，执行 `agy --print "<prompt>"`，完成后返回。三个问题及其解决方法：
1. **MCP 客户端请求超时（~60 秒）。** 长任务使客户端放弃，即使 `agy` 继续运行。 → **异步作业模式：** `use_antigravity` 在后台启动 `agy`，立即返回 `jobId`，将结果写入 OS 临时目录中的 JSON 文件（`agy_jobs/`），客户端轮询 `antigravity_result`。无需阻塞请求。
2. **agy 的自身打印超时（默认 5 分钟）。** 重提示达到 `timeout waiting for response`。 → 每个作业传递 `--print-timeout 10m`。
3. **无头文件权限门控。** 在 `--print` 模式下，agy 的文件写入被“询问”策略拒绝，作业挂起。 → `auto_approve`（默认为 true）传递 `--dangerously-skip-permissions`；`add_dirs` 传递 `--add-dir <path>` 以获取工作区。
---
## 安全说明
`auto_approve` 默认值为 **true** (`--dangerously-skip-permissions`) — agy 将在无提示的情况下创建/编辑文件并运行终端命令。这是故意的：在无头 `--print` 模式下，agy 否则会因权限提示而挂起。对于不受信任的提示，更喜欢 `sandbox: true`（终端限制，廉价 — 一个权限层，而不是 VM）而不是关闭自动批准。对于确实仅限读取的询问，仅使用 `auto_approve: false`。
---
## 平台支持
完全跨平台 — **macOS、Windows 和 Linux**。Windows 获取 `node-pty` 路径以实现干净的流式传输（如果不可用则自动回退），并自动将非 ASCII 用户名解析为 8.3 短路径；macOS/Linux 使用纯 `child_process`。每个 OS 的唯一区别是 `agy` 的位置和客户端配置文件的位置（两者都在上面介绍过）。
---
## License
MIT © Türker Yakup.
