wpf-visual-tree

WpfVisualTreeMcp

让 AI Agent 查看、调试并操控正在运行的 WPF 应用。 面向 AI 的 Snoop + Playwright，通过模型上下文协议提供服务 — 可查看可视化树、绑定和屏幕截图，并执行鼠标拖动、触摸手势、文本输入和键盘操作。无需修改源代码即可检查正在运行的应用；触摸行为取决于应用的输入支持。

拖放、移动画布项、轻触、按住、平移、捏合缩放和旋转 — 然后查询控件、填写表单、选择项并诊断绑定错误。手势序列通过 MCP 记录真实的 WPF 输入，按 AutomationId 定位控件并检查应用的响应，就像自动化测试一样。

直接观看动画演示。

v0.20.0 新增： 已验证支持 .NET 9、.NET 10 和 .NET Framework 4.8.1 上的 WPF，同时支持 x86 和 x64。CI 会在全部六个受支持的目标框架上测试自动注入和自托管，并使用 .NET 8、9 和 10 测试项目验证已安装的 C# SDK。即使未安装 .NET 8，x86 注入助手也可使用 .NET 9 或 10。

WpfVisualTreeMcp.Automation C# SDK 可操作虚拟化的 DataGrid/TreeView、等待控件、管理 WPF 窗口并流式传输属性变更。包含 38 个工具的 MCP 服务和 CLI 共用检查与输入引擎，包括直接按 AutomationId 定位。

工作流录制/回放/xUnit 导出、聚合诊断、完整内容屏幕截图以及对 .NET Framework 4.7.2 的支持仍可从 v0.16.0 使用。感谢 @miloszkukla 在 PR #22 中完成兼容性和屏幕截图相关工作。

快速入门（60 秒）

1. 从最新发布版本下载并解压 WpfVisualTreeMcp-vX.Y.Z-win-x64.zip（需要 .NET 8、9 或 10 Desktop Runtime）。
2. 在 MCP 客户端中注册 — 对于 Claude Code，将其添加到 .mcp.json：

   {
     "mcpServers": {
       "wpf-visual-tree": {
         "command": "C:/path/to/WpfVisualTreeMcp.Server.exe",
         "args": []
       }
     }
   }
   

3. 向 Agent 提问：“查看我正在运行的 WPF 应用，并告诉我为什么‘保存’按钮处于禁用状态。”

更喜欢使用终端？同一个 exe 也是功能完整的 CLI：WpfVisualTreeMcp.Server.exe help。 从 v0.14.0 起，运行 wpfinspect update（或 WpfVisualTreeMcp.Server.exe update） 即可更新当前启动的安装。请参阅更新。 使用 Codex？请按照插件安装同时安装 MCP 配置和技能。

C# 测试 SDK

WpfVisualTreeMcp.Automation 将检查和输入引擎作为 C# 对象公开，支持直接附加到进程以及使用 AutomationId 定位器。该程序包包含注入负载，无需启动 MCP 服务或 CLI 即可使用。

组件	支持的框架
被自动化的 WPF 应用程序	.NET Framework 4.7.2、4.8、4.8.1；.NET 8、9、10
使用 Automation NuGet 的 C# 项目	.NET 8、9、10
架构	Windows x86 和 x64；使用 x64 测试进程即可控制这两种架构

应用程序和测试项目可以使用不同的框架：例如，.NET 10 测试可以自动化 .NET Framework 4.8.1 应用程序。该 SDK 的 net8.0 库可用于 .NET 9/10 测试项目；它不是 .NET Framework 测试库。 发布前会测试兼容性矩阵，包括实际运行时版本检查。Framework 4.x 目标版本的构建会在已安装的 4.8.1 运行时上运行，因为这些运行时会原位更新。

dotnet add package WpfVisualTreeMcp.Automation --version 0.20.0

using WpfVisualTreeMcp.Automation;

await using var app = await WpfApplication.AttachAsync(processId);
await app.ByAutomationId("LoadButton").ClickAsync();
await app.ByAutomationId("StatusTextBox").WaitForTextAsync(
    "loaded", timeout: TimeSpan.FromSeconds(30));
await app.ByAutomationId("Canvas").PanAsync(100, 0);
await app.ByAutomationId("Canvas").ZoomAsync(1.5);

文本等待会比较属性的精确值：not loaded 与 loaded 不匹配。超时会抛出异常，其中包含预期值和最后观测到的值。此外，还支持属性谓词、取消、拖动、触摸、断言、检查以及录制/回放。释放附加会话时，应用仍会运行；默认情况下，已启动的会话拥有其进程，并会负责清理。

await app.ByAutomationId("Orders").AsDataGrid()
    .RowByKey("Id", "42").Cell("Quantity").SetTextAsync("7");
