使用说明

WinUI3 MCP服务器

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

这是什么

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

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

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

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

这是 与剧作家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

关键技术：

组件	角色
模型上下文协议	允许AI代理通过stdio JSON-RPC调用工具
FlaUI	.NET UI自动化库——直接与Windows UIA3对话，无需WinAppDriver
微软UI自动化（UIA3）	用于读取UI元素树并与之交互的Windows辅助功能API
Figma REST API	提取设计标记并将帧渲染为PNG，用于设计到代码的工作流

先决条件

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应用程序。

参数	类型	说明
`appPath`	string	完整路径 `.exe` 或打包应用程序的AUMID
`workingDirectory`	string	可选工作目录

示例提示：

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。

参数	类型	说明
`saveToPath`	string	保存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)用于其他工具。

参数	类型	说明
`maxDepth`	int	树深度（1-10，默认值8）。较低的值在大型应用程序上更快。
`includeBounds`	bool	包含 `(x,y w×h)` 每个元素的bounding rect（默认为false）

示例提示：

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

`ClickElement`

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

参数	类型	说明
`elementRef`	string	元素引用自 `GetSnapshot`例如。 `w1e5`

示例提示：

use winui3 to click the Settings button then take a screenshot

`TypeText`

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

参数	类型	说明
`elementRef`	string	元素引用自 `GetSnapshot`例如。 `w1e5`
`text`	string	要键入的文本

示例提示：

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`

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

参数	类型	说明
`width`	int	目标宽度（像素）
`height`	int	目标高度（像素）

`SendKeys`

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

参数	类型	说明
`keys`	string	组合键，例如。 `Ctrl+S`, `Alt+F4`, `F5`, `Escape`, `Ctrl+Shift+P`

`WaitForElement`

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

参数	类型	说明
`nameOrId`	string	要等待的名称或Automation Id（部分，不区分大小写）
`timeoutMs`	int	最大等待时间（毫秒）（默认值5000）
`pollIntervalMs`	int	轮询间隔（毫秒）（默认值300）

`HighlightElement`

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

参数	类型	说明
`elementRef`	string	GetSnapshot中的元素引用，例如。 `w1e5`
`saveToPath`	string	保存带注释的PNG的可选文件路径

设置和构建

步骤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\<YourUsername>\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的功能：

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

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

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

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

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

使用的NuGet包

包装	版本	用途
`ModelContextProtocol`	0.8.0-preview.1	MCP服务器SDK（stdio传输）
`Microsoft.Extensions.Hosting`	10.0.3	.NET通用主机/DI
`FlaUI.Core`	5.0.0	UI自动化抽象层
`FlaUI.UIA3`	5.0.0	UIA3提供程序（Windows 10+）
`System.Drawing.Common`	8.0.10	截图和图像比较

故障排除

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

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

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

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

“找不到元素”

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

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

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

OpenCode不显示winui3工具

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

未来改进/讨论点

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

可能的增强功能

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

公开辩论问题

这应该是一个独立的NuGet包吗 这样其他开发人员就可以将其添加到他们的自己的MCP设置而不克隆此仓库？
截图分析是否应该专门使用视觉模型 （克劳德，GPT-4o）还是让总代理决定？一个专门的愿景步骤可能会带来更好的结果。
与Visual Studio的XAML热重载集成 --是否有可能触发编辑XAML后从MCP服务器热重新加载，以便代理可以验证其修复视觉上没有完全重建？
AUMID发现工具 --是否应该有 ListInstalledApps 返回的工具所有已安装的WinUI 3应用程序及其AUMID都是自动安装的吗？

许可证

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

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

使用说明

WinUI3 MCP服务器

这是什么

工作原理（建筑）

先决条件

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

2.安装。NET 8 SDK

3.安装OpenCode

项目结构

MCP工具参考

LaunchApp

CaptureScreenshot

GetSnapshot

ClickElement

TypeText

GetWindowInfo

CloseApp

ResizeWindow

SendKeys

WaitForElement

HighlightElement

设置和构建

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

步骤2--还原和构建

步骤3--使用OpenCode注册

运行完整工作流

步骤1--启动OpenCode

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

端到端场景示例

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

使用的NuGet包

故障排除

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

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

“找不到元素”

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

OpenCode不显示winui3工具

未来改进/讨论点

可能的增强功能

公开辩论问题

许可证

相关资源

Figma→ WinUI 3工作流程

一次性设置-Figma API令牌

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

第二步——阅读设计

步骤3——实施和验证

示例提示（一体式）

相关 MCP

iOS/macOS 构建 MCP 服务器与命令行工具

iOS模拟器交互服务器

网页截图工具

网页无障碍扫描器

ADB设备管理服务器

网页调试代理服务

`LaunchApp`

`CaptureScreenshot`

`GetSnapshot`

`ClickElement`

`TypeText`

`GetWindowInfo`

`CloseApp`

`ResizeWindow`

`SendKeys`

`WaitForElement`

`HighlightElement`