UI Toolkit MCP

一个 MCP 服务器，让 AI 代理可以在 Unity 编辑器保持打开的状态下检查 UI Toolkit 屏幕。它可以检查 UXML/USS 文件的结构和外观，并在不进入播放模式或构建 Player 的情况下捕获屏幕截图。

主要功能：

• 列出 UXML 文件和打开的 UI Toolkit 窗口

• 检查元素树、文本、值、位置、大小和已解析的样式

• 将整个屏幕或选中的元素捕获为 PNG 图像

• 自动将长屏幕分割为多个图块（每张图像最多 8192 像素，总计最多 100 MP）

• 重新导入 UXML/USS 文件

• 已通过 Unity 2022.3 LTS 和 Unity 6.3 的兼容性测试

设置

1. 添加 Unity 包

在 Unity 编辑器中，打开 Window > Package Manager，点击左上角的 + 按钮，然后选择 Add package from git URL...。

输入以下 URL：

https://github.com/adzukyat/ui-toolkit-mcp.git?path=/unity-package

预览服务器会在 Unity 完成脚本编译后自动启动。使用期间请保持 Unity 编辑器处于打开状态。

2. 注册 MCP 服务器

需要 Node.js 20 或更高版本。Codex 的示例配置：

[mcp_servers.ui_toolkit_mcp]
command = "npx"
args = [
  "-y",
  "ui-toolkit-mcp-server@latest",
  "mcp"
]

Related MCP server: Unity MCP Server

MCP 工具

首先使用 ui_list_projects 查找项目，然后使用 ui_select_project 选择它。接下来，使用 ui_list_targets 找到要检查的屏幕，然后使用 ui_inspect 或 ui_screenshot。

预览配置（可选）

在项目根目录放置一个 .ui-toolkit-mcp-preview.json 文件，以定义稳定的别名、额外的 USS 文件、主题和视口。复制并调整以下示例：

{
  "$schema": "./Packages/me.adzuki.ui-toolkit-mcp.preview-server/Schemas/ui-toolkit-mcp-preview.schema.json",
  "schemaVersion": 1,
  "previews": [
    {
      "alias": "settings",
      "document": "Assets/UI/Settings.uxml",
      "stylesheets": ["Assets/UI/Settings.uss"],
      "theme": "editor-dark",
      "selector": "#settings-root",
      "viewport": { "width": 480, "height": "full" }
    }
  ]
}

支持的主题有 editor-dark、editor-light 和 runtime。对于 runtime 主题，也可以指定 panelSettings 资源路径。

开发和验证

npm test
npm run typecheck
npm run build
node scripts/mcp-smoke.mjs [project-id]

Unity EditMode 测试位于 test-projects/2022.3 和 test-projects/6000.3 中。像素级精确验证需要图形设备。树检查可以在 -nographics 下工作，但 PNG 渲染不行，因此请在正常启动的 Unity 编辑器中执行最终验证。

当前限制

• 服务器主要针对静态 UI 状态。对于在 C# 中稍后构建的屏幕，请打开实际的 EditorWindow 或在预览 UXML 文件中准备所需的状态。

• 编辑器离屏渲染器通过反射调用 UI Toolkit 内部 API。ui_status 会对不支持的 Unity 版本报告警告。

• 打开的窗口 ID 仅在当前 Unity 会话中有效。

• 尚不支持悬停和焦点等伪状态注入、指针/键盘交互以及固定动画时间。

• 字体、图标、自定义控件和数据绑定仅在目标项目中可以解析时才会渲染。