hx-multianim-mcp

An MCP server that connects Claude (or any MCP client) to a running hx-multianim application via its DevBridge.

Call connect first. All other tools return a not_connected error until connect succeeds. The DevBridge port is printed to game stdout as [DevBridge] Listening on port N (default 9001).

Tools

Connection & health

Tool	Description
connect	Connect to a game instance on a specific port/host. Must be called first.
ping	Lightweight health check — uptime and port
performance	FPS, draw calls, triangle count, object count, scene dimensions

Scene inspection

Tool	Description
list_screens	Registered screens with active/failed status
list_builders	Loaded .manim builders and their parameter definitions
scene_graph	Recursive scene tree dump (depth)
inspect_element	Position, size, visibility, text of a named element
inspect_programmable	Deep inspection of a live programmable (params, slots, refs, elements)
find_element_at	Hit-test scene coords, front-to-back list of objects
get_screen_state	Screen manager state: mode, transitions, pause, counts
get_tween_state	All active tweens with target, duration, progress
list_interactives	Interactive hit-test regions with IDs and bounds
list_slots	Swappable container slots of a programmable
list_active_programmables	Live incremental-mode programmables with current state
list_resources	Loaded sprites, fonts, .manim, .anim files
list_fonts	Registered font names
list_atlases	Loaded sprite atlases and tile/sprite names
coordinate_transform	Convert between scene and element-local coordinates
check_overlaps	Detect overlapping interactives/visuals to find layout bugs

Screenshots

Tool	Description
screenshot	Capture current frame as PNG (optional width/height scale-down)

State manipulation

Tool	Description
set_parameter	Modify a programmable parameter at runtime (incremental mode)
get_parameters	Current parameter values and definitions for a programmable
set_visibility	Toggle element visibility
reload	Hot-reload .manim files (specific file or all changed)
eval_manim	Parse and validate .manim snippets

Game control

Tool	Description
pause	Pause/resume the game loop
step	Advance N frames while paused (max 100)
wait_for_idle	Check if no tweens/transitions are active
quit	Cleanly shut down the game

Input injection

Tool	Description
send_event	Inject a single mouse/keyboard/wheel event
send_events	Sequence of events with frame steps (drag, scrub, multi-step gestures)
click_button	Click an interactive by ID, bypassing hit testing

Diagnostics

Tool	Description
get_traces	Recent trace() output (ring buffer)
get_errors	Accumulated runtime errors/exceptions
get_debugger_hits	Poll DevBridge.debugger(data, pause?) breakpoint hits (cursor-based)

Breakpoints from game code

Call DevBridge.debugger(data, pause) anywhere in your game code to capture a data snapshot (with auto-captured file/line/method):

screenManager.devBridge.debugger({hp: unit.hp, target: unit.target?.name});     // pauses by default
screenManager.devBridge.debugger({fps: hxd.Timer.fps()}, false);                 // push-only, no pause

Hits are delivered two ways:

• Push — real-time debugger SSE events surfaced as warning-level MCP log notifications.
• Poll — get_debugger_hits tool with since_id cursor (in case the agent missed the push).

If pause=true, resume with pause({paused:false}).

Usage

Claude Code

// .mcp.json
{
  "mcpServers": {
    "hx-multianim": {
      "command": "npx",
      "args": ["-y", "@bh213/hx-multianim-mcp"]
    }
  }
}

Environment variables

Variable	Default	Description
HX_DEV_PORT	9001	DevBridge port
HX_DEV_HOST	localhost	DevBridge host

License

BSD-3-Clause