Windows桌面应用自动化工具

WinApp MCP

Website · GitHub · npm · VS Code Marketplace

Playwright for Windows Desktop Apps

A Model Context Protocol (MCP) server that gives AI assistants full control over native Windows applications — launch, inspect, click, type, screenshot, and test any WinUI3, WPF, WinForms, UWP, or Win32 app.

为什么存在

浏览器自动化有Playwright。Mobile有Appium。但是 AI代理的Windows桌面自动化？ 现有的选择不够深入。

GitHub Copilot、Claude和ChatGPT等人工智能助手可以浏览网页、运行终端命令和编辑文件。但他们 无法与本机Windows应用程序交互。他们无法单击WinUI3应用程序中的按钮，无法从WPF窗体读取值，也无法测试WinForms对话框。

WinApp MCP弥合了这一差距。 它通过以下方式公开了55个UI自动化工具 模型上下文协议，让任何兼容MCP的人工智能助手控制Windows桌面应用程序，就像Playwright控制浏览器一样。

问题

解决方案

WinApp MCP提供人工智能助手 眼睛和手 对于任何Windows桌面应用程序：

┌─────────────────────┐      MCP (stdio)      ┌──────────────────────┐
│   AI Assistant       │◄─────────────────────►│   WinApp MCP Server  │
│   (Copilot, Claude)  │   JSON-RPC over stdio │   (.NET 10 + FlaUI)  │
└─────────────────────┘                        └──────────┬───────────┘
                                                          │ UI Automation
                                                          ▼
                                               ┌──────────────────────┐
                                               │  Windows Application │
                                               │  WinUI3/WPF/WinForms│
                                               └──────────────────────┘

主要特点

🔍 深度UI检查

• 类似DOM的快照 整个UI元素树的深度可配置
• 筛选的搜索 按控件类型、Automation Id或名称
• 模糊匹配 Levenshtein距离——允许拼写错误和部分名称
• 元素存在检查 --无需读取完整属性的快速布尔查询

🖱️ 完全互动

• 单击、双击、右键单击、调用（通过UIA模式）
• 键入文本、按键、组合键（Ctrl+S、Alt+F4等）
• 填写完整表格 在一次调用中--无顺序键入
• 在一个原子操作中选择下拉选项
• 在元素之间拖放
• 展开/折叠树项目、菜单和手风琴

🪟 多窗口HWND瞄准

• 通过本机句柄（HWND）定位特定窗口
• 单击、设置值并拍摄弹出窗口、对话框和辅助窗口的快照
• 对于多窗口应用程序和系统对话框至关重要

⚡ 性能优化

• 后代缓存 （2s TTL）——避免重复 FindAllDescendants 复杂应用程序上需要200-800毫秒的通话
• 窗口缓存 （30s TTL）--消除了昂贵的窗口查找
• 智能缓存失效 --突变后缓存会自动清除（单击、键入、导航）
• 令牌感知截图 --自动调整图像大小以适应LLM上下文限制

📊 高级UIA模式

• 网格图案 --DataGrid中按行/列直接访问单元格
• 滚动ItemPattern --滚动屏幕元素进入视图
• 虚拟化项目模式 --实现WinUI3虚拟化列表（ListView、GridView）中的项目
• 展开折叠模式 --树项目和菜单的程序化展开/折叠
• 数据容器模式 --大型/虚拟化容器中的高效搜索

📡 事件监控

• 监视器 焦点变化, 结构变化 （添加/删除元素），以及 属性变化 实时的
• 基于会话的500事件环形缓冲区
• 调试异步UI更新、动画和后台数据加载

📸 目视验证

• 带有LLM代币预算自动调整大小的屏幕截图
• 带注释的屏幕截图 --在指定图元周围绘制红色边界框
• 像素差异比较 --比较两个屏幕截图并突出显示更改
• HWND针对特定窗口的截图

🪟 最小化和锁定会话支持

