Metadata-Version: 2.4
Name: peekaboowin
Version: 0.1.2
Summary: Windows 桌面自动化 MCP 服务器 - 让 AI 代理能看见和操作 Windows 桌面应用
Author: wangneal
License: MIT
Project-URL: Homepage, https://github.com/wangneal/PeekabooWin
Project-URL: Repository, https://github.com/wangneal/PeekabooWin
Project-URL: BugTracker, https://github.com/wangneal/PeekabooWin/issues
Keywords: mcp,windows,automation,uia,desktop-automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Desktop Environment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: structlog>=24.0
Requires-Dist: comtypes>=1.4
Requires-Dist: mss>=9.0
Requires-Dist: Pillow>=10.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: numpy>=1.24
Provides-Extra: ocr
Requires-Dist: paddleocr>=2.8; extra == "ocr"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# PeekabooWin MCP

Windows 桌面自动化 MCP 服务器 — 让 AI 代理能看见和操作 Windows 桌面应用。

基于 Windows UI Automation (UIA) + SendInput + PaddleOCR，提供完整的桌面交互能力：元素发现、输入模拟、截图、窗口管理、剪贴板、OCR 识别。

---

## 系统要求

- **操作系统**: Windows 10 或 Windows 11
- **工具**: 推荐 [uv](https://docs.astral.sh/uv/)（Python 包管理）
- **权限**: 管理员身份运行可解锁所有功能（向提升权限窗口发送输入）
- **OCR**: 可选，需安装 PaddleOCR（约 1GB）

---

## 安装

### 方式一：一键安装（推荐）

```powershell
irm https://raw.githubusercontent.com/wangneal/PeekabooWin/main/install.ps1 | iex
```

脚本自动安装 uv 和 PeekabooWin，打印 MCP 配置。

### 方式二：uvx 直接运行（无需安装）

```bash
uvx peekaboowin
```

第一次自动从 PyPI 下载缓存，之后秒级启动。

### 方式三：安装到本地

```bash
# 需要先安装 uv: https://docs.astral.sh/uv/#installation

# 从 PyPI 安装（推荐）
uv tool install peekaboowin

# 可选：OCR 扩展（约 1GB）
uv tool install peekaboowin[ocr]

# 或从源码安装
git clone https://github.com/wangneal/PeekabooWin.git
cd PeekabooWin
uv pip install -e ".[ocr]"
```

安装后可用 `peekaboowin` 命令直接启动。

---

## MCP 客户端配置

安装后，在不同客户端中添加以下配置。

### OpenCode

配置文件: `C:\Users\<用户名>\.config\opencode\opencode.json`

**uvx 方式（推荐，无需安装）：**

```json
{
  "mcp": {
    "peekaboowin": {
      "type": "local",
      "command": ["uvx", "peekaboowin", "-y"],
      "enabled": true
    }
  }
}
```

**安装后直接运行：**

```json
{
  "mcp": {
    "peekaboowin": {
      "type": "local",
      "command": ["peekaboowin"],
      "enabled": true
    }
  }
}
```

两种方式任选一种，uvx 方式会自动从 PyPI 下载并缓存，无需手动安装。

### Claude Desktop

配置文件: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "peekaboowin": {
      "command": "uvx",
      "args": ["peekaboowin", "-y"]
    }
  }
}
```

### Cursor

设置路径: Settings → Features → MCP Servers → Add custom MCP

```json
{
  "mcpServers": {
    "peekaboowin": {
      "command": "uvx",
      "args": ["peekaboowin", "-y"]
    }
  }
}
```

### Windsurf

配置文件: `~/.codeium/windsurf/mcp_config.json`

```json
{
  "mcpServers": {
    "peekaboowin": {
      "command": "uvx",
      "args": ["peekaboowin", "-y"]
    }
  }
}
```

### GitHub Copilot (VS Code)

配置文件: `.vscode/mcp.json`

```json
{
  "servers": {
    "peekaboowin": {
      "command": "uvx",
      "args": ["peekaboowin", "-y"]
    }
  }
}
```

所有客户端均已统一为 `uvx` 方式，自动从 PyPI 拉取，无需手动安装 pip。

---

## 工具参考

共 32 个工具，按功能分类：

### 截图与屏幕

| 工具 | 参数 | 说明 |
|------|------|------|
| `screenshot` | `monitor?`, `region?`, `image_format?`, `quality?` | 捕获屏幕或区域截图 |
| `capture_window` | `hwnd`, `image_format?`, `quality?` | 捕获指定窗口截图 |
| `list_monitors` | — | 列出所有显示器 |
| `health_check` | — | 系统诊断：DPI、权限、OCR 状态 |

### UI 元素发现

| 工具 | 参数 | 说明 |
|------|------|------|
| `find_element` | `name?`, `class_name?`, `automation_id?`, `scope?` | 按名称/类名/ID 查找元素；UIA 无结果时自动 OCR 降级 |
| `get_element_info` | `element_ref` | 获取元素详细属性 |
| `get_children` | `element_ref`, `depth?` | 获取子元素树 |
| `get_desktop` | `depth?` | 获取桌面元素树 |
| `harvest_ui` | `target?`, `depth?` | 一站式 UI 发现，UIA 稀疏时自动 OCR 补充 |

**元素引用格式**: `hwnd:12345` / `point:100,200` / `desktop`

**harvest_ui target**: `desktop`（所有窗口）/ `foreground`（前台窗口）/ `12345`（指定 HWND）

### 输入模拟

| 工具 | 参数 | 说明 |
|------|------|------|
| `click` | `x`, `y`, `button?`, `double?` | 鼠标点击（自动聚焦目标窗口） |
| `move_mouse` | `x`, `y` | 移动鼠标（自动聚焦目标窗口） |
| `drag` | `x1`, `y1`, `x2`, `y2`, `duration?` | 拖拽（自动聚焦起始窗口） |
| `scroll` | `x`, `y`, `delta?` | 滚动（自动聚焦目标窗口） |
| `type_text` | `text` | 输入 Unicode 文本（盲发，需先激活窗口） |
| `press_keys` | `keys` | 按键组合：`ctrl+s`, `alt+tab`, `win+r` 等 |
| `click_element` | `element_ref` | 语义点击（自动聚焦目标窗口） |
| `type_into_element` | `element_ref`, `text` | 语义输入（自动聚焦目标窗口） |

**press_keys 支持的键名（128+ 个）**:

格式: `press_keys("组合")`，多个键用 `+` 连接，如 `ctrl+s`、`alt+tab`、`win+r`、`ctrl+shift+escape`。不区分大小写。

| 类别 | 键名 | 别名 |
|------|------|------|
| 修饰键 | `ctrl`, `alt`, `shift`, `win` | `control`, `lctrl/rctrl`, `lalt/ralt`, `lshift/rshift`, `lwin/rwin` |
| 导航 | `enter`, `tab`, `escape`, `space`, `backspace`, `delete` | `return`, `esc`, `back`, `del`, `forward_delete` |
| 方向 | `up`, `down`, `left`, `right` | — |
| 功能键 | `f1` ~ `f24` | — |
| 编辑 | `home`, `end`, `pageup`, `pagedown`, `insert` | `pgup`, `pgdn`, `ins` |
| 锁定 | `capslock`, `numlock`, `scrolllock` | — |
| 小键盘 | `num0` ~ `num9`, `numpad0` ~ `numpad9` | `numseparator` |
| 小键盘运算 | `numpad_add`, `numpad_subtract`, `numpad_multiply`, `numpad_divide`, `numpad_decimal` | `num+`, `num-`, `num*`, `num/`, `num.` |
| 多媒体 | `volumeup`, `volumedown`, `volumemute`, `nexttrack`, `prevtrack`, `playpause`, `stop` | — |
| 浏览器 | `browserback`, `browserforward`, `browserrefresh`, `browserstop`, `browsersearch`, `browserfavorites`, `browserhome` | — |
| 启动 | `launchmail`, `launchcalculator`, `launchmedia`, `launchapp1`, `launchapp2` | — |
| 其他 | `printscreen`, `pause`, `break`, `apps`, `sleep`, `clear`, `help`, `select`, `execute`, `print` | `prtsc` |
| 符号单字符 | `= + - [ ] \ ; ' , . / `` ` | 自动通过 VkKeyScanW 解析，`+` 会自动按下 Shift |