await app.ByAutomationId("Folders").AsTreeView().Node("Projects", "WPF").SelectAsync();
await app.ByAutomationId("Enabled").CheckAsync();
await using var changes = await app.ByAutomationId("StatusTextBox").ObservePropertyAsync("Text");

该 SDK 是与 MCP 工具 WpfVisualTreeMcp 分开的程序包。 请参阅安装说明、API 示例和要求。

概述

WpfVisualTreeMcp 是一个 Model Context Protocol (MCP) 服务，允许 AI 编码 Agent（Codex、Claude Code、Cursor、GitHub Copilot）检查并与正在运行的 WPF 应用程序交互。可以把它想象成让你的 AI 助手具备与 Snoop WPF 或 Visual Studio 的实时可视化树等工具相同的能力。

这为何重要

传统上，调试 WPF UI 问题需要使用专门工具进行手动检查。该项目通过 MCP 提供 WPF 检查功能，弥合了这一差距，使 AI Agent 能够：

• 在代码审查期间了解 UI 结构
• 自动诊断绑定错误
• 为布局问题提出修复建议
• 协助完成 UI 重构任务
• 实时分析可视化树层级结构

功能

核心检查

• 进程发现 - 列出所有可供检查的正在运行的 WPF 应用程序
• 可视化树导航 - 遍历完整的可视化树层级结构
• 逻辑树访问 - 浏览逻辑树结构
• 属性检查 - 读取任意 UI 元素的所有依赖属性

绑定与资源

• 绑定分析 - 检查绑定，支持转换器、StringFormat、FallbackValue 和 MultiBinding
• DataContext 检查 - 查看 DataContext 类型、属性、INPC 状态和继承链
• 绑定错误检测 - 自动捕获并报告绑定错误，并进行分类
• 资源枚举 - 浏览任意范围内的资源字典
• 样式检查 - 查看已应用的样式和模板

搜索与监控

• 元素搜索 - 按类型、名称或属性值查找元素
• 深度搜索 - 搜索整棵树，包括 AdornerLayer 和 Popup 元素
• 属性监视 - 实时监控属性变化

交互与导出

• 触摸手势 (v0.13.0) - wpf_touch_gesture / CLI touch：使用一个或两个触点执行原生轻触、长按、滑动、捏合和旋转。包含交互式演示和 WPF 兼容性指南。
• 鼠标拖动 - wpf_drag / CLI drag：在可视化树元素之间拖动，或按本地位移拖动；支持左键、右键和中键，可配置持续时间以及本地起点和终点。支持滑块滑块、分隔条和拖放操作。请参阅参数和示例。
• 屏幕截图 - 当前源代码使用 auto 捕获原生托管内容，并报告所选模式；显式渲染不支持的原生区域时会报错。捕获 AI Agent 可见的窗口/元素截图；full_content=true / CLI --full-content 可捕获可滚动内容（包括虚拟化列表），并恢复原始滚动位置
• 元素高亮 - 在运行中的应用中直观地高亮显示元素
• 控件点击 (v0.4.0) - 通过 UI Automation（Invoke/Toggle/Select/ExpandCollapse）或真实的 OS 鼠标点击来点击元素
• 设置文本 (v0.5.0 新增) - 通过 UI Automation IValueProvider.SetValue 填充 TextBox/ComboBox/PasswordBox，并支持 TextBox.Text / PasswordBox.Password / 反射的 Text 回退方式；也可设置 physical=true，通过 OS 键盘输入文本（完整 Unicode BMP）
• 发送按键 (v0.5.0 新增) - 通过 OS 键盘输入向元素或获得焦点的窗口发送键盘快捷键（Ctrl+S、Alt+F4、F5、Enter、Ctrl+Shift+F 等）
• 布局信息 - 获取详细的布局指标
• 树导出 - 将可视化树导出为 XAML 或 JSON 格式
• 自动注入 - 将 Inspector 注入运行中的 WPF 进程（无需更改源代码）；从 v0.6.0 起支持多种架构——64 位服务可通过随附的 WpfInjectorHelper.exe 注入 32 位 WPF 应用

双模式 CLI (v0.4.0 新增)

同一个 WpfVisualTreeMcp.Server.exe 可以作为 MCP stdio 服务运行（默认不带参数）， 也可以作为单次调用 CLI运行（使用任意已识别的子命令）。 适用于 MCP 服务未连接时、编写脚本以及手动验证流程。运行 WpfVisualTreeMcp.Server.exe help 可查看完整命令列表。输出为 stdout 上的 JSON；诊断信息发送到 stderr。

对比

与通用工具类别对比：

	WpfVisualTreeMcp	Snoop	FlaUI / WinAppDriver	通用计算机操作（截图 + 鼠标）
