Win32 自动化桥 qianbkk/aardio-windows-mcp

aardio Windows 自动化 MCP 桥接

概览：把 aardio 的全部能力——轻量、免安装的原生 Windows 开发语言——封装成标准 HTTP RPC 与 MCP（Model Context Protocol） 协议。
任何 AI 智能体、LLM 客户端或自动化脚本都能直接调用原生 Windows Win32 API、GUI 自动化、高精度鼠标/键盘控制、截图/取色能力，以及 1000+ aardio 标准库，无需额外开销。

┌────────────────────────────────────────────────────────┐
│ AI Assistant / Agent Clients (Claude / DSH / Cursor) │
└───────────────────────────┬────────────────────────────┘
│ Standard MCP stdio
▼
┌────────────────────────────────────────────────────────┐
│ MCP Bridge Protocol Layer (scripts/mcp-aardio-bridge) │
│ · Exposes 22 semantic tools (eval/exec/mouse/screen) │ │ · On-demand cold start, auto-recovery & self-healing │ └───────────────────────────┬────────────────────────────┘ │ Local HTTP RPC (127.0.0.1:42179) ▼ ┌────────────────────────────────────────────────────────┐ │ aardio Native Service Layer (dist/rpc-server.exe) │ │ · Core Bootstrap (31 endpoints): mouse/keys/proc/eval │ │ · Extension Layer (19 endpoints): images/QR/vault/etc.│ └────────────────────────────────────────────────────────┘

✨ 特性

- 🚀 零配置、独立运行：预编译成单个原生 Win32 可执行文件（rpc-server.exe，约 3MB）。不需要重量级运行时、SDK，也不用安装。
- 🔄 按需冷启动、自愈：MCP 桥接会自动检测服务健康状态。服务离线或被终止时，它会在 0.5s 内静默启动并无缝重试。不用时不占后台内存。
- ⚡ 图灵完备的动态求值：/api/eval 端点能在运行时动态执行任意 aardio 脚本，让 AI 立刻用上 1000+ Win32、COM、WMI、GDI+ 和加密库。
- 🖱️ 完整的 Computer Use 原语：精确的鼠标绝对坐标控制、左/右/双击、滚动、拖放、键盘热键/组合键，以及多显示器截屏。
- 🔌 通用智能体兼容：已在 DeepSeek Harness（DSH）、Claude Desktop、Claude Code、Cursor、Windsurf、LibreChat 和标准 MCP 客户端上测试通过。
- 🛑 完整生命周期控制：提供 server_stop 工具，自动化任务结束后 AI 可以关掉后台进程、释放资源。

📁 仓库结构

aardio_1/
├── README.md ← Project README (English)
├── README_CN.md ← 中文项目说明 (Chinese) ├── docs/ │ ├── CORE-BOOTSTRAP-SPEC.md ← Architectural spec & self-bootstrap proof │ ├── AARDIO-BRIDGE.md ← Full 50-endpoint RPC API reference │ ├── EXPERIENCE.md ← 开发笔记与最佳实践 │ └── MAINTENANCE.md ← 维护与自动化构建指南 ├── projects/00-rpc-server/ ← 核心服务器源码 │ ├── default.aproj ← aardio 项目定义 │ ├── main.aardio ← 核心引导模块（31 个端点） │ ├── ext-tools.aardio ← 扩展模块（19 个实用端点） │ └── dist/ │ ├── rpc-server.exe ← 编译好的独立服务器二进制 │ └── ext-tools.aardio ← 扩展模块分发副本 ├── scripts/ │ ├── mcp-aardio-bridge.py ← Python MCP 桥接（22 个 MCP 工具） │ ├── service-autostart.py ← 可选自启动管理器（winreg） │ ├── rebuild-rpc-server.py ← 无人值守自动重新编译 │ ├── stop-server.ps1 ← 优雅关闭脚本 │ └── test-all-endpoints.ps1 ← 全量回归测试套件 └── tools/ ← 30 个独立原生 aardio GUI 桌面工具

🚀 快速开始

1. 启动原生 RPC 服务器

直接运行预编译好的独立可执行文件： .\projects\00-rpc-server\dist\rpc-server.exe 端口发现：默认监听 127.0.0.1:42179。如果端口被占用，会自动偏移，并把当前端口保存到 %LOCALAPPDATA%\aardio-rpc\port.txt，供 MCP 桥接发现。

检查健康状态：
curl http://127.0.0.1:42179/api/health
Output: {"ok":true,"port":42179,"status":"running",...}

