Back to Details

mcp-plugin

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

UE Audio MCP Plugin — TCP Control

UE Audio MCP插件 — TCP控制

Drive the C++ TCP server inside Unreal Editor. All commands use 4-byte big-endian length prefix + UTF-8 JSON on 
127.0.0.1:9877
.
驱动Unreal Editor内置的C++ TCP服务器。所有命令在
127.0.0.1:9877
端口使用4字节大端长度前缀 + UTF-8格式的JSON。

Connection

连接

python
undefined
python
undefined

Python SDK

Python SDK

from ue_audio_mcp.ue5_connection import get_ue5_connection conn = get_ue5_connection() resp = conn.send_command({"action": "ping"})
from ue_audio_mcp.ue5_connection import get_ue5_connection conn = get_ue5_connection() resp = conn.send_command({"action": "ping"})

Raw TCP

Raw TCP

python3 -c " import socket, struct, json s = socket.socket(); s.settimeout(5); s.connect(('127.0.0.1', 9877)) p = json.dumps({'action':'ping'}).encode() s.sendall(struct.pack('>I', len(p)) + p) r = s.recv(4); l = struct.unpack('>I', r)[0]; print(json.loads(s.recv(l))) "
undefined
python3 -c " import socket, struct, json s = socket.socket(); s.settimeout(5); s.connect(('127.0.0.1', 9877)) p = json.dumps({'action':'ping'}).encode() s.sendall(struct.pack('>I', len(p)) + p) r = s.recv(4); l = struct.unpack('>I', r)[0]; print(json.loads(s.recv(l))) "
undefined

All 24 Commands

全部24条命令

System

系统类

CommandParamsReturns
ping
—engine, version, project, features[]
命令参数返回值
ping
—engine, version, project, features[]

Builder Lifecycle

构建器生命周期

CommandParamsReturns
create_builder
asset_type (Source/Patch/Preset), nameasset_type, name
add_interface
interface—
build_to_asset
name, path (/Game/...)name, path
命令参数返回值
create_builder
asset_type (Source/Patch/Preset), nameasset_type, name
add_interface
interface—
build_to_asset
name, path (/Game/...)name, path

Graph I/O

图谱输入输出

CommandParamsReturns
add_graph_input
name, type, default?name, type
add_graph_output
name, typename, type
命令参数返回值
add_graph_input
name, type, default?name, type
add_graph_output
name, typename, type

Nodes

节点操作

CommandParamsReturns
add_node
id, node_type, position? [x,y]id, node_type
set_default
node_id, input, valuenode_id, input
connect
from_node, from_pin, to_node, to_pinall four
__graph__
= sentinel node ID for graph boundary connections.
命令参数返回值
add_node
id, node_type, position? [x,y]id, node_type
set_default
node_id, input, valuenode_id, input
connect
from_node, from_pin, to_node, to_pinall four
__graph__
= 图谱边界连接的标记节点ID。

Audition

试听控制

CommandParamsReturns
audition
name?—
stop_audition
——
open_in_editor
——
命令参数返回值
audition
name?—
stop_audition
——
open_in_editor
——

Variables (UE 5.7+)

变量操作（UE 5.7+）

CommandParamsReturns
add_graph_variable
name, type, default?name, type
add_variable_get_node
id, variable_name, delayed?id, variable_name
add_variable_set_node
id, variable_nameid, variable_name
命令参数返回值
add_graph_variable
name, type, default?name, type
add_variable_get_node
id, variable_name, delayed?id, variable_name
add_variable_set_node
id, variable_nameid, variable_name

Presets

预设转换

CommandParamsReturns
convert_to_preset
referenced_asset (/Game/...)referenced_asset
convert_from_preset
——
命令参数返回值
convert_to_preset
referenced_asset (/Game/...)referenced_asset
convert_from_preset
——

Query

查询操作