使用者	AI Agent（MCP）+ 人类（CLI）	人类（GUI）	测试代码（C#）	AI Agent
可视化树、依赖属性	✅	✅	❌（仅 UIA 视图）	❌
数据绑定、绑定错误、DataContext	✅	✅	❌	❌
按可见文本 / 属性查找控件	✅	手动	部分支持（UIA）	像素猜测
点击 / 输入 / 选择 / 快捷键	✅	❌	✅	✅（盲操作）
等待 UI 条件（无需循环休眠）	✅	❌	✅	❌
元素截图 + 支持弹出窗口的屏幕捕获	✅	❌	部分支持	仅全屏
无需修改目标源代码即可使用	✅（自动注入）	✅	✅	✅

与其他 WPF MCP 服务对比。 大多数 WPF MCP 服务基于 UI Automation（FlaUI）构建：它们读取无障碍树，只有在将它们的进程内探针安装到要检查的应用中后，才能访问 WPF 内部信息——绑定、DataContext、ViewModel 状态。此服务采用 Snoop 的方式：它会在运行时注入，因此无需对目标应用做任何改动，就能读取真实的可视化树，并诊断绑定错误和 DataContext——无需添加任何内容到构建中，也无需将任何内容部署到生产环境。

	WpfVisualTreeMcp	基于 UIA 的服务（FlaUI）	其他基于注入的服务
可查看真实的可视化树（而不只是 UIA 视图）	✅ 注入	❌ 无障碍树	✅
无需在目标应用中安装探针即可查看绑定错误 + DataContext	✅	❌（需要进程内探针）	部分支持
交互方式	点击（UIA + 物理点击，双击 / 右键）、拖动、触控手势、设置文本并回读、发送按键、选择项目（支持虚拟化）	点击 / 输入 / 选择	通常仅支持调用
等待元素条件	✅ wpf_wait_for	✅	❌
弹出窗口 / 下拉列表 / 上下文菜单截图	✅ 屏幕模式	部分支持	仅截图
跨架构注入（x64 ⇄ x86）	✅	不适用	❌
双模式：MCP 服务和一次性 CLI	✅	❌	❌
分发方式	NuGet（dnx/tool）、官方 MCP 注册表、Codex 插件 + skill	不一	不一

简而言之：基于 UIA 的工具只能看到无障碍功能所暴露的内容，而计算机操作 Agent 只能看到像素。本项目让 Agent 无需在目标应用中安装探针，就能像 WPF 开发者使用 Snoop 一样深入查看应用，并提供丰富的操作能力，且采用所有 AI 编码工具都支持的协议。

安装

先决条件

• Windows 10/11
• .NET 8.0 SDK 或更高版本
• 要检查的 WPF 应用

构建并运行完整兼容性套件需要 .NET 10 SDK、x64 和 x86 版本的 .NET 8/9/10 Desktop 运行时，以及 .NET Framework 4.8.1。

安装

选项 1：.NET 工具 / NuGet（推荐）

dotnet tool install -g WpfVisualTreeMcp     # installs the `wpfinspect` command

此程序包也以 MCP 服务程序包（PackageType: McpServer）的形式发布，因此支持由 NuGet 托管服务的 MCP 客户端可以直接启动它：

dnx WpfVisualTreeMcp                        # runs the MCP stdio server

选项 2：下载 Release

从 GitHub Releases 下载最新版本：

1. 下载 WpfVisualTreeMcp-vX.X.X-win-x64.zip
2. 解压到某个文件夹（例如 C:\Tools\WpfVisualTreeMcp）
3. MCP 服务可执行文件为 server/WpfVisualTreeMcp.Server.exe

桌面扩展（MCPB）

支持 MCP bundle 的客户端可以导入 WpfVisualTreeMcp-v0.20.0-win-x64.mcpb。 此 Windows x64 bundle 包含服务运行时和独立的 x86 注入辅助程序。较小的 compact bundle 提供相同的工具，但运行时更精简，适用于有上传限制的目录。通过客户端的扩展界面更新任一 bundle。有关要求、打包和验证，请参阅 MCPB 指南。

选项 3：从源代码构建

git clone https://github.com/faze79/WpfVisualTreeMcp.git
cd WpfVisualTreeMcp
# Visual Studio Developer PowerShell (C++ v143 toolset + Windows SDK)
./scripts/Build-NativeBootstrapper.ps1
dotnet build -c Release

有关注入构建要求、包布局和故障排除，请参阅 Injector README。向 x86 应用注入需要辅助程序使用 x86 .NET 8 运行时。

更新

wpfinspect update --check   # current/latest stable version; no installation changes
wpfinspect update           # download and schedule installation automatically
wpfinspect update --status  # confirm completion or inspect a failure