**示例**:
- `press_keys("win")` — 打开开始菜单
- `press_keys("win+r")` — 打开运行对话框
- `press_keys("ctrl+shift+escape")` — 打开任务管理器
- `press_keys("alt+f4")` — 关闭当前窗口
- `press_keys("win+d")` — 显示桌面

### 窗口管理

| 工具 | 说明 |
|------|------|
| `list_windows` | 列出所有可见窗口 |
| `get_foreground_window` | 获取前台窗口信息 |
| `activate_window` `hwnd` | 激活窗口到前台 |
| `move_window` / `resize_window` | 移动/调整窗口 |
| `minimize_window` / `maximize_window` / `restore_window` | 最小化/最大化/还原 |
| `close_window` | 发送 WM_CLOSE 关闭窗口 |

### 等待/轮询

| 工具 | 参数 | 说明 |
|------|------|------|
| `wait_for_element` | `name?`, `automation_id?`, `class_name?`, `control_type?`, `timeout?`, `interval?`, `visible?` | 等待元素出现/消失 |
| `wait_for_window` | `title?`, `class_name?`, `timeout?`, `interval?`, `appear?` | 等待窗口出现/消失 |

### 剪贴板

| 工具 | 参数 | 说明 |
|------|------|------|
| `read_clipboard` | — | 读取剪贴板文本 |
| `write_clipboard` | `text` | 写入剪贴板 |
| `paste_text` | `text` | 写入剪贴板 + Ctrl+V |

