AGY Observer MCP

让 MCP 客户端调用 Antigravity CLI，并在本地窗口查看提问、公开回复和运行状态。

每次调用保存一份记录，可在本地窗口查看。 仅依赖 MCP Python SDK 与标准库，无需完整 PAL 环境或前端构建工具。当前版本 0.2.1 Alpha。

快速开始 · 连接 MCP · 使用方式 · 配置参考 · 设计说明 · 验证范围

主要功能

• 直观查看对话：调用前请求打开本地窗口，流式显示公开回复、警告信息与真实终态。

• 历史便于浏览：左侧历史列表与右侧对话区域独立滚动；离线测试与模拟记录默认隐藏。

• 按需启用执行：默认关闭模型执行；同一时间只允许一个模型调用，不自动重试或切换模型。

• 保留公开记录：每次调用均保存状态、公开事件和 Markdown 格式对话记录。

• 按需读取详情：列表仅拉取摘要；完整对话按选中项加载，事件明细展开后才读取。

本地页面为只读设计，不直接发送模型请求。“历史”为独立调用的记录集合；当前不支持沿同一远端会话自动续聊、文件上传或后台执行队列。

Related MCP server: agy-worker-mcp

快速开始

环境要求 Python 3.10+。发起真实调用需预先安装并登录官方 agy CLI；桌面 IDE 无法替代 CLI。克隆或下载仓库源码后，在项目根目录执行：

Windows PowerShell

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install .
.\.venv\Scripts\python.exe -m agy_observer.demo --state-dir ./state --port 8766 --open

Linux / macOS

python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/python -m agy_observer.demo --state-dir ./state --port 8766 --open

演示脚本仅写入合成模拟数据，不启动真实 CLI、不调用模型。窗口会明确标识“离线模拟”；按 Ctrl+C 退出。开发验证可在同一虚拟环境中运行：python -m unittest discover -s tests -v。

连接 MCP

将客户端配置指向所创建虚拟环境中的 Python，并替换为实际绝对路径。Windows 环境 Python 路径为 .venv\Scripts\python.exe；JSON 中反斜杠需转义，或统一使用正斜杠。

{
  "mcpServers": {
    "agy-observer": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "agy_observer.server"],
      "env": {
        "AGY_OBSERVER_ENABLED": "0",
        "AGY_OBSERVER_CLI": "/absolute/path/to/agy",
        "AGY_OBSERVER_WORKSPACE": "/absolute/path/to/empty-workspace",
        "AGY_OBSERVER_STATE_DIR": "/absolute/path/to/private-state"
      }
    }
  }
}

配置完成后重启客户端，建议先调用 agy_info 确认工具可用性。确认费用、工作目录与执行授权后，将 AGY_OBSERVER_ENABLED 改为 1 并重新启动 MCP 服务。模型请求可能产生费用，CLI 工具也可能执行外部操作；客户端仍需自行处理审批流程。

默认请求模型为 gemini-3.8-flash-low，实际可用性取决于账号权限与 CLI 配置。完整环境变量说明、WSL 配置指引及故障排查请参阅 配置参考。另可参考 通用 JSON 配置 与 Codex TOML 配置。

使用方式

例如在 MCP 客户端中输入：“请用 agy_run 解释这个函数的边界情况，只讨论，不修改文件。”调用开始前系统会请求打开本地窗口；执行完成后可通过返回的 run_id 查询详细信息。请注意，提示词中的“只讨论”不代表系统层面的强制权限隔离。

每次调用的记录保存在私有状态目录中：

runs/<run_id>/
  status.json     # 当前状态与完整公开问答
  events.jsonl    # 追加的公开事件
  transcript.md   # 结束时生成的可读记录

界面中的“离线测试”（早期记录可能标记为“夹具”）表示测试使用的预设数据或模拟进程，不是实际模型对话，需手动勾选后展示。页面心跳只表示仍在等待，不代表模型完成百分比。

从 0.1 升级

在 0.2 版本中，agy_history 优化为仅返回摘要信息，不再携带完整的 task、response 与 warnings 数据；请使用 task_preview 预览提问，并通过 agy_status(run_id) 按需拉取完整详情。已有的有效历史状态文件可继续读取。

验证与边界

离线测试覆盖 MCP 协议握手、执行门禁控制、严格事件流解析、双流限额、超时与取消控制、历史记录读取以及本地只读路由。已完成真实 MCP 调用；平台、测试结果与验证范围见 验证记录。

进程执行限制：CLI 请求限时 30 秒，外层捕获超时 40 秒，进程清理提供有限等待窗口；stdout 与 stderr 各设置 2 MiB 读取限额。注意：--mode plan --sandbox 参数不构成已验证的强制只读保证；跨平台下的进程组与进程树清理亦存在系统边界，详情请参阅 安全与隐私说明。

历史文件会以明文形式存储输入提示词与公开回复。请勿上传状态目录、CLI 登录 HOME、CLI 可执行文件、虚拟环境或真实对话内容。 本地 Web 服务严格绑定 127.0.0.1，请勿直接暴露至公网环境。

来源与许可证

本项目基于对 PAL MCP Server 的本地化适配成果整理重构，保留完整的 来源与改动说明，采用 Apache-2.0 许可证。本项目非 Google、PAL 或 OpenAI 官方产品。

参考文档：Antigravity Headless 事件规范 · MCP Python SDK 仓库。