# For an extracted release or a published folder, invoke that exact executable:
C:\Tools\WpfVisualTreeMcp\server\WpfVisualTreeMcp.Server.exe update

update 从 v0.14.0 起可用。对于较旧的全局工具，请先引导安装一次：

dotnet tool update -g WpfVisualTreeMcp

对于较旧的便携副本，请解压最新版本，并使用其 server 文件夹。

此命令仅更新启动它的安装。全局工具和自定义 --tool-path 工具会下载精确匹配的官方 NuGet 包，然后从暂存包运行 dotnet tool update（需要 .NET SDK）。临时 NuGet 下载失败和发布延迟最多会重试四次，重试间隔为 10、20 和 30 秒。如果准备失败，已安装的文件不会更改；请稍后重试。便携文件夹会获取最新稳定版 GitHub 发布中的完整服务载荷，并通过 SHA-256 摘要进行验证。bin 下的源代码构建由源代码/构建工作流处理；本地清单工具和 dnx 缓存则由其包管理器处理。--check 会说明检测到的安装类型。

在 Windows 上，安装会在 CLI 退出后于隐藏工作进程中启动，以便解锁其可执行文件。scheduled 结果表示工作进程已启动，并不表示安装已完成。运行 update --status，直到其报告 updated 或 failed；失败状态会返回退出代码 1。JSON 输出包含日志路径。状态、日志和便携版备份存储在 %LOCALAPPDATA%\WpfVisualTreeMcp\updates 下，并按安装分别保存。

更新前，请关闭使用相同文件的其他 MCP 实例。更新程序不会停止应用程序：被占用的文件会导致错误，便携版替换失败时会从备份恢复。无关文件和 MCP 配置会保留。成功后，请重启 MCP 客户端和之前检查过的 WPF 应用，以便服务和注入的 Inspector 都使用新版本。其他已安装副本以及任何单独复制的可自托管 Inspector 都需要各自更新。

配置

此服务使用官方 Microsoft/Anthropic MCP SDK for .NET，确保与 Claude Code 和其他 MCP 客户端兼容。

Claude Code

选项 1：命令行（推荐）

使用 claude mcp add 命令直接添加服务：

# Add to current project only
claude mcp add wpf-visual-tree -- C:/path/to/WpfVisualTreeMcp/publish/WpfVisualTreeMcp.Server.exe

# Add globally (available in all projects)
claude mcp add --scope user wpf-visual-tree -- C:/path/to/WpfVisualTreeMcp/publish/WpfVisualTreeMcp.Server.exe

你可以验证是否已添加服务：

claude mcp list

选项 2：项目级 JSON 配置

在项目根目录中创建或编辑 .mcp.json：

{
  "mcpServers": {
    "wpf-visual-tree": {
      "command": "C:/path/to/WpfVisualTreeMcp/publish/WpfVisualTreeMcp.Server.exe",
      "args": []
    }
  }
}

选项 3：全局 JSON 配置

添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "wpf-visual-tree": {
      "command": "C:/path/to/WpfVisualTreeMcp/publish/WpfVisualTreeMcp.Server.exe",
      "args": []
    }
  }
}

重要说明：

• 使用已构建 .exe 文件的绝对路径
• 在 Windows 上的路径中使用正斜杠（/）
• 用于生产环境时，请以 Release 模式构建：dotnet build -c Release
• 更改配置后重启 Claude Code

Cursor

添加到 Cursor 设置（.cursor/mcp.json）：

{
  "mcpServers": {
    "wpf-visual-tree": {
      "command": "C:/path/to/WpfVisualTreeMcp/publish/WpfVisualTreeMcp.Server.exe",
      "args": []
    }
  }
}

Codex 插件

此存储库包含一个 WPFVisualTreeMcp Codex 插件，可同时安装 MCP 配置和 wpfvisualtreemcp 技能。它运行的是最新稳定版 NuGet 包，而不是检出源码的构建版本。无需指定特定于机器的可执行文件路径。

此安装方式的前提条件：

• Windows 10/11，以及支持插件的本地 Codex 客户端。
• 用于运行 dotnet dnx 的 .NET 10 SDK，版本为 .NET 10 中的 10.0.300 或更高版本，以及 .NET 8 运行时。
• 每次启动 MCP 时都能访问 nuget.org，以解析最新稳定版本。下载的包会由 .NET 缓存。若要进行 x86 注入，还需安装 x86 .NET 8 运行时。

在存储库根目录下，注册本地市场并安装插件。你也可以从 GitHub Releases 下载 WpfVisualTreeMcp-v0.20.0-codex-plugin.zip，解压后在解压得到的根目录中运行以下命令：

codex plugin marketplace add .
codex plugin add wpfvisualtreemcp@WPFVisualTreeMcp

