NexusLink

# Tool List **Language**: **English** · [English](README.en.md) MCP integration plugin based on Unreal Engine, exposing UE project context to AI tools through MCP protocol. > Supports UE 4.26 and above, including UE5 ## Architecture Overview ```mermaid flowchart TB subgraph NL["NexusLink Plugin"] Server["FNexusMcpServer<br/>HTTP + WebSocket"] Disp["FNexusMcpDispatcher<br/>SearchMode / MultiTool"] ToolReg["FNexusMcpToolRegistry<br/>REGISTER_MCP_TOOL"] Tool["FNexusMcpTool<br/>3 Meta Tools"] CapReg["FNexusCapabilityRegistry<br/>O(1) Lookup by Name"] Cap["FNexusCapability<br/>Atomic Work Unit"] Multi["FNexusMultiSectionCapability<br/>sections[] Batch"] end Server --> Stream["POST /stream<br/>MCP Streamable HTTP"] Server --> Status["GET /status<br/>Stateless Probe"] Server --> WS["WebSocket<br/>Rider / VSCode Long Connection"] Server --> Disp Disp --> ToolReg --> Tool Tool --> CapReg --> Cap --> Multi ``` ### Exposure Mode (ToolsListMode) | Mode | tools/list Return | initialize.instructions | Applicable Scenario | |---|---|---|---| | **SearchMode** (Default) | 3 Meta Tools | `InitializeInstructions.SearchMode.md` (Complete Routing Table) | AI On-demand `search_capabilities` Discovery | | **MultiTool** | All Enabled Capabilities (Each as Independent Tool) + `submit_feedback` | `InitializeInstructions.MultiTool.md` (Simplified Constraints) | Scenarios Requiring tools/list to Enumerate All Capabilities at Once | Mode Switching Path: Editor → Editor Preferences → Plugins → NexusLink → **Tool List Mode**. Capability changes automatically broadcast `notifications/tools/list_changed`. ## Installation and Enablement Download `nexus-mcp-unreal-<version>.zip` from [NexusLink Releases](https://github.com/bytepine/NexusLink/releases), or clone this repository to the project's `Plugins/Developer/NexusLink`. 1. Place the plugin in the project's `Plugins/Developer/NexusLink`, enable it in **Edit → Plugins → Developer → NexusLink** 2. After restarting the editor, open **Edit → Editor Preferences → Plugins → NexusLink** 3. Check **Enable MCP Server** ( **Disabled by Default** ) - after checking, immediately start HTTP (`POST /stream`) and WebSocket, and register instances for Rider/VSCode discovery; unchecking stops immediately, **no need to restart the editor** When unchecked: The toolbar does not display the port, IDE proxy scanning cannot find the instance, and AI directly connects to `http://127.0.0.1:45000/stream` without response. See the complete user guide in [docs/usage-guide.md](docs/usage-guide.md) §2. ## Using with IDE Proxy NexusLink is a **UE-side plugin** (providing HTTP `:45000` + WebSocket `:55000`). Daily development is recommended to be used with **IDE Proxy**, which is responsible for scanning UE instances, maintaining long connections, and switching between multiple Editor/PIE; AI clients only need to connect to the proxy's fixed port. ### Get IDE Proxy (Recommended to Install from Store) | IDE Proxy | Recommended Installation Method | Alternative | |----------|-------------|------| | **NexusRider** | [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/32499-nexus-mcp) — Rider **Settings → Plugins → Marketplace** search **Nexus MCP** | [GitHub Releases](https://github.com/bytepine/NexusRider/releases) download zip | | **NexusVSCode** | Extension store search **Nexus MCP** — [Open VSX](https://open-vsx.org/extension/byteyang/nexus-mcp-vscode) (Cursor / CodeBuddy / Windsurf, etc.) · [VS Marketplace](https://marketplace.visualstudio.com/items?itemName=byteyang.nexus-mcp-vscode) | [GitHub Releases](https://github.com/bytepine/NexusVSCode/releases) download `.vsix` | > **Prioritize installation from the store**, which can automatically update; Releases / local zip / `.vsix` are only for offline or development debugging. | Access Method | Endpoint | Applicable | |----------|------|------| | **Rider Proxy** | `http://127.0.0.1:6800/stream` | JetBrains Rider | | **VSCode/Cursor Proxy** | `http://127.0.0.1:6900/stream` | VSCode / Cursor / CodeBuddy / Windsurf | | **Direct Connection to UE** | `http://127.0.0.1:45000/stream` | Without IDE Plugin; must specify UE port | Source code and detailed instructions: [NexusRider](https://github.com/bytepine/NexusRider) · [NexusVSCode](https://github.com/bytepine/NexusVSCode) ### Recommended Collaboration Process 1. **UE Side**: Install and enable this plugin (see previous section), check **Enable MCP Server** 2. **IDE Side**: Install the corresponding proxy from the store and enable the master switch - Rider: Marketplace install **Nexus MCP** → `Settings → Tools → Nexus MCP → Enable Nexus MCP Server` (must **Open Project** afterwards) - VSCode/Cursor: Extension store install **Nexus MCP** → `Settings → nexusMcp.enabled = true` 3. **AI Client**: MCP configuration points to the proxy port (not UE's `45000`) ```json { "mcpServers": { "nexus-unreal": { "url": "http://127.0.0.1:6900/stream" } } } ``` Rider users change the URL to `http://127.0.0.1:6800/stream`. The proxy connects to UE via WebSocket, and the tool capabilities are consistent with direct connection. > Three-layer master switches must all be turned on: UE **Enable MCP Server** → IDE Proxy **Enable** → AI Client MCP Configuration. **Any layer turned off is unavailable.** > > Detailed installation, status bar, multi-instance switching see [docs/usage-guide.md](docs/usage-guide.md) §3 (Rider), §4 (VSCode/Cursor). ### Development Path **Path A — Pure Tool** (Lightweight no-section tool, directly rewrite `ExecuteImpl`) 1. Create `Private/Tools/<Module>/NexusMcpToolXxx.h/.cpp`, inherit `FNexusMcpTool` 2. Implement `GetName()` / `GetDescription()` / `ExecuteImpl()` 3. `.cpp` end `REGISTER_MCP_TOOL(FNexusMcpToolXxx)` **Path B — Capability** (Mainstream path, business logic encapsulated in Capability, can be called independently) 1. Create `Private/Capabilities/<Category>/NexusXxxCapability.h/.cpp`, inherit `FNexusCapability` (multi-section then inherit `FNexusMultiSectionCapability`) 2. Implement `BuildDefinition()` / `Execute()`, `.cpp` end `REGISTER_MCP_CAPABILITY(FNexusXxxCapability)` 3. Follow [Resources/CapabilitySpec.md](Resources/CapabilitySpec.md) (naming / four-section description / self-inspection checklist) 4. Capability directly calls through `call_capability` meta tool, or exposes as an independent MCP Tool in MultiTool mode --- ## Function List ### Meta Tools - [x] `search_capabilities` — Discover Capability by intention. Failure looks at `errorKind` (`not_found`/`disabled`/`disabled_only`); `capabilityName` exact query or `query` 1–2 words; nested `parameters[]` (e.g., `widgets[].action` enum) - [x] `call_capability` — Execute Capability; failure looks at `errorKind` (`disabled` do not retry). Old names (e.g., `create_blackboard`) automatically map to standard names. **Single** / **Batch** `calls[]` - [x] `submit_feedback` — Report tool/Capability usage friction, continuously improve discovery and schema. Trigger timing: retry ≥2 times without progress / cannot find suitable cap / schema field needs guessing / forced ≥3 serial calls ### Editor Tools - [x] `get_editor_info` — Get engine version, project name, platform, build configuration - [x] `get_editor_context` — Read-only editor context (`sections`: `selection_actors` / `selection_assets` / `content_browser_path`; editor World ≠ PIE) - [x] `search_console_variables` — Search console variable names by substring (read-only, including current value) - [x] `get_output_log` — Query UE output log buffer (classification/detail level/text filtering + offset/limit pagination, last 2000 lines) - [x] `set_log_capture_filter` — Dynamically set log capture whitelist (pass empty array=capture all, pass list=capture specified classification) - [x] `save_asset` — Persistently save assets (`assetPaths` batch); after `SaveDirtyPackage` landing, Live Coding returns `deferred=true` - [x] `delete_asset` — Delete a single asset package - [x] `rename_asset` — Rename/move assets (engine automatically redirects references) - [x] `duplicate_asset` — Copy assets to a new path (any type, source asset remains unchanged) - [x] `export_asset` — Export assets to disk files (Fbx/Stl, etc., by type) - [x] `reimport_asset` — Reimport assets from source files - [x] `control_pie` — Control PIE (start / stop / status) - [x] `exec_command` — Execute UE console commands and capture output - [x] `get_asset_refs` — Query asset dependencies (dependencies) or referencers (referencers), support recursive/filtering/pagination - [x] `get_gameplay_tags` — Query Gameplay Tags level tree (section=hierarchy), runtime Actor properties (section=actor), asset properties (section=asset), query referenced assets by Tag (section=referencers, need `tag`) - [x] `capture_viewport` — Capture the editor window (`editor` / `editor_desktop` entire window), panel area or PIE viewport (PNG/JPG, support cutting by Actor bounding box, by UMG Widget area, multi-view shooting); screenshot stored in `Saved/NexusCaptures/`, automatically retain the last 20 ### General Asset Tools - [x] `search_asset` — Search project assets (assetType / pathFilter / nameFilter / query, pagination) - [x] `get_asset_refs` — Query asset dependencies/references (see Editor Tools section) - [x] `get_asset_lua_binding` — Query blueprint UnLua binding (return bound/moduleName/filePath; if `bound=false` stop, do not guess path) - [x] `rename_asset` / `duplicate_asset` / `delete_asset` / `compile_blueprint` (`save_asset` see Editor Tools section) - [x] `get_asset_texture` — Read Texture2D (size, compression, sRGB, LOD) - [x] `get_asset_static_mesh` — Read StaticMesh (LOD, material slot, collision summary) - [x] `get_asset_anim_sequence` — Read AnimSequence (duration, frame rate, frame count, bone reference, notifies list) - [x] `get_asset_skeletal_mesh` — Read SkeletalMesh (LOD, material slot, bone, PhysicsAsset) - [x] `get_asset_skeleton` — Read Skeleton (bone tree pagination, Socket summary) - [x] `get_asset_sound_wave` — Read SoundWave (duration, sample rate, channel) - [x] `get_asset_sound_cue` — Read SoundCue (duration, SoundNode summary) - [x] `get_asset_niagara_system` — Read NiagaraSystem (emitter list; UE5+ user parameter summary; need `WITH_NIAGARA=1`) - [x] `get_asset_level` — Read-only check level (UWorld package): `sections` `actors` (pagination+filtering) / `settings` (WorldSettings summary); `editor_only` - [x] `manage_asset_texture` — Edit Texture2D properties (compression, sRGB, LODGroup, etc.) - [x] `manage_asset_static_mesh` — Edit StaticMesh material slot and properties - [x] `manage_asset_skeletal_mesh` — Edit SkeletalMesh material slot and properties - [x] `manage_asset_skeleton` — Manage Skeleton Socket (add/delete/modify) - [x] `manage_asset_anim_sequence` — Edit AnimSequence (`add_notify` / `remove_notify` / `set_frame_rate` / `set_root_motion`) - [x] `manage_asset_sound_wave` — Edit SoundWave properties (`action=set_property`) - [x] `manage_asset_sound_cue` — Edit SoundCue (`set_property` / `add_node` / `remove_node` / `connect_nodes`) - [x] `manage_asset_niagara_system` — Edit Niagara system (`set_property` / `set_user_parameter`; `WITH_NIAGARA=1`) - [x] `manage_asset_level` — Edit level (`set_property` modify WorldSettings; `spawn_actor` / `remove_actor` / `set_actor_property` modify disk Actor; `editor_only`) ### Blueprint Tools - [x] `create_asset_blueprint` — Create a new blueprint asset (can specify parent class) - [x] `get_asset_blueprint` — Read blueprint details (sections: variables / functions / components / defaults / graphOverview / graphs / all); automatically detect UnLua binding return `luaModule` + `luaFilePath` - [x] `manage_asset_blueprint` — Full-featured batch editing of blueprints: variable CRUD (add/remove_variable), node operations (add/remove/set_node), connection operations (connect/disconnect), SCS components (add/remove_component, Actor BP dedicated), CDO default value (set_defaults) ### Animation Asset Tools - [x] `create_asset_anim_blueprint` — Create AnimBlueprint asset (associated with specified Skeleton, automatically compiled) - [x] `get_asset_anim_blueprint` — Read ABP structure (sections: variables / statemachines / defaults / graphOverview) - [x] `manage_asset_anim_blueprint` — Manage state machine (add/remove state_machine / state / transition) - [x] `create_asset_anim_montage` — Create AnimMontage asset (associated with specified Skeleton) - [x] `get_asset_anim_montage` — Read AnimMontage (Slot/Segment list, Section list) - [x] `manage_asset_anim_montage` — Manage AnimMontage Segment (add/remove_segment) and Section (add/remove_section) ### Material Tools - [x] `create_asset_material` — Create Material or MaterialInstance (can specify materialDomain / parentMaterial) - [x] `get_asset_material` — Read material parameters, node graph (sections: parameters / graph / all) - [x] `manage_asset_material` — Material batch editing entry (actions: set_param / add_node / remove_node / set_node / recompile; Texture node supports defaultValue binding asset path and deriving SamplerType) ### Struct Tools - [x] `create_asset_struct` — Create new UserDefinedStruct asset - [x] `get_asset_struct` — Read Struct field list (name/type/defaultValue) - [x] `manage_asset_struct_field` — Struct field batch management (add/remove/set; supports renaming/type change/default value change) ### Data Asset Tools (DataAsset / DataTable) - [x] `create_asset_data_asset` — Create new DataAsset asset (need to specify parent class) - [x] `create_asset_data_table` — Create new DataTable asset (need to specify row struct class name) - [x] `get_asset_data_asset` — Read DataAsset properties - [x] `get_asset_data_table` — Read DataTable row data (supports rowNames filtering, pagination) - [x] `manage_asset_data_asset` — Batch modify DataAsset fields (`action`: `set` / `reset`) - [x] `manage_asset_data_table` — DataTable row batch add/delete/modify (action: add / remove / set) ### Widget Tools - [x] `create_asset_user_widget` — Create new WidgetBlueprint asset (can specify parent class) - [x] `get_asset_user_widget` — Read WidgetBlueprint control tree (`widgets` include `layout`) + UMG animation list (`sections=widgets|animations`) - [x] `manage_asset_user_widget` — Control tree batch management (`add` / `remove` / `set_slot` / `set_property`; design-time operation) ### Lua Runtime Tools (require UnLua plugin) - [x] `eval_runtime_lua` — Execute Lua code snippet (need PIE/Game + UnLua) - [x] `dofile_runtime_lua` — Execute Lua file (need PIE/Game + UnLua) - [x] `set_runtime_lua` — Set Lua global variable - [x] `gc_runtime_lua` — Execute Lua garbage collection - [x] `hotreload_runtime_lua` — Hot reload Lua module - [x] `get_runtime_lua_env` — Read Lua global environment table overview - [x] `get_runtime_lua_value` — Read Lua variable value by path - [x] `get_runtime_lua_loaded` — List loaded Lua modules - [x] `get_runtime_lua_stack` — Read Lua call stack - [x] `get_runtime_lua_metatable` — Check Lua object metatable - [x] `get_runtime_lua_object` — Read runtime Actor's Lua instance data - [x] `get_runtime_lua_memory` — Lua memory statistics - [x] `get_asset_lua_binding` — Query blueprint's UnLua binding (see General Asset Tools) ### Runtime Tools (require PIE/Game) - [x] `list_runtime_actors` — List current World actors (classFilter / nameFilter / tagFilter + pagination) - [x] `spawn_runtime_actor` — Batch generate actors (`spawns:[{blueprintPath?|className?,location?,rotation?}]`) - [x] `destroy_runtime_actor` — Destroy specified actor - [x] `get_runtime_actor_property` — Read actor properties (sections: components / attach_hierarchy / all; or diagnose preset; supports dot notation path + container subscript; FUNC call) - [x] `set_runtime_actor_property` — Batch write actor properties (take effect immediately) - [x] `diff_runtime_actors` — Compare actor property differences (pairwise comparison or batch benchmark mode) - [x] `get_runtime_actor_animation` — Query actor AnimInstance runtime state (sections: state / slots / variables) - [x] `interact_runtime_actor_animation` — PIE montage play/stop (`action=play_montage|stop_montage|stop_all`) and AnimInstance variable write (`set_anim_variable`) - [x] `get_runtime_actor_behavior_tree` — Read actor's AI runtime behavior tree execution state (section=runtime) - [x] `interact_runtime_actor_behavior_tree` — Runtime set blackboard key, restart/stop behavior tree - [x] `list_runtime_widgets` — List all active UserWidgets at runtime - [x] `spawn_runtime_widget` — Create UserWidget in PIE/Game and add to viewport - [x] `destroy_runtime_widget` — Remove and destroy runtime UMG panel from viewport - [x] `interact_runtime_widget` — Operate runtime controls (click / check / toggle / set / read; supports Button/CheckBox/Slider/TextBlock/EditableText/ProgressBar) - [x] `get_runtime_widget_property` — Read runtime Widget properties; without `propertyPath`, includes `layout` - [x] `set_runtime_widget_property` — Write runtime Widget properties - [x] `get_runtime_slate_widget` — Get Slate widget information by Widget Reflector hexadecimal address (includes `layout`: anchor, AutoWrapText, etc.) ### AI Tools (Behavior Tree / Blackboard) - [x] `create_asset_behavior_tree` — Create BehaviorTree asset (optional to create associated BlackboardData) - [x] `create_asset_blackboard` — Independently create empty BlackboardData asset - [x] `get_asset_behavior_tree` — Read behavior tree node structure, path index, and decorator/service properties - [x] `get_asset_blackboard` — Read Blackboard Keys - [x] `manage_asset_behavior_tree` — Manage behavior tree node tree (`set_root` / `add_node` / `remove_node` / `move_node` / decorator and service / `set_property`; `add_node` supports `childIndex`) - [x] `manage_asset_blackboard` — Batch add/delete/rename Blackboard Key (supports bool/float/int/enum/string/name/vector/rotator/object/class) - [x] `get_runtime_actor_behavior_tree` — Runtime AI execution state (see Runtime section) ### GAS Tools (Gameplay Ability System, registered when `WITH_GAS=1`) > Need to enable `GameplayAbilities` plugin in project `.uproject`. Graph node editing still uses `manage_asset_blueprint`. **Gameplay Ability** - [x] `create_asset_gameplay_ability` — Create GameplayAbility Blueprint (can specify parent class) - [x] `get_asset_gameplay_ability` — Read GA CDO (sections: metadata / tags / costs / graphOverview) - [x] `manage_asset_gameplay_ability` — Modify GA CDO: `set_tags` (Tag container + mode) / `set_policy` (instantiation/network policy) / `set_cost_cooldown` (Cost/Cooldown GE binding) **Gameplay Effect** - [x] `create_asset_gameplay_effect` — Create GameplayEffect Blueprint - [x] `get_asset_gameplay_effect` — Read GE CDO (sections: policy / modifiers / tags / cues) - [x] `manage_asset_gameplay_effect` — Batch modify GE: `set_policy` (Duration/Period) / `set_tags` / `add_modifier` / `remove_modifier` / `set_modifier` **AttributeSet** - [x] `create_asset_attribute_set` — Create AttributeSet Blueprint - [x] `get_asset_attribute_set` — Read AttributeSet CDO all `FGameplayAttributeData` properties (name / baseValue / currentValue) - [x] `manage_asset_attribute_set` — Batch `set`/`reset` AttributeSet CDO property default values **Runtime** - [x] `get_runtime_actor_ability_system` — PIE runtime read Actor ASC snapshot (sections: abilities / effects / attributes; read-only) - [x] `interact_runtime_actor_ability_system` — PIE cast/cancel Ability, apply/remove GE, modify Attribute base value --- ## Server Framework Features - [x] MCP Streamable HTTP (`POST /stream`), per-session isolation (`Mcp-Session-Id`), multi-client concurrent safety - [x] `GET /status` — Stateless probe endpoint (project name, engine version, WS port, `netRole`) - [x] WebSocket server (default 55000), for Rider / VSCode agent long connection; `nexus/instructions` returns `InitializeInstructions.*.md` by ToolsListMode; `nexus/proxy_config` returns `ProxyConfig.json` (connection tool description, initialize prefix, error text, for agent dynamic pull) - [x] **SearchMode** (default): tools/list exposes only 3 meta-tools, AI discovers capabilities on demand by `search_capabilities` - [x] **MultiTool**: tools/list exposes all enabled Capability (each as independent MCP Tool) + `submit_feedback`; without `search_capabilities` / `call_capability` - [x] Capability change or mode switch broadcasts `notifications/tools/list_changed` - [x] **Enable MCP Server** master switch (default off): Editor Preferences → Plugins → NexusLink → Server; checked to start HTTP/WebSocket and register instance immediately - [x] Port automatic allocation, automatic switch on conflict; instance registration mechanism supports zero-scan discovery (`{PID}.json` write to temporary directory) - [x] **Enable/Disable by Capability** (`IsCapabilityEnabled`): Editor Preferences → Plugins → NexusLink → Capabilities; supports category level / single-level checkbox - [x] **Default response value compression** (`FNexusResponseCompactorUtils`): recursively scan object array fields, popular values automatically extracted as `<field>_defaults`, reduce response volume; can disable globally by setting panel `response default value compression` --- ## Related Documents - [docs/tool-reference.md](docs/tool-reference.md) — Capability complete parameter manual (script-generated, update by `py scripts/build_tool_reference.py`) - [Resources/CapabilitySpec.md](Resources/CapabilitySpec.md) — Capability metadata specification (naming / description four-section / self-inspection checklist) - [Resources/InitializeInstructions.SearchMode.md](Resources/InitializeInstructions.SearchMode.md) — AI handshake SearchMode workflow description ( **First Action** / Tool Model / Intent→Capability routing / Hard Rules) - [Resources/InitializeInstructions.MultiTool.md](Resources/InitializeInstructions.MultiTool.md) — MultiTool mode simplified constraints - [Resources/AIRules.mdc](Resources/AIRules.mdc) — IDE side AI workflow Rule template (copy to game project `.cursor/rules/`, see [usage-guide §2.8](docs/usage-guide.md)) - [docs/testing.md](docs/testing.md) — pytest E2E regression test suite - [CHANGELOG.md](CHANGELOG.md) — Version change record ## Test Two-layer automation framework: - **L1 C++ Automation** (`Source/NexusLinkTests/`): pure tool function + plugin loading + Capability registration table smoke + `FNexusResponseCompactorUtils` full assertion. Need to trigger manually by UEEditor-Cmd: ```bash UEEditor-Cmd YourProject.uproject -ExecCmds="Automation RunTests NexusLink.; Quit" -unattended -nullrhi -NoSound -NoSplash ``` - **L2 pytest E2E** (maintained in host game project `Tests/` directory): E2E regression test for all Capability by `call_capability` (SearchMode call, not dependent on MultiTool): ```powershell pip install -r Tests/requirements.txt python Script/run_e2e.py --ue-url http://127.0.0.1:45000/stream ``` Report output to `Saved/Logs/TestReport.xml`. See details in [docs/testing.md](docs/testing.md). **When adding new Capability**: add at least one happy-path test case in host game project `Tests/test_*.py` corresponding stage file, using `client.call_capability("cap_name", {...})` call form. ## Local Packaging ```bash py scripts/build_unreal.py --version <version> --output release/ ``` Product: `release/nexus-mcp-unreal-<version>.zip`, extract to UE project `Plugins/Developer/`. ### Release (Maintainer) GitHub Release **only source** is `CHANGELOG.md` `[X.Y.Z]` paragraph (CI extracts by `scripts/extract_release_notes.py --verify`). Prohibit web handwritten Release description or `gh release create`. 1. Archive `[Unreleased]` → `[X.Y.Z] - YYYY-MM-DD`, update `VERSION` 2. `py scripts/extract_release_notes.py --version X.Y.Z --verify` (preview stdout, confirm correct) 3. `git commit` → `git tag -a nexus-link-vX.Y.Z` → `git push origin HEAD` + `git push origin nexus-link-vX.Y.Z` Push tag, `.github/workflows/release.yml` packages `nexus-mcp-unreal-<ver>.zip` and publishes Release. ## License [MIT](LICENSE) © byteyang > When adding/modifying Capability, synchronize this file's function list and run `py scripts/build_tool_reference.py` to regenerate `docs/tool-reference.md`.