UnrealMCPHub 开发者指南

注意：本文件面向 Hub 代码库本身的维护与开发。 如需了解如何使用 Hub 驱动 UE 开发，请参阅

skills/use-unrealhub/SKILL.md

（随 Hub 仓库一起发布）。

维护规约：对 Hub 的任何功能变更（新工具、参数修改、行为变化） 都必须同步更新

skills/use-unrealhub/SKILL.md

。详见下方「添加新工具检查清单」。

架构概览

UnrealMCPHub/
├── src/unrealhub/
│   ├── server.py              # MCP 服务器入口、工具注册
│   ├── config.py              # 项目配置管理
│   ├── tools/
│   │   ├── project_tools.py   # setup/config/remove/status
│   │   ├── build_tools.py     # build_project
│   │   ├── launch_tools.py    # launch/stop/restart editor
│   │   ├── install_tools.py   # check_plugin_status
│   │   ├── discovery_tools.py # discover/manage instances
│   │   ├── monitor_tools.py   # health check
│   │   ├── log_tools.py       # get_log
│   │   ├── proxy_tools.py     # ue_status/list/call/run_python
│   │   └── session_tools.py   # add_note/get_session
│   └── core/
│       ├── instance_manager.py
│       ├── process_manager.py
│       └── watcher.py
├── skills/
│   ├── unrealhub-developer/
│   │   └── SKILL.md           # 本文件（开发者指南）
│   ├── use-unrealhub/
│   │   └── SKILL.md           # 使用者技能（随 Hub 发布）
│   └── ue-benchmark/
│       ├── SKILL.md           # Benchmark 通用框架
│       └── scenarios/         # 各评测场景规格
│           └── vampire-survivors-v1.md

工具注册模式

所有工具在

server.py

中通过

@mcp.tool()

装饰器注册。添加新工具时：

1. 在对应的

   tools/*.py

   中实现函数
2. 在

   server.py

   中导入并注册
3. 更新

   skills/use-unrealhub/SKILL.md

   的工具速查表

代理工具原理

proxy_tools.py

中的

ue_call

/

ue_run_python

通过 HTTP 转发到 UE 内运行的 RemoteMCP 插件。关键逻辑：

• 活跃实例选择：

  instance_manager.get_active()

• HTTP 转发：

  POST http://{host}:{port}/mcp/call

• 离线降级：返回引导信息而非抛异常

添加新工具检查清单

• tools/*.py

  中实现

• server.py

  中注册
• 错误处理（连接失败、实例离线、参数校验）
• 同步更新

  skills/use-unrealhub/SKILL.md

• 如有新的使用模式/注意事项，同步补充到技能文件的对应 Part

发布检查清单

每次 Hub 发版（打 tag / bump version）前必须执行：

• 更新

  PLUGIN_TAG

  ：检查 RemoteMCP 最新 tag， 将

  src/unrealhub/config.py

  中的

  PLUGIN_TAG

  更新为该 tag（如

  "v1.0.0"

  ）
• 更新

  pyproject.toml

  version：与 git tag 一致
• 全量测试通过：

  pytest tests/ -v

• SKILL.md 同步：确认

  skills/use-unrealhub/SKILL.md

  反映所有变更
• Lint 清零：无新增 lint 错误