yingdao-RPA-mcp

把影刀（ShadowBot）社区版机器人变成 AI 助手里的"原生工具"—— 微信里说一句话，就能列出、启动、停止你电脑上的 RPA 流程。

English TL;DR: An MCP (Model Context Protocol) server that exposes Yingdao/ShadowBot Community Edition RPA robots to any AI client. Local stdio + remote streamable-http (Tailscale-friendly) with token auth, a built-in Mock mode, graceful-stop-only design (never kill processes), and 94 cross-platform tests. MIT licensed, unofficial, community-driven.

为什么做这个

影刀社区版没有官方 API，机器人只能靠人点界面启动。已有的民间方案（见致谢）解决了 "远程一键启动"，但接到 AI 助手上还有四道坎：协议不对口（AI 助手说 MCP）、跑完没下文（拿不到结构化结果）、 停止不可靠（杀进程会烂尾）、远程不安全（裸端口）。

本项目把影刀社区版的四条"民间侦察通道"封装成 5 个标准 MCP 工具，在 52 台真实机器人的环境里、 通过微信 AI 助手完成了端到端验收。

Related MCP server: mcp-windows-server

功能特性

• 🔧 5 个 MCP 工具：list_robots 列出 / run_robot 启动（支持中文传参、产出文件回收）/ get_status 三层日志验证 / stop_robot 优雅停止 / tail_log 排障

• 🔌 双传输：本地 stdio（Claude Desktop 即插即用）+ 远程 streamable-http（Tailscale 组网跨网操控）

• 🔐 安全边界：静态 Bearer token、绑定地址可控、stateless-http（网关重启对客户端透明）、 Windows 防火墙仅放行 Tailscale 网段

• 🧪 Mock 模式：没有 Windows / 没装影刀也能体验全部工具，同时是 94 个自动化测试的替身

• 🛑 只优雅停止，永不杀进程：keybd_event 发送 Ctrl+Alt+Q（工具描述内置全局停止警告， AI 会先向你确认）

• 🇨🇳 中文友好：机器人名/传参值支持中文原样，错误信息统一"code + 中文说明 + 下一步提示"

• 📦 Windows 一键安装：一条命令完成 Python 探测、虚拟环境、token、防火墙、开机自启、自检

5 个工具一览

快速开始

前置条件

• 影刀社区版已安装（官网）

• Python 3.10+（仅本地 stdio / 手动运行需要；一键安装脚本会自动引导）

• 一个支持 MCP 的 AI 客户端（Claude Desktop、微信 AI 助手等）

形态一：Mock 模式（先体验，30 秒）

任何系统（含 Linux/macOS）都能跑，不需要影刀：

pip install -e .
python -m yingdao_rpa_mcp --mock        # stdio，接到任意 MCP 客户端

MCP Inspector 里看效果：

npx @modelcontextprotocol/inspector python -m yingdao_rpa_mcp --mock

你会看到 3 个演示机器人，所有返回都带 "mock": true 标识。

形态二：本机 AI 客户端（Claude Desktop + 真实影刀，stdio）

Claude Desktop 配置文件（claude_desktop_config.json）中加入：

{
  "mcpServers": {
    "yingdao-rpa-mcp": {
      "command": "python",
      "args": ["-m", "yingdao_rpa_mcp"]
    }
  }
}

重启 Claude Desktop，然后对它说："列出我的影刀机器人"。 （完整样例见 examples/mcp.claude-desktop.json）

形态三：远程 AI 助手（Tailscale + token，http）——微信操控家里的影刀

AI 助手在云服务器、影刀在你家 PC？两步：

1. PC 上一键安装（管理员 PowerShell，在仓库目录）：

   .\scripts\install-windows.ps1

   自动完成：Python 探测 → 虚拟环境 → token 生成 → 防火墙仅放行 Tailscale 网段 → 登录自启 → 401 自检

2. 组网与接线：按 examples/tailscale-setup.md 走（含一个必踩的 DNS 坑的解法）

之后在微信里说"列出我的影刀机器人"即可。完整配置样例见 examples/mcp.cow-assistant.json。

配置参考

优先级：CLI 参数 > 环境变量（前缀 YINGDAO_MCP_）> config.toml。 全量带注释样例见 examples/config.toml，常用项：

