valkor-ai MCP Driver — Runtime Debug & Inspection
$ARGUMENTS
When to use this skill
MCP is the upgrade path when faster tools hit a wall. The fast loop handles most issues:
| Problem type | Fast path (no MCP) |
|---|---|
| Syntax / parse error | headless-build |
| Unit test failure | gdunit-driver |
| API lookup | godot-api |
Escalate to MCP when:
- Compile-pass / runtime-fail — headless-build says OK but something is wrong when the game actually runs
- Test-pass / behavior-wrong — unit tests pass but the game does not behave correctly in practice
- Visual issue — screen is black, sprites missing, z-order wrong, camera not following
- Input not working — keys/mouse/gamepad produce no response at runtime
- Physics misbehavior at runtime — objects pass through each other, wrong gravity, jittery movement
- Need live state — want to see the actual node tree, console output, or runtime errors
- Repeated headless failure — a fix has been attempted 2+ times via headless path without success
If none of these apply, use the fast path skill instead.
Debug-fix loop (overview)
When you escalate to MCP, follow this loop. Max 3 iterations before asking the user for help.
1. RUN — run_project (optionally with a specific scene)
2. CAPTURE — get_debug_output → collect errors, warnings, prints
3. ANALYZE — parse output, identify root cause
4. FIX — modify code / scene / config to address the issue
5. VERIFY — stop_project → run_project again, get_debug_output
6. REPORT — summarize what was wrong, what was changed, and the outcome
Each step is detailed in references/workflow.md. Common runtime issue patterns are in references/debug-patterns.md.
Project path
MCP tools require a projectPath parameter — the directory containing project.godot. Determine it from the current working directory or ask the user if ambiguous:
# Quick check
ls project.godot 2>/dev/null && echo "Project root: $(pwd)"
Tool quick reference
Full tool documentation: references/tools.md
Debug tools (primary use)
| Tool | Purpose |
|---|---|
run_project |
Launch project in debug mode, capture output |
get_debug_output |
Retrieve console output and errors from running project |
stop_project |
Stop the running project, get final output |
Inspection tools
| Tool | Purpose |
|---|---|
get_project_info |
Analyze project structure (scene/script/asset counts) |
get_godot_version |
Check installed Godot version |
list_projects |
Find Godot projects in a directory |
launch_editor |
Open the Godot editor (for manual inspection) |
Scene management tools
| Tool | Purpose |
|---|---|
create_scene |
Create new scene file |
add_node |
Add node to existing scene |
load_sprite |
Load texture into Sprite2D node |
save_scene |
Save/resave scene file |
export_mesh_library |
Export scene as MeshLibrary |
UID tools (Godot 4.4+)
| Tool | Purpose |
|---|---|
get_uid |
Get UID for a specific file |
update_project_uids |
Resave all resources to update UID references |
Iteration budget
| Iteration | Action |
|---|---|
| 1 | Run → capture → analyze → apply most likely fix → verify |
| 2 | Re-analyze output, try alternative hypothesis → verify |
| 3 | Broaden investigation (check project structure, cross-reference with reviewer skills) → verify |
| After 3 | Stop and ask the user. Report what was tried and what was observed. |
Cross-references
After MCP reveals the root cause, hand off to the appropriate skill for the fix:
- Physics issues → physics reviewer skill
- Animation issues → animation reviewer skill
- UI layout issues → ui reviewer skill
- Shader/rendering → shader reviewer skill
- ECS entity problems → gecs skill