Nexus MCP for Unreal Engine — VS Code / Cursor

语言 / Language: 简体中文 · English

在 VS Code / Cursor 中连接 AI 与 Unreal Engine。 NexusVSCode 是 NexusLink — Unreal Engine MCP 的 IDE 客户端，在扩展商店名为 Nexus MCP。配合 UE 侧 NexusLink，可让 AI 读取项目、编辑资产和调试运行状态。

VS Marketplace · Open VSX · UE 插件（NexusLink） · 安装与使用 · 下载 VSIX

扩展负责自动发现 UE 实例、复制 AI 客户端配置和多实例切换；蓝图、资产、PIE 等能力由 NexusLink 提供。本地 MCP HTTP 端口默认 :6900，经 WebSocket 转发工具调用。

编辑器长操作支持按会话查询、等待期间的 MCP 进度及取消等待；底层测试停止须显式请求，Live Coding 不承诺取消。任务状态不缓存，写操作断线不重试。

四端端口与开关层数见 NexusLink 使用指南。本扩展是三层开关中的 IDE 层。本机不要与 NexusDesktop / Rider 代理同时开。

截图响应中的标准 MCP PNG/JPEG 图片块直接内联透传，并保留 FilePath 元数据；含图片的响应不做大文本转存或代理缓存。

依赖

安装与使用

须开总开关：扩展在启动后激活（onStartupFinished），但 MCP HTTP 默认不监听。将 nexusMcp.enabled 设为 true 后才监听；改回 false 立即停止，无需重载窗口。

1. 先准备好 UE

安装并启用 NexusLink，勾选 启用 MCP 服务器（步骤见 usage-guide §2）。未勾选时扫描为空。

2. 安装本扩展

方式 A — 扩展商店（推荐）：在 VSCode / Cursor / CodeBuddy / Windsurf 搜索 Nexus MCP（Open VSX · VS Marketplace）。

方式 B — vsix：从 NexusVSCode Releases 下载 → Extensions: Install from VSIX... → 重载窗口。

然后 Settings 搜索 nexusMcp → Nexus Mcp: Enabled = true（默认 :6900）。

3. 配置项

跨机与身份验证（开关、多 token、本机自动读文件）见 usage-guide §1。

4. 状态栏与命令

状态栏始终显示已连接项目名 / 未连接，悬浮提示保留 Agent 转发暂停状态，点击切换实例或复制 MCP 配置。

批量调用（含部分失败）会清理目标实例的读缓存，失败读取不会进入缓存。大响应临时文件相互隔离，仅清理超过 1 小时的文件。客户端断开、停用扩展或重启中转时，暂停队列中的请求会被取消，不会在恢复后补发。

兼容已发布 2.x 的工具调用格式和当前格式，请求原样转发。新版临时目录与旧 2.x 分开，避免旧进程清理新版结果。

唯一实例自动连接；多实例优先 hostKind=Editor（旧 UE 无该字段时改用 netRole=Editor）。断线保留工具列表缓存；还能返回带 _proxy.degraded 的上次读取结果。读缓存与断线快照按 UE host/port 隔离，切换实例不会复用另一实例的数据。会话层约定见 proxy-session.md。

复制客户端配置与身份验证

Settings 搜索 nexusMcp 时，Enabled / Require Auth 说明里也有同样步骤（可点命令链接）。

复制 MCP 配置（JSON / TOML）

1. Ctrl+Shift+P → Nexus MCP: 复制 MCP 客户端配置（未启用代理也能用；或点状态栏选同一项）
2. 先选客户端，再选传输协议（推荐 Streamable HTTP；Codex 自动选择）；开 LAN 且多网卡时先选写入 url 的 IP
3. 粘贴到对应 AI 客户端（一次只复制一份）：

• Cursor：~/.cursor/mcp.json → mcpServers 下的 nexus-unreal 段
• Codex：~/.codex/config.toml（或自定义 CODEX_HOME）中的 mcp_servers.nexus-unreal 段
• 其他客户端：按选项说明粘贴，下方列出各组格式与位置

1. 可选「打开预览」核对后再贴

粘贴后须将 nexusMcp.enabled 设为 true，AI 才能连上。默认 http://127.0.0.1:6900/stream。已启动则按实际监听端口写入；端口自动换成下一个时以状态栏 / 启动通知为准。旧版客户端选 SSE（/sse）。

