MCP Computer Use

当前开发版本：v0.4.1

最新预发布版本：v0.4.1-rc2

MCP Computer Use 是一套面向 AI Agent 的本地计算机操作运行时。它把桌面无障碍树、物理输入、截图、浏览器 DOM/ARIA、视觉定位、等待与结果验证统一成 MCP 工具，让支持 Model Context Protocol 的宿主可以用一套稳定接口控制 macOS、Windows、Linux X11 和 Chromium 系浏览器。

项目不仅提供底层 MCP Server，还包含一个有界上下文的 Reference Agent Runtime、一套原生 Electron Agent Client，以及用于约束模型调度行为的 computer-mcp-execution Skill。

这是本地 GUI 自动化项目，不是云端网页爬虫，也不是适合部署到无桌面容器里的常驻服务。桌面工具必须运行在拥有真实登录会话、系统无障碍权限和屏幕录制权限的机器上；纯浏览器工具可以在无头模式运行。

目录

• 项目解决什么问题

• 核心能力

• 架构与运行方式

• 工具面与引用模型

• 环境要求

• 从源码构建

• 部署方式一：接入现有 MCP 宿主

• 部署方式二：运行原生 Electron Agent Client

• 部署方式三：运行 Reference Agent CLI

• 视觉定位配置

• 平台权限与系统准备

• 部署后验证

• 升级与回滚

• 安全建议

• 常见错误与排障

• 开发与测试

• 目录结构

• 当前限制

Related MCP server: ClawdCursor

项目解决什么问题

传统 GUI Agent 往往把每一步都交给截图和坐标：模型反复看整屏、猜位置、点击，再用下一张整屏截图确认。这样容易出现四类问题：

1. 不稳定：窗口移动、缩放、主题变化后坐标立即失效。

2. 昂贵：完整截图、无障碍树和历史 reasoning 被反复回灌，几轮就可能消耗大量上下文。

3. 难恢复：元素过期、页面跳转、视觉目标失效时，模型不知道应该重新观察还是重试动作。

4. 难验收：动作执行成功不等于任务完成，缺少明确的 post-condition 和新鲜证据。

本项目采用“结构化优先、视觉兜底、动作后验证”的执行模型：

已有有效 ui_N / web_N / visual_N
                 │
                 ▼
             直接执行动作
                 │
                 ▼
         wait / verify / expect
                 │
                 ▼
          fresh evidence_N
                 │
                 ▼
              完成任务

没有有效目标
    │
    ├─ 桌面：computer_observe → computer_resolve → Vision fallback
    └─ 浏览器：browser_observe → DOM/ARIA locator

视觉不是默认路径，裸坐标是最后兜底。模型看到的是紧凑的语义元素、引用 ID 和结构化错误，而不是无限增长的原始 UI 历史。

核心能力

桌面自动化

• 跨平台窗口枚举和稳定 window_N 引用。

• 通过 macOS AX、Windows UIA、Linux AT-SPI 读取结构化元素树。

• 语义点击、输入、快捷键与窗口激活。

• 必要时使用 CGEvent、SendInput 或 XTest 执行物理输入。

• 全屏或指定窗口截图。

• 基于条件的事件式 wait 和结果 verify，主路径不使用固定 sleep。

• 元素代际和过期检测，拒绝把陈旧 ui_N 当成当前元素继续操作。

浏览器 Fast Path

• 使用 playwright-core 启动 Chrome、Edge 或可用 Chromium。

• 通过 DOM/ARIA 读取可交互元素，而不是把完整 HTML 交给模型。

• 会话级全局 web_N、页面级 page_N 和代际过期保护。

• 区分 STALE_ELEMENT、ELEMENT_PAGE_MISMATCH、ELEMENT_NOT_FOUND 与真实 LOCATOR_FAILED。

• 支持导航、点击、输入、快捷键、截图、事件等待和验证。

• browser_evaluate 属于高能力调试工具，可以通过环境变量彻底关闭。

截图和视觉

• 截图默认返回小型 capture_N 元数据引用，不把 base64 塞进模型上下文。