重启 Codex 或开启新会话，然后让它检查正在运行的 WPF 应用。也可以显式调用该技能：$wpfvisualtreemcp。

或者，无需手动克隆上游 Git 存储库即可直接安装：

codex plugin marketplace add https://github.com/faze79/WPFVisualTreeMcp.git
codex plugin add wpfvisualtreemcp@WPFVisualTreeMcp

使用 codex plugin list --marketplace WPFVisualTreeMcp 检查安装情况。这是一个存储库市场，并不表示插件已发布到 OpenAI 的公共插件目录。如果你的客户端没有 codex plugin add 命令，请使用支持插件的客户端，或使用下方的直接 MCP 配置。

若要使用自己的构建版本，或避免依赖 .NET 10 SDK，请直接注册已发布的可执行文件，而不要安装插件：

codex mcp add wpf-visual-tree -- "C:/Tools/WpfVisualTreeMcp/server/WpfVisualTreeMcp.Server.exe"

将示例替换为实际的可执行文件路径。不要同时启用此手动配置项和插件，否则会启动两个服务。

插件文件位于 plugins/wpfvisualtreemcp/；市场条目位于 .agents/plugins/marketplace.json。插件使用 Codex 支持的 .codex-plugin/plugin.json 兼容格式。其清单版本用于标识插件配置和技能，与 NuGet 服务版本相互独立。启动 MCP 时不指定包版本，并使用 --no-http-cache，以便每次启动时都从 nuget.org 解析最新稳定版本。不包含预发布版本。要获取新的服务版本，请重启 MCP 服务或 Codex；正在运行的服务不会原地更新。切勿将 list 等 CLI 子命令添加到 MCP 启动参数中：不指定子命令时会选择 stdio 模式。

插件在自己的目录中启动，并包含一个 global.json，用于选择 SDK 10.0.300 或更高版本的稳定 .NET 10 SDK。这样可避免目标项目中较旧的 SDK 固定版本禁用 dotnet dnx。已使用 SDK 10.0.402 和 Codex CLI 0.162.1 验证非交互式启动以及 x64/x86 Inspector 注入。SDK 固定版本可确保启动时采用经过测试的 .NET 10 命令行行为。

兼容性 MCP 配置使用 "cwd": "."；Codex 会将其解析为相对于已安装的插件根目录。安装后在隔离配置文件中通过 codex mcp list --json 验证了此解析方式。 编辑本地插件文件后，重新运行 codex plugin add wpfvisualtreemcp@WPFVisualTreeMcp 以刷新已安装的副本，然后开启新的 Codex 会话。

对于基于 Git 的市场，使用以下命令更新插件配置和配套技能：

codex plugin marketplace upgrade WPFVisualTreeMcp
codex plugin add wpfvisualtreemcp@WPFVisualTreeMcp

对于本地市场，请先更新其源代码检出，然后再重新安装插件。配套技能介绍鼠标拖动、触控手势和更新行为。wpfinspect update 会更新单独安装的 CLI 或便携副本；它不会刷新插件或其技能，也不应用于修改插件共享的 dnx 包缓存。独立安装的更新说明请参阅更新。

自托管模式（推荐）

要让你的 WPF 应用程序可供检查，请添加对 Inspector DLL 的引用，并在启动时对其进行初始化：

1. 添加对 WpfVisualTreeMcp.Inspector 的项目引用

2. 在 App.xaml.cs 中：

using System.Diagnostics;
using System.Windows;
using WpfVisualTreeMcp.Inspector;

public partial class App : Application
{
    protected override void OnStartup(StartupEventArgs e)
    {
        base.OnStartup(e);

        // Initialize the WPF Visual Tree Inspector
        InspectorService.Initialize(Process.GetCurrentProcess().Id);
    }

    protected override void OnExit(ExitEventArgs e)
    {
        InspectorService.Instance?.Dispose();
        base.OnExit(e);
    }
}

这样，MCP 服务就可以通过命名管道连接到你的应用程序，以进行实时检查。

使用示例

列出正在运行的 WPF 应用程序

Use the wpf_list_processes tool to show all running WPF applications.

连接并检查可视化树

Attach to the MyApp.exe WPF application and show me the visual tree of the main window.

查找绑定错误

Check the attached WPF application for any binding errors and explain what's causing them.

搜索元素

Find all Button elements in the visual tree that have IsEnabled set to false.

导出可视化树

Export the visual tree of the current window to JSON format so I can analyze the structure.

架构

