/mcp-driver

name: mcp-driver
description: |
  Runtime debugging and live project inspection via godot-mcp.
  Use when headless tools cannot diagnose the problem: code compiles but runtime behavior
  is wrong, tests pass but the game does not work as expected, or you need to inspect
  live state (node tree, console output, rendering).
  Escalation trigger: a task has failed 2+ times through the headless path (headless-build,
  gdunit-driver), or the issue is inherently runtime-only (visual glitches, input not
  responding, physics behaving unexpectedly at runtime).
  DO NOT use for: syntax/compile errors (use headless-build), unit test failures
  (use gdunit-driver), API lookups (use godot-api).
  Requires: godot-mcp MCP server registered as "godot" (@coding-solo/godot-mcp).

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