• 像素保存在 MCP Server 的短期 Capture Store 中，默认 TTL 10 分钟，并受 LRU 和总字节上限约束。

• 需要图片时通过 MCP resource computer://capture/{capture_N} 显式读取。

• 支持区域裁剪、视觉 grounding 和带 provenance 的 visual_N。

• 远程视觉上传默认关闭，需要两个独立开关同时启用。

• Context Firewall 会阻止 base64 或二进制内容意外进入文本 Tool Result。

Reference Agent Runtime

• 每轮从紧凑 TaskState 重建 Working Context，不保存逐字 reasoning 或旧图片。

• 按 discover / act / settle / recover 阶段动态暴露少量工具。

• 本地拒绝互斥参数冲突、重复失败调用和危险的未知结果重试。

• 对模型超时、用户取消、视觉格式错误、过期元素和完成证据失败提供有界恢复。

• 完成时必须提交动作后的新鲜成功证据，避免“点完就宣布成功”。

原生 Electron Client

• 在 Electron 主进程中管理模型 Provider、MCP stdio、Rust Runtime 和 Capture 生命周期。

• API Key 使用系统 safeStorage 加密，不返回 Renderer。

• 按任务选择 desktop-vision 或 browser 最小工具面。

• 浏览器任务在同一 MCP 会话中确定性预启动 Browser Runtime，避免首步直接导航时出现 BROWSER_NOT_RUNNING。

• UI 展示任务预算、路由阶段、工具结果、恢复原因和完成证据。

架构与运行方式

                      ┌──────────────────────────────┐
                      │ MCP Host / Electron Client   │
                      │ Reference Agent / other LLM  │
                      └──────────────┬───────────────┘
                                     │ MCP over stdio
                            ┌────────▼────────┐
                            │   MCP Server    │
                            │ schema / policy │
                            │ capture store   │
                            └───────┬─────────┘
                    ┌───────────────┴────────────────┐
                    │                                │
          ┌─────────▼──────────┐          ┌──────────▼──────────┐
          │ Desktop Runtime     │          │ Browser Runtime     │
          │ Rust stdio JSON-RPC │          │ TypeScript          │
          └─────────┬──────────┘          │ Playwright + ARIA   │
                    │                      └──────────┬──────────┘
         ┌──────────┼───────────┐                     │
         ▼          ▼           ▼                     ▼
       macOS      Windows    Linux X11        Chrome / Edge / Chromium
       AX/SCK       UIA       AT-SPI/XTest

各层职责：

MCP Server 不是常驻守护进程。通常由 MCP Host 为一个会话启动 Server；Server 再启动桌面 Runtime，并在会话结束时回收自己拥有的进程。Browser Runtime 同样是 MCP 会话内状态，不等同于系统里已经打开的普通 Chrome 窗口。

工具面与引用模型

项目完整注册 25 个工具，但生产环境通常应通过 COMPUTER_TOOL_PROFILE 只暴露当前场景需要的子集：

完整工具分类：

常见引用：

computer_click 的三种定位方式严格互斥：只传 target，或只传 query，或只传 x + y。不要为了“保险”同时传多个定位方式。

模型调度规范见 skills/computer-mcp-execution/SKILL.md。

环境要求

通用依赖

playwright-core 不保证为每台机器下载浏览器。服务器会依次尝试 Chrome、Edge 和 Playwright 可解析的 Chromium；部署机器上安装 Chrome 或 Edge 是最稳妥的选择。

平台要求

从源码构建

1. 克隆固定版本

生产部署建议固定到 release tag，不要直接跟随开发分支：

git clone --branch v0.4.1-rc2 --depth 1 https://github.com/FloraAurella/mcp-computer-use.git
cd mcp-computer-use

需要完整历史时去掉 --depth 1。

2. 安装 Node 依赖

npm ci

仓库包含 package-lock.json，部署和 CI 应使用 npm ci 获得可复现依赖；只有修改依赖时才使用 npm install。

3. 编译 TypeScript 工作区

npm run build

