内容
# 全能计算机使用
Anthropic 官方 `computer-use` 工具表面的**1:1 复制品** — 作为适用于 Windows 的普通 **MCP 服务器**提供。它允许 **Claude Code CLI**（或任何 MCP 客户端）像 Claude Desktop 内置的 computer-use 一样控制 Windows 桌面：截图、鼠标 / 键盘 / 滚动 / 拖动 / 批量输入、剪贴板、多显示器和应用程序启动。
*真实会话，一次拍摄：CLI 激活 omni（光晕 + 药丸 + 终端停靠到角落），打开 VS Code，并输入。角落终端是生成此 GIF 的实际对话。*
与桌面工具相同的工具名称、相同的参数、相同的坐标语义 — 已经知道 Anthropic 的 computer-use 的代理在这里无需更改。构建并针对 Claude Desktop 自己的 `computer-use` 进行验证，作为可靠的参考。
> 基于视觉和坐标，如官方工具（而不是 UI 树 / 无障碍方法）— 当您想要在 Windows CLI 上使用 Anthropic 的 computer-use 范式时：桌面自动化、GUI 测试，或让代理验证您正在构建的应用程序。
## 安装
需要 Windows 和 Python 3.11+（uv / uvx 为您获取 Python）。PyPI 包名称带有 `-mcp` 后缀；其他所有内容 — 命令、服务器密钥、此存储库 — 都是普通的 `omni-computer-use`。
**推荐 — 安装到 Claude Code 中。** Claude Desktop 读取 Claude Code 的 MCP 服务器 *除了* 其自身服务器，因此此命令使服务器在 Claude Code CLI 和 Claude Desktop 应用程序中都可用：
```powershell
claude mcp add omni-computer-use -s user -- uvx omni-computer-use-mcp
claude mcp list # 预期：omni-computer-use … ✓ 已连接
```
其他方向更狭隘。在 Claude Desktop 的 `claude_desktop_config.json` 中 — 仅对 Claude Desktop 可见，CLI 看不到它：
```json
{
"mcpServers": {
"omni-computer-use": { "command": "uvx", "args": ["omni-computer-use-mcp"] }
}
}
```
桌面扩展包（`.mcpb`，一键安装）附在每个 GitHub 版本中 — 相同的范围警告：仅限 Claude Desktop。
独立运行（任何 MCP 客户端，或只是随便试试）：
```powershell
uvx omni-computer-use-mcp
```
> Windows 启动提示：`uv`/`uvx` 是原生可执行文件，不需要包装器。如果您的 MCP 客户端通过 `.cmd` 垫片（像 `npx`）启动服务器，*该* 需要一个 `cmd /c` 前缀 — 此服务器不需要。
## 示例
在多显示器设置中，每个截图都会自我描述 — 它会命名捕获的显示器和附加的其他显示器，因此代理永远不会失去正在查看哪个屏幕的跟踪：
```
此截图是在显示器 "\\.\DISPLAY2" 上拍摄的（2560x1600，主显示器）。
其他附加显示器： "\\.\DISPLAY1"（2560x1440）。使用 switch_display
捕获不同的显示器。
```
`open_application` 报告实际发生的情况，而不是直接执行：
```
打开了 "计算器"。 # 出现了一个真正的窗口
启动了 "…" 但其进程在 ~2 秒内退出 # 启动时崩溃 — 已报告，而不是伪造
没有显示窗口 …
```
## 状态
- **29 个工具** — 27 个与 Claude Desktop 的 computer-use 匹配，加上 `deactivate` 和 `display_overview`；开发版 `reload` 工具在 `COMPUTER_USE_DEV=on` 时达到 **30**。
- **16 个场景端到端测试套件** 在 `tests/` 下（`scen_*.json`），每个都通过全新的 MCP 进程运行。
- 在 **Windows 11** 上构建并验证（2560×1600 @ 150% DPI），与 Claude Desktop 的 computer-use 作为参考；截图降采样与 CDC 的 ~1.2 MP 匹配。
- **自 2026-06 起每日使用**。
## 工具
**匹配 Anthropic 的 computer-use（27 个）：** `request_access`、`list_granted_applications`、`request_teach_access`、`screenshot`、`zoom`、`switch_display`、`cursor_position`、`mouse_move`、`left_click`、`right_click`、`middle_click`、`double_click`、`triple_click`、`left_click_drag`、`left_mouse_down`、`left_mouse_up`、`scroll`、`key`、`hold_key`、`type`、`wait`、`open_application`、`read_clipboard`、`write_clipboard`、`computer_batch`、`teach_step`、`teach_batch`。
**omni 特有（2 个）：**
- `deactivate` — 结束会话而不终止进程（关闭光晕，恢复控制窗口，撤销授予）；`request_access` 的对应方法。
- `display_overview` — 根据虚拟桌面布局，将所有显示器的图像合并成一张带有标签的图像（一种方向辅助工具，用于确定哪个屏幕上有特定窗口；不是点击表面）。
所有点击 / 移动 / 滚动 / 拖动 / 缩放坐标都位于**最近截图的图像像素空间**中；服务器将它们映射回物理像素。
## 工作原理（值得阅读的部分）
**忠实的桌面视觉效果。** 在会话活动期间，服务器会重现 Claude Desktop 的屏幕视觉效果，根据参考捕获进行像素校准：静态橙色边缘光晕、居中的“Claude 正在使用您的计算机”药丸，该药丸飞到角落，控制窗口（运行 CLI 的 Windows 终端或 Claude Desktop 窗口本身）缩小并停靠在右上角，**在每次捕获期间隐藏在屏幕外**，因此截图显示的是真正的桌面，没有黑色方块。点击穿透是善意感知的：非分层终端在每次合成点击时都会降低到 z 顺序的底部；分层的 Claude Desktop 窗口获得 `WS_EX_TRANSPARENT`（桌面工具自己的方法），因此点击会传递到其下方的任何内容 — 窗口本身永远不会移动，因此用户的真实鼠标不受影响。
**键盘自我伤害防护。** 合成按键发送到当前拥有操作系统焦点的窗口。如果控制窗口（Claude 窗口或托管终端）是顶层窗口，则 `type` / `key` **被阻止** — 否则文本将进入代理自己的对话，或作为带有换行符的 shell 命令运行。防护是无条件的，并通过窗口标识和拥有进程识别控制表面，同时仍然允许第二个无关终端窗口成为合法目标。鼠标操作除外（点击带有自己的坐标）。
**多显示器。** 截图带有事件驱动的注释，注明捕获的显示器，并在显示器更改时标记；`open_application` 在窗口打开在与当前捕获目标不同的显示器上时发出警告 — 精确地，按显示器名称，当它拥有窗口句柄时；`display_overview` 返回所有屏幕的地图。光晕和缩小落在控制窗口自己的显示器上，留下其他显示器不变。
**诚实的启动和自我修复。** `open_application` 会轮询真实窗口，并区分 *已打开* / *正在运行但尚未显示窗口* / *启动时崩溃* / *未启动*，而不是总是报告成功。强制终止会话的缩小终端将在下次启动时从一个小状态文件（防止窗口句柄重用）恢复。
**热重载（开发）。** 设置 `COMPUTER_USE_DEV=on` 以添加一个 `reload` 工具，该工具在进程中重新加载逻辑模块，以便在不重新启动会话的情况下使编辑的代码生效 — 在针对服务器开发自动化时非常方便。它默认关闭（干净的 29 工具表面）。
参见 **[SPEC.md](SPEC.md)** 获取权威的工具逐一契约和模块架构。
## 与桌面工具的区别（设计使然）
内置的计算机使用权授予来自已安装应用程序列表的应用程序，并应用分层模型：浏览器可见但只读，终端和 IDE 仅可点击 — 无按键，由架构决定。适用于常规桌面使用的明智默认设置，以及为此服务器构建的工作流程关闭：让代理启动您正在**构建的应用程序** — 一个宽松的 `.exe`，没有安装列表；点击它，输入它，验证行为，然后返回 IDE 并编辑代码。
omni 授予 `tier:"full"` 下的每个已批准应用程序 — 包括 IDE、终端和开发版本（`open_application` 接受完整的 `.exe` 路径）。全力以赴，您负责。
CLI 没有权限 GUI，因此 `request_access` **自动授予** 可解析的应用程序，并返回相同的 JSON 形状；默认情况下，前台门控是允许的（仅在空允许列表时出错）。非允许列表窗口的屏蔽默认关闭（基于矩形的屏蔽器过度屏蔽）。教学模式是一个存根 — 它执行步骤的操作并返回截图，但没有全屏工具提示叠加层（桌面应用程序的功能）。每个都由以下环境变量控制。
## 配置
| 变量 | 默认值 | 含义 |
| --- | --- | --- |
| `COMPUTER_USE_MAX_PIXELS` | `1200000` | 缩略图的最大像素数（≈ 1.2 MP）。 |
| `COMPUTER_USE_MASKING` | `off` | 在截图中屏蔽非允许列表应用程序窗口。 |
| `COMPUTER_USE_ENFORCE_FOREGROUND` | `off` | 当最前面的应用程序未被允许列表时阻止输入。 |
| `COMPUTER_USE_AUTOGRANT` | `on` | 在 `request_access` 上自动授予可解析的应用程序。 |
| `COMPUTER_USE_DEV` | `off` | 注册开发者 `reload` 热重载工具（开启 → 30 个工具）。 |
| `COMPUTER_USE_LOG_DIR` | `%LOCALAPPDATA%\omni-computer-use\logs` | 旋转 `mcp.log`（工具调用 + 回溯）的目录。 |
| `COMPUTER_USE_GLOW` | `on` | 会话活动时的静态橙色边缘光晕。 |
| `COMPUTER_USE_SHRINK_TERMINAL` | `on` | 将控制窗口缩小到右上角。 |
| `COMPUTER_USE_HIDE_CONTROLLING` | `on` | 在捕获期间将控制窗口隐藏在屏幕外。 |
| `COMPUTER_USE_PILL` | `on` | 居中的“Claude 正在使用您的计算机”药丸。 |
| `COMPUTER_USE_GLOW_COLOR` | `217,119,87` | 光晕 / 药丸颜色（#D97757）。 |
| `COMPUTER_USE_GLOW_ALPHA` | `0.4` | 边缘光晕的最大不透明度。 |
| `COMPUTER_USE_GLOW_BAND` | `0.05` | 光晕带宽度占较小屏幕尺寸的分数。 |
| `COMPUTER_USE_GLOW_EXCLUDE` | `on` | 从捕获中排除光晕 / 药丸。 |
## 注意事项（真实的 Windows 行为）
- **IME 影响 `key` / `hold_key`，但不影响 `type`。** `type` 直接注入 Unicode 并绕过输入法（CJK 和表情符号在任何布局中都有效）。`key` / `hold_key` 发送虚拟键码，**通过**活动 IME — 因此，当活动 IME 为中文时，发送字母 `a` 会打开拼音候选列表，而不是输入 `a`。使用 `type` 输入文本；将 IME 切换到英语以获取字母快捷键。
- **提升的应用程序**（任务管理器，UAC 提示，管理员安装程序）无法驱动 — Windows UIPI 阻止来自非提升进程的输入。与桌面工具相同的限制。
## 测试
`tests/` 包含 16 个场景端到端测试套件（`scen_*.json`），以及驱动程序，启动全新的服务器并运行场景的 JSON 工具调用列表，交叉插入返回的图像：
```powershell
uv run python tests/drive.py tests/scen_calc.json # 计算 7×8 通过点击，截图，验证
```
`tests/dev/` 包含在开发过程中编写的特殊 Win32 探针（光晕/药丸采样，z 顺序和捕获亲和力实验）。
## 技术栈
Python ≥ 3.11，带有 [uv]，src 布局，hatchling。[ `mcp` ] Python SDK（FastMCP）通过 stdio；[ `mss` ] 用于捕获；[ `pillow` ] 用于成像；[ `pywin32` ] + `ctypes` 用于 DPI 感知，窗口 / 剪贴板 / 前台访问和原始 Win32 `SendInput` 鼠标/键盘注入。
## 隐私政策
omni-computer-use 完全在您的机器上运行，没有服务器端。
- **数据收集：无。** 源代码不导入任何网络库，不包含任何遥测、分析或崩溃报告。永远不会将任何数据上传到任何地方。
- **使用和存储。** 截图、剪贴板内容和输入事件在您的机器上在内存中处理，并仅通过 stdio 返回到您连接的 MCP 客户端。唯一写入磁盘的是一个旋转的本地日志（`mcp.log`，工具调用和回溯），位于 `%LOCALAPPDATA%\omni-computer-use\logs` 下 — 可通过 `COMPUTER_USE_LOG_DIR` 配置，可在任何时候删除。
- **第三方共享：无。** 无帐户，无外部服务，无第三方。
- **数据保留。** 您自己的磁盘上的日志轮换是唯一的保留方式；您控制它。
- **联系方式。** 隐私问题：[打开一个 GitHub 问题](https://github.com/Jason26214/omni-computer-use/issues)。
注意，您附加的任何 MCP 客户端（例如 Claude Desktop，Claude Code CLI）都会接收此服务器捕获的截图和文本，并受其自身的隐私政策约束。
## 许可证
MIT © Jason26214
[uv]: https://github.com/astral-sh/uv
[`mcp`]: https://github.com/modelcontextprotocol/python-sdk
[`mss`]: https://github.com/BoboTiG/python-mss
[`pillow`]: https://python-pillow.org/
[`pywin32`]: https://github.com/mhammond/pywin32
<!-- mcp-name: io.github.Jason26214/omni-computer-use -->
