Metadata-Version: 2.4
Name: peekaboowin
Version: 0.1.0
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。

### 方式二：手动安装

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

# 从 GitHub 安装
uv tool install git+https://github.com/wangneal/PeekabooWin.git

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

# 可选：OCR 扩展（约 1GB）
uv pip install -e ".[ocr]"
```

---

## MCP 客户端配置

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

### OpenCode

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

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

如果尚未安装，可让 opencode 自动通过 `uvx` 拉取：

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

> 注意：`uvx peekaboowin` 方式需要先将包发布到 PyPI。在发布之前，请先用 `uv tool install git+https://github.com/wangneal/PeekabooWin.git` 安装，然后使用 `"command": ["peekaboowin"]`。

### Claude Desktop

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

```json
{
  "mcpServers": {
    "peekaboowin": {
      "command": "peekaboowin",
      "env": {
        "PEEKABOOWIN_LOG_LEVEL": "info"
      }
    }
  }
}
```

### Cursor

设置路径: Settings → Features → MCP Servers → Add new MCP server

```json
{
  "mcpServers": {
    "peekaboowin": {
      "command": "peekaboowin"
    }
  }
}
```

### Windsurf

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

```json
{
  "mcpServers": {
    "peekaboowin": {
      "command": "peekaboowin"
    }
  }
}
```

### GitHub Copilot (VS Code)

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

```json
{
  "servers": {
    "peekaboowin": {
      "command": "peekaboowin"
    }
  }
}
```

---

## 工具参考

共 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 支持的键名**: 修饰键（ctrl/alt/shift/win）、导航（enter/tab/escape/方向键/delete/backspace）、功能键（f1-f24）、编辑（home/end/pageup/pagedown/insert）、小键盘（num0-num9/numpad 操作符）、符号单字符（= + - [ ] \ ; ' , . / `）自动通过 VkKeyScanW 解析。

### 窗口管理

| 工具 | 说明 |
|------|------|
| `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