┌─────────────────────────────────────────────────────────────┐
│                    AI Agent (Claude Code)                    │
└─────────────────────────┬───────────────────────────────────┘
                          │ MCP Protocol (stdio)
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                 WpfVisualTreeMcp Server                      │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐  │
│  │   MCP Handler   │  │  Tree Navigator │  │   Injector  │  │
│  │  (Tools/Res.)   │  │   & Inspector   │  │   Manager   │  │
│  └────────┬────────┘  └────────┬────────┘  └──────┬──────┘  │
└───────────┼────────────────────┼───────────────────┼────────┘
            │                    │                   │
            └────────────────────┼───────────────────┘
                                 │ Named Pipes / IPC
                                 ▼
┌─────────────────────────────────────────────────────────────┐
│                   Target WPF Application                     │
│  ┌─────────────────────────────────────────────────────────┐│
│  │              Injected Inspector DLL                      ││
│  │  • VisualTreeHelper access                              ││
│  │  • LogicalTreeHelper access                             ││
│  │  • Property/Binding inspection                          ││
│  │  • Resource dictionary enumeration                      ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

如需详细了解架构，请参阅 docs/ARCHITECTURE.md。

可用工具

工具	描述
wpf_list_processes	列出所有正在运行的 WPF 应用程序
wpf_attach	附加到 WPF 应用程序（支持通过 auto_inject 注入 DLL）
wpf_get_visual_tree	获取可视树层级结构（默认深度：25，最大：100）
wpf_get_element_properties	获取元素的所有依赖属性
wpf_find_elements	按精确的 AutomationId、类型、x:Name、可见文本、属性值和可见性查询元素；结果包含文本、自动化 ID、启用/可见状态和屏幕边界
wpf_find_elements_deep	使用相同的查询筛选条件且不限制结果数量，搜索所有窗口（包括装饰器/弹出窗口）
wpf_capture_screenshot	捕获窗口或元素的屏幕截图（返回图像）；mode='screen' 会包含弹出窗口和菜单；渲染模式下使用 full_content=true 可捕获可滚动内容
wpf_report	汇总当前绑定/验证错误、UI 状态计数和近期绑定跟踪，并明确说明扫描限制和覆盖范围
wpf_record / wpf_get_recording	使用稳定选择器启动、停止、检查或清除工作流录制
wpf_assert	断言依赖属性的值；成功的断言会包含在活动录制中
wpf_replay	在全新的应用中重放工作流，遇到第一个失败步骤时停止
wpf_export_test	将已停止的录制导出为可运行的 xUnit 项目或工作流 JSON
wpf_get_bindings	获取元素的数据绑定（包括 MultiBinding、converter、StringFormat）
wpf_get_binding_errors	列出所有捕获的绑定错误
wpf_clear_binding_errors	清除已捕获的绑定错误列表
wpf_get_data_context	获取 DataContext 类型、属性、INPC 状态和继承链
wpf_get_resources	枚举资源字典
wpf_get_styles	获取已应用的样式和模板
wpf_watch_property	监视属性变化
wpf_evaluate_binding	解释属性为何具有当前值——值来源；对于绑定，则逐步解析路径，精确指出失效绑定出错的位置
wpf_explain_triggers	根据当前状态评估 Style 和 ControlTemplate 触发器（条件、当前值、是否激活、设置器）——回答“为什么这个触发器没有触发？”；并指出属性值是由哪个样式设置器/活动触发器设置的
wpf_snapshot	在指定标签下捕获元素子树的状态（布局、可见性、画刷、文本）
wpf_diff	对比两个快照——精确衡量更改导致的变化（属性从→到、新增/移除）
wpf_set_property	在运行时实时编辑依赖属性（自动转换类型），无需重新构建即可测试更改。会更改状态，可撤销。
wpf_revert_property	撤销 wpf_set_property 编辑（单项、筛选项或全部）——恢复先前的绑定/值/默认值。
wpf_highlight_element	以视觉方式突出显示元素
wpf_click_element	通过句柄或 AutomationId 点击控件——直接传入 automation_id="form.clear"；可选的 root_handle 用于限定查找范围，重复 ID 会导致失败。默认使用 UI Automation invoke，设置 physical=true 可执行真实的 OS 鼠标点击，设置 click_type='double'/'right' 可双击/右键单击。会更改状态。
wpf_move_mouse	在局部坐标处移动鼠标/悬停，不执行点击。v0.17.0 起提供。
wpf_scroll	垂直或水平滚轮输入；由应用决定滚动还是缩放。v0.17.0 起提供。
wpf_drag	用鼠标拖动——源和目标元素或相对位移、局部坐标点、左/右/中键、渐进移动和释放清理。会更改状态。
wpf_touch_gesture	原生触控——在可见元素内轻触、长按、滑动、双指捏合和旋转。需要应用支持触控。会更改状态。
wpf_select_item	按可见文本或索引选择项目（ComboBox/ListBox/ListView/TabControl）——适用于虚拟化项目。会更改状态。
wpf_wait_for	等待元素变为可见/存在/启用/隐藏，在目标应用中轮询——无需使用休眠后重试循环。
wpf_set_text	设置文本/值（TextBox/ComboBox/PasswordBox）——默认使用 UI Automation IValueProvider.SetValue，设置 physical=true 可通过 OS 键盘输入。会更改状态。
wpf_send_keys	向元素或当前聚焦的窗口发送键盘快捷键（Ctrl+S、Alt+F4、F5、Enter，……）。会更改状态。
wpf_get_layout_info	获取布局信息
wpf_export_tree	将可视树导出为 XAML 或 JSON
完整的工具文档请参阅 docs/TOOLS_REFERENCE.md。

