nexus-vscode — VSCode / Cursor MCP 代理扩展

语言 / Language: 简体中文 · English

VSCode / Cursor 端 MCP 代理：本地 HTTP 服务器（默认 :6900），发现 UE 实例，经 WebSocket 把 AI 工具调用转发给 NexusLink。蓝图、资产、PIE 等能力由 UE 侧提供，本扩展不实现游戏逻辑。

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

依赖

Related MCP server: UE-Editor-MCPServer

安装与使用

须开总开关：扩展在启动后激活（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. 状态栏与命令

状态栏显示已连接项目名 / 未连接，点击切换实例或复制 MCP 配置。

唯一实例自动连接；多实例优先 netRole=Editor。断线保留工具列表缓存；耐久读可返回带 _proxy.degraded 的上次快照。会话层契约见 proxy-session.md。

复制 mcp.json 与鉴权

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

复制 MCP JSON

1. Ctrl+Shift+P → Nexus MCP: 复制 MCP 客户端配置（mcp.json）（未启用代理也能用；或点状态栏选同一项）

2. 选传输协议（推荐 Streamable HTTP），再选客户端（Cursor / CodeBuddy）；开 LAN 且多网卡时先选写入 url 的 IP

3. 粘贴到对应 AI 客户端（一次只复制一份）：

   • Cursor：~/.cursor/mcp.json → mcpServers 下的 nexus-unreal 段

   • CodeBuddy / Windsurf：自定义 MCP 的 Nexus 段

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

粘贴后须将 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。

Cursor 完整文件示例：

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

已连接时 tools/list 合并 UE 工具。多实例并发可在 arguments 中带 targetPort。

常见问题

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

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

工具列表不刷新

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

查看日志

Help → Toggle Developer Tools → Console，搜索 Nexus MCP。

改了 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。

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