@itoseo/agy-mcp/README.md

MCP Server for Antigravity CLI — 让 CodeX/Claude Code 调用 AGY 作为执行子代理

# @itoseo/agy-mcp

用于 **CodeX** 或 **Claude Code** 调用 **Antigravity CLI (agy)** 作为执行子代理的 MCP (Model Context Protocol) 服务。

## 定位与优势

- **CodeX / Claude Code**：负责高级思考、架构设计与决策规划。
- **AGY (Antigravity)**：作为执行子代理（Subagent），负责读取文件、执行代码、应用修改、运行终端等具体编码任务。成本低（默认使用 `Gemini 3.7 Flash (High)`），执行效率高。

---

## 核心特性

- ⚡ **并发安全与实时流式**：
  - **终端精准透传**：实时将 AGY 思考与生成内容通过 `stderr` 管道输出至控制台，并发任务自动携带专属短 ID 前缀（如 `[agy:6be7cb]`）。
  - **独立隔离日志**：每次调用分配唯一执行 ID，生成专属日志文件 `/tmp/agy-mcp/<executionId>.log`，彻底杜绝并行任务日志互相覆盖。
  - **便捷追踪最新任务**：自动更新软链接 `/tmp/agy-mcp/latest.log`，随时 `tail -f /tmp/agy-mcp/latest.log`。
  - **响应携带日志路径**：每次工具返回元数据中均包含专属 `log: /tmp/agy-mcp/...` 路径，方便针对单个任务进行排查。
  - **MCP 协议通知**：自动检测客户端 `progressToken` 并通过 `notifications/progress` 协议推送。
- 🎯 **显式模型控制**：默认始终显式传递 `--model "Gemini 3.7 Flash (High)"`，兼顾速度与推理质量。
- 🛡️ **安全自动化**：默认启用 `--dangerously-skip-permissions`（免除频繁确认）与 `--sandbox`（终端沙箱隔离）。
- 🔄 **会话连续性**：支持多轮对话（`agy_conversation`），可在同一个上下文内持续追问与迭代修改。

---

## 提供的 MCP 工具

### 1. `agy_prompt`
向 Antigravity 发送任务并获取响应。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|:---|:---|:---:|:---|:---|
| `prompt` | string | ✅ | - | 发送给 Antigravity 的任务描述 |
| `cwd` | string | ❌ | 当前目录 | 任务执行的工作目录（绝对路径） |
| `add_dirs` | string[] | ❌ | - | 额外添加到工作区的目录列表 |
| `mode` | string | ❌ | `accept-edits` | 执行模式：`accept-edits` 或 `plan` |
| `model` | string | ❌ | `Gemini 3.7 Flash (High)` | 指定 AI 模型 |
| `effort` | string | ❌ | `high` | 推理强度：`low` / `medium` / `high` |
| `timeout_seconds` | number | ❌ | `300` | 超时时间（秒） |

### 2. `agy_conversation`
延续已有的 Antigravity 对话上下文。

| 参数 | 类型 | 必填 | 说明 |
|:---|:---|:---:|:---|
| `conversation_id` | string | ✅ | 上一次 `agy_prompt` 返回的会话 ID |
| `prompt` | string | ✅ | 追加的指令或反馈 |
| `timeout_seconds` | number | ❌ | 超时时间（秒） |

### 3. `agy_models`
查询当前环境可用的 Antigravity AI 模型列表。

---

## 安装与使用

### 方式一：npx 直接运行（推荐，无需安装）

在 MCP 客户端配置中直接使用 `npx`，首次运行会自动下载。

### 方式二：全局安装

```bash
npm install -g @itoseo/agy-mcp
```

安装后可直接使用 `agy-mcp` 命令。

---

## 配置示例

### CodeX（TOML 格式）

在 `~/.codex/config.toml` 中添加：

**npx 方式：**
```toml
[mcp_servers.agy]
command = "npx"
args = ["@itoseo/agy-mcp"]
```

**全局安装方式：**
```toml
[mcp_servers.agy]
command = "agy-mcp"
```

### Claude Code / Cursor / AGY（JSON 格式）

在对应的 MCP 配置文件（如 `~/.claude/mcp_servers.json` 或 `~/.gemini/config/mcp_config.json`）中添加：

**npx 方式：**
```json
{
  "mcpServers": {
    "agy": {
      "command": "npx",
      "args": ["@itoseo/agy-mcp"]
    }
  }
}
```

**全局安装方式：**
```json
{
  "mcpServers": {
    "agy": {
      "command": "agy-mcp"
    }
  }
}
```

### 调试（MCP Inspector）

```bash
npx @modelcontextprotocol/inspector npx @itoseo/agy-mcp
```