WinUI MCP

WinUI3 MCP服务器

A. 模型上下文协议（MCP）服务器 用C#（.NET 8）编写，提供AI编码代理 （如OpenCode） 启动、捕获、检查WinUI 3 Windows并与之交互 应用 --就像Playwright为网络浏览器所做的那样。

______________________________________________________________________

这是什么

当你在开发WinUI 3应用程序时遇到UI问题（布局损坏、颜色错误、， 元素未显示、尺寸错误等），通常您必须：

1. 手动运行应用程序
2. 你自己看看屏幕
3. 猜猜XAML更改修复了什么
4. 重建并重复

使用此MCP服务器，您的AI代理（OpenCode）可以为您完成所有这些工作：

1. 自动启动您的应用程序
2. 截图并 看见 UI
3. 检查完整的UI元素树
4. 找到损坏的元素
5. 阅读XAML源代码
6. 直接应用修复程序

这是 与剧作家MCP的概念相同 --但适用于本机Windows桌面应用程序。

______________________________________________________________________

工作原理（建筑）

AI Agent (OpenCode / Claude / any MCP client)
       |
       | MCP Protocol (stdio / JSON-RPC)
       |
WinUI3McpServer.exe  (this project)
       |
       | FlaUI — Windows UI Automation 3 (UIA3)
       | No external service required
       |
Your WinUI 3 App

关键技术：

______________________________________________________________________

先决条件

1.在Windows中启用开发人员模式

Settings > Privacy & Security > For Developers > Developer Mode  ->  ON

2.安装。NET 8 SDK

https://dotnet.microsoft.com/download/dotnet/8.0

通过以下方式进行验证：

dotnet --version

3.安装OpenCode

npm install -g opencode-ai

______________________________________________________________________

项目结构

Z:\openCode contribution\
└── WinUI3-MCP\
    └── WinUI3McpServer\
        ├── Program.cs              # MCP server entry point / host setup
        ├── WinUI3Tools.cs          # All 8 MCP tool implementations
        ├── WinUI3McpServer.csproj  # Project file with NuGet dependencies
        └── WinUI3McpServer.sln     # Solution file

______________________________________________________________________

MCP工具参考

服务器暴露 24工具 致AI代理：

LaunchApp

启动WinUI 3应用程序。

示例提示：

use winui3 to launch my app at C:\Projects\MyApp\bin\Debug\net8.0-windows\MyApp.exe

launch MyApp_1.0.0.0_x64__abc123!App using the winui3 tool

______________________________________________________________________

CaptureScreenshot

截取正在运行的应用程序窗口的屏幕截图。返回AI可以分析的Base64 PNG。

示例提示：

use winui3 to take a screenshot and describe what UI issues you see

capture a screenshot and save it to C:\screenshots\before.png using winui3

______________________________________________________________________

GetSnapshot

返回完整的UI元素树——每个控件、其类型、名称、可见性和启用状态。元素被分配了短引用（例如。 w1e5)用于其他工具。

示例提示：

use winui3 to get the UI tree and find why the Save button is not visible

______________________________________________________________________

ClickElement

单击UI元素。可用于导航到不同页面以测试不同的UI状态。

示例提示：

use winui3 to click the Settings button then take a screenshot

______________________________________________________________________

TypeText

在TextBox或输入字段中键入文本。

示例提示：

use winui3 to type 'hello world' into the element with id 'txtInput'

______________________________________________________________________

GetWindowInfo

返回窗口标题、大小和位置。

示例提示：

use winui3 to get the current window info

______________________________________________________________________

CloseApp

关闭应用程序并结束自动化会话。

示例提示：

use winui3 to close the app

______________________________________________________________________

ResizeWindow

将当前应用程序窗口调整为特定尺寸。对于响应式布局测试至关重要。

______________________________________________________________________

SendKeys

将键盘快捷键发送到当前应用程序窗口。

______________________________________________________________________

WaitForElement

轮询可访问性树，直到出现具有给定名称/AutomationId的元素。

______________________________________________________________________

HighlightElement

在指定的元素参考周围绘制一个红色矩形，以捕获屏幕截图。

______________________________________________________________________

设置和构建

步骤1--克隆或打开项目

cd "Z:\openCode contribution\WinUI3-MCP\WinUI3McpServer"

步骤2--还原和构建

dotnet build --configuration Release

预期产量：

Build succeeded.
    0 Warning(s)
    0 Error(s)

步骤3--使用OpenCode注册

这 opencode.jsonc 配置文件位于 C:\Users\\opencode.jsonc 应包含：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "winui3": {
      "type": "local",
      "command": [
        "dotnet",
        "run",
        "--project",
        "Z:\\openCode contribution\\WinUI3-MCP\\WinUI3McpServer\\WinUI3McpServer.csproj",
        "--configuration",
        "Release"
      ],
      "enabled": true
    }
  }
}

此文件已在为您创建 C:\Users\Kathi\opencode.jsonc.

______________________________________________________________________

运行完整工作流

步骤1--启动OpenCode

在您的项目目录中：

opencode

第二步——让OpenCode修复你的UI

Use the winui3 tool to:
1. Launch my app at C:\Projects\MyApp\bin\Debug\net8.0-windows\MyApp.exe
2. Take a screenshot
3. Get the UI element tree
4. Look at my XAML files and fix whatever layout issues you see

OpenCode将使用MCP工具查看您的应用程序、诊断问题并编辑XAML。

______________________________________________________________________

端到端场景示例

问题： 你的WinUI 3应用程序有一个按钮，在较小的窗口尺寸上是屏幕外的。

你对OpenCode说什么：

My Save button disappears when the window is small.
Use winui3 to launch the app, resize the window to 800x600,
take a screenshot, find the Save button element, and fix the XAML layout.

OpenCode的功能：