关键产物：

packages/mcp-server/dist/index.js
packages/agent-runtime/dist/index.js
apps/reference-agent/dist/cli.js

4. 编译桌面 Runtime

cargo build --release -p computer-runtime-ipc

产物位置：

macOS / Linux: target/release/computer-runtime
Windows:       target/release/computer-runtime.exe

5. 可选：构建 Electron Client

npm run client:build

macOS 编译准备

先安装 Xcode Command Line Tools：

xcode-select --install

runtime/platform/macos/build.rs 会调用 xcrun clang 编译一个 Objective-C/ARC ScreenCaptureKit 桥接层，不需要额外下载第三方原生库。

Linux X11 准备

Ubuntu/Debian 可安装运行和 Electron 测试所需组件：

sudo apt-get update
sudo apt-get install -y at-spi2-core xvfb libgtk-3-0 libnss3 libasound2 libgbm1 x11-utils wmctrl

确认当前不是纯 Wayland 会话，并且 GUI 进程能访问 DISPLAY 和 AT-SPI accessibility bus。无交互桌面的普通 Docker 容器无法直接控制宿主桌面。

Windows 准备

在 PowerShell 中安装 Rust、Node.js 和 Git 后执行：

npm ci
npm run build
cargo build --release -p computer-runtime-ipc

Windows 不需要 macOS 的 TCC 授权，但目标应用必须运行在与 Runtime 相同的交互式用户会话中。以 Windows Service、Session 0 或无桌面 CI 运行时无法控制普通用户桌面。

部署方式一：接入现有 MCP 宿主

这是最轻量的部署方式：保留你现有的 AI Host，只把本仓库的 MCP Server 注册进去。

1. 选择稳定安装目录

构建完成后可以直接使用仓库内产物。macOS 上长期部署更建议把 computer-runtime 复制到不会被 Cargo 反复覆盖的稳定绝对路径，再对启动 Host 授权一次。无论采用哪种方式，MCP 配置都应使用绝对路径。

2. macOS / Linux 配置示例

将下面内容合并到宿主的 MCP JSON 配置中，并替换 /absolute/path/to/mcp-computer-use：

{
  "mcpServers": {
    "computer": {
      "command": "/absolute/path/to/node",
      "args": [
        "/absolute/path/to/mcp-computer-use/packages/mcp-server/dist/index.js"
      ],
      "env": {
        "COMPUTER_RUNTIME_BIN": "/absolute/path/to/mcp-computer-use/target/release/computer-runtime",
        "COMPUTER_TOOL_PROFILE": "desktop-vision",
        "COMPUTER_SCREENSHOT_MODE": "reference",
        "COMPUTER_ENABLE_EVALUATE": "0"
      }
    }
  }
}

如果 Host 能从 PATH 正确找到 Node，command 可以写成 node；图形应用从 Finder/Dock 启动时 PATH 往往不完整，因此生产配置推荐写 Node 的绝对路径。

3. Windows 配置示例

JSON 中的反斜杠必须写成双反斜杠：

{
  "mcpServers": {
    "computer": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\mcp-computer-use\\packages\\mcp-server\\dist\\index.js"
      ],
      "env": {
        "COMPUTER_RUNTIME_BIN": "C:\\mcp-computer-use\\target\\release\\computer-runtime.exe",
        "COMPUTER_TOOL_PROFILE": "desktop-core",
        "COMPUTER_SCREENSHOT_MODE": "reference",
        "COMPUTER_ENABLE_EVALUATE": "0"
      }
    }
  }
}

4. 按场景选择工具面

• 只操作桌面结构化 UI：desktop-core

• 桌面需要截图和视觉兜底：desktop-vision

• 只操作网站：browser

• Host 需要同时动态切换桌面和浏览器：full

• 排查 Schema 和 Tool Result 大小：debug

工具面是在 MCP Server 启动时确定的。修改配置后需要让 Host 重新启动该 MCP 会话。

5. 浏览器模式注意事项

