majiayu000 MCP Recovery Skill
Autonomous recovery procedures for Godot MCP connection issues.
When to Use This Skill
Use when:
- MCP commands timeout or return "Connection refused"
- Port 9080 is not listening
- Multiple Godot processes are running
- MCP CLI is unresponsive
- Health check returns "degraded" or "down"
Recovery Levels
Level 1: Light Recovery
Use for: Transient MCP issues, single command failures
Actions:
- Test MCP CLI connection
- Restart MCP CLI if needed
- Verify port 9080
Commands:
# Test connection
npx -y godot-mcp-cli@latest get_project_info
# If timeout, restart MCP CLI (no action needed - CLI is stateless)
Level 2: Medium Recovery
Use for: Port 9080 not listening, MCP not responding
Actions:
- Check for duplicate Godot processes
- Kill duplicate Godot instances
- Restart MCP server via Godot
Commands:
# Check for duplicates
tasklist | findstr /i "Godot"
# If more than 1 Godot process, kill extras
Stop-Process -Name "Godot*" -Force
# Restart Godot with MCP
powershell -File .claude/skills/godot-mcp-dap-start/scripts/ensure_godot_mcp.ps1
Level 3: Heavy Recovery
Use for: Complete MCP failure, corrupted state
Actions:
- Kill all Godot processes
- Wait 2 seconds for cleanup
- Start fresh Godot instance
- Wait for MCP port 9080
- Verify MCP handshake
Commands:
# Full restart using recovery script
powershell -ExecutionPolicy Bypass -File .claude/skills/mcp-recovery/scripts/recover.ps1
Quick Reference
| Symptom | Recovery Level | Command |
|---|---|---|
| Single command timeout | Light | Retry command |
| "Connection refused" | Medium | Kill duplicate Godot processes |
| Port 9080 not listening | Medium | Restart Godot with MCP |
| Multiple Godot processes | Medium | Stop-Process -Name "Godot*" -Force |
| Complete MCP failure | Heavy | powershell -File .claude/skills/mcp-recovery/scripts/recover.ps1 |
Health Check
Before attempting recovery, run health check:
powershell -ExecutionPolicy Bypass -File scripts/mcp-health-check.ps1
Or for JSON output (parsing):
powershell -ExecutionPolicy Bypass -File scripts/mcp-health-check.ps1 -JSON
Escalation
Ask user for help if:
- Recovery script fails multiple times
- Godot fails to start after heavy recovery
- MCP addon fails to load (check Godot console for errors)
- Port 9080 never becomes available
- You don't understand the error message
Integration with Other Skills
- godot-mcp-dap-start: Use for starting Godot with MCP
- playtesting: Run health check before HPV sessions
- minimax-mcp: Separate MCP server, not affected by Godot MCP issues
Notes
- MCP CLI (
npx -y godot-mcp-cli@latest) is stateless - no need to restart it - Godot MCP server runs inside Godot editor on port 9080
- Multiple Godot instances cause port conflicts - only one can bind port 9080
- The recovery script automates the full recovery process