内容
# agy-mcp-server
版本：0.0.1
一个本地的STDIO MCP服务器，提供工具和可重复使用的提示，用于在受控的工作空间中运行Google Antigravity CLI（`agy`）。
## 链接
- 模型上下文协议（MCP）：https://modelcontextprotocol.io/
- FastMCP：https://github.com/PrefectHQ/fastmcp
- FastMCP 文档：https://gofastmcp.com/
- uv：https://github.com/astral-sh/uv
- uv 文档：https://docs.astral.sh/uv/
- Pydantic：https://github.com/pydantic/pydantic
- Pydantic 设置：https://github.com/pydantic/pydantic-settings
- Antigravity CLI（agy）：https://github.com/google-antigravity/antigravity-cli
## 为什么这个项目存在
> 很久以前，我开始使用Google Antigravity进行编程。它是最好的代理IDE。我取消了OpenAI订阅并购买了一年的Gemini Pro（感觉像是一个好交易）。之后，我们最喜欢的MegaCorp：
>
> - 改变了定价方式，使得发展中国家的开发者无法使用他们的产品
> - 用一个感觉像旧版削弱版的新版本替换了原本好用的模型
> - 随着Antigravity 2.0发布了史上最糟糕的升级，感觉像是一个为vibe coder准备的玩具IDE（并且它像Chevrolet Chevelle一样烧钱）
>
> 今天我醒来，Antigravity 2.0自动更新了，我感觉被骗了。由于不知道如何处理一年期的Pro计划，我决定构建这个MCP服务器，使我的计划可移植。现在我可以在任何代理IDE中使用我的Google计划。
>
> 这是自由。
>
> 现在您可以在任何IDE中使用antigravity-cli：
> - Cursor
> - Windsurf
> - Trae（我最喜欢的）
>
> 我不会就此止步。我将继续发展这个MCP服务器，并构建其他服务器以支持其他CLI（codex、claude、deepseek等）。
>
> 享受。
## 功能
**工具**
- `agy_health`：检查`agy`是否安装并返回其版本
- `agy_run_task`：运行同步（阻塞）任务
- `agy_start_task`：启动异步任务
- `agy_poll_task`：轮询异步任务
- `agy_cancel_task`：取消正在运行的任务
- `agy_list_runs`：列出最近的运行
- `agy_quota`：混合配额检查（本地计数器、故障分类器、可选探测、可选外部API）
- `agy_clear_cache`：清除`uv`缓存以恢复免受过时软件包错误的影响
- `agy_init_persistence`：创建`~/.open-cli-router/agy/`并附带可编辑的`AGENTS.md`、`PROJECTS.md`、`MEMORY.md`
- `agy_read_persistence`：读取三个持久性文件之一
- `agy_append_persistence`：追加内容（典型用法：会话后记忆）
- `agy_update_persistence`：通过标题锚点替换部分
- `agy_load_persistence_context`：加载截断的摘录作为会话上下文
**提示**
- `prompt_sync_orchestration`：`agy_run_task`的指导
- `prompt_async_orchestration`：`agy_start_task` → `agy_poll_task` → `agy_cancel_task`的指导
- `prompt_model_selection_guidance`：解释模型选择的工作原理及其局限性
- `prompt_security_and_workspace_rules`：总结工作空间和安全规则，供编排器使用
- `agy_persistence_protocol`：指导编排器如何维护持久性内存层
## 持久内存
该MCP服务器附带一个基于文件的持久层，位于`~/.open-cli-router/agy/`。编排器（Trae IDE）获取可编辑的Markdown文件，用于系统提示（`AGENTS.md`）、项目摘要（`PROJECTS.md`）和永久内存（`MEMORY.md`）。当启用时，服务器自动将这些文件的摘录添加到发送到`agy`的提示中，以便上下文在会话之间存活。参见[PLAN_PERSISTENCE.md](PLAN_PERSISTENCE.md)和[CONTRATO_TOOLS.md](CONTRATO_TOOLS.md)了解详情。
## 快速入门
先决条件：
- Python 3.11+
- 已安装uv
- 已安装并认证`agy`（运行`agy -i`一次并完成任何登录流程）
```bash
uv sync
uv run python -m fastmcp.cli run src/agy_mcp_server/server.py --transport stdio
```
运行测试：
```bash
uv sync --extra dev
uv run pytest
```
## 在Trae中使用此服务器
参见[USO_TRAE.md](USO_TRAE.md)。
## 配置
该服务器通过Pydantic设置（前缀`AGY_MCP_`）使用环境变量。
| 变量 | 描述 | 默认值 |
| --- | --- | --- |
| `AGY_MCP_ALLOWED_ROOTS` | 允许的工作空间根目录的JSON列表 | 当前`cwd` |
| `AGY_MCP_MODE` | `safe`或`permissive` | `safe` |
| `AGY_MCP_DEFAULT_TIMEOUT_S` | 默认超时（秒） | `300` |
| `AGY_MCP_MAX_OUTPUT_BYTES` | stdout/stderr捕获限制 | `2000000` |
| `AGY_MCP_FORCE_SANDBOX_IN_SAFE_MODE` | 在安全模式下强制使用沙箱 | `true` |
| `AGY_MCP_ALLOW_ENV_KEYS` | 允许的环境键的JSON列表（允许模式） | `[]` |
| `AGY_MCP_ALLOW_EXTRA_ARGS` | 允许的额外参数的JSON列表（允许模式） | `[]` |
本地配置：
```bash
cp .env.example .env
```
## Antigravity CLI模型选择
MCP服务器不控制每次运行`agy`使用的模型。模型在交互式CLI中选择，并在会话之间持续。
1) 启动交互式CLI：
```bash
agy -i
```
2) 输入`/model`：
```
> /model
> /model 设置模型
↑/↓ 导航 · enter 选择 · tab 完成
esc 取消
```
3) 选择模型（使用箭头键和Enter）。活动模型标记为`(current)`：
```
切换模型
Gemini 3.5 Flash (Medium) (当前)
Gemini 3.5 Flash (高)
Gemini 3.5 Flash (低)
Gemini 3.1 Pro (低)
> Gemini 3.1 Pro (高)
Gemini 3 Flash
键盘：↑/↓ 导航 enter 选择 esc 返回
```
模型设置存储在：
```
~/.gemini/antigravity/
```
## 安全
默认情况下为安全模式（`AGY_MCP_MODE=safe`）：
- 拒绝`env`
- 拒绝`extra_args`
- 拒绝`dangerously_skip_permissions`
- 可以强制使用沙箱
允许模式仍然强制执行显式允许列表：
- `AGY_MCP_ALLOW_ENV_KEYS`
- `AGY_MCP_ALLOW_EXTRA_ARGS`
参见[CONTRATO_TOOLS.md](CONTRATO_TOOLS.md)了解工具合同和可用提示。
## 故障排除
### `No module named fastmcp.__main__`
通过Python调用时使用`fastmcp.cli`（而不是`fastmcp`）：
```bash
python -m fastmcp.cli run src/agy_mcp_server/server.py --transport stdio
```
### `agy not found in PATH`
```bash
which agy
```
如果需要，设置`AGY_MCP_AGY_PATH`为`agy`二进制文件的完整路径。
### `workspace_path is outside allowed roots`
设置`AGY_MCP_ALLOWED_ROOTS`以包含工作空间根目录：
```bash
export AGY_MCP_ALLOWED_ROOTS='["/path/to/your/projects"]'
```
### `Unable to handle .../.venv`
这通常是由于编辑器的Python环境发现尝试加载无效的venv。重新创建环境并使用`uv sync`，并确保服务器配置指向正确的解释器（`.venv/bin/python`）。
