内容
# ue-ikrig-mcp
UE5 中用于创建和微调 IK Rigs 和 IK Retargeters 的 MCP 服务器。
通过 Claude Code 实现对话式重定向微调：“左臂看起来不对，顺时针旋转 5 度” -> 在 UE 编辑器视口中立即实时更新。
## 先决条件
- UE5.x 且 **Python 编辑器脚本插件** 已启用
- 编辑器首选项中 **Python 远程执行** 已启用
- [uv](https://docs.astral.sh/uv/) 已安装（`pip install uv` 或 `curl -LsSf https://astral.sh/uv/install.sh | sh`）
对于 Windows 主机 UE 和 WSL 主机代理，请在重试 MCP 调用之前验证 UE 的 Python 远程执行设置：
```ini
[/Script/PythonScriptPlugin.PythonScriptPluginSettings]
bRemoteExecution=True
RemoteExecutionMulticastGroupEndpoint=239.0.0.1:6766
RemoteExecutionMulticastBindAddress=0.0.0.0 ; 或正确的 Windows 适配器 IP
RemoteExecutionMulticastTtl=1 ; WSL/Windows；仅在同一命名空间中保留 0
```
在 WSL 中运行 MCP 服务器且 UE 在 Windows 上运行时，请勿使用 `RemoteExecutionMulticastBindAddress=127.0.0.1`。这会将 UE 的远程执行 UDP 监听器绑定到 Windows 环回地址，仅限 Windows 环回端口；WSL 发现则要么看不到 `pong`，要么因 Windows 环回端口映射到 WSL 而无法绑定 `0.0.0.0:6766`。MCP 默认配置包含 WSL 多播组绑定回退，但 UE 仍需要非环回绑定地址和更改设置后的编辑器重启。
在 WSL 中开发时，请通过 Windows Python（pythonw.exe）启动 MCP 服务器，以便它可以直接发现 Windows localhost 上的 UE；这样就不再需要 WSL→Windows 桥。例如：
`.venv-win/Scripts/pythonw.exe -m ue_ikrig_mcp`。在 WSL 中运行服务器将无法发现 Windows 主机上的编辑器（WSL/Windows 网络命名空间阻止了发现 UDP），并且服务器会打印有关此问题的警告。
更改插件或网络设置后，UE 可能需要重启。Windows Defender 防火墙必须允许 `UnrealEditor.exe`、UDP 多播端口 `6766` 和从 Windows 返回到 MCP 主机的 TCP 回调端口。
## 安装
### Claude Code（推荐）
在项目的 `.mcp.json` 中添加：
```json
{
"mcpServers": {
"ue-ikrig": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "git+https://github.com/tridot-io/ue-ikrig-mcp.git", "ue-ikrig-mcp"]
}
}
}
```
无需手动安装。`uvx` 自动处理所有安装事宜。
### 手动安装
```bash
pip install git+https://github.com/tridot-io/ue-ikrig-mcp.git
ue-ikrig-mcp
```
## 工具
### 连接（5）
- `preflight_discovery` - 确定性 UDP ping/pong 和可选的 TCP 回调诊断
- `discover_editors` - 查找正在运行的 UE 编辑器实例；响应可能包含多个可选择的 `node_id`
- `connect_to_editor` - 打开此 MCP 进程的单个活动命令通道到一个选定的编辑器（当发现不明确时需要 `node_id`）
- `disconnect_editor` - 关闭此 MCP 进程持有的命令/发现套接字
- `connection_status` - 检查连接状态，包括活动 `node_id`、已发现节点和是否需要选择
### IK Rig（10）
- `create_ik_rig` - 创建新的 IK Rig 资源
- `inspect_ik_rig` - 读取完整的 Rig 状态
- `set_ik_rig_mesh` - 分配骨骼网格
- `set_retarget_root` - 设置重定向根骨骼
- `add_retarget_chain` / `remove_retarget_chain` / `get_retarget_chains` - 管理链
- `list_bones` - 列出骨骼层次结构
- `list_ik_assets` - 查找现有的 IK/RTG 资源
- `save_asset` - 将资源保存到磁盘
### IK Retargeter（7）
- `create_retargeter` - 创建新的 IK Retargeter 资源
- `inspect_retargeter` - 读取完整的 Retargeter 状态
- `set_retargeter_rigs` - 分配源/目标 IK Rigs
- `auto_map_chains` - 按名称相似性自动映射链
- `set_chain_mapping` / `get_chain_mappings` - 手动链映射
- `auto_align_all_bones` - 自动对齐重定向姿势
### 微调（10）
- `get_bone_rotation_offset` / `set_bone_rotation_offset` - 读取/写入骨骼旋转
- `adjust_bone_rotation` - 增量欧拉旋转（主要调优工具）
- `set_root_offset` - 调整根节点平移
- `get_chain_settings` / `set_chain_settings` - FK/IK 混合设置
- `get_global_settings` / `set_global_settings` - 全局重定向设置
- `create_retarget_pose` / `set_current_pose` - 姿势管理
### 批处理和实用工具（4）
- `batch_retarget` - 批量重定向动画
- `execute_python` - 原始 Python 出口（`mode` 和可选 `timeout_seconds`）；自动连接，本地验证语法，注入帮助前奏，返回失败提示
- `list_skeletal_meshes` - 查找骨骼网格
- `ue_python_guide` - MCP 驱动器的 UE Python 脚本指南（结果协议，令牌经济，资产路径，API 陷阱，超时）
### 脚本存储（4）
- `save_script` - 持久化一个可重用的 UE Python 脚本，名称（语法检查；会话生存）
- `run_script` - 使用 JSON 参数重放保存的脚本，公开为 `ARGS` 字典
- `list_scripts` / `delete_script` - 管理存储（`UE_MCP_SCRIPT_DIR`，默认为 `~/.ue_ikrig_mcp/scripts`）
### API 目录（3）
- `build_api_catalog` - 编辑器的 `unreal` Python API 的一次性收集（类/方法/属性及其签名和文档摘要）以及来自资产注册表的项目自己的类型（蓝图/小部件/动画蓝图类，材质资产/函数/实例，用户结构体/枚举，数据资产 - 具有父类和资产路径，无资产加载）到本地文件，按引擎版本索引；当编辑器连接时自动运行，因此显式调用主要用于 `force=true` 重建
- `search_unreal_api` - 即时本地 BM25 关键字搜索整个目录 - 无编辑器往返，防止虚构的 API 名称；零命中查询会通过 UE 同义词、子字符串和容错传递（`match_mode` 报告哪些）；种类过滤器包括 `blueprint`、`widget`、`animbp`、`material`、`material_function`、`material_instance`、`struct`、`enum`、`dataasset`
- `describe_unreal_api` - 一个符号的完整文档字符串（连接时来自编辑器，否则来自目录）；类响应带有祖先链，`include_inherited=true` 将每个祖先映射到其贡献的成员（UE 成员位于定义类）；项目蓝图/小部件/动画蓝图/材质/材质函数/材质实例符号解析为资产 - 父类，在适用情况下生成的类，蓝图变量（`UE_MCP_CATALOG_DIR`，默认为 `~/.ue_ikrig_mcp/api_catalog`)
### 蓝图家族功能（1）
- `blueprint_family_capabilities` - 蓝图/K2、WidgetBlueprint、AnimBlueprint、Control Rig、Material/MaterialFunction/MaterialInstance 和 TAPython 表面的只读功能路由器。使用前请调用此功能以获取支持标签、推荐工具、停止条件和夹具/验证要求；它永远不会改变资产。
### 捕获（3）
- `capture_viewport` - 通过 UE AutomationLibrary 捕获关卡编辑器视口截图（实时/重绘强制）
- `capture_ue_window` - 操作系统级别的窗口或标签截图，带有 PrintWindow 回退（适用于任何可见的 UE 窗口）
- `capture_asset_editor` - 在其编辑器中打开资产并捕获预览视口截图（IK Retargeter、AnimBP、SkeletalMesh、PhysicsAsset、ControlRig）
## 架构
```
Claude Code <--stdio--> MCP 服务器（Python） <--UDP/TCP--> UE 编辑器
```
服务器通过内置的 Python 远程执行协议（UDP 多播发现 + TCP 命令）与 UE 编辑器通信。如果配置的命令端口仍被另一个本地 MCP 进程占用，`connect_to_editor` 会自动回退到空闲的本地端口，除非设置了 `UE_COMMAND_PORT_STRICT=true`。
多个独立的 MCP 服务器进程可以连接到同一个 Unreal 编辑器。此并发边界 **按 MCP 进程**: 每个进程保持自己的发现状态和本地命令监听器。它 **不意味着** 一个 MCP 进程可以同时保持多个活动编辑器连接。当第二个 MCP 进程针对同一个编辑器，默认本地命令端口已占用时，它应该回退到临时本地端口，并在 `connection_status` 中报告这一点。
### 发现多个，连接一个
`discover_editors` 是一个发现工具：它可以通过直接 UDP 返回每个可见的 Unreal 编辑器节点。使用返回的 `node_id` 值显式选择目标编辑器。
`connect_to_editor` 是一个选择工具：一个 MCP 服务器进程一次保持一个活动编辑器连接。当发现多个编辑器且没有仍然有效的活动编辑器已选择时，省略 `node_id` 是不明确的。工具报告稳定模糊信号：
```json
{
"error": true,
"error_code": "MULTIPLE_EDITORS_DISCOVERED",
"classification": "MULTIPLE_EDITORS_DISCOVERED",
"message": "发现了多个 Unreal 编辑器实例。请使用 node_id 重新尝试。",
"nodes": [
{
"node_id": "...",
"project_name": "...",
"_transport": "direct_udp"
}
],
"next_action": "调用 connect_to_editor(node_id=<其中一个节点.node_id>)。"
}
```
使用 `connect_to_editor(node_id="<选择的 node_id>")` 重试，将此 MCP 进程绑定到一个编辑器。选择不同的 `node_id` 后，进程会切换到该编辑器；它不会创建第二个活动会话。
如果 `connection_status` 已经显示一个仍然有效的活动编辑器，后续的 `connect_to_editor()` 调用（省略 `node_id`）是幂等的：它重用当前活动编辑器，即使发现可以查看其他编辑器。状态响应通过 `connected`、`node_id`、`discovered_nodes`、`selection_required` 和 `one_active_editor_per_process` 等字段区分活动选择和发现清单。
## 发现预检/医生
在 `discover_editors`/`connect_to_editor` 之前运行 `preflight_discovery` 以启动新的机器或编辑器。它发送 Unreal 的确切远程执行 UDP `ping` 数据包并等待 `pong`。仅在收到 `pong` 后，它才会测试 TCP `open_connection` 回调；它永远不会在 Unreal 中执行 Python。
如果 `preflight_discovery` 报告 `NO_PONG_RECEIVED_UNPROVEN`，则发现未经验证。不要重试 `connect_to_editor` 或 `execute_python`；请先修复发现：
- 在 Unreal 中启用 Python 远程执行，
- 将 `RemoteExecutionMulticastGroupEndpoint` 与 `UE_MULTICAST_GROUP`/`UE_MULTICAST_PORT` 匹配，
- 设置正确的 Unreal 多播绑定地址，
- 检查 Windows 防火墙和网络配置文件，
- 如果在 WSL 下运行，请通过 Windows Python（pythonw.exe）启动服务器，以便发现运行在 Windows 主机上而不是跨 WSL 命名空间。
有用的环境覆盖变量：
```bash
UE_MULTICAST_GROUP=239.0.0.1
UE_MULTICAST_PORT=6766
UE_MULTICAST_BIND=0.0.0.0,239.0.0.1 # 逗号/分号列表接受
UE_MULTICAST_INTERFACE=172.30.1.10 # 可选；WSL 未设置时自动检测
UE_MULTICAST_MEMBERSHIP=172.30.1.10 # 可选；WSL 未设置时自动检测
UE_MULTICAST_TTL=1 # WSL 默认；非 WSL 默认值为 0
UE_COMMAND_HOST=0.0.0.0
UE_COMMAND_PORT=6777
UE_COMMAND_EXEC_TIMEOUT=120 # 秒为直接 TCP 命令执行
UE_CONNECTION_STATUS_TIMEOUT=0.25 # 秒为 connection_status 生存探测
UE_CALLBACK_HOST=172.30.1.10 # 永远不要宣传 0.0.0.0 到 Unreal
UE_DISCOVERY_SETTLE=0.25 # 首次 pong 后额外等待更多编辑器
UE_BROKER=true # 共享编辑器命令代理（原生，非 WSL）；false 禁用
UE_SCRIPT_PREFLIGHT=true # 本地语法检查，然后将脚本发送到 UE
UE_MCP_SCRIPT_DIR=~/.ue_ikrig_mcp/scripts # 保存的脚本存储位置
UE_MCP_CATALOG_DIR=~/.ue_ikrig_mcp/api_catalog # unreal API 目录位置
```
### MCP 驱动器的脚本指南
- `ue_python_guide` 返回脚本指南（结果协议、资产路径规则、现代与过时 API、超时规则、失败分类）；每个会话读取一次，然后再生成非平凡脚本。
- 对于蓝图、WidgetBlueprint、AnimBlueprint、Control Rig、Material/MaterialFunction/MaterialInstance 和 TAPython 表面的图作者，请先调用 `blueprint_family_capabilities` 并参阅 `docs/ue_graph_authoring_driver_guideline.md`，然后再假设节点创建或引脚连接支持。
- `execute_python` 在没有编辑器连接的情况下自动连接，在任何编辑器往返之前验证脚本语法（`UE_SCRIPT_PREFLIGHT=false` 禁用），并且失败结果包括 `hints` 列表，将 Unreal Python 常见失败（虚构或已弃用的 API、错误的资产路径、缺少 `__MCP_RESULT__` 监视器、超时）分类为可行的修复。
### 驱动器的令牌经济
生成 UE Python 内联会消耗驱动器令牌；服务器会移除循环开销：
- **帮助前奏**: 在 `ExecuteFile` 模式下，每个 `execute_python`/`run_script` 调用都有 `load()`、`mcp_result()`、`subsys()`、`asset_registry()` 和 `unreal`/`json` 导入预定义 - 脚本仅包含唯一逻辑（`inject_helpers=false` 退出）。
- **保存的脚本**: `save_script` 一次，`run_script(name, args)` 永远 - 参数作为 `ARGS` 字典到达，脚本在会话间持久化（`UE_MCP_SCRIPT_DIR`，默认为 `~/.ue_ikrig_mcp/scripts`）。
- **结果塑形**: 当脚本通过 `__MCP_RESULT__` 返回结构化数据时，原始输出回声被省略（`compact=false` 保留）；超大文本在 `max_output_chars` 处截断头部+尾部（默认为 8000，`0` = 无限制）。
- `ue_python_guide` `tokens` 主题为驱动器提供最便宜的路径排名：专用工具 → 批处理工具 → `run_script` → `execute_python`。
失败的预检输出包括 OS/WSL 检测、本地 IPv4 候选地址、多播组选择的路由地址、绑定/接口/成员资格候选地址、TTL、ping 时间戳、pong 源、数据包解析错误、回调侦听器详细信息和套接字错误。如果需要帮助，请收集：
- `Saved/Logs/<Project>.log`，
- 过滤为 Python、套接字或远程执行的 Unreal 输出日志，
- `UnrealEditor.exe` 的 Windows 防火墙状态，
- 证据数据包，如 WSL `tcpdump udp port 6766` 或 Windows Wireshark/`pktmon`。
`connection_status` 积极探测当前传输，然后报告 `connected`：直接 TCP 套接字被 peek 以检查对等方关闭，并且代理连接会进行状态 ping。`connection_liveness` 字段记录探测结果，并且过时的传输被清除而不是报告为已连接。它还会在 `package` 下报告加载的包版本/源文件。对于多编辑器会话，请单独检查活动 `node_id` 和 `discovered_nodes`：`selection_required=true` 表示发现了多个编辑器，下一个连接必须命名一个 `node_id`；`selection_required=false` 且 `connected=true` 表示此 MCP 进程有一个活动编辑器被选中。
`execute_python` 接受 `timeout_seconds` 以设置每次调用的命令边界。当省略时，命令执行使用 `UE_COMMAND_EXEC_TIMEOUT`（默认为 120 秒）。
## 许可证
MIT
