---
name: randallliuxin/mcp-driver
source: https://app.decimal.ai/s/randallliuxin-mcp-driver@1/SKILL.md
source_sha256: 1e0bf77be129
---

# 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:

```bash
# 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