内容
# UIInspect.MCP
UIInspect.MCP 是一个基于用户同意的 C# 模型上下文协议服务器，通过 UI 自动化 3（UIA3）为 AI 代理提供 Windows 应用程序的语义访问。MVP 版本发现并附加到 WPF、WinForms、WinUI、Avalonia 和 .NET MAUI Windows 应用程序窗口，当这些框架公开标准 UIA 提供程序时。它返回一个有界的控件树，并对不透明的元素引用执行确定性的操作，而不是依赖像素坐标。
主机使用 `ModelContextProtocol` 1.4.1、.NET 10、FlaUI 5.0 UIA3、stdio 传输、TUnit 和 Microsoft Testing Platform。
## MVP 状态
已实现：
- 具有进程实例标识和本机句柄的顶级窗口发现。
- 每个进程实例的显式受信任 Windows 批准对话框。
- 按进程 ID 附加，可选本机窗口句柄。
- 有界、扁平化的 UIA 控件树快照。
- 不透明的、生成范围内的元素引用以及解释性语义路径。
- 密码元素编辑和检查期间不收集控件值。
- 调用、解析点击、ValuePattern 设置、SelectionItemPattern 选择、展开/折叠和允许的逻辑键。
- 每个客户端/进程的同意、过期、PID 重用检查、速率限制、仅追加的编辑 JSONL 审计和确定性会话清理。
- 确定性 WPF 和 WinForms 固定应用程序。
- TUnit/MTP 单元和实时 Windows 集成测试。
延期到后续里程碑：
- XAML 源/视觉树、依赖属性、绑定、验证、DataContext、命令诊断和热重载钩子。UIA 不公开这些；它们需要设计中描述的显式启用的进程内代理。
- 截图/叠加层、录制/重放、虚拟化助手、UIA2 回退、TCP 传输和签名的 CI 客户端令牌。
- 专用 WinUI、Avalonia 和 MAUI 固定套件。它们的标准控件已经可以通过 UIA3 访问，但每个提供程序都需要单独的兼容性套件和打包/运行时设置。
MVP 中不包含 DLL 注入、任意反射、OCR、屏幕抓取、shell 执行或通用属性写入。
## 架构
```text
MCP 客户端
│ stdio JSON-RPC
▼
UIInspect.MCP.Server
│ 仅限工具适配器
▼
UIInspect.MCP.Core
│ 进程实例同意 + 授权 + 速率限制 + 审计 + 会话
▼
UIInspect.MCP.Windows
│ 序列化 FlaUI/UIA3 适配器 + 语义定位器重新解析
▼
目标进程可访问性提供程序
```
项目：
| 项目 | 责任 |
|---|---|
| `UIInspect.MCP.Core` | 平台中立的合约、结果模型、同意注册、速率限制、审计和协调器 |
| `UIInspect.MCP.Windows` | Windows 进程标识、受信任的同意 UI、FlaUI UIA3 发现/会话适配器 |
| `UIInspect.MCP.Server` | MCP 1.4.1 stdio 主机和受控工具注册 |
| `UIInspect.Sample.Wpf` | 确定性 WPF UIA 固定装置 |
| `UIInspect.Sample.WinForms` | 确定性 WinForms UIA 固定装置 |
| `UIInspect.MCP.Tests` | TUnit/MTP 单元、主机和实时 UIA 集成测试 |
## 构建和测试
需求：
- 具有交互式桌面的 Windows 10/11。
- .NET SDK 10.0.301 或兼容的功能带。
- 服务器必须在同一 Windows 登录会话中运行，并具有足够的完整性级别以满足其目标。
```powershell
dotnet restore .\UIInspect.MCP.slnx
dotnet build .\UIInspect.MCP.slnx -c Release --no-restore
dotnet test .\src\UIInspect.MCP.Tests\UIInspect.MCP.Tests.csproj -c Release --no-build --no-restore -- `
--coverage `
--coverage-settings .\eng\coverage.runsettings `
--coverage-output .\artifacts\coverage\coverage.cobertura.xml `
--coverage-output-format cobertura `
--report-trx `
--no-progress
```
覆盖率允许列表包括三个生产程序集，仅排除测试程序集、固定装置应用程序、编译器生成的源代码和方法，并具有审查过的 `ExcludeFromCodeCoverage` 理由。门槛是 100% 的合格生产代码；检查 Cobertura 报告以获取确切的行数和分支指标。
## 运行
从源代码：
```powershell
dotnet run --project .\src\UIInspect.MCP.Server\UIInspect.MCP.Server.csproj -c Release
```
MCP 协议拥有 stdout。所有控制台日志记录都转到 stderr。
本地 MCP 客户端配置示例：
```json
{
"servers": {
"uiinspect": {
"type": "stdio",
"command": "dotnet",
"args": [
"run",
"--project",
"D:\\Projects\\Github\\chrispulman\\UIInspect.MCP\\src\\UIInspect.MCP.Server\\UIInspect.MCP.Server.csproj",
"-c",
"Release"
]
}
}
}
```
相同的 stdio 命令可用于 Codex、VS Code、Visual Studio 2022/2026 MCP 兼容的代理集成和其他 MCP 客户端。仅调整客户端特定的配置容器。
设置 `UIINSPECT_AUDIT_PATH` 以覆盖默认审计位置 `%LOCALAPPDATA%\UIInspect.MCP\audit\actions.jsonl`。
## MCP 工具
| 工具 | 目的 | 同意 |
|---|---|---|
| `uiinspect_discover_windows` | 列出顶级 UIA 窗口 | 速率限制的发现 |
| `uiinspect_request_consent` | 显示受信任的本地批准对话框 | 本地用户决定 |
| `uiinspect_attach` | 为 PID/HWND 打开不透明的会话 | 检查 |
| `uiinspect_inspect_tree` | 返回有界的语义快照 | 检查 |
| `uiinspect_invoke` | 使用 InvokePattern | 交互 |
| `uiinspect_click` | 点击语义解析的元素 | 交互 |
| `uiinspect_set_value` | 使用 ValuePattern | 交互 |
| `uiinspect_set_text` | ValuePattern 的文本别名 | 交互 |
| `uiinspect_select_item` | 使用 SelectionItemPattern | 交互 |
| `uiinspect_expand_collapse` | 使用 ExpandCollapsePattern | 交互 |
| `uiinspect_send_key` | 在聚焦后发送一个允许的逻辑键 | 键盘 |
| `uiinspect_close_session` | 处置会话 | 会话所有者 |
每次成功的动作都会使当前元素引用生成无效。每次动作前请调用 `uiinspect_inspect_tree`。
## 安全工作流程
1. 调用 `uiinspect_discover_windows`。
2. 独立识别目标进程和窗口。
3. 调用 `uiinspect_request_consent`；本地用户必须批准确切的进程实例和功能集。
4. 调用 `uiinspect_attach`。
5. 调用 `uiinspect_inspect_tree`，使用最小的有用深度和节点预算。
6. 优先使用模式优先工具（`invoke`、`set_value`、`select_item`、`expand_collapse`）而不是 `click` 或键盘。
7. 在每次成功的动作后重新检查。
8. 调用 `uiinspect_close_session`。
有关威胁模型，请参阅 [Security](docs/security.md)，有关当前边界和后续里程碑的信息，请参阅 [MVP 设计](docs/mvp-design.md)。
