Skip to main content
Glama

agy-mcp

License: MIT Python CI Tests

语言: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 落地路径、剩余可选项。
  • OpenAI Codex CLI:向 ~/.codex/config.toml 追加:

    [mcp_servers.agy]
    command = "agymcp"
    args = []

    重启 Codex 会话生效。

  • Cursor / Cline / Continue / 其它 MCP 客户端:在客户端的 MCP server 配置里加一条 name=agy、command=agymcp、transport=stdio 即可。具体语法各家不同,参考各自文档。

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


Related MCP server: Antigravity MCP Server

它是什么

把 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 工具

工具

用途

agy

同步一次性调用(PROMPT / cd / sandbox / SESSION_ID + mode / backend / output_protocol / worktree / allow_write / extra_env)

agy_continue

续 SESSION_ID

agy_start

后台启动长任务,立即返回 job_id

agy_status

查 job 状态:running / completed / failed / cancelled / upstream_error;job_id 可用唯一前缀

agy_read

读 job 事件流(raw / claude / codex 三协议);job_id 可用唯一前缀

agy_result

取已完成 job 的结果;不传 job_id 时返回最近完成任务;传参可用唯一前缀

agy_cancel

跨平台 process group 终止;job_id 可用唯一前缀

agy_sessions

列最近 session

agy_doctor

环境 + 鉴权 + capability 探测(不泄漏 secrets)

agy_install_skill

把 SKILL bundle 装到 Claude / Codex / Antigravity 目录

agy_purge

清理本机 session-store 目录(refuse days<=0)

何时调用 / 何时不调用

情景

建议路径

上下文里能直接答的 Q&A

不调,自己答

Bug 假设的第二意见

agy(..., mode="review")

给 review 用的 diff

agy(..., mode="prototype")(无 allow_write)

应用 reviewed diff

agy(..., mode="execute", allow_write=True)(自动 worktree)

数小时大重构

agy_start(..., mode="long") 然后轮询

需要 Anthropic / OpenAI 对话状态

不调 —— agy 是独立模型独立上下文

安全底线

  • 所有错误 / 日志 / 响应字段先过 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:

文档目录

文件

内容

docs/installation.md

安装 + Claude Code / Codex 注册 + SKILL + 验证

docs/architecture.md

模块图(caller / MCP server / bridge / supervisor / adapter / safety)

docs/output-strategy.md

Hybrid backend:stdout + klog + transcript.jsonl + 协议翻译器

docs/README_EN.md

English README

docs/README_ZH-TW.md

繁體中文 README

docs/README_JA.md

日本語 README

docs/security.md

威胁模型、防护清单、明确不防御项

docs/cli-capabilities.md

agy --help 实测 + capability 矩阵

docs/examples.md

7 个典型场景

docs/comparison-with-cli-wrappers.md

Stream-json passthrough vs Hybrid backend 两种 wrapper 模式对比

docs/release.md

PyPI trusted publishing + GitHub Release 发布手册(一次性设置 + 常规流程)

CHANGELOG.md

版本变更记录(Keep a Changelog)

开发

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.

Available Tools

11 tools
agyA

Run agy --print synchronously and return the assistant text + metadata. Compatible drop-in for the legacy gemini tool: same PROMPT / cd / sandbox / SESSION_ID / return_all_messages / model fields, with new mode / timeout / allow_write / worktree / backend / output_protocol options.

Inputs: PROMPT (required), cd, mode, debug, +11 more. Returns: Stable result envelope returned by the bridge CLI and MCP tools.

agy_cancelA

Signal a running job to stop by full job_id or unique prefix. Returns success=True, signalled=True if the worker was alive, signalled=False if it was unknown / already finished.

Inputs: job_id (required). Returns: Envelope returned by ``agy_cancel``.

agy_continueA

Continue an existing agy session. Identical to agy except SESSION_ID is required and the underlying adapter resumes the Antigravity conversation.