• 应用程序最小化时有效 --在鼠标/键盘操作之前自动恢复窗口，使用 PrintWindow API用于屏幕截图而无需恢复
• 桌面锁定时工作 --通过UIA模式（调用模式、切换模式、选择项模式）而不是鼠标模拟进行点击；通过ValuePattern读取/写入值；通过以下方式捕获屏幕截图 PrintWindow
• 智能回退链 --尝试UIA模式→ 自动恢复+鼠标模拟→ 信息性错误
• 会话状态检测 — check_session_status 报告会话是否已锁定、应用程序是否已最小化以及哪些操作可用
• 手动恢复 — restore_window 按需将最小化的应用程序带回前台

为什么重要： 运行长自治管道的AI代理不应该因为屏幕保护程序启动或用户最小化应用程序而崩溃。WinApp MCP会优雅地降级——即使鼠标/键盘模拟无法正常工作，基于UIA模式的操作也会继续工作。

🛡️ 安全

• 紧急释放 --通过一次调用松开所有修改键和鼠标按钮
• 等待图元 --等待元素、条件和输入空闲状态
• 超时控制 关于所有封锁行动

用例

🤖 AI驱动的E2E测试

让AI助手以QA工程师的方式测试您的Windows应用程序——导航页面、填写表单、验证数据、测试状态转换、捕获证据。

"Navigate to Invoices → Create New → Fill all fields → Save → Verify detail page → Test status change to Sent"

🔄 自动UI验证

在代码生成或重构之后，让AI启动应用程序，并验证UI是否正确呈现，按钮是否正常工作，表单是否正确验证。

🧪 视觉回归测试

拍摄基线截图，进行更改，拍摄新截图，并使用 screenshot_diff 以检测意外的视觉变化。

📋 表单自动化和数据输入

在单个表单中填写复杂的多字段表单 fill_form 电话。自动化跨桌面应用程序的重复数据输入。

🏗️ CI/CD桌面测试

集成到构建管道中，以便在每次构建后自动测试桌面应用程序。MCP服务器通过stdio传输运行无头兼容。

🔍 可访问性审计

检查UI自动化树，以验证所有控件是否具有正确的Automation ID、名称和模式——这对屏幕阅读器的兼容性至关重要。

安装

适用于 任何MCP客户端 --VS Code、Claude Desktop、Cursor、Windsurf、Cline等。

选项1:npm（随处可用）⭐

使用任何MCP客户端运行WinApp MCP的通用方法。不。需要NET SDK。

npm install -g winapp-mcp

或者直接运行而不安装：

npx -y winapp-mcp

然后添加到MCP客户端配置中（请参阅 客户端特定配置 在......下面

选项2:VS代码扩展（VSIX）

VS Code/GitHub Copilot用户最简单的方法。捆绑MCP服务器并在安装时自动注册。

1. 下载最新 .vsix 文件来自 发布
2. 在VS代码中： Ctrl+Shift+P → “扩展：从VSIX安装…” → 选择文件
3. 重新加载VS代码——MCP服务器自动注册

注： 也可从 VS代码扩展市场 --在扩展中搜索“WinApp MCP”。

选项3：从源代码构建

git clone https://github.com/floatingbrij/desktop-pilot-mcp.git
cd desktop-pilot-mcp/src
dotnet build
dotnet run

发布为自包含的可执行文件（目标上不需要.NET SDK）：

dotnet publish -c Release -r win-x64 --self-contained
# Output: bin/Release/net10.0-windows10.0.19041.0/win-x64/publish/WinAppMCP.exe

客户端配置

VS代码/GitHub副本

选项A --安装VSIX（自动注册，无需配置）。

选项B --添加到 .vscode/mcp.json 在您的工作空间中：

{
  "servers": {
    "winapp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "winapp-mcp"]
    }
  }
}

克劳德桌面

添加 %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "winapp": {
      "command": "npx",
      "args": ["-y", "winapp-mcp"]
    }
  }
}

