AGY MCP for Windows

基于 npm 包 @itoseo/agy-mcp@1.0.0 的 Windows 适配与本地部署版本。

来源、致谢与社区认同

本仓库的初始代码来自 npm 上由 itoseo 发布的 @itoseo/agy-mcp@1.0.0。原始发布包仅包含构建后的 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

Related MCP server: WinCommander

Windows 改动

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

/tmp/agy-mcp

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

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 发送任务并获取响应。

2. agy_conversation

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

3. agy_models

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

Windows 本地运行

前提

1. 安装 Node.js 20 或更高版本。

2. 安装并完成 Antigravity CLI（agy） 的登录。

3. 在 PowerShell 中确认 AGY 可用：

   agy models

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

   npm ci --omit=dev

启动

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

run-agy-mcp.cmd

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

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

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

node .\dist\index.js

OpenCode 配置示例

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

{
  "$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 仍可能先抛出：

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 调用实际带上：

{ "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。

• 原始包：@itoseo/agy-mcp@1.0.0

• 本仓库的修改内容与日期见 CHANGELOG.md。

• 本仓库只收录 npm 发布的构建产物及其修改版本；原作者的 TypeScript 原始工程未随 npm 包公开。