ZCode Computer Use MCP Windows（Windows提取版）

从 C:\Program Files\ZCode 提取的内置 Computer Use MCP，不依赖 ZCode/Electron 宿主，可接入任意 MCP 客户端。

提取版本：0.5.14（对应 @zcode/zcode-cua-plugin / @zcode/zcode-cua-helper-runtime） 原版文件保持不动，本目录是副本。

目录

zcode-cua-standalone\
  launcher.mjs              # 一键启动器：拉起 helper + MCP server(stdio)
  test-client.mjs           # 最小 MCP 客户端，用于自检
  plugin\                   # MCP server 侧（原 resources\glm\packages\zcode-cua-plugin）
    dist\mcp\server.js      #   30 个工具 + 帧/坐标投影 + broker 客户端
    node_modules\           #   未提交，需 npm install 还原（sharp/koffi）
  helper\                   # Windows 平台 helper（原 resources\tools\cua-helper）
    dist\windows-helper.js  #   broker server + 平台逻辑
    build\Release\ax_native.node  # 原生插件：UIA / WGC / SendInput / 剪贴板 / DPI
    node_modules\           #   未提交，需 npm install 还原（sharp）
    runtime-manifest.json
  skill\computer-use\SKILL.md   # 从 MCP 剥离出的行为指南（宿主侧内容，非 MCP 提供）
  mcp-config.example.json   # MCP 客户端配置示例
  run-mcp.cmd               # 便捷入口（等价于 node launcher.mjs）

Related MCP server: atomic-computer-mcp

运行要求

• Windows 10/11 x64，交互式桌面会话（不能跑在服务/无桌面会话）

• Node.js（实测 v24.14.1；ax_native.node 是 N-API 插件，ABI 稳定）

• 无需 ZCode.exe；无需管理员权限（但也因此无法操作以管理员身份运行的窗口，UIPI 限制）

安装（首次使用）

仓库不包含 node_modules，克隆后先在两个子目录还原运行时依赖：

git clone https://github.com/A8Cl233395/zcode-computer-use-mcp-windows.git
cd zcode-computer-use-mcp-windows\helper
npm install --omit=dev

cd ..\plugin
npm install --omit=dev

• 版本固定为提取时的 sharp@0.34.5、koffi@2.15.6，npm 会自动拉取 win32-x64 预编译二进制。

• helper\build\Release\ax_native.node 已随仓库提供，无需本地编译。

• 原 plugin\package.json 里指向 pnpm workspace 的 catalog: 依赖已改为上述精确版本，因此可以脱离原 monorepo 独立安装。

使用

1. 自检

node C:\path\to\zcode-cua-standalone\test-client.mjs

路径替换为实际克隆目录，下同。

预期：打印 30 tools: ... 和一段 list_apps 的应用列表。

2. 接入 MCP 客户端

配置示例（Claude Desktop / Claude Code / 其它支持 stdio 的宿主）：

{
  "mcpServers": {
    "computer-use": {
      "command": "node",
      "args": ["C:\\path\\to\\zcode-cua-standalone\\launcher.mjs"]
    }
  }
}

launcher.mjs 的职责：

1. 生成随机命名管道 \\.\pipe\zcode-cua-helper-<hex> 与随机 token；

2. 以 --socket <pipe> --parent-pid <自己> 启动 helper，token 经环境变量 ZCODE_CUA_PERMISSION_BROKER_TOKEN 传入；

3. 收到 helper 的 ready（原生插件加载完成）后设置 ZCODE_CUA_PERMISSION_BROKER_SOCKET/TOKEN 并调用 MCP server 的 main()；

4. 客户端断开 / 进程退出时通知 helper 关闭；helper 自身也有 parent-pid 看门狗，且 90 秒内无人认领（首个 broker_info）会自杀，避免孤儿进程。

Skill 是怎么提供的（不是 MCP）

原版 plugin.json 里的 "skills": "skills" 是 ZCode 插件宿主的功能：宿主扫描 skills/**/SKILL.md，把 frontmatter 的 name/description 注册成"技能"，在需要时把正文注入模型上下文（与 Claude Skills 同类的机制）。MCP 本身不提供 skill——tools/list 里只有 30 个工具，没有 resources/prompts。MCP 工具描述里原来只有一句指向 SKILL.md "Choose the target" 的提示（SKILL_REF），本提取版已把这两处置空，因此 MCP 工具 schema 里不再出现 SKILL.md 引用。

剥离后的技能文件在：

skill\computer-use\SKILL.md   # 完整行为指南：a11y 优先、元素/坐标目标选择、重试安全等

接入方式（任选其一，取决于宿主）：

• Claude Code / Codex / opencode 等读 AGENTS/CLAUDE 的宿主：把 SKILL.md 放到技能目录，或在 AGENTS.md/CLAUDE.md 里 @/引用该文件；

• 任意 MCP 宿主：把 SKILL.md 正文作为 system prompt 或项目指令注入（内容本身与工具 schema 无关）；

• 想让 MCP 自己提供：需改 plugin/dist/mcp/server.js 注册 prompts（MCP 的 prompt 机制），多数客户端目前不会自动使用，不推荐。

实现要点（为什么能独立跑）

• MCP server 与 helper 之间是命名管道上的 NDJSON JSON-RPC（\\.\pipe\zcode-cua-helper-*），token 认证，不依赖 Electron IPC。

• ZCode 宿主只做三件事：传 socket/token、显示权限面板、PiP 窗口；这些都不参与操控链路，缺失只影响对应 UI 功能。

• 观测：get_app_state → UIA 元素树（CoCreateInstance(CUIAutomation)）；截图走 Windows Graphics Capture（D3D11），PNG 再由 MCP 侧 sharp 压到最长边 1568 / JPEG。

• 动作：元素目标 → UIA 模式（Invoke/Value/Toggle/...，后台可点）；坐标目标 → 模型给栅格像素，MCP 用帧投影换成屏幕坐标，helper 校验前台后调用 SendInput（Windows 下坐标原始输入要求目标窗口前台）。

已知限制

• 只提取了 Windows helper；macOS（ZCode Computer Use.app）与 Linux 需要各自的 helper 与 .node。

• 原宿主提供的权限引导面板、PiP 实时画面、prevent_activation 宿主策略等不再存在；request_access 只返回状态快照。

• 键盘/鼠标高层 API 行为受原版策略约束：strategy=event 的原始输入要求目标应用在最前；不要用它操作管理员窗口。

• 本目录中的二进制与代码版权归原项目（ZCode/Z.ai）所有，仅供本地研究/集成使用，请遵守原始许可。