2. 直接使用 HTTP（任意语言 / 命令行）

1. Read system clipboard
curl "http://127.0.0.1:42179/api/clipboard"

2. Execute command
curl "http://127.0.0.1:42179/api/exec?cmd=ipconfig"

3. Dynamic aardio evaluation (access 1000+ libraries)
curl "http://127.0.0.1:42179/api/eval?expr=time.now()"

4. Get current cursor coordinates
curl "http://127.0.0.1:42179/api/mouse/pos"

5. List all 50 available endpoints
curl "http://127.0.0.1:42179/api/help"

🤖 接入 AI 智能体（MCP）

安装 Python 依赖（推荐 Python 3.10+）：
pip install mcp

1. Claude Desktop / Cursor / Windsurf

添加到 claude_desktop_config.json 或 mcp.json： {
"mcpServers": {
"aardio-bridge": {
"command": "python",
"args": [
"D:/path/to/aardio_1/scripts/mcp-aardio-bridge.py"
]
}
}
}

2. DeepSeek Harness（DSH）

方案 A：原生 DSH 插件（dsh-plugin-aardio）—— 带 Web GUI 开关！

把随附的包安装到你的配置档（例如 ~/.dsh/profiles/desktop）：
pnpm add file:D:/path/to/aardio_1/packages/dsh-plugin-aardio
添加到 cordis.patch.yml：
- id: dsh-plugin-aardio
name: "dsh-plugin-aardio"
disabled: false
会在 DSH Web GUI 中渲染一张独立插件卡片，带可交互的开关！

方案 B：标准 MCP 客户端

添加到 cordis.patch.yml：
- id: mcp-aardio
name: "@deepseek-ai/dsh-mcp-client"
config:
serverName: aardio
transport: stdio
command: "python"
args:
- "D:/path/to/aardio_1/scripts/mcp-aardio-bridge.py"
failOnStartupError: false

3. Claude Code 命令行

添加到 ~/.claude.json： {
"mcpServers": {
"aardio-bridge": {
"command": "python",
"args": [
"D:/path/to/aardio_1/scripts/mcp-aardio-bridge.py"
]
}
}
}

🛠️ MCP 工具参考（22 个工具）

| 工具名 | 分类 | 说明 |
| list_endpoints | 元工具 | 运行时动态查看全部 50+ 个可用 RPC 端点 |
| call_endpoint | 元工具 | 通用调用器，调用任意 RPC 端点，无需改动桥接代码 |
| eval | 核心 | 执行任意 aardio 表达式；访问全部 1000+ 个 Win32/COM 库 |
| server_stop | 生命周期 | 停止后台服务器释放内存；下次调用工具时自动重启 |
| clipboard_read / clipboard_write | 剪贴板 | 读取 Windows 系统剪贴板文本，或写入文本 |
| exec / exec_bg | Shell | 同步或非阻塞执行命令，返回输出或 PID |
| screenshot | 视觉 | 截取全屏或活动窗口，保存为图片文件 |
| mouse_pos / mouse_move / mouse_click / mouse_scroll | 计算机操作 | 定位光标、模拟点击（左键/右键/双击）、滚轮滚动 |
| keyboard | 输入 | 发送按键、热键（Ctrl+C、F7），或输入任意文本字符串 |
| window_list / window_topmost | 窗口 | 枚举所有桌面窗口句柄/标题，切换置顶状态 |
| process_list / process_kill | 进程 | 按内存/CPU/PID 排序查询运行中的进程，终止进程 |
| find_files | 文件系统 | 高性能通配符与递归文件扫描器 |
| http_get / weather / sqlite_query | 实用工具 | 原生 HTTP 代理、天气查询、直接执行 SQLite 查询 |

端点详细文档见 docs/AARDIO-BRIDGE.md，架构原理见 docs/CORE-BOOTSTRAP-SPEC.md。

⚙️ 编译与开发

要修改源码或添加自定义底层端点：
1. 下载免费的便携版 aardio IDE（约 6.5MB）。
2. 打开 projects/00-rpc-server/default.aproj。
3. 编辑 main.aardio（核心端点）或 ext-tools.aardio（扩展端点）。
4. 在 IDE 内按 F7，发布新的 dist/rpc-server.exe。
5. 也可以运行无人值守的无头重建脚本：
python scripts/rebuild-rpc-server.py

📄 许可证

基于 MIT License 分发。个人与商业用途均免费。