# AGY MCP for Windows

> 基于 npm 包 [`@itoseo/agy-mcp@1.0.0`](https://www.npmjs.com/package/@itoseo/agy-mcp) 的 Windows 适配与本地部署版本。

## 来源、致谢与社区认同

本仓库的初始代码来自 npm 上由 **itoseo** 发布的 [`@itoseo/agy-mcp@1.0.0`](https://www.npmjs.com/package/@itoseo/agy-mcp)。原始发布包仅包含构建后的 `dist/index.js`、`dist/index.d.ts`、`README.md` 与 `package.json`，没有公开的 TypeScript 原始工程、构建配置或源码仓库地址。

本仓库保留原项目的功能定位和许可证，并在 `CHANGELOG.md` 中明确记录本地改动。原项目作者并未参与本仓库的维护，也不为本仓库的改动背书。

认同 **LinuxDo（L站）社区**对开放交流、经验共享、来源可追溯与尊重开源许可的实践。这个仓库按同样的原则保留来源、改动与运行边界。

- 原始 npm 页面：<https://www.npmjs.com/package/@itoseo/agy-mcp>
- 原始 1.0.0 发布文件索引：<https://unpkg.com/@itoseo/agy-mcp@1.0.0/?meta>
- npm 维护者：`itoseo`
- 原包许可证声明：`GPL-3.0-only`

## Windows 改动

原发布包将运行日志固定写入 Linux/POSIX 路径：

```text
/tmp/agy-mcp
```

本仓库将其替换为 Windows 本地目录：

```text
D:\agy-mcp
```

每次任务生成独立日志，`latest.log` 用于定位最近一次任务日志。Windows 无法创建符号链接时，会降级为写入实际日志路径的普通文件，而不会静默失败。

此外，本仓库移除了原发布代码中硬编码的 `--dangerously-skip-permissions` 与 `--sandbox` 启动旗标。AGY 的工具权限与产物审查权限改由其官方持久化配置 `~/.gemini/antigravity-cli/settings.json` 统一控制。此举不自动降低权限：若你的 AGY 设置为 `always-proceed`，它仍会以高自主模式执行，请只在可信工作区和可信调用链中使用。

## 原项目功能说明

以下内容按原 npm README 的结构转录，日志路径和权限旗标描述已按本仓库实际实现修正。

### 定位与优势

- **CodeX / Claude Code**：负责高级思考、架构设计与决策规划。
- **AGY (Antigravity)**：作为执行子代理（Subagent），负责读取文件、执行代码、应用修改、运行终端等具体编码任务。原 README 默认以 `Gemini 3.7 Flash (High)` 为示例模型。

### 核心特性

- ⚡ **并发安全与实时流式**：
  - **终端精准透传**：实时将 AGY 思考与生成内容通过 `stderr` 管道输出至控制台，并发任务自动携带专属短 ID 前缀，例如 `[agy:6be7cb]`。
  - **独立隔离日志**：每次调用分配唯一执行 ID，生成专属日志文件 `D:\agy-mcp\<executionId>.log`。
  - **便捷追踪最新任务**：自动更新 `D:\agy-mcp\latest.log`，用于定位最近一次任务日志。
  - **响应携带日志路径**：每次工具返回元数据中包含专属 `log: D:\agy-mcp\...` 路径，便于单独排查。
  - **MCP 协议通知**：检测客户端 `progressToken` 后，通过 `notifications/progress` 推送文本型执行进度。
- 🎯 **显式模型控制**：默认传递 `--model "Gemini 3.7 Flash (High)"`；可通过工具参数指定模型与推理强度。
- 🛡️ **权限由 AGY 官方配置管理**：不在 MCP 内硬编码危险启动旗标；请在 AGY 的 `settings.json` 中审计 `toolPermission`、`artifactReviewPolicy`、`enableTerminalSandbox` 与细粒度 `permissions`。
- 🔄 **会话连续性**：支持多轮对话（`agy_conversation`），可在同一个上下文内持续追问与迭代修改。

### 提供的 MCP 工具

#### 1. `agy_prompt`

向 Antigravity 发送任务并获取响应。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|:---|:---|:---:|:---|:---|
| `prompt` | string | ✅ | - | 发送给 Antigravity 的任务描述 |
| `cwd` | string | ❌ | 当前目录 | 任务执行的工作目录（绝对路径） |
| `add_dirs` | string[] | ❌ | - | 额外的工作目录列表（绝对路径） |
| `mode` | string | ❌ | `accept-edits` | 执行模式：`accept-edits` 或 `plan` |
| `model` | string | ❌ | `Gemini 3.7 Flash (High)` | 指定 AI 模型 |
| `effort` | string | ❌ | `high` | 推理强度：`low` / `medium` / `high` |
| `timeout_seconds` | number | ❌ | `300` | MCP 等待 AGY 终端结果的最长时间，单位为秒 |

#### 2. `agy_conversation`

延续已有的 Antigravity 对话上下文。

| 参数 | 类型 | 必填 | 说明 |
|:---|:---|:---:|:---|
| `conversation_id` | string | ✅ | 上一次 `agy_prompt` 返回的会话 ID |
| `prompt` | string | ✅ | 追加的指令或反馈 |
| `timeout_seconds` | number | ❌ | 超时时间（秒） |

#### 3. `agy_models`

查询当前环境可用的 Antigravity AI 模型列表。

## Windows 本地运行

### 前提

1. 安装 Node.js 20 或更高版本。
2. 安装并完成 [Antigravity CLI（`agy`）](https://antigravity.google/docs/cli/) 的登录。
3. 在 PowerShell 中确认 AGY 可用：

   ```powershell
   agy models
   ```

4. 安装此项目的运行依赖：

   ```powershell
   npm ci --omit=dev
   ```

### 启动

项目附带 Windows 启动包装脚本：

```bat
run-agy-mcp.cmd
```

它会将 `AGY_EXECUTABLE` 设为当前机器安装位置：

```text
C:\Users\Administrator\AppData\Local\agy\bin\agy.exe
```

这个路径属于本机部署约定。若你的 AGY 位置不同，请修改该脚本，或自行在启动环境中设置 `AGY_EXECUTABLE` 后运行：

```powershell
node .\dist\index.js
```

### OpenCode 配置示例

OpenCode 使用 `mcp.<name>.timeout` 作为 MCP 请求超时，单位为**毫秒**。对 AGY 一类长任务，建议显式设置为 600 秒：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agy-local": {
      "type": "local",
      "command": [
        "cmd.exe",
        "/d",
        "/c",
        "D:\\path\\to\\agy-mcp-windows\\run-agy-mcp.cmd"
      ],
      "cwd": "D:\\path\\to\\agy-mcp-windows",
      "enabled": true,
      "timeout": 600000
    }
  },
  "experimental": {
    "mcp_timeout": 600000
  }
}
```

配置写入后，应完整重启 OpenCode，使已运行的 MCP 客户端实例重新读取设置。

## 个人使用经验与已知限制

### OpenCode 的超时需要手动放宽

这是实际测试中遇到的情况：OpenCode 的 `mcp.<name>.timeout` 单位是毫秒，并可能成为比 `agy_prompt.timeout_seconds` 更早触发的外层超时。

例如 `timeout: 15000` 只代表 15 秒；即使 MCP 工具参数传入 `timeout_seconds: 600`，OpenCode 仍可能先抛出：

```text
McpError: MCP error -32001: Request timed out
```

建议把 OpenCode 的 `mcp.agy-local.timeout` 设为 `600000`，并同时设置 `experimental.mcp_timeout: 600000`。这只能放宽 OpenCode 的 MCP 请求层；OpenCode 更外层的模型工具步骤、AGY 自身状态及服务端限制仍可能先结束任务。

### `timeout_seconds: 600` 必须真正作为工具参数传入

本 MCP 的 `timeout_seconds` 默认是 300 秒。只有 MCP 调用实际带上：

```json
{ "timeout_seconds": 600 }
```

内部 AGY 子进程等待计时器才会改为 600 秒。仅在自然语言提示中说“允许执行 600 秒”，不能保证上游模型会把这个字段放入工具调用 JSON。

### AGY 或 Gemini 网页端都无法调用模型时

曾出现 AGY CLI 与 Gemini 网页端都无法使用 AI 模型的现象。此类情况在本地表现为 CLI 请求无法正常得到模型结果，网页端也无法完成模型调用。

这是基于当时表现作出的**环境侧判断**：更像网络、地区、代理、账号会话或服务可用性问题，而非本 MCP 的代码问题。它不是 AGY 官方对具体原因的确认，也不能排除平台临时故障。排查时先验证网络/代理与账号状态，再用 `agy models`、一个极短的 `agy -p` 请求和 Gemini 网页端交叉确认。

### 日志可能包含敏感信息

`D:\agy-mcp` 的日志会记录 AGY 过程文本，可能含有提示词、代码片段和文件路径。请按敏感本地数据管理并定期清理。

## 许可证

原 npm 包在 `package.json` 中明确声明许可证为 **GPL-3.0-only**。本仓库作为基于该发布包的修改版本，整体继续以 **GNU General Public License v3.0 only** 发布。

- 完整许可证文本见 [`LICENSE`](LICENSE)。
- 原始包：[`@itoseo/agy-mcp@1.0.0`](https://www.npmjs.com/package/@itoseo/agy-mcp)
- 本仓库的修改内容与日期见 [`CHANGELOG.md`](CHANGELOG.md)。
- 本仓库只收录 npm 发布的构建产物及其修改版本；原作者的 TypeScript 原始工程未随 npm 包公开。