# RPA-Python MCP Server

基于 [Tebel.org RPA-Python](https://github.com/tebelorg/RPA-Python) 封装的 **MCP (Model Context Protocol)** 服务，让 AI 模型（Claude、GPT 等）能够直接操控浏览器，实现网页自动化。

## 项目结构

```
rpa_mcp_server.py       # MCP Server 主入口，注册 54 个 RPA 工具
tagui.py                 # RPA-Python 核心引擎（基于 TagUI）
test_mcp.py              # MCP Server 连通性测试（列出所有工具）
test_workflow_bing.py    # 端到端工作流测试（Bing 搜索自动化）
requirements.txt         # Python 依赖
```

## 快速开始

### 1. 安装依赖

```powershell
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

### 2. 安装 TagUI（首次使用）

```powershell
.venv\Scripts\python.exe -c "import tagui as r; r.setup()"
```

> TagUI 约 200MB，会自动安装到 `%APPDATA%\tagui\`。

### 3. 验证 MCP Server

```powershell
.venv\Scripts\python.exe test_mcp.py
```

正常输出应显示 54 个注册工具。

### 4. 运行端到端测试

```powershell
.venv\Scripts\python.exe test_workflow_bing.py
```

会自动打开 Chrome → Bing 首页 → 搜索框输入 "MCP" → 点击搜索，验证整个工作流。

## 配置到 AI 客户端

### Claude Desktop

在 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "rpa-python": {
      "command": "D:\\Javaproject\\RPA-Python\\.venv\\Scripts\\python.exe",
      "args": ["D:\\Javaproject\\RPA-Python\\rpa_mcp_server.py"]
    }
  }
}
```

### Cursor / VS Code

在 `.cursor/mcp.json` 或 VS Code MCP 配置中添加：

```json
{
  "mcpServers": {
    "rpa-python": {
      "command": ".venv\\Scripts\\python.exe",
      "args": ["rpa_mcp_server.py"],
      "cwd": "D:\\Javaproject\\RPA-Python"
    }
  }
}
```

## MCP 工具列表

共 **54 个工具**，按功能分类：

### 生命周期管理

| 工具 | 说明 |
|------|------|
| `rpa_init` | 启动 RPA 会话（支持 Chrome / Edge） |
| `rpa_close` | 关闭 RPA 会话 |
| `rpa_setup` | 下载安装 TagUI |
| `rpa_update` | 更新 RPA-Python 和 TagUI |
| `rpa_pack` | 打包 TagUI 用于离线部署 |

### 网页导航

| 工具 | 说明 |
|------|------|
| `rpa_url` | 打开网页 / 获取当前 URL |
| `rpa_frame` | 切换到 iframe |
| `rpa_popup` | 切换到弹窗 |
| `rpa_focus` | 聚焦应用程序窗口 |

### 元素交互

| 工具 | 说明 |
|------|------|
| `rpa_click` | 点击元素 |
| `rpa_rclick` | 右键点击 |
| `rpa_dclick` | 双击 |
| `rpa_hover` | 鼠标悬停 |
| `rpa_type` | 输入文本（支持 `[enter]` `[clear]` 等特殊键） |
| `rpa_select` | 选择下拉框选项 |

### 元素读取

| 工具 | 说明 |
|------|------|
| `rpa_read` | 读取元素文本 |
| `rpa_exist` | 检查元素是否存在（等待超时） |
| `rpa_present` | 检查元素是否立即存在 |
| `rpa_count` | 统计匹配元素数量 |
| `rpa_text` | 获取页面全部文本 |
| `rpa_title` | 获取页面标题 |

### 视觉自动化

| 工具 | 说明 |
|------|------|
| `rpa_snap` | 截图保存到文件 |
| `rpa_capture` | 截图返回 base64（供 AI 视觉分析） |
| `rpa_keyboard` | 模拟键盘输入 |
| `rpa_mouse` | 模拟鼠标按下/释放 |
| `rpa_mouse_xy` | 获取鼠标坐标 |
| `rpa_mouse_x` / `rpa_mouse_y` | 获取鼠标 X/Y 坐标 |
| `rpa_clipboard` | 读写剪贴板 |
| `rpa_vision` | 执行 SikuliX 视觉命令 |

### DOM / JavaScript

| 工具 | 说明 |
|------|------|
| `rpa_dom` | 执行 JavaScript 并返回结果 |

### 文件操作

| 工具 | 说明 |
|------|------|
| `rpa_upload` | 上传文件 |
| `rpa_download` | 下载文件 |
| `rpa_load` | 读取文件内容 |
| `rpa_dump` | 写入文件（覆盖） |
| `rpa_write` | 追加写入文件 |
| `rpa_download_location` | 设置下载目录 |
| `rpa_unzip` | 解压 zip 文件 |

### 表格提取

| 工具 | 说明 |
|------|------|
| `rpa_table` | 提取 HTML 表格为 CSV |

### 工具函数

| 工具 | 说明 |
|------|------|
| `rpa_wait` | 等待指定秒数 |
| `rpa_timeout` | 设置元素等待超时 |
| `rpa_timer` | 获取会话已运行时间 |
| `rpa_echo` | 打印消息 |
| `rpa_ask` | 弹出输入框获取用户输入 |
| `rpa_get_text` | 从字符串中提取子串 |
| `rpa_del_chars` | 删除字符串中指定字符 |
| `rpa_check` | 条件判断打印 |
| `rpa_debug` | 开启/关闭调试模式 |
| `rpa_error` | 开启/关闭异常模式 |

### 系统 & 通讯

| 工具 | 说明 |
|------|------|
| `rpa_run` | 执行系统命令 |
| `rpa_telegram` | 发送 Telegram 消息 |
| `rpa_bin` | 上传文件到 pastebin |
| `rpa_send` | 发送原始 TagUI 指令 |
| `rpa_tagui_location` | 设置 TagUI 安装路径 |

## 典型工作流

```
1. rpa_init(chrome_browser=True)          → 启动浏览器
2. rpa_url("https://example.com")         → 打开网页
3. rpa_type("#search-box", "关键词")       → 输入文本
4. rpa_click("#submit-btn")               → 点击按钮
5. rpa_read("#result")                    → 读取结果
6. rpa_close()                            → 关闭浏览器
```

## 浏览器支持

| 参数 | 浏览器 |
|------|--------|
| `browser="chrome"` | Google Chrome（默认） |
| `browser="edge"` | Microsoft Edge |

## 依赖

- Python 3.8+
- [MCP SDK](https://github.com/modelcontextprotocol/python-sdk) >= 1.0.0
- [TagUI](https://github.com/tebelorg/TagUI)（自动安装）
- Chrome 或 Edge 浏览器

## 许可证

基于 [Tebel.org RPA-Python](https://github.com/tebelorg/RPA-Python) (Apache License 2.0) 构建。