# Pi Computer-Use MCP

让 Pi 能直接操控 **Windows 桌面**（从 WSL 内发起）。

## 它做什么

本 MCP 服务器跑在 WSL（Node 进程），通过
`/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe`
调用 Windows 侧的 .NET 与 `user32.dll`，从而对**真实的 Windows 桌面**截屏、移动鼠标、敲键盘、操作窗口。

```text
Pi (WSL) ──stdio──> index.js (Node) ──powershell.exe──> Windows 桌面
```
## 安装

### 1. 前置条件

- **Windows 10/11** + **WSL2**（本服务器跑在 WSL 里，操控 Windows 桌面）
- WSL interop 必须开启（默认开启）：`/etc/wsl.conf` 里不要有 `interop.enabled = false`
- Node.js **>= 20**

### 2. 获取代码

````bash
git clone https://github.com/q18857450491-ux/wsl-computer-use-mcp.git
cd wsl-computer-use-mcp
npm install
````

### 3. 注册到 MCP 客户端

**Pi（配合 `pi-mcp-adapter`）** —— 把下面内容写进 `~/.pi/agent/mcp-adapter.json`：

```json
{
  "mcpServers": {
    "computer-use": {
      "command": "node",
      "args": ["/abs/path/to/wsl-computer-use-mcp/index.js"]
    }
  }
}
```

> ⚠️ 文件名必须是 **`mcp-adapter.json`** —— `pi-mcp-adapter` 不读 `mcp.json`（那个归 Pi 内置 MCP 用）。
> 仓库里的 `mcp-adapter.example.json` 可直接改路径使用。

**其他 MCP 客户端**（Claude Desktop、Cursor、Cline 等）：把同样的 `mcpServers` 段放进它们的配置文件即可。

### 4. 验证

```bash
node test.js        # 只读测试：截屏 / 列窗口 / 读剪贴板 —— 不会动鼠标键盘
```

看到 `结果：5 通过 / 0 失败` 即安装成功。

### 5. 试试看

在 AI 客户端里直接说：

- 「截个屏，看看现在屏幕上是什么」
- 「打开记事本，输入『你好』」
- 「列出所有窗口」
- 「点一下计算器的 7」


## 20 个工具（两种模式）

### 语义模式（UIA）—— 推荐先用

| 工具 | 说明 |
|---|---|
| `list_elements` | 列出窗口内控件：类型、文字、位置、可用模式（`Invoke`/`Value`…）。**能直接读到按钮文字** |
| `click_element` | 点击控件。优先 `InvokePattern` —— **不移动鼠标、不抢键盘焦点** |
| `set_text` | 往输入框写值（`ValuePattern.SetValue`）—— **不敲键盘**，中文/emoji 无忧 |
| `read_element` | 读控件内容（输入框的值、文本块的文字） |
| `focus_element` | 把键盘焦点移到控件（只改焦点，不发按键）|

### 坐标模式（user32.dll 输入模拟）


| 工具 | 说明 |
|---|---|
| `screen_info` | 屏幕尺寸、显示器列表、光标坐标、前台窗口句柄 |
| `screenshot` | 截图。`format=image` 返回图片；`format=file` 存盘返回路径。`scale` 控制缩放（默认 0.75）|
| `mouse_move` | 移动鼠标到 (x, y) |
| `mouse_click` | 点击（左/右/中，单击/双击/三击），可带坐标 |
| `mouse_drag` | 拖拽（选中文本、拖动窗口/文件）|
| `scroll` | 滚轮，正数向上 |
| `key_press` | 组合键：`ctrl+c`、`alt+tab`、`win+r`、`ctrl+shift+t`、`f5`… |
| `type_text` | 输入文本。默认走「剪贴板 + Ctrl+V」，**中文/emoji 都能可靠输入** |
| `list_windows` | 列出所有窗口（句柄/PID/进程/标题/位置），标记前台窗口 |
| `focus_window` | 激活窗口（用 handle / pid / title 指定）|
| `window_action` | `restore` / `minimize` / `maximize` / `close` |
| `launch_app` | 启动程序、打开文件或 URL |
| `get_clipboard` | 读剪贴板 |
| `set_clipboard` | 写剪贴板（支持中文）|
| `run_powershell` | 执行任意 PowerShell（万能后备）|

## 该用哪种模式