复制身份验证 Token

默认 nexusMcp.requireAuth = true，AI 连接须带 Authorization: Bearer <token>。

可写多个：Bearer <tok1>, <tok2>。本机 token 与 UE / Desktop / Rider 共用，不要填进 extraAuthTokens。规则见 usage-guide §1.1。

客户端配置与 Desktop 保持一致：Cursor / Windsurf、Codex、Claude Code / VS Code、CodeBuddy、Cline、Roo Code 六组。相同格式合并显示，粘贴位置单独说明，复制内容不含注释。Codex 生成 ~/.codex/config.toml（或自定义 CODEX_HOME）所需的 TOML，自动使用 Streamable HTTP；其余客户端生成 JSON 条目。Claude Code 使用 .mcp.json 的 mcpServers，VS Code 使用 .vscode/mcp.json 的 servers；已有同名条目时替换，保留其他配置。

Cursor 完整文件示例：

{
  "mcpServers": {
    "nexus-unreal": {
      "url": "http://127.0.0.1:6900/stream",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

已连接时 tools/list 合并 UE 工具。多实例并发可在 arguments 中带 targetPort，须为 1024–65535 的整数；非法显式端口返回 -32602，不会转发到当前实例或返回缓存。

常见问题

AI 客户端「MCP 初始化超时」

确认 nexusMcp.enabled 为 true、UE 已启用 MCP、状态栏已显示项目名、AI 端口与实际监听一致。

工具列表不刷新

连接/断开后会推送 notifications/tools/list_changed。未更新时重连 MCP 或重启 AI 会话。

查看日志

点击 Nexus 状态栏菜单 → 打开日志，或运行命令面板 Nexus MCP: 打开日志，会打开当前启动的日志通道，代理停用时也可使用。每次扩展启动（包括重载）新建带启动时间的 Nexus MCP (...) 通道和独立日志文件，旧日志保留。VSCode/Cursor 管理文件落盘与滚动；通过命令面板 Developer: Open Logs Folder 可获取对应启动时间的 Nexus MCP 日志文件。

默认 INFO 即记录客户端版本、会话创建与握手、失效或淘汰、HTTP 拒绝、SSE 通断、调用开始/完成/耗时与失败，以及服务器停止原因和连接恢复。session 是会话摘要，request 是本次服务器运行内的请求编号；missing_session / unknown_session 区分缺少 ID 与 ID 已不存在。Token、完整会话 ID、工具参数和响应正文不写入日志。

最多保留 50 个 MCP 会话；容量满时仅回收超过 30 分钟没有请求、也没有进行中调用或 SSE 连接的会话（idle_timeout）。正在初始化或使用的会话不会被新连接淘汰；无法回收时，新连接返回 503 和 Retry-After（session_limit）。客户端可通过携带会话 ID 的 DELETE /stream 主动结束会话（client_delete）。回收后的 ID 需要重新 initialize。

反馈断连时请提供报错时间、AI 客户端名称与版本、客户端日志及对应时段的 Nexus MCP 日志。服务器重启会使原会话失效，客户端需要重新 initialize，可关闭再开启该 MCP 连接。nexusMcp.logLevel=debug 额外显示诊断细节，常规扫描和心跳不会刷 INFO。

改了 UE 资产但磁盘未变化

属 NexusLink 里保存到磁盘的行为。见 usage-guide FAQ。

本地构建与发版

py scripts/build_vscode.py --version <version> --output release/

或 npm ci && npm run build 后 npx vsce package --no-dependencies。调试：npm run watch，F5 开 Extension Development Host。

提交前运行 npm run lint（TypeScript 类型检查）、npm run test:policy（会话策略、多实例转发及旧/新工具清单重连刷新回归）、npm run test:timing 和 npm run test:diagnostics（真实 HTTP 的会话并发、容量回收、主动结束及 INFO 日志与脱敏回归）。CI 将这些检查作为必过步骤。

GitHub Release 正文仅来自 CHANGELOG.md（py scripts/extract_release_notes.py --version X.Y.Z --verify）。tag：nexus-vscode-vX.Y.Z。商店详情页文案在 README.marketplace.md，不与本 README 混用。

源码：src/（入口 extension.ts）

License

MIT © byteyang