### OCR

| 工具 | 参数 | 说明 |
|------|------|------|
| `ocr_read` | `source?`, `hwnd?`, `region?`, `lang?` | OCR 文本识别，支持屏幕/窗口/区域 |

---

## 配置

通过环境变量配置，前缀 `PEEKABOOWIN_`：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `PEEKABOOWIN_LOG_LEVEL` | `info` | 日志级别 |
| `PEEKABOOWIN_LOG_FORMAT` | `json` | 日志格式 |
| `PEEKABOOWIN_SCREENSHOT_FORMAT` | `png` | 截图格式 |
| `PEEKABOOWIN_SCREENSHOT_QUALITY` | `85` | JPEG 质量 |
| `PEEKABOOWIN_SCREENSHOT_MAX_WIDTH` | `1920` | 截图最大宽度 |
| `PEEKABOOWIN_OCR_ENABLED` | `false` | OCR 开关（有 paddleocr 时自动开启） |
| `PEEKABOOWIN_OCR_LANGUAGE` | `ch` | OCR 语言 |
| `PEEKABOOWIN_UIA_TIMEOUT` | `2.0` | UIA 操作超时（秒） |
| `PEEKABOOWIN_UIA_MAX_DEPTH` | `10` | UIA 树遍历最大深度 |
| `PEEKABOOWIN_INPUT_CLICK_DELAY` | `0.05` | 点击后延迟（秒） |
| `PEEKABOOWIN_INPUT_TYPE_DELAY` | `0.02` | 按键间延迟（秒） |

示例:
```json
{
  "mcpServers": {
    "peekaboowin": {
      "command": "peekaboowin",
      "env": {
        "PEEKABOOWIN_LOG_LEVEL": "debug",
        "PEEKABOOWIN_SCREENSHOT_MAX_WIDTH": "3840"
      }
    }
  }
}
```

---

## AI Agent 提示词指南

### 核心规则

1. **每步操作后必须等待确认** — `press_keys("win+r")` 后必须 `wait_for_window(title="运行")`，不能连续发操作
2. **先观察后操作** — 用 screenshot / harvest_ui 了解界面状态再执行
3. **语义操作优先** — `click_element` / `type_into_element` 优于坐标操作
4. **UWP 应用特殊处理** — UIA 树稀疏时 `find_element` 自动降级到 OCR，结果带 `"source": "ocr_fallback"` 标记

### 示例：打开记事本

```
press_keys("win+r")
wait_for_window(title="运行", timeout=3)
type_text("notepad")
press_keys("enter")
wait_for_window(title="记事本", timeout=5)
type_text("Hello from AI!")
screenshot()
```

### 自动聚焦说明

- `click` / `click_element` / `type_into_element` / `drag` / `scroll` / `move_mouse` 会自动 `AttachThreadInput` + `SetForegroundWindow` 激活目标窗口
- `type_text` / `press_keys` 是盲发操作，不会自动聚焦，使用前需 `activate_window`

---

## 架构

```
Tool Layer      — 32 个 @mcp.tool()，统一 @tool_error_handler 装饰器
Service Layer   — 单例服务，业务逻辑编排
Platform Layer  — comtypes (UIA) / ctypes (SendInput) / mss (截图) / PaddleOCR
```

三层职责清晰：Tool 层做参数校验，Service 层编排逻辑，Platform 层封装 Win32 API。

---

## 限制

- **仅 Windows 10/11** — 依赖 Windows UI Automation API
- **UWP 应用 UIA 稀疏** — 自动降级到 OCR，但 OCR 元素缺少 `automation_id` / `hwnd`，无法用于 `click_element`
- **窗口截图非真实窗口内容** — `capture_window` 使用 BitBlt 屏幕裁剪，UWP/DirectX 窗口显示黑屏
- **后台点击有限** — UIA InvokePattern 可实现后台操作，当前尚未实现
- **UAC 隔离** — 非管理员进程无法向提升权限窗口发送输入

---

## License

MIT