Inputs: PROMPT (required), SESSION_ID (required), cd, mode, +11 more. Returns: Stable result envelope returned by the bridge CLI and MCP tools.

agy_doctorA

Run capability + auth + session-store probes. Returns a structured report (no secrets) suitable for surfacing to a user via MCP. Pass force_refresh=true to drop the cached binary probe (use after upgrading the underlying agy / gemini CLI without restarting the MCP server).

Inputs: force_refresh. Returns: Envelope returned by ``agy_doctor``. ``report`` is a generic dict — DoctorRepor…

agy_install_skillA

Install the agy-mcp collaboration skill bundle into one or more agent platforms. targets may include 'claude', 'codex', 'antigravity', or 'all' (default expands to all three). User scope writes to ~/.claude/skills/, ~/.agents/skills/, and ~/.agy/skills/ respectively; project scope writes to .claude/skills/, .agents/skills/, and .antigravity/skills/ under the supplied project_root. Antigravity's wrapper-owned ~/.agy/ is used in user scope because the standing rule 'do not write under ~/.gemini/' rules out the Antigravity CLI's own state directory. force=False (the default) skips files whose on-disk body already matches; force=True rewrites every file unconditionally.

Inputs: force, scope, targets, project_root. Returns: Envelope returned by ``agy_install_skill``.

agy_purgeA

Delete session-store job directories whose mtime is older than days. Returns the removed job ids and a coarse count of remaining jobs. days must be a positive integer <= 3650; zero or negative values are rejected to avoid an accidental wipe via off-by-one config.

Inputs: days. Returns: Envelope returned by ``agy_purge``. ``removed`` carries the redacted job ids th…

agy_readB

Read events from a job's event log. since is the 0-based offset; translate may be 'raw', 'claude', or 'codex' to wire-format the events (default returns canonical events as dicts). job_id may be a full id or unique prefix.

Inputs: job_id (required), since, translate. Returns: Envelope returned by ``agy_read``. ``events`` is a list of generic dicts becaus…

agy_resultA

Return the captured output for a finished background job. Pass job_id (full id or unique prefix) to select a job, or omit it to use the latest finished job from agy_sessions. Set include_events=true to also return stored events; otherwise use agy_read for the full event log.

Inputs: since, job_id, include_events. Returns: Envelope returned by ``agy_result``.

agy_sessionsA

List recent jobs, newest first. limit defaults to 50; pass 0 for the full list.

Inputs: limit. Returns: Envelope returned by ``agy_sessions``.

agy_startA

Start an agy session in the background. Returns an envelope with status='running' and a job_id you can poll via agy_status / agy_read / agy_cancel.

Inputs: PROMPT (required), cd, mode, debug, +10 more. Returns: Stable result envelope returned by the bridge CLI and MCP tools.

agy_statusB

Return the JobRecord (status, exit code, error, timestamps) for a job_id or unique job-id prefix.

Inputs: job_id (required). Returns: Envelope returned by ``agy_status``.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: synchronous run vs background start vs continue, and job inspection is split into status, result, read, and sessions with descriptions that explain the boundaries. The overlap around job state/output is minimal and resolvable from the descriptions.

    Naming Consistency4/5

    Names are consistently snake_case with an agy_ prefix, except for the main tool named simply 'agy' as a legacy drop-in. The verb/noun mix (start, read, cancel vs status, result, sessions) is readable but not a single uniform pattern.

    Tool Count5/5

    Eleven tools is well-scoped for an MCP wrapper that manages background jobs, synchronous runs, sessions, diagnostics, and skill installation. Each tool appears to earn its place without obvious redundancy.

    Completeness4/5

    The surface covers the core job lifecycle: start, run, continue, status, read, result, cancel, list, and purge, plus diagnostics and skill installation. Minor gaps exist, such as no explicit single-job deletion or skill uninstall/update operation, but agents can work around them.

    Maintenance

    ActivitySlowing
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers