# agy-mcp-server

一个零第三方 Python 运行依赖的 MCP stdio 服务，用于调用本机 `agy` CLI。支持同步执行、
超时自动转后台任务、会话续跑，以及任务状态和结果查询。

## 要求

- Python 3.9+
- macOS 或 Linux
- 已安装并能独立运行的 `agy`

服务不会读取或复制 OAuth token；认证由 `agy` 自身完成。

## 安装

直接使用源码：

```bash
git clone https://github.com/HackerWilson/agy-mcp-server.git
cd agy-mcp-server
python3 server.py
```

也可以安装命令行入口：

```bash
pipx install git+https://github.com/HackerWilson/agy-mcp-server.git
# 或
uv tool install git+https://github.com/HackerWilson/agy-mcp-server.git
```

## 配置

使用源码：

```json
{
  "mcpServers": {
    "antigravity": {
      "command": "python3",
      "args": ["/absolute/path/to/agy-mcp-server/server.py"]
    }
  }
}
```

使用 `pipx` 或 `uv tool` 安装后：

```json
{
  "mcpServers": {
    "antigravity": {
      "command": "agy-mcp-server",
      "args": []
    }
  }
}
```

MCP stdio 服务由客户端按需启动，并通过标准输入输出通信。直接执行后没有终端提示、一直等待
输入属于正常现象；客户端关闭连接后，服务进程也会退出。

如果客户端的环境变量中找不到 `agy`，可以显式指定路径：

```json
{
  "env": {
    "ANTIGRAVITY_MCP_AGY_PATH": "/absolute/path/to/agy"
  }
}
```

## 工具

- `run_antigravity`：同步执行新任务，达到等待阈值后返回后台 Job。
- `antigravity_continue`：续跑已有会话，同样支持超时降级。
- `antigravity_start`：直接启动异步任务。
- `antigravity_job_status`、`antigravity_job_result`、`antigravity_job_cancel`：管理后台任务。
- `antigravity_sessions`、`antigravity_transcript`：读取本机历史会话和执行轨迹。
- `antigravity_doctor`、`antigravity_models`：环境诊断和模型列表。

`read_only=true` 会启用 `agy --sandbox`，但这不是严格的文件系统只读保证。
`yolo=true` 会传递 `--dangerously-skip-permissions`，仅应在可信工作目录中使用。
`timeout_seconds` 只控制同步工具等待多久后返回后台 Job；`print_timeout_seconds` 控制
`agy` 任务本身的最长执行时间，默认为 3600 秒，可设置为 60–86400 秒。
续跑时可以传入完整会话 ID，也可以传入至少 8 位的十六进制前缀；短前缀只有在本机会话
数据库中唯一匹配时才会展开。完整 UUID 在本机数据库中不存在时会拒绝启动，避免 `agy`
忽略 `--conversation` 后静默创建新会话。任务完成后，状态和结果会分别显示请求/实际会话
ID、续跑判定和 turn 数。
`agy` 要求 prompt 作为 `-p` 的命令行参数；运行期间，本机同一用户的进程查看工具可能看到
prompt，因此不要在任务文本中直接放置密码或 token。单次 prompt 上限为 120 KiB。

Job 状态默认保存在 `~/.gemini/antigravity-mcp/jobs`。目录权限为 `0700`，文件权限为
`0600`；可通过 `ANTIGRAVITY_MCP_JOBS_DIR` 修改位置。

## 更新与卸载

```bash
# 源码安装
git -C /path/to/agy-mcp-server pull --ff-only

# pipx
pipx upgrade agy-mcp-server
pipx uninstall agy-mcp-server

# uv
uv tool upgrade agy-mcp-server
uv tool uninstall agy-mcp-server
```

源码更新不会热替换已经运行的 stdio MCP 进程；更新后需要让 MCP Client 断开并重新创建该
进程。若客户端会缓存失败或已断开的 MCP 通道，则需要重启客户端应用。

## 测试

```bash
python3 -m unittest -v
```

测试使用临时 fake `agy`，不会访问网络、读取认证信息或消耗模型额度。

## 参考

- https://github.com/x51xxx/antigravity-mcp-server
- https://github.com/chenhg5/cc-connect