agy-mcp

语言：English · 繁體中文 · 日本語

把 Google Antigravity CLI（agy）包装成 11 个 typed MCP 工具， 任何 MCP 客户端（Claude Code / OpenAI Codex / Cursor / Cline / Continue …）都能直接调用。配套可选 Skill bundle，让支持 skill 的 平台学会何时调、用哪个 mode。

快速开始

# 1. 装 uv（已有可跳过）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 装 agy-mcp（从 PyPI）
uv tool install agy-mcp

# 3. 注册 MCP server（以 Claude Code 为例；其它客户端见折叠区）
claude mcp add agy -s user --transport stdio -- agymcp

# 4. （可选）装 SKILL，让 Claude / Codex / Antigravity 学会何时调
agy-install-skill --target all

# 5. 验证（不调真实 agy API）
agy-doctor

请帮我把 agy-mcp 这个开源 MCP 安装好。具体目标：

1. 用 uv tool 装本仓库的 console scripts（agymcp / agy-bridge /
   agy-doctor / agy-install-skill）。如果本机没有 uv，先用
   `curl -LsSf https://astral.sh/uv/install.sh | sh` 装好。
2. 把 agy MCP server 注册到我当前正在使用的 agent 平台：
   - 如果你是 Claude Code，执行：
     `claude mcp add agy -s user --transport stdio -- agymcp`
     并用 `claude mcp list` 确认 `agy: ✓ Connected`。
   - 如果你是 OpenAI Codex CLI，向 `~/.codex/config.toml` 追加：
     ```toml
     [mcp_servers.agy]
     command = "agymcp"
     args = []
     ```
     并重启 Codex 会话让其生效。
3. 装协作 SKILL（让本平台知道何时调用 agy）：直接调用刚才暴露的
   `agy_install_skill` MCP 工具，参数 `targets=["all"], scope="user"`。
   它会写到 `~/.claude/skills/`、`~/.agents/skills/`、`~/.agy/skills/`
   三处。装完后告诉我重启窗口让 SKILL 生效。
4. 验证：调用 `agy_doctor` MCP 工具，把返回的 JSON 完整贴给我看；
   预期 `healthy=true`，主要 check 全部 `ok=true`。如果 `auth` 这项
   显示未登录，告诉我手动跑一次 `agy --version` 触发 OAuth 流程，
   然后再调一次 `agy_doctor`。
5. 安装来源默认走 PyPI：`uv tool install agy-mcp`。如果我让你装某个
   未发布分支或本地 clone，再切到 `git+https://github.com/Boulea7/agy-mcp.git`
   或本地 `--from <项目本地绝对路径>`。

约束：
- 不要 push 任何东西、不要改我的 .gitconfig。
- 在没有我确认前不要调真实的 `agy` 模型（只能跑 doctor / dry-run）。
- 任何写入操作（包括上面这些）做之前先简短说一下要做什么，等我点头
  再执行；如果你的当前权限模式允许 acceptEdits，就直接执行。

每完成一步给我一行汇报，全部完成后给出一份 4 行总结：装在哪、11 个
MCP 工具是否齐、SKILL 落地路径、剩余可选项。

完整安装与故障排查 → docs/installation.md。

它是什么

把 Google 新发布的 Antigravity CLI（agy）包装成可被任意 MCP 客户端 调用的协作 agent backend。两条等价路径：

• MCP server：agymcp 经 FastMCP stdio 暴露 11 个 typed JSON 工具， pydantic envelope 稳定可解析。任何 MCP 客户端皆可。
• Skill bundles：装到 ~/.claude/skills/、~/.agents/skills/、 ~/.agy/skills/，教 agent 何时调 agy、用哪个 mode、注意哪些安全 规则。仅对 Claude Code / OpenAI Codex / Antigravity 三家有效。
• 共享 backend：两条路径都走同一 bridge.py → adapter → safety policy → worktree，行为一致。

除 agy_doctor 与 --dry-run 外，agy / agy_start 会启动真实 agy --print，可能消耗 Antigravity 请求额度。本项目只包装、路由、 隔离、审计，不重新实现 agy API。

11 个 MCP 工具

何时调用 / 何时不调用

安全底线

• 所有错误 / 日志 / 响应字段先过 SafetyPolicy.redact：/Users/<u>/ → ~/，PEM / JWT / AKID / Bearer 全脱敏；
• mode=execute 写入必须显式 allow_write=True；destructive prompt 即使置位仍拒；
• execute 模式下读 / 提及 ~/.ssh、~/.aws/credentials、浏览器 cookie、OS keychain 都拒；
• mode=execute + allow_write 默认 worktree=True（可经 ~/.config/agy-mcp/config.toml 或 AGY_MCP_WORKTREE_DEFAULT=0 关闭）；
• 不写任何文件到 ~/.gemini/（Antigravity CLI 自有状态目录）；user-scope antigravity skill 落在 ~/.agy/skills/。

完整威胁模型与「不防御」清单 → docs/security.md。

项目协议片段

直接复制到项目根的 CLAUDE.md / AGENTS.md：

• prompts/CLAUDE.md — Claude Code 协作协议
• prompts/AGENTS.md — OpenAI Codex 协作协议
• prompts/antigravity-system.md — agy 端 system prompt 建议

文档目录

开发

uv sync
uv run pytest        # 全量测试
uv run agymcp        # 启动 MCP stdio server（人工测试用）
uv run agy-bridge --cd . --PROMPT "Hello" --mode ask --dry-run --debug
uv run agy-doctor    # 环境与鉴权探测

License

MIT.