所有输入操作都接受 automation_id，而非 element_handle，包括单击、鼠标移动、滚动、拖动、所有触摸手势、选择、文本输入和键盘输入。断言和属性编辑也接受该参数。ID 与 AutomationProperties.AutomationId 完全匹配，且区分大小写；重复的 ID 会导致失败。使用 root_handle 限定查找范围。拖动目标接受 target_automation_id 和独立的 target_root_handle。录制和导出的测试也适用相同的选择器。

wpf_touch_gesture(automation_id="Canvas", gesture="tap")
wpf_touch_gesture(automation_id="Canvas", gesture="swipe", delta_x=80)
wpf_touch_gesture(automation_id="Canvas", gesture="pinch", scale=1.5)
wpf_drag(automation_id="Source", target_automation_id="Destination")
wpf_set_text(automation_id="UserName", text="test")
wpf_assert(automation_id="UserName", property_name="Text", expected_value="test")

对应的 CLI 参数为 --automation-id、--root、--target-automation-id 和 --target-root。触摸平移使用 swipe，缩放使用 pinch；应用必须支持触摸／操作，才能响应这些手势。

路线图

阶段 1：核心检查 ✅

• 项目结构和架构
• 进程发现和枚举
• 基本进程附加
• 视觉树导航
• 属性检查
• 元素搜索

阶段 2：高级功能 ✅

• 通过命名管道进行 IPC 通信
• 绑定分析和错误检测
• 资源字典枚举
• 样式和模板检查
• 属性变更监控（含通知）

阶段 3：交互与诊断 ✅

• 元素高亮覆盖层
• XAML/JSON 导出
• 屏幕截图捕获（返回 MCP ImageContentBlock）
• 自动将 DLL 注入正在运行的 WPF 进程（x64/x86）
• AdornerLayer 和 Popup 视觉树遍历

阶段 4：CLI + 操控应用 ✅ (v0.4.0 / v0.5.0)

• 双模式可执行文件（MCP stdio + 单次 CLI）(v0.4.0)
• 通过 UI Automation 模式单击控件 (v0.4.0)
• 将物理 OS 鼠标单击作为可选后备方案 (v0.4.0)
• 用户级 Claude Code 技能打包 CLI (v0.4.0)
• 通过 UI Automation IValueProvider 和后备方案设置文本／值 (v0.5.0)
• 支持 Unicode BMP 的物理键盘输入 (v0.5.0)
• 通过 OS 输入执行键盘快捷键（Ctrl+S、Alt+F4、F5 等）(v0.5.0)

阶段 5：多架构支持 ✅ (v0.6.0)

• 跨位数自动注入（64 位服务 → 32 位目标）
• 与架构匹配的 WpfInjectorHelper.exe（32 位 .NET 8）
• 移除 v0.5.0 的已知限制；可操控 x86 和 x64 WPF 应用

阶段 6：查询引擎与完整操控 ✅ (v0.7.0)

• 按可见文本、属性值和可见性查询元素
• 增强结果：文本、自动化 ID、启用／可见状态、屏幕边界
• wpf_select_item — 按文本或索引在 ComboBox/ListBox/TabControl 中进行选择
• 双击／右键单击；物理输入前滚动到视图范围内
• 屏幕模式截图（显示弹出窗口、下拉菜单和上下文菜单）
• 设置文本后的回读验证；弱元素句柄缓存
• 修复关键 IPC 序列化问题（请求参数曾被静默丢弃）

阶段 7：分发与 Agent 易用性 ✅ (v0.7.1 / v0.8.0)

• NuGet 包，可通过 dnx / dotnet tool install 安装（MCP 服务包类型）
• 发布到 nuget.org（可信发布／OIDC）和官方 MCP 注册表
• 修复绑定错误捕获（此前从未接入），修复 IPC 参数丢失问题
• wpf_wait_for — 等待元素／条件，无需反复休眠重试
• 并发 IPC 连接（长时间等待不再阻塞其他命令）

后续计划