外部 MCP Host 应先调用一次 browser_launch，再使用 browser_navigate、browser_pages 或 browser_observe。原生 Electron Client 会自动完成预启动；普通 Host 如果跳过 launch，会收到 BROWSER_NOT_RUNNING。

默认浏览器是无头模式。需要观察实际窗口时设置：

{
  "COMPUTER_BROWSER_HEADED": "1"
}

6. 常用 MCP Server 环境变量

COMPUTER_LEGACY_SCREENSHOT=1 仅用于迁移旧 Host，会恢复原始图片行为并产生弃用警告，不建议新部署使用。

部署方式二：运行原生 Electron Agent Client

Electron Client 适合希望直接获得完整任务执行 UI、模型配置、预算、轨迹和恢复提示的用户。

启动

npm ci
npm run build
cargo build --release -p computer-runtime-ipc
npm run client:start

首次启动后：

1. 打开左下角“设置”。

2. 填写 OpenAI-compatible 模型端点、模型名和 API Key。

3. 选择 desktop 或 browser surface。

4. 确认 Runtime 和 MCP Server 路径指向本次构建产物。

5. 先执行“测试 MCP”；该操作只测试本地工具握手，不调用外部模型。

6. 再执行“测试模型”；该操作会产生一次很小的纯文本模型请求。

7. 保存后回到执行台运行任务。

远程模型地址必须使用 HTTPS；只有 127.0.0.1、localhost 或 ::1 可以使用 HTTP。API Key 由 Electron safeStorage 加密保存在用户应用数据目录，不会写进仓库或传回 Renderer。

可通过环境变量提供初始默认值：

不要把真实 API Key 写入 shell history、README、Git 配置或 MCP JSON。优先在客户端设置页使用系统加密存储，或通过受控的进程环境注入。

部署方式三：运行 Reference Agent CLI

Reference Agent CLI 适合调试 Agent Runtime、接入自动化流水线或自行开发上层 UI。

macOS / Linux

export AGENT_MODEL_BASE_URL="https://provider.example/v1"
export AGENT_MODEL_API_KEY="replace-with-a-secret-from-your-secret-manager"
export AGENT_MODEL_NAME="multimodal-model"
export AGENT_MODEL_SUPPORTS_VISION=1
export AGENT_CONTEXT_WINDOW_TOKENS=131072
export COMPUTER_RUNTIME_BIN="/absolute/path/to/mcp-computer-use/target/release/computer-runtime"

# desktop 是默认 surface
npm run agent:run -- "打开目标窗口，完成操作并验证结果"

# 浏览器任务
AGENT_SURFACE=browser npm run agent:run -- "打开目标网页并验证页面状态"

Windows PowerShell

$env:AGENT_MODEL_BASE_URL = "https://provider.example/v1"
$env:AGENT_MODEL_API_KEY = "replace-with-a-secret-from-your-secret-manager"
$env:AGENT_MODEL_NAME = "multimodal-model"
$env:COMPUTER_RUNTIME_BIN = "C:\mcp-computer-use\target\release\computer-runtime.exe"
$env:AGENT_SURFACE = "desktop"

npm run agent:run -- "打开目标窗口，完成操作并验证结果"

其他 Agent 变量：

CLI 最终输出 compact task state、context profile 和脱敏 telemetry，不输出 Authorization、原始 Provider payload、base64 图片或逐字 reasoning。

视觉定位配置

视觉 grounding 默认关闭。结构化无障碍树能解决的问题不需要启用视觉。

本地 Mock Vision

用于测试协议和恢复链路，不上传截图：

{
  "COMPUTER_VISION_ENABLED": "1",
  "COMPUTER_VISION_PROVIDER": "mock"
}

OpenAI-compatible Vision Provider

远程图片上传必须同时开启 Vision 和 Remote Upload：

{
  "COMPUTER_VISION_ENABLED": "1",
  "COMPUTER_VISION_PROVIDER": "openai-compatible",
  "COMPUTER_VISION_REMOTE_UPLOAD": "1",
  "COMPUTER_VISION_BASE_URL": "https://provider.example/v1",
  "COMPUTER_VISION_MODEL": "multimodal-model",
  "COMPUTER_VISION_API_KEY": "inject-from-a-secret-manager"
}

