内容
# Antigravity to Codex
Antigravity 到 Codex 的只读 MCP（模型上下文协议）适配器。
Read-only MCP (Model Context Protocol) adapter for running the local Antigravity CLI from Codex.
## 项目简介 | Overview
这个项目让 Codex 可以调用本地 Antigravity CLI（命令行工具）进行代码库扫描、调用链查找、配置检查和测试结果整理。适配器只负责收集证据，不修改目标代码。
This project allows Codex to use the local Antigravity CLI for repository scans, call-chain searches, configuration checks, and test triage. The adapter only gathers evidence and does not modify the target repository.
适配器会以计划模式和沙箱限制启动 Antigravity，捕获正常输出和错误输出，并要求返回结构化报告后才标记为成功。
The adapter starts Antigravity in plan mode with sandbox restrictions, captures stdout and stderr, and only reports success when a structured report is returned.
## 工具 | Tools
- `run_antigravity_readonly`: 执行一次有时间限制的扫描并等待最终报告。
- `start_antigravity_readonly`: 启动异步扫描并返回任务编号。
- `get_antigravity_result`: 查询异步任务，返回部分输出或最终报告。
- `cancel_antigravity_job`: 取消正在运行的任务。
- `run_antigravity_readonly`: Run a bounded scan and wait for the final report.
- `start_antigravity_readonly`: Start an asynchronous scan and return a job id.
- `get_antigravity_result`: Poll an asynchronous job for partial or final output.
- `cancel_antigravity_job`: Cancel a running job.
## 环境要求 | Requirements
- Windows 和 Python 3.10 或更高版本。
- 已安装并完成登录的 Antigravity CLI（`agy.exe`）。
- 可用的网络连接，或通过 `ANTIGRAVITY_PROXY_URL` 配置本地代理。
- Windows with Python 3.10 or newer.
- The Antigravity CLI (`agy.exe`) installed and authenticated.
- A working network connection, or a local proxy configured through `ANTIGRAVITY_PROXY_URL`.
适配器会先查找 `ANTIGRAVITY_CLI`，然后查找系统 `PATH`（系统命令搜索路径）和 Windows 默认安装路径。
The adapter checks `ANTIGRAVITY_CLI` first, then searches `PATH` and the default Windows installation path.
## 配置 | Configuration
环境变量 | Environment variables:
| 变量 | 用途 | 默认值 | Variable | Purpose | Default |
| --- | --- | --- | --- | --- | --- |
| `ANTIGRAVITY_CLI` | `agy.exe` 的完整路径 | Windows 默认路径或 `PATH` | `ANTIGRAVITY_CLI` | Full path to `agy.exe` | Windows default path or `PATH` |
| `ANTIGRAVITY_MODEL` | Antigravity 模型名称 | `claude-sonnet-4-6` | `ANTIGRAVITY_MODEL` | Antigravity model name | `claude-sonnet-4-6` |
| `ANTIGRAVITY_PROXY_URL` | HTTP/HTTPS 代理地址 | 空 | `ANTIGRAVITY_PROXY_URL` | HTTP/HTTPS proxy URL | Empty |
| `ANTIGRAVITY_NO_PROXY` | 不经过代理的主机 | `localhost,127.0.0.1` | `ANTIGRAVITY_NO_PROXY` | Hosts that bypass the proxy | `localhost,127.0.0.1` |
| `ANTIGRAVITY_ALLOWED_ROOTS` | 允许扫描的目录，多个路径用分号分隔 | 不限制 | `ANTIGRAVITY_ALLOWED_ROOTS` | Allowed repository roots, separated by semicolons | Any directory |
### Codex 配置示例 | Codex configuration example
```toml
[mcp_servers.antigravity_readonly]
type = "stdio"
command = "C:\\Windows\\py.exe"
args = ["-3", "C:\\path\\to\\antigravity-to-codex\\server.py"]
startup_timeout_sec = 30
[mcp_servers.antigravity_readonly.env]
ANTIGRAVITY_PROXY_URL = "http://127.0.0.1:7890"
```
修改 MCP（模型上下文协议）路径后，需要重启 Codex，让它启动新的服务进程。
After changing the MCP path, restart Codex so it starts a new server process.
## 使用方式 | Usage
### 同步调用 | Synchronous call
当当前任务需要在结束前拿到最终报告时，使用 `run_antigravity_readonly`。它会等待 CLI 完成，并把报告直接放在工具返回内容中。
Use `run_antigravity_readonly` when the final report is needed before the current task can finish. It waits for the CLI and returns the report in the tool result.
### 异步调用 | Asynchronous call
只有在 Codex 可以继续处理独立工作时，才使用异步工具对：
Use the asynchronous pair only when Codex can continue independent work:
1. 调用 `start_antigravity_readonly`，记录 `job_id`（任务编号）。
2. 持续调用 `get_antigravity_result`，直到状态变为 `success`、`incomplete`、`failed`、`timeout` 或 `cancelled`。
3. 不能把 `queued`、`running`、只有启动提示的输出或未知任务编号当作最终报告。
1. Call `start_antigravity_readonly` and record the `job_id`.
2. Poll `get_antigravity_result` until the status is `success`, `incomplete`, `failed`, `timeout`, or `cancelled`.
3. Do not treat `queued`, `running`, startup-only output, or an unknown job id as a final report.
异步任务状态保存在内存中。服务重启后，旧任务编号会失效；如果可靠性比并行执行更重要，应使用同步工具。
Asynchronous job state is held in memory. A server restart invalidates old job ids, so use the synchronous tool when reliability is more important than parallel execution.
## 开发与测试 | Development and Testing
使用 Python 标准库运行测试：
Run the tests with the Python standard library:
```powershell
py -3 -m unittest discover -s . -p "test_*.py" -v
```
检查语法：
Check syntax:
```powershell
py -3 -m py_compile server.py test_server.py
```
服务端只使用 Python 标准库，没有运行时第三方依赖。
The server uses only Python standard-library modules and has no runtime package dependencies.
## 安全说明 | Security Notes
- 传入的代码库路径会作为工作目录提供给 Antigravity。
- 不要在任务描述中包含密码、令牌或无关的私有目录。
- 如果 MCP 服务被多人共享，请设置 `ANTIGRAVITY_ALLOWED_ROOTS` 限制可访问目录。
- 适配器的设计目标是只读，但 Antigravity CLI 仍会读取指定目录中的文件并将其作为模型上下文。
- The requested repository path is passed to Antigravity as an additional workspace directory.
- Do not include secrets or unrelated private directories in a delegated task.
- Set `ANTIGRAVITY_ALLOWED_ROOTS` to restrict paths when the MCP server is shared.
- The adapter is read-only by intent, but the Antigravity CLI still receives the files in the requested directory as model context.
## 项目结构 | Project Structure
```text
server.py MCP stdio server implementation
test_server.py Unit tests
pyproject.toml Python project metadata
.env.example Environment variable examples
.github/workflows/test.yml GitHub Actions test workflow
```
