内容
# 天空 MCP 服务器
克劳德与谷歌 **Antigravity 的 `agy` 命令行工具** 之间的桥梁 — 让克劳德代码（或任何 MCP 客户端）通过工具调用驱动 Antigravity 代理。
```mermaid
graph LR
A[克劳德代码] --> B[agy MCP 服务器]
B --> C[agy 命令行工具]
C --> D[Antigravity / Gemini]
style A fill:#FF6B35
style B fill:#4A90E2
style C fill:#00D4AA
style D fill:#FFA500
```
本项目镜像了 [`codex-mcp-server`](https://github.com/tuannvm/codex-mcp-server) 的架构，但包装的是 `agy` 而不是 `codex`。
## 工作原理
`agy` 暴露了一个非交互式的 **打印模式**：`agy -p "<提示>"` 运行一个单独的提示（提示是 `-p` 的值）并将响应打印到 **标准输出**。该服务器启动 `agy -p "<提示>"` 以提示作为参数，始终关闭标准输入，以便 `agy` 永远不会阻塞等待输入，并将标准输出作为 MCP 工具结果返回。（`agy` 仅在 `-p` 为空时从标准输入读取提示；裸 `-p` 而没有值会报错 "flag needs an argument"。）
## 要求
- **`agy` 命令行工具 v1.0.3+** 在您的 `PATH` 上（`agy --version`）。它随 Google Antigravity 交付。
- 您必须 **登录 Antigravity** — `agy` 重用桌面应用的凭证，因此此处没有 API 密钥需要配置。
## 安装
> 先决条件（所有方法）：`agy` 命令行工具（v1.0.3+）必须安装并登录 Antigravity 在运行 MCP 服务器的机器上。
### A) 通过 GitHub + npx（无需手动克隆）
```bash
claude mcp add agy-cli -- npx -y github:toonPt0473/agy-mcp-server
```
`npx` 克隆仓库并运行 `prepare` 脚本（`tsc`）以构建 `dist/`，然后启动服务器。需要 `git` 和 Node 在 `PATH` 上。
更新：升级仓库；npx 在下一次冷安装时重新获取（或清除 npx 缓存）。
### B) 从本地克隆
```bash
git clone https://github.com/toonPt0473/agy-mcp-server.git
cd agy-mcp-server
npm install # 自动通过 `prepare` 脚本运行构建
claude mcp add agy-cli -- node "$(pwd)/dist/index.js"
```
### C) 全局二进制文件（与源文件夹解耦）
```bash
npm install -g . # 在克隆的仓库中；暴露 `agy-mcp-server` 二进制文件
claude mcp add agy-cli -- agy-mcp-server
```
该仓库还附带了一个项目范围的 `.mcp.json`，指向 `dist/index.js`，当从项目目录运行时，克劳德代码会自动拾取。
## 工具
| 工具 | 描述 |
|------|-------------|
| `agy` | 通过 `agy -p`（打印模式）运行提示，可选模型，会话继续，额外目录，沙盒和跳过权限 |
| `models` | 列出可用于 agy 的模型（`agy models`） |
| `listSessions` | 查看活跃的对话会话 |
| `ping` | 测试服务器连接 |
| `help` | 获取 `agy --help` 输出 |
| `changelog` | 显示 `agy` 变更日志 / 发布说明 |
### `agy` 工具参数
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `prompt` | 字符串 | — （必填） | 任务/问题。传递为 `agy -p` 的值。 |
| `model` | 字符串 | — | 此调用的模型（`--model`）。使用 `models` 工具的名称，例如 `Claude Opus 4.6 (Thinking)`。省略使用 agy 的默认值（或 `AGY_MCP_DEFAULT_MODEL`）。 |
| `sessionId` | 字符串 | — | 多轮上下文。第一轮 = 新对话；后续轮次继续。 |
| `resetSession` | 布尔值 | `false` | 为此会话启动新的对话。 |
| `conversationId` | 字符串 | — | 恢复特定的 agy 对话（`--conversation <id>`）。 |
| `continueConversation` | 布尔值 | `false` | 强制 `agy --continue`（最近的对话）。 |
| `addDirs` | 字符串数组 | — | 额外的 工作区目录（`--add-dir`，可重复）。 |
| `sandbox` | 布尔值 | `false` | `--sandbox`（终端限制）。 |
| `skipPermissions` | 布尔值 | `false` | ⚠️ `--dangerously-skip-permissions` — 自动批准所有工具使用。需要 agy 无需人工干预即可运行工具。 |
| `printTimeout` | 字符串 | `5m` | `--print-timeout`（Go 时长，例如 `90s`，`1h30m`）。 |
## 示例
```
使用 agy 解释此仓库中的身份验证流程
使用 models 工具查看可用的 agy 模型
使用 agy 模型 "Claude Opus 4.6 (Thinking)" 审查此设计
使用 sessionId "refactor" 的 agy 分析此模块
使用 sessionId "refactor" 的 agy 现在实施更改 # 继续相同的对话
使用 skipPermissions true 和 addDirs ["./src"] 的 agy 重构和编写文件
```
## 选择模型
`agy` v1.0.5+ 支持选择模型。使用 `models` 工具（运行 `agy models`）列出可用模型，然后将确切的名称作为 `agy` 工具的 `model` 参数传递 — 名称包含空格/括号，并作为单个参数安全传递，例如 `Claude Opus 4.6 (Thinking)` 或 `Gemini 3.5 Flash (High)`。
优先级：每次调用的 `model` 参数 → `AGY_MCP_DEFAULT_MODEL` 环境变量 → 省略（agy 使用其自己的默认值）。未知模型名称不会被拒绝 — agy 恢复到其默认值。需要 `agy` ≥ v1.0.5（较旧版本没有 `--model` 标志）。
## 会话模型和限制
- `agy` 打印模式 **不** 发出对话 ID，因此在 `sessionId` 内进行多轮对话使用 `agy --continue`（继续 **最近** 的对话）。
- 由于 "最近" 是 `agy` 全局的，因此避免交织多个会话或在会话中间手动运行 `agy` — 继续可能会附加到错误的对话。为了精确恢复，请传递您从 Antigravity 应用获得的 `conversationId`。
- 没有 `skipPermissions: true`，使 `agy` 想要使用工具的提示可能会阻塞直到 `printTimeout`，因为无法非交互式地给予批准。使用 `skipPermissions` 进行代理/文件编写任务；对于问答，请关闭它。
## 环境变量
- `AGY_BIN` — `agy` 二进制文件的路径（默认值：`PATH` 上的 `agy`）。
- `AGY_MCP_DEFAULT_MODEL` — 未设置每次调用的 `--model` 时的默认值（默认值：无 → agy 自身的默认值）。
- `AGY_MCP_PRINT_TIMEOUT` — 未设置每次调用的 `--print-timeout` 时的默认值（默认值 `5m`）。
- `AGY_MCP_LOG_DIR` — 将对话日志记录到此目录（请参见下文）。
- `AGY_MCP_LOG_FILE` — 将对话日志记录到此单个文件（覆盖 `AGY_MCP_LOG_DIR`）。
- `STRUCTURED_CONTENT_ENABLED` — 在结果中发出 `structuredContent`（`1`/`true`/`yes`/`on`）。默认关闭； `_meta` 始终包含在克劳德代码中。
## 对话日志记录
每次 `agy` 工具调用（克劳德发送的提示和 `agy` 返回的响应）都可以追加到 **Markdown 成绩单**。日志记录 **默认关闭**；通过设置以下任意一个启用：
- `AGY_MCP_LOG_DIR=/path/to/dir` → 每天一个文件：`agy-conversations-YYYY-MM-DD.md`
- `AGY_MCP_LOG_FILE=/path/to/file.md` → 单个文件（优先）
在 `.mcp.json` 的 `env` 块中设置它，例如：
```json
{
"mcpServers": {
"agy-cli": {
"type": "stdio",
"command": "npx",
"args": ["-y", "github:toonPt0473/agy-mcp-server"],
"env": { "AGY_MCP_LOG_DIR": "/abs/path/to/project/.agy-logs" }
}
}
}
```
每个条目记录时间戳，模式（新建/继续/恢复），sessionId，对话 ID，持续时间，标志（沙盒/跳过权限/添加目录）和完整的提示和响应。日志记录失败报告到标准错误流，但永远不会破坏工具。 将日志目录添加到 `.gitignore`，如果您不想提交成绩单。
## 开发
```bash
npm install # 安装依赖
npm run dev # 从源代码运行并使用 tsx
npm run build # 编译到 dist/
npm test # 运行测试套件
npm run lint # eslint
npm run format # prettier
```
## 许可证
ISC