可调参数：

远程视觉会把目标窗口或裁剪区域的像素传给你配置的第三方模型服务。启用前应确认数据分类、隐私要求、服务端保留政策和网络边界。

平台权限与系统准备

macOS

在“系统设置 → 隐私与安全性”中，为真正启动 MCP Server/Runtime 的终端或 Host App 开启：

• 辅助功能：读取 AX 树、语义动作、窗口激活和物理输入。

• 屏幕与系统音频录制：ScreenCaptureKit 全屏和指定窗口截图。

权限属于启动实体。若从 Terminal 测试正常、从某个 MCP Host 运行失败，应给该 Host 本身授权，而不是只给 Terminal 授权。

macOS 截图能力会分别报告：

• permission：TCC 预检结果。

• available：真实小尺寸截图探测结果。

• backend：screencapturekit、screencapture-cli 或 none。

建议把 release Runtime 放到稳定路径。Cargo 反复替换 target/release/computer-runtime 后，系统可能继续关联旧的执行身份。稳定路径只需要重新授权一次。

Windows

• Runtime 和目标应用必须位于同一登录用户、同一交互式桌面会话。

• 如果目标应用以管理员权限运行，普通权限 Runtime 可能无法操作它；应尽量保持相同完整性级别。

• Windows Service、Session 0 和锁屏状态不是受支持的交互环境。

Linux X11

• 必须有可访问的 DISPLAY。

• 必须有 AT-SPI accessibility bus；缺少时会提示安装 at-spi2-core。

• XTest 用于物理输入，当前 X11 文本兜底主要支持 ASCII。

• Wayland 会显式返回 UNSUPPORTED，不会静默猜测坐标。

部署后验证

建议按从底层到上层的顺序验证，便于快速定位问题。

1. 验证 Runtime 二进制

target/release/computer-runtime capabilities
target/release/computer-runtime windows
target/release/computer-runtime observe

macOS 正常截图能力示例：

{
  "screen_capture": {
    "permission": true,
    "available": true,
    "backend": "screencapturekit"
  }
}

2. 验证无副作用 Mock Runtime

target/release/computer-runtime --mock observe

3. 验证 TypeScript 和 MCP

npm run build
npm run test:profiles
npm run test:mcp

4. 验证浏览器链路

node tests/browser/run.mjs

5. 验证 Agent 和客户端

npm run test:agent
npm run client:test
npm run client:build

6. 直接调试 Runtime CLI

target/release/computer-runtime screenshot runtime-check.png
target/release/computer-runtime click 655,544
target/release/computer-runtime key cmd+a
target/release/computer-runtime --mock observe

Windows 将路径替换为 target\release\computer-runtime.exe，macOS 快捷键使用 cmd，Windows/Linux 通常使用 ctrl。

升级与回滚

升级到指定版本

git fetch --tags origin
git checkout v0.4.1-rc2
npm ci
npm run build
cargo build --release -p computer-runtime-ipc

完成后重启 MCP Host 或 Electron Client。正在运行的 MCP 会话不会自动切换到新构建产物。

回滚

1. 停止当前 MCP 会话或 Electron Client。

2. 切换到之前验证过的 tag/commit。

3. 重新执行 npm ci、TypeScript build 和 Rust release build。

4. 确认 MCP 配置仍指向对应工作目录的绝对路径。

5. 重新启动 Host 并运行 computer_capabilities。

不要混用不同版本的 packages/mcp-server/dist 和 computer-runtime 二进制；协议和错误模型可能不一致。

安全建议

• 生产环境优先使用最小 COMPUTER_TOOL_PROFILE。

• 不需要任意页面脚本时设置 COMPUTER_ENABLE_EVALUATE=0。

• 保持 COMPUTER_SCREENSHOT_MODE=reference，不要默认开放 raw ImageContent。

• 只有在理解数据去向后才启用 COMPUTER_VISION_REMOTE_UPLOAD=1。