1. 呼叫 LaunchApp → 打开您的应用程序
2. 呼叫 CaptureScreenshot → 查看当前状态
3. 呼叫 GetSnapshot → 查找包括缺失按钮在内的所有元素
4. 呼叫 HighlightElement 带有按钮的参考号→ 目视检查其边界
5. 读取XAML文件→ 识别布局问题
6. 编辑XAML→ 修复 Grid 行/列定义或添加 ScrollViewer

______________________________________________________________________

查找应用程序的AUMID（打包应用程序）

如果您的WinUI 3应用程序已打包（MSIX），请使用PowerShell查找AUMID：

Get-StartApps | Where-Object { $_.Name -like "*YourAppName*" }

这 AppID 列是AUMID。将其用作 appPath 参数在 LaunchApp.

______________________________________________________________________

使用的NuGet包

______________________________________________________________________

故障排除

“启动应用程序时出错：引发了响应为null的异常…”

FlaUI无法找到或连接到应用程序窗口。验证 appPath 是正确的，并且该应用程序尚未在冲突的实例中运行。

“启动应用程序时出错：未启用开发人员模式”

首选 Settings > Privacy & Security > For Developers 并打开开发者模式。

“找不到元素”

使用 GetSnapshot 首先查看所有可用元素并找到正确的元素 AutomationId 或 Name.

应用程序启动，但屏幕截图为空白/黑色

一些WinUI 3应用程序使用硬件加速渲染，可以生成黑色屏幕截图。 尝试添加 x:Name XAML元素的属性和使用 GetSnapshot 相反。

OpenCode不显示winui3工具

确保 opencode.jsonc 位于您的主目录中(C:\Users\\)以及 路径到 .csproj 文件正确，有双反斜杠。

______________________________________________________________________

未来改进/讨论点

这个项目是作为基础而建的。以下是可供发表意见和辩论的领域：

可能的增强功能

• 可视化差异工具 --比较两个屏幕截图（修复前后）并突出显示更改
• XAML热重载集成 --在不重新启动应用程序的情况下应用XAML编辑
• 可访问性审计工具 --检查是否丢失 AutomationProperties.Name 关于控制
• 多窗口支持 --处理具有多个窗口或对话框的应用程序
• 视频记录 --将会话记录为 .mp4 用于错误报告
• 元素高亮显示 --在屏幕截图中找到的元素周围画一个红色边框
• 主题测试 --在亮/暗/高对比度主题之间切换并捕捉每个主题
• 响应式测试 --将窗口调整为多种大小，并分别进行截图

公开辩论问题

1. 这应该是一个独立的NuGet包吗 这样其他开发人员就可以将其添加到他们的

自己的MCP设置而不克隆此仓库？

1. 截图分析是否应该专门使用视觉模型 （克劳德，GPT-4o）

还是让总代理决定？一个专门的愿景步骤可能会带来更好的结果。

1. 与Visual Studio的XAML热重载集成 --是否有可能触发

编辑XAML后从MCP服务器热重新加载，以便代理可以验证其修复 视觉上没有完全重建？

1. AUMID发现工具 --是否应该有 ListInstalledApps 返回的工具

所有已安装的WinUI 3应用程序及其AUMID都是自动安装的吗？

______________________________________________________________________

许可证

麻省理工学院——免费使用、修改和贡献。

______________________________________________________________________

相关资源

• 模型上下文协议文档
• OpenCode文档
• WinUI 3文档
• Windows UI自动化概述
• Figma REST API

______________________________________________________________________

Figma→ WinUI 3工作流程

您可以将代理指向Figma设计，并让它直接在XAML中实现UI。

一次性设置-Figma API令牌

在以下位置生成个人访问令牌 figma.com→ 设置→ 个人访问令牌，然后将其设置为环境变量，这样您就不必每次调用都传递它：

# In your shell / VS Code terminal (or add to system env vars)
$env:FIGMA_TOKEN = "figd_xxxxxxxxxxxxxxxxxxxx"

步骤1——发现文件中的帧

Use ListFigmaFrames("https://www.figma.com/design/ABC123/MyApp") to show me
all pages and frame node IDs in this file.

该工具返回每个页面和框架，并准备好使用 ReadFigmaDesign(...) 电话。

第二步——阅读设计

Use ReadFigmaDesign("https://www.figma.com/design/ABC123/MyApp?node-id=12-34")
to extract the design tokens and show me the rendered frame.

工具返回：

• 内联PNG 框架——视觉模型直接看到设计
• 设计代币 映射到WinUI3 XAML属性名：

- Background="#1E1E2E", Foreground="#CDD6F4" - FontFamily="Inter" FontSize="14" FontWeight="SemiBold" - CornerRadius="8", Padding="16,12,16,12", Spacing="8" - Layout: StackPanel Orientation="Vertical" - BorderBrush="#313244" BorderThickness="1"

步骤3——实施和验证

Now implement this design in Z:\source\MyApp\MainWindow.xaml, then call
BuildDeployLaunch("Z:\source\MyApp\MyApp.csproj") and compare the result
with CompareScreenshot to check how close it is.

完整的循环是：

ListFigmaFrames → ReadFigmaDesign → edit XAML → BuildDeployLaunch → CompareScreenshot

示例提示（一体式）

I have a Figma design at https://www.figma.com/design/ABC123/MyApp?node-id=12-34
and a WinUI 3 project at Z:\source\MyApp\MyApp.csproj.

Please:
1. Read the Figma design and show me what it looks like
2. Open Z:\source\MyApp\MainWindow.xaml
3. Apply the colors, typography, layout, and spacing from the Figma design
4. Build, deploy, and launch the app with BuildDeployLaunch
5. Take a screenshot and compare it with CompareScreenshot
6. Iterate until the result matches the design