光标

添加到光标设置→ MCP服务器，或 .cursor/mcp.json:

{
  "mcpServers": {
    "winapp": {
      "command": "npx",
      "args": ["-y", "winapp-mcp"]
    }
  }
}

帆板运动

添加 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "winapp": {
      "command": "npx",
      "args": ["-y", "winapp-mcp"]
    }
  }
}

Cline（VS代码扩展）

通过临床MCP设置或 cline_mcp_settings.json:

{
  "mcpServers": {
    "winapp": {
      "command": "npx",
      "args": ["-y", "winapp-mcp"]
    }
  }
}

任何其他MCP客户端

WinApp MCP使用 stdio传输 （JSON-RPC通过标准输入/标准输出）。为您的客户指出：

npx -y winapp-mcp

或者直接在可执行文件上：

path/to/WinAppMCP.exe

⚠️ 注意事项

此工具控制您的鼠标和键盘。 当自动化运行时，它将移动光标、单击按钮并键入文本。在测试执行期间，不要与计算机交互——这可能会干扰自动化并产生意外结果。

最小化/锁定模式： 当应用程序最小化或会话锁定时，WinApp MCP会自动回退到UIA模式（调用模式、值模式） PrintWindow 对于屏幕截图，在此模式下不使用鼠标或键盘模拟。

开始之前

• 关闭敏感应用程序 --该工具可以列出所有可见的窗口及其标题。在自动化会话期间关闭私人应用程序。
• 保存您的工作 --自动化与实时应用程序交互。不正确的单击可能会关闭其他应用程序中未保存的工作。
• 单次会话 --一次运行一个自动化会话。并发会话可能会导致鼠标/键盘冲突。

自动化过程中

• 请勿触摸鼠标/键盘 --让自动化完成。在操作过程中移动鼠标可能会导致点击错过目标。
• 使用 release_all --如果自动化意外停止，并且您的Ctrl/Shift/Alt键感觉“卡住”，请致电 release_all 重置。
• 观察超时 --所有阻塞操作都有超时。如果一个元素没有出现，调用将优雅地失败，而不是挂起。

已知限制

• 仅限Windows --需要Windows 10版本1903+或Windows 11
• UI自动化依赖关系 --目标应用程序必须公开UIA树。完全自定义绘制的应用程序（DirectX/OpenGL游戏、具有自定义渲染的Electron）可能对UIA支持有限或没有支持。
• 无跨进程剪贴板写入 — get_clipboard 读取剪贴板内容，但不写入
• 流程范围 --服务器每次为每个应用ID连接一个应用。为多应用工作流使用多个应用ID。
• 屏幕分辨率 --屏幕截图坐标是绝对的。远程办公桌上的自动化或不同的DPI可能需要调整。
• 管理员应用程序 --如果目标应用程序以管理员身份运行，则MCP服务器也必须以提升权限运行。
• 单显示器优化 --多显示器坐标转换不自动处理
• 锁定会话限制 --当桌面锁定（Win+L）时，使用UIA模式的操作（通过Invoke点击、读/写值、通过PrintWindow截图）可以工作，但原始鼠标/键盘模拟则不能。服务器会自动检测到这一点，并在可能的情况下使用基于模式的回退。

工具概述

WinApp MCP公开 55工具 分为10类：

应用程序生命周期（5个工具）

窗口和元素发现（7个工具）

读取和检查（5个工具）

点击与互动（8个工具）

输入（4个工具）

等待与同步（4个工具）

屏幕截图和可视化（5个工具）

HWND多窗口（3个工具）

高级模式（6个工具）

事件监控（3个工具）

会话和窗口管理（2个工具）

📖 包含参数、示例和提示的完整工具文档： 看 文件.md

快速开始

示例1：启动并检查应用程序

User: "Open Notepad and show me the UI tree"

AI calls:
  1. launch_app(exePath: "C:\\Windows\\notepad.exe")        → "app_1234"
  2. get_snapshot(appId: "app_1234", maxDepth: 3)           → UI tree