已在 v0.13.0 中发布：鼠标拖动和原生触控手势、MCP/CLI 功能对齐、示例演示、输入清理，以及在 net48 x86/x64 和 net8 x64 上进行的真实桌面验证。 已在 v0.14.0 中发布：CLI 自更新，包含版本检查和安装状态。 已在 v0.15.0 中发布：Codex 插件市场、配套技能和插件 ZIP。 已在 v0.16.0 中发布：工作流录制/回放/xUnit 导出、聚合诊断、完整内容截图，以及对 .NET Framework 4.7.2 的兼容支持。

“更改 → 测量 → 是否有效？”循环现已完成：实时编辑属性，然后对比更改前后的快照，准确查看发生了哪些变化。

• wpf_set_property / wpf_revert_property — 实时编辑依赖属性，然后撤销 (v0.9.0)
• wpf_snapshot / wpf_diff — 对比更改前后的快照，验证更改效果 (v0.10.0)
• wpf_evaluate_binding — 解释属性为何具有当前值；逐步解析绑定路径 (v0.11.0)
• wpf_record → wpf_export_test — 基于稳定选择器进行回放并生成全新进程中的 xUnit 测试，涵盖拖动/触控 (v0.16.0)
• wpf_report — 提供有明确覆盖范围的有限聚合诊断 (v0.16.0)
• .NET Framework 4.7.2 和完整内容滚动截图 (v0.16.0)
• 适用于可自托管模式的仅含检查器的 NuGet 包（引用而非注入）
• 向 MCP 客户端流式传输绑定错误/属性更改通知
• 支持 WinUI 3

完整优先级计划请参阅 docs/ROADMAP.md（包括理由、设计说明、工作量和建议的实施顺序）。

参与贡献

欢迎贡献！欢迎提交 Pull Request。

开发环境设置

1. 克隆仓库：

   git clone https://github.com/faze79/WpfVisualTreeMcp.git
   cd WpfVisualTreeMcp
   

2. 在 Visual Studio 2022 或 VS Code 中打开：

   code .
   # or
   start WpfVisualTreeMcp.sln
   

3. 构建并运行测试：

   dotnet build
   dotnet test
   

4. 运行示例 WPF 应用进行测试：

   dotnet run --project samples/SampleWpfApp
   

项目结构

WpfVisualTreeMcp/
├── src/
│   ├── WpfVisualTreeMcp.Server/        # MCP Server (.NET 8) - Uses official MCP SDK
│   │   ├── Program.cs                  # Server initialization with MCP SDK
│   │   ├── WpfTools.cs                 # 38 inspection, interaction and workflow tools
│   │   ├── Cli/CliRunner.cs            # One-shot CLI front-end (v0.4.0)
│   │   └── Services/                   # Process & IPC management
│   ├── WpfVisualTreeMcp.Inspector/     # Injected DLL (Framework 4.7.2/4.8/4.8.1; .NET 8/9/10)
│   ├── WpfVisualTreeMcp.Injector/      # Managed injection logic (CreateRemoteThread; net48 + net8.0)
│   ├── WpfVisualTreeMcp.InjectorHelper/# x86 .NET 8 helper exe for cross-arch injection (v0.6.0)
│   ├── WpfVisualTreeMcp.Bootstrapper/  # Native C++ DLL for CLR hosting
│   └── WpfVisualTreeMcp.Shared/        # Shared models & IPC contracts
├── samples/
│   └── SampleWpfApp/                   # Test application
├── tests/
│   ├── WpfVisualTreeMcp.Tests/         # Unit tests
│   └── WpfVisualTreeMcp.IntegrationTests/ # Live WPF integration tests
├── publish/                            # Published server + native DLLs
│   └── native/{x64,x86}/              # Architecture-specific bootstrapper
└── docs/                               # Documentation

技术详情

• MCP SDK：使用 Microsoft/Anthropic 提供的官方 C# MCP SDK构建
• 协议：通过 stdio 传输的 JSON-RPC 2.0
• 目标框架：.NET 8.0（服务）/ .NET Framework 4.7.2、4.8 和 .NET 8.0-windows（检查器）
• IPC：使用命名管道进行服务与应用程序之间的通信
• 工具：通过 [McpServerTool] 属性自动发现 38 个工具，涵盖检查、诊断、交互以及工作流录制/测试。回放会执行录制的操作；完整内容截图可能会临时滚动控件。
• CLI：同一可执行文件在提供子命令时也可作为一次性 CLI 运行（Program.cs 通过 CliRunner.IsCliCommand 进行路由）

致谢

• 灵感来自 Snoop WPF——原始 WPF 监视工具
• 基于 Anthropic 的 Model Context Protocol 构建
• 感谢 .NET 和 WPF 社区

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。