| | 语义模式（UIA）| 坐标模式 |
|---|---|---|
| 定位方式 | **按控件文字/类型**（`"取消"`、`Button`）| 屏幕像素坐标 |
| 侵入性 | **非侵入** —— 不夺鼠标、不抢焦点，你可同时用电脑 | 侵入 —— 操作期间鼠标会自己动 |
| 通用性 | 依赖应用的 UIA 支持 | **任何界面都能用**（游戏、canvas、自绘 UI）|
| 可靠性 | 界面改版也不易失效 | 界面一变坐标就废 |

**推荐流程**：`list_elements` 找出控件 → `click_element` / `set_text` 操作 → 若控件无 `Invoke`/`Value` 模式，再退回坐标模式（`screenshot` + `mouse_click` / `type_text`）。

### UIA 覆盖率实测（2026-09-29）

| 应用类型 | 支持度 | 实测结果 |
|---|---|---|
| **UWP / 现代应用**（计算器、Windows 设置）| ✅ 完整 | 计算器 52 控件、设置 51 控件；`Invoke`、`Value` 模式齐全，点击/写入全通过 |
| **Chromium**（Chrome / Edge）| ✅ 良好 | 读到 2235 个控件，`Button \| 关闭 \| Invoke,ScrollItem` |
| **Win11 记事本**（XAML Islands 混合）| ⚠️ 差 | 只暴露 2 个 `Pane`，编辑区无 UIA |
| **老式 Win32 对话框**（Win+R 运行框）| ⚠️ 差 | 控件全退化为 `Pane`，无 `Value`/`Invoke` 模式 |

→ 这正是必须**双轨**的原因：语义模式精准但不通用，坐标模式通用但侵入。

> `list_elements` 支持 `filter`（按文字搜）、`interactiveOnly`（只列可交互控件）、`maxItems`/`maxDepth` 控制输出量。默认最多 60 条，避免像 Chrome 那样一次吐出 2235 个。


## 坐标系统

坐标基于**虚拟桌面**（多显示器时是一整块画布）。
先用 `screen_info` 看 `virtual.x / virtual.y / virtual.width / virtual.height`，
再用 `screenshot` 观察实际布局。注意：截图若用了 `scale < 1`，
图片上的像素坐标要**除以 scale** 才是真实坐标。

## 关于中文输入

`type_text` 默认用剪贴板法：先把文本写入剪贴板 → 发 Ctrl+V → **恢复原剪贴板内容**。
因此中文、emoji、任何特殊符号都不会出问题。

如果想逐键敲（保留剪贴板），传 `method: "sendkeys"`，但该方式对非 ASCII 支持很差。

## 环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `COMPUTER_USE_POWERSHELL` | `/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe` | PowerShell 路径 |
| `COMPUTER_USE_SCALE` | `0.75` | 截图默认缩放 |
| `COMPUTER_USE_SHOT_DIR` | `/tmp/computer-use-shots` | `format=file` 时的存盘目录 |

## 自测

```bash
cd ~/.pi/mcp-servers/computer-use
node test.js          # 只读测试，不会动鼠标键盘
```

## 已知限制

- **需要 WSL interop**：若 `/etc/wsl.conf` 里 `interop.enabled=false`，本服务器无法工作。
- **每次调用约 0.2–1s**：PowerShell 每次都要 `Add-Type` 编译 P/Invoke 声明（约 300ms 开销）。
- **Windows 前台锁定**：`focus_window` 可能被 Windows 的 `SetForegroundWindow` 策略拒绝（返回 false），
  重试通常可成功，或改用点击任务栏。
- **首次截图较慢**：首次加载 `System.Drawing` 需 1–5 秒。
- **安全软件**：卡巴斯基等可能把「模拟鼠标键盘」判为可疑行为，建议把
  `powershell.exe` 与本项目所在目录加入排除项（路径形如 `\\wsl.localhost\<发行版名>\<你的家目录>\...`）。

## 安全须知

这套工具等同于**把 Windows 桌面的完全控制权**交给 AI：
能点任何按钮、输任何内容、执行任意 PowerShell。
`run_powershell` 风险最高——它可以在 Windows 上做任何当前用户权限内的事。

## 卸载

```bash
# 1. 从 pi 的 MCP 配置中移除
rm ~/.pi/agent/mcp-adapter.json     # 或删掉其中 computer-use 这一项

# 2. 删除本目录
rm -rf ~/.pi/mcp-servers/computer-use
```

## License

[MIT](LICENSE)