• API Key、Cookie 和用户脚本不要提交到 Git；使用系统密钥存储或 Secret Manager。

• MCP Server 和 Runtime 使用普通用户权限运行，避免不必要的管理员/root 权限。

• 对高风险目标应用使用 Host 的 allowlist 或任务 scope。

• 将 stderr 日志视为运行诊断信息；不要在自定义代码里记录 Authorization 或模型原始请求。

• Browser Runtime 只清理自己启动并标记的浏览器进程，不应对系统中其他 Chrome 进程做广泛终止。

本仓库根目录的 scripts/ 被明确列入 .gitignore，用于保留本机私有自动化脚本，不属于发布内容。

常见错误与排障

macOS permission=true 但截图仍失败

1. 确认获得授权的是实际启动 Runtime 的 App。

2. 运行 computer-runtime capabilities 查看真实 backend。

3. 把二进制复制到稳定路径并重新授权。

4. 重启 Host；TCC 变化通常不会对已运行进程即时生效。

5. 不要通过长期降低 Rust release 优化级别规避问题。

浏览器无法启动

1. 安装当前稳定版 Chrome 或 Edge。

2. 确认当前用户有权限执行浏览器。

3. 无头 Linux 检查 Chromium 运行依赖和沙箱限制。

4. 设置 COMPUTER_BROWSER_HEADED=1 观察真实启动错误。

5. 查看 MCP stderr 中的 could not launch Chromium/Chrome/Edge 具体原因。

开发与测试

常用命令

cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

npm run build
npm run test:unit
npm run test:agent
npm run client:test
npm run test:profiles
npm run test:mcp
node tests/integration/run.mjs --mock
node tests/integration/run.mjs
node tests/browser/run.mjs

测试分层

测试不依赖公网或真实 LLM。涉及模型的 Agent 测试使用 scripted/mock provider。

目录结构

runtime/core             平台无关核心：Registry、wait/verify、事件、Mock
runtime/platform/macos   AX、CGEvent、ScreenCaptureKit Clang/ARC bridge
runtime/platform/windows UIA、Win32、SendInput、GDI
runtime/platform/linux   AT-SPI、X11、XTest、XGetImage
runtime/ipc              computer-runtime CLI 与 stdio JSON-RPC

packages/protocol        共享协议类型和版本
packages/client-sdk      Runtime 类型化客户端和生命周期
packages/browser-runtime Browser Fast Path、page_N/web_N Registry
packages/vision-runtime  Vision Provider、grounding、visual_N
packages/mcp-server      MCP tools、Capture Store、Context Firewall
packages/agent-runtime   TaskState、Context、Router、Recovery、Completion

apps/reference-agent     Reference Agent CLI
apps/agent-client        Electron Agent Client
apps/test-gui            桌面集成测试 GUI
apps/test-web            Browser E2E 本地站点

skills/computer-mcp-execution  模型工具调度 Skill
tests/                         单元、Agent、MCP、桌面和浏览器测试
benchmarks/                    性能基准

当前限制

• macOS 是当前主要真机验证平台；Windows 和 Linux 的代码、编译与单测已覆盖，但生产部署前仍应在目标机器做 GUI 验收。

• Linux 只支持 X11，不支持 Wayland。

• Linux 物理文本输入兜底主要支持 ASCII；优先使用 AT-SPI 语义输入。

• Browser Runtime 是会话内新浏览器，不接管用户现有浏览器个人资料或登录态。

• playwright-core 不保证自动下载浏览器，部署机器建议预装 Chrome 或 Edge。

• 无真实桌面、无权限或被锁定的会话无法执行桌面 GUI 自动化。

• 视觉 grounding 受截图质量、目标描述和 Provider 输出约束；低置信度或歧义目标会 fail-closed。

• Reference Agent 是参考实现，不替代 Host 自身的审批、权限、数据治理和高风险操作确认机制。

仓库地址：https://github.com/FloraAurella/mcp-computer-use

问题反馈：https://github.com/FloraAurella/mcp-computer-use/issues