Windows 自动化/MCP 工具服务器

📚 相关资源

• 设计文档
• 架构导图
• 演示视频
• API文档

📋 目录

• 项目简介
• 环境要求
• 快速开始
• 基本交互
• 常见任务流程
• 配置文件
• 工具清单
• 常见问题
• 示例代码
• 相关资源

📖 项目简介

Windows 自动化/MCP 工具服务器，基于 stdio 的 JSON-RPC。提供窗口管理、鼠标/键盘、截图/OCR、文本查找点击、Shell 等工具，并支持任务规划执行。

核心特性

• ✅ 窗口管理与操作
• ✅ 鼠标/键盘自动化
• ✅ 截图与OCR识别
• ✅ 文本查找与点击
• ✅ Shell命令执行
• ✅ 任务规划与执行
• ✅ 离线语音识别（可选）

架构概览

• 入口点：src/main.rs 调用 server::run() 启动主循环
• 通信协议：JSON-RPC over stdio
• 可选组件：离线语音识别 Vosk（build.rs + VOSK_LIB_DIR）

🔧 环境要求

• 操作系统：Windows 10+ x86_64
• 开发工具：Rust MSVC 工具链（stable-x86_64-pc-windows-msvc）
• 可选依赖：Vosk 本地库（仅 stt_vosk_tool 需要）

🚀 快速开始

构建与运行

# 进入项目目录
cd d:\0721\main

# 构建发布版本
cargo build --release

# 运行程序
.\target\release\main.exe

MCP 客户端集成

可按 configs/cherrystudio.mcp.json 集成 MCP 客户端（如 Cherry Studio）。

📡 基本交互（JSON-RPC）

列出可用工具

{
  "id": 1,
  "method": "tools/list",
  "params": {}
}

调用工具

{
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "launch-hyphen-tool",
    "input": {
      "path": "C:\\Windows\\System32\\notepad.exe"
    }
  }
}

执行计划

{
  "id": 3,
  "method": "assistant/execute-plan",
  "params": {
    "steps": [
      {
        "tool": "launch-hyphen-tool",
        "input": {
          "path": "..."
        }
      },
      {
        "tool": "wait-window-tool",
        "input": {
          "title": "记事本"
        }
      }
    ]
  }
}

🔄 常见任务流程

启动并点击文本按钮

1. launch-hyphen-tool → 启动应用
2. wait-window-tool → 获取 hwnd
3. screenshot-hyphen-tool（mode:"window"）
4. ocr-hyphen-tool → 文本
5. find-text-hyphen-tool → 坐标
6. click-hyphen-tool 或 click-text-hyphen-tool → 点击

屏幕坐标识别

screenshot-hyphen-tool（mode:"screen" + region）配合 find-text-hyphen-tool

⚙️ 配置文件

配置文件	描述	主要配置项
configs/server.toml	服务器配置	transport = "stdio"，`log_level = "info"
configs/cherrystudio.mcp.json	MCP 客户端配置	命令与参数
build.rs	构建配置	VOSK_LIB_DIR（可选）
configs/brain.toml	规划策略配置	规划相关参数

🛠️ 工具清单

系统与窗口管理

工具名称	功能描述	输入参数	输出结果
launch-hyphen-tool	启动应用	{ path, args? }	{ pid }
wait-window-tool	等待窗口	{ title, timeout_ms }	{ hwnd }
focus-tool	聚焦窗口	{ hwnd }	{ ok }

输入与交互

工具名称	功能描述	输入参数	输出结果
click-hyphen-tool	鼠标点击	{ x, y, button }	{ ok }
type-tool	文本输入	{ text, enter? }	{ ok }
shortcut-hyphen-tool	快捷键	{ keys }	{ ok }

图像与文本处理

工具名称	功能描述	输入参数	输出结果
screenshot-hyphen-tool	截图	{ mode, hwnd?, region? }	{ image_bgra_base64 }
ocr-hyphen-tool	OCR识别	{ image_bgra_base64, lang }	{ text }
find-text-hyphen-tool	查找文本	{ image_bgra_base64, query, fuzz }	{ bbox, score }
click-text-hyphen-tool	文本点击	{ hwnd?, query, region? }	{ ok }

应用特定工具

工具名称	功能描述	输入参数	输出结果
play-cloudmusic-tool	网易云音乐控制	{ action }	{ ok }

注意：screenshot-hyphen-tool 使用两阶段捕获（窗口 DC BitBlt → 屏幕 DC 裁剪兜底），已移除 PrintWindow

❓ 常见问题

构建与运行

• 构建警告：未使用导入/变量不影响功能，可后续清理
• 权限问题：UAC 提升应用需管理员运行

截图与OCR

• 截图空白/裁剪错误：优先 mode:"window" + hwnd；必要时用 mode:"screen" + 明确 region
• 文本定位偏差：调 fuzz、限定 region、提高截图清晰度

💡 示例代码

截图工具

{
  "name": "screenshot-hyphen-tool",
  "input": {
    "mode": "window",
    "hwnd": 123456,
    "region": {
      "x": 0,
      "y": 0,
      "w": 800,
      "h": 600
    }
  }
}

文本查找

{
  "name": "find-text-hyphen-tool",
  "input": {
    "image_bgra_base64": "...",
    "query": "开始播放",
    "fuzz": 0.3
  }
}

鼠标点击

{
  "name": "click-hyphen-tool",
  "input": {
    "x": 100,
    "y": 200,
    "button": "left"
  }
}