CommandParamsReturns
list_node_classes
filter?, limit? (200)nodes[], total, shown
get_node_locations
asset_pathnodes[], edges[]
get_graph_input_names
—names[], count
set_live_updates
enabled (bool)enabled
命令参数返回值
list_node_classes
filter?, limit? (200)nodes[], total, shown
get_node_locations
asset_pathnodes[], edges[]
get_graph_input_names
—names[], count
set_live_updates
enabled (bool)enabled

Blueprint & Assets

蓝图与资源

CommandParamsReturns
call_function
function, args?function, return_value?
list_assets
class_filter?, path?, limit?assets[], total, shown
scan_blueprint
asset_path, audio_only?, include_pins?graphs[], audio_summary
Allowlisted functions: PlaySound2D, PlaySoundAtLocation, SpawnSoundAtLocation, SpawnSound2D, SetSoundMixClassOverride, ClearSoundMixClassOverride, PushSoundMixModifier, PopSoundMixModifier, SetGlobalPitchModulation, SetGlobalListenerFocusParameters, PlayDialogue2D, PlayDialogueAtLocation, SpawnDialogue2D, SpawnDialogueAtLocation, GetPlayerCameraManager, GetPlayerController, GetPlayerPawn.
class_filter values: Blueprint, WidgetBlueprint, AnimBlueprint, MetaSoundSource, MetaSoundPatch, SoundWave, SoundCue, SoundAttenuation, SoundClass, SoundConcurrency, SoundMix, ReverbEffect.
命令参数返回值
call_function
function, args?function, return_value?
list_assets
class_filter?, path?, limit?assets[], total, shown
scan_blueprint
asset_path, audio_only?, include_pins?graphs[], audio_summary
允许调用的函数列表：PlaySound2D, PlaySoundAtLocation, SpawnSoundAtLocation, SpawnSound2D, SetSoundMixClassOverride, ClearSoundMixClassOverride, PushSoundMixModifier, PopSoundMixModifier, SetGlobalPitchModulation, SetGlobalListenerFocusParameters, PlayDialogue2D, PlayDialogueAtLocation, SpawnDialogue2D, SpawnDialogueAtLocation, GetPlayerCameraManager, GetPlayerController, GetPlayerPawn.
class_filter可选值：Blueprint, WidgetBlueprint, AnimBlueprint, MetaSoundSource, MetaSoundPatch, SoundWave, SoundCue, SoundAttenuation, SoundClass, SoundConcurrency, SoundMix, ReverbEffect.

Key Pin Names

关键引脚名称

  • Sine/Saw/Square/Triangle: IN: Frequency, Phase Offset, Glide, Bias; OUT: Audio
  • AD Envelope: IN: Trigger, Attack Time, Decay Time; OUT: Out Envelope
  • ADSR Envelope: IN: Trigger Attack, Trigger Release, Attack Time, Decay Time, Sustain Level, Release Time; OUT: Out Envelope
  • Biquad Filter: IN: In, Cutoff Frequency, Bandwidth, Filter Type; OUT: Out
  • Wave Player: IN: Play, Stop, Wave Asset, Start Time, Loop, Pitch Shift; OUT: Out Audio, On Finished
  • Multiply/Add (Audio): IN: Primary Operand, Operand; OUT: Out
  • Map Range: IN: Value, In Range A, In Range B, Out Range A, Out Range B, Clamped; OUT: Out
Full pin reference: 
scripts/ms_node_specs.json
(93 nodes, 464 pins)
  • Sine/Saw/Square/Triangle：输入：Frequency, Phase Offset, Glide, Bias；输出：Audio
  • AD Envelope：输入：Trigger, Attack Time, Decay Time；输出：Out Envelope
  • ADSR Envelope：输入：Trigger Attack, Trigger Release, Attack Time, Decay Time, Sustain Level, Release Time；输出：Out Envelope
  • Biquad Filter：输入：In, Cutoff Frequency, Bandwidth, Filter Type；输出：Out
  • Wave Player：输入：Play, Stop, Wave Asset, Start Time, Loop, Pitch Shift；输出：Out Audio, On Finished
  • Multiply/Add (Audio)：输入：Primary Operand, Operand；输出：Out
  • Map Range：输入：Value, In Range A, In Range B, Out Range A, Out Range B, Clamped；输出：Out