示例2：填写表格并保存

User: "Create a new invoice in the app"

AI calls:
  1. attach_to_app(processName: "MyApp")                   → "app_5678"
  2. click_element(appId: "app_5678", name: "Invoices")     → navigates
  3. wait_for_element(appId: "app_5678", name: "New")       → page loaded
  4. click_element(appId: "app_5678", name: "New")          → opens form
  5. fill_form(appId: "app_5678", fieldsJson: {             → fills all fields
       "CustomerComboBox": "Acme Corp",
       "ItemName": "Widget",
       "Quantity": "10"
     })
  6. click_element(appId: "app_5678", name: "Save")         → saves
  7. take_screenshot(appId: "app_5678", outputPath: "...")   → evidence

示例3：测试状态转换

User: "Test the invoice lifecycle"

AI calls:
  1. click_element(appId: "app_5678", name: "Mark as Sent")
  2. wait_for_condition(appId: "app_5678", property: "name",
       expectedValue: "Sent", automationId: "StatusBadge")
  3. element_exists(appId: "app_5678", name: "Record Payment")  → "true"
  4. click_element(appId: "app_5678", name: "Record Payment")
  5. take_screenshot_optimized(appId: "app_5678", outputPath: "...", maxTokens: 1000)

演出

WinApp MCP针对快速连续多次检查同一UI的AI代理工作流程进行了优化：

这 后代缓存 是最大的胜利-- FindAllDescendants() 是最昂贵的UIA操作，AI代理通常在每个UI状态下调用它3-5次。2秒TTL确保数据新鲜，同时避免冗余遍历。

缓存是 自动失效 在任何突变（点击、键入、设置值）之后，你总是能得到准确的结果。

建筑

src/
├── Program.cs              # Entry point — .NET Generic Host + MCP server registration
├── WinAppTools.cs           # 55 MCP tool definitions (thin wrappers)
├── WinAppAutomation.cs      # Core automation engine (~2800 lines)
└── WinAppMCP.csproj         # .NET 10, FlaUI.UIA3 5.0.0, MCP 1.1.0

设计原则：

• 薄刀具层 — WinAppTools.cs 仅包含 [McpServerTool] 包装纸。零商业逻辑。
• 单台自动化引擎 — WinAppAutomation.cs 处理所有UIA交互、缓存和状态管理。
• 静态单例 --一个 WinAppAutomation 实例在所有工具调用中共享。
• 标准运输 --通过stdin/stdout清理JSON-RPC。日志记录仅转到stderr。
• FlaUI之外没有外部依赖 --没有Selenium，没有WebDriver，没有COM互操作包装器。

技术栈

与备选方案的比较

文档

• 文件.md --包含参数、返回值、示例和提示的所有55个工具的完整参考
• 更改日志.md --版本历史和发行说明

需求

• 操作系统： Windows 10（版本1903/内部版本18362）或更高版本，或Windows 11
• 运行时间： .NET 10.0 SDK（用于从源代码构建）-如果使用VSIX或预构建的二进制文件，则不需要
• 编辑： VS代码1.99+，带GitHub复制副本（用于VSIX扩展）
• 目标应用程序： 必须公开UI自动化树（WinUI3、WPF、WinForms、UWP、大多数Win32应用程序）

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-tool)
3. 提交您的更改(git commit -m 'Add amazing-tool')
4. 推到分支(git push origin feature/amazing-tool)
5. 打开拉取请求

开发设置

git clone https://github.com/floatingbrij/desktop-pilot-mcp.git
cd desktop-pilot-mcp/src
dotnet restore
dotnet build
dotnet run  # Starts the MCP server on stdio

许可证

该项目根据 MIT许可证 --看看 许可证 文件以获取详细信息。

Built entirely with GitHub Copilot by Brijesharun G — for AI-powered Windows app testing.
If this helps your workflow, give it a ⭐