架构

MCP 工具层（FastMCP：协议、参数校验、等待编排、错误语义）
        │
        ▼
ShadowBotGateway   ←—— 唯一架构接缝（scan / launch / status / stop / tail_log）
        │
   ├── MockGateway      产品功能（无 Windows 体验）兼全量自动化测试替身
   └── WindowsGateway   真实侦察通道（目录扫描 / URL Scheme / 日志三层验证 / keybd_event）

设计细节见 SPEC.md；94 个自动化测试全部基于 Mock，任何 OS 可跑（CI 双矩阵验证）。

踩坑 FAQ（全部来自真实部署）

Tailscale Linux 端默认 accept-dns=true，会劫持 /etc/resolv.conf（指向 100.100.100.100）， 而 MagicDNS 不转发公网域名。解法（我们用裸 IP 连 PC，不需要 MagicDNS）：

tailscale set --accept-dns=false
# 用 Docker 跑 AI 助手的话，重启一次容器刷新 resolv.conf

瞬时任务（几秒内跑完）的日志由影刀异步落盘，可能晚于验证窗口。v0.1.0 起已内置有界重试； 若仍出现，可用 tail_log / get_status 二次确认——就像下面这个真实案例：

启动检测窗口没赶上（launched: false），但日志显示 14:24:40 启动、14:24:41 正常退出（exitCode 0）。

网关进程在 AI 客户端两次调用之间被重启过（比如 PC 重启后计划任务拉起了新进程）。 当前版本已默认启用 stateless-http（无会话状态，重启透明）；旧版本遇到时重启 AI 客户端即可。

Windows PowerShell 5.1 对无 BOM 的 UTF-8 脚本按 GBK 解码。仓库内的脚本已带 BOM； 如果你自己改编过脚本，请确保以"UTF-8 with BOM"保存。

杀进程会让影刀内部状态机走不完，产出和日志烂尾，甚至不可恢复。Ctrl+Alt+Q 是影刀的全局停止快捷键， 必须用 keybd_event 发送（影刀靠全局键盘钩子监听，SendInput 触发不了）。 ⚠️ 它是全局停止——会停掉所有运行中的机器人，AI 调用前必须征得你确认。

与原仓库的关系

核心机制全部继承自 yingdao_robot_run_api_manage_and_skill， 本项目是其 MCP 化继任者。继承/补齐逐项对照见 docs/COMPARISON.md—— 如果你只想要一个带界面的桌面工具 + 局域网 REST，原仓库仍然是不二之选；想让 AI 原生操控影刀，用本项目。

🙏 致谢

本项目的核心机制并非发明，而是继承自湖南大白熊的 yingdao_robot_run_api_manage_and_skill（MIT，含 skills 技术文档）：

• 「侦察代替 API」哲学——不走企业版接口，用民间通道给社区版赋能

• 机器人发现：users\<ID>\apps 目录扫描（4 个候选 package 路径、_temp 跳过、mtime 排序）

• 启动与传参：shadowbot:Run?robot-uuid=…&key=value URL Scheme（含"仅编码 & = # % 空格、中文原样"的实测口径）

• 状态验证：影刀主日志解析（TaskManager / engine running / exited LIFO 配对）+ GetExitCodeProcess 存活检测

• 优雅停止：keybd_event 发送 Ctrl+Alt+Q（以及"SendInput 无法触发影刀全局钩子"的实测结论）， 还有"严禁杀进程"这条铁律

没有前人踩坑，就没有这个项目。如果你因本项目受益，请也给 原仓库 一个 Star。

⚠️ 免责声明

• 本项目为个人开源作品，与影刀官方（杭州分叉智能科技有限公司）无任何关联； "影刀 / ShadowBot"商标归其权利人所有

• 本项目使用未公开接口（URL Scheme、本地日志、全局快捷键）自动化操作影刀客户端， 这些通道可能随影刀版本更新失效，使用风险自担

• 仅供学习交流使用；stop_robot 会全局停止所有运行中的机器人，生产环境请自行评估

• 本项目继承的侦察机制同样继承原仓库的免责立场

License

MIT © 继承自 HnBigVolibear（原仓库）与 Seethelightdie（本项目）的贡献者