完整引脚参考：
scripts/ms_node_specs.json
（93个节点，464个引脚）

Example Workflows

示例工作流

Simple Sine → Output

简单正弦波 → 输出

json
{"action":"create_builder", "asset_type":"Source", "name":"MySine"}
{"action":"add_interface", "interface":"MetaSound"}
{"action":"add_graph_output", "name":"Out Mono", "type":"Audio"}
{"action":"add_node", "id":"osc", "node_type":"UE::Sine::Audio"}
{"action":"set_default", "node_id":"osc", "input":"Frequency", "value":440}
{"action":"connect", "from_node":"osc", "from_pin":"Audio", "to_node":"__graph__", "to_pin":"Out Mono"}
{"action":"build_to_asset", "name":"MySine", "path":"/Game/Audio/MCP"}
json
{"action":"create_builder", "asset_type":"Source", "name":"MySine"}
{"action":"add_interface", "interface":"MetaSound"}
{"action":"add_graph_output", "name":"Out Mono", "type":"Audio"}
{"action":"add_node", "id":"osc", "node_type":"UE::Sine::Audio"}
{"action":"set_default", "node_id":"osc", "input":"Frequency", "value":440}
{"action":"connect", "from_node":"osc", "from_pin":"Audio", "to_node":"__graph__", "to_pin":"Out Mono"}
{"action":"build_to_asset", "name":"MySine", "path":"/Game/Audio/MCP"}

Filtered Synth with Envelope

带包络的滤波合成器

json
{"action":"create_builder", "asset_type":"Source", "name":"FilteredSynth"}
{"action":"add_interface", "interface":"MetaSound"}
{"action":"add_graph_output", "name":"Out Mono", "type":"Audio"}
{"action":"add_graph_input", "name":"Cutoff", "type":"Float", "default":"2000.0"}
{"action":"add_node", "id":"osc", "node_type":"UE::Saw::Audio"}
{"action":"add_node", "id":"filt", "node_type":"UE::Biquad Filter::Audio"}
{"action":"add_node", "id":"env", "node_type":"AD Envelope"}
{"action":"add_node", "id":"mul", "node_type":"UE::Multiply::Audio"}
{"action":"connect", "from_node":"osc", "from_pin":"Audio", "to_node":"filt", "to_pin":"In"}
{"action":"connect", "from_node":"__graph__", "from_pin":"Cutoff", "to_node":"filt", "to_pin":"Cutoff Frequency"}
{"action":"connect", "from_node":"filt", "from_pin":"Out", "to_node":"mul", "to_pin":"Primary Operand"}
{"action":"connect", "from_node":"env", "from_pin":"Out Envelope", "to_node":"mul", "to_pin":"Operand"}
{"action":"connect", "from_node":"mul", "from_pin":"Out", "to_node":"__graph__", "to_pin":"Out Mono"}
{"action":"build_to_asset", "name":"FilteredSynth", "path":"/Game/Audio/MCP"}
json
{"action":"create_builder", "asset_type":"Source", "name":"FilteredSynth"}
{"action":"add_interface", "interface":"MetaSound"}
{"action":"add_graph_output", "name":"Out Mono", "type":"Audio"}
{"action":"add_graph_input", "name":"Cutoff", "type":"Float", "default":"2000.0"}
{"action":"add_node", "id":"osc", "node_type":"UE::Saw::Audio"}
{"action":"add_node", "id":"filt", "node_type":"UE::Biquad Filter::Audio"}
{"action":"add_node", "id":"env", "node_type":"AD Envelope"}
{"action":"add_node", "id":"mul", "node_type":"UE::Multiply::Audio"}
{"action":"connect", "from_node":"osc", "from_pin":"Audio", "to_node":"filt", "to_pin":"In"}
{"action":"connect", "from_node":"__graph__", "from_pin":"Cutoff", "to_node":"filt", "to_pin":"Cutoff Frequency"}
{"action":"connect", "from_node":"filt", "from_pin":"Out", "to_node":"mul", "to_pin":"Primary Operand"}
{"action":"connect", "from_node":"env", "from_pin":"Out Envelope", "to_node":"mul", "to_pin":"Operand"}
{"action":"connect", "from_node":"mul", "from_pin":"Out", "to_node":"__graph__", "to_pin":"Out Mono"}
{"action":"build_to_asset", "name":"FilteredSynth", "path":"/Game/Audio/MCP"}

Project Scan

项目扫描

json
{"action":"list_assets", "class_filter":"Blueprint"}
{"action":"scan_blueprint", "asset_path":"/Game/BP_Player", "audio_only":true}
{"action":"list_assets", "class_filter":"MetaSoundSource"}
{"action":"get_node_locations", "asset_path":"/Game/Audio/MS_Gunshot"}
Or batch: 
python scripts/scan_project.py --full-export --import-db --rebuild-embeddings
json
{"action":"list_assets", "class_filter":"Blueprint"}
{"action":"scan_blueprint", "asset_path":"/Game/BP_Player", "audio_only":true}
{"action":"list_assets", "class_filter":"MetaSoundSource"}
{"action":"get_node_locations", "asset_path":"/Game/Audio/MS_Gunshot"}
或批量执行：
python scripts/scan_project.py --full-export --import-db --rebuild-embeddings

Gotchas

注意事项

  • Must call 
    create_builder
    before any node/connection ops
  • __graph__
    is NOT a real node — it's the boundary sentinel
  • Path must start with 
    /Game/
    or 
    /Engine/
    , no 
    ..
  • Audio vs Float: cannot cross-connect — use correct node variant
  • TCP drops after ~17 rapid commands — use reconnect with progressive delay
  • Builder state is global — only one active builder at a time
  • list_node_classes
    discovers real class names — the 65-name registry may miss some
  • 执行任何节点/连接操作前必须调用
    create_builder
  • __graph__
    并非真实节点，而是边界标记
  • 路径必须以
    /Game/
    或
    /Engine/
    开头，不能包含
    ..
  • 音频与浮点类型不能跨类型连接，请使用正确的节点变体
  • 连续发送约17条命令后TCP连接会断开，请使用带渐进延迟的重连机制
  • 构建器状态为全局唯一，同一时间只能存在一个活跃构建器
  • list_node_classes
    会获取真实类名，65个名称的注册表可能会遗漏部分节点

Source Files

源文件

  • C++ commands: 
    ue5_plugin/UEAudioMCP/Source/UEAudioMCP/Private/Commands/
  • TCP server: 
    ue5_plugin/UEAudioMCP/Source/UEAudioMCP/Private/AudioMCPTCPServer.cpp
  • Python tools: 
    src/ue_audio_mcp/tools/
  • Node registry: 
    src/ue_audio_mcp/knowledge/metasound_nodes.py
    (144 nodes, 798 pins)
$ARGUMENTS
  • C++命令实现：
    ue5_plugin/UEAudioMCP/Source/UEAudioMCP/Private/Commands/
  • TCP服务器：
    ue5_plugin/UEAudioMCP/Source/UEAudioMCP/Private/AudioMCPTCPServer.cpp
  • Python工具：
    src/ue_audio_mcp/tools/
  • 节点注册表：
    src/ue_audio_mcp/knowledge/metasound_nodes.py
    （144个节点，798个引脚）
$ARGUMENTS