The MCP that understands your Godot project

Call FIRST alongside project_summary. Returns editor state: open scenes, selected nodes, is game running, project path.

> godotiq_editor_context
  Scene: main.tscn, 3 selected, game: stopped

Live editor scene tree with actual state: transforms, scripts, groups, visibility. Unlike scene_map (reads .tscn from disk), this reads the editor's live state.

> godotiq_scene_tree --depth 3
  Main → World → Player (pos: 3,1,0) → Camera3D

Core scene editing tool. Batch operations with Ctrl+Z undo: move, rotate, scale, set_property, add_child, delete, duplicate, reparent, rename, get_property. All ops in one call = one undo action.

> godotiq_node_ops [{op: "move", node: "Shelf", position: [2,0,3]}]
  ✓ Shelf moved to (2, 0, 3) — Ctrl+Z to undo

Create multiple nodes in a scene using high-level patterns. One call = many nodes with Ctrl+Z undo. Modes: grid, line, scatter, explicit list.

> godotiq_build_scene --grid {rows: 3, cols: 4, scene: "res://shelf.tscn"}
  ✓ 12 nodes created in grid pattern

Persist editor changes to disk. Call after node_ops or any scene modifications.

> godotiq_save_scene
  ✓ Saved main.tscn

Read, write, or patch GDScript files with convention validation. Patch mode (find-and-replace) is safest.

> godotiq_script_ops --op read --path Player.gd
  class_name Player extends CharacterBody3D (42 lines)

Filesystem operations: list, read, write, move, delete, search, tree, uid_to_path, path_to_uid, rename with reference updates. Respects protected files from .godotiq.json.

> godotiq_file_ops --op list --path res://scenes
  5 files: main.tscn, level1.tscn, menu.tscn...

Execute GDScript code. Last resort, prefer dedicated tools. Code MUST contain 'func run():'.

> godotiq_exec "func run():
  return Engine.get_version_info()"
  {major: 4, minor: 3}

Start or stop the Godot game. Must call play before using any game-side tools.

> godotiq_run --action play --scene main
  ✓ Game started (scene: main.tscn)

Simulate player input in the running game: actions, keys, UI taps, waits. Supports signal verification and side-effect tracking.

> godotiq_input [{actions: ["move_left"], hold_ms: 500}, {wait_ms: 200}]
  ✓ 2 commands executed, 0 errors

Visual verification of the game or editor viewport. Use scale=0.25, quality=0.3 for token-efficient checks.

> godotiq_screenshot --viewport editor --scale 0.25
  Captured 480×270 webp (12KB)

Editor 3D camera control: get current position, reposition, or focus on a node. Editor-side, no game needed.

> godotiq_camera --action focus_node --node Player
  Camera focused on Player at (3, 1, 0)

Query runtime property values. Cheaper than screenshots for checking state. Supports autoload lookup, node paths, nested properties, method calls.

> godotiq_state_inspect [{autoload: "EconomyManager", properties: ["balance"]}]
  EconomyManager.balance = 1500

FPS, draw calls, memory, node count from the running game.

> godotiq_perf_snapshot
  60 FPS, 142 draw calls, 12.4MB texture memory

Persistent property monitoring. Start watching, then read accumulated changes over time.

> godotiq_watch --action start --watches [{node: "Player", properties: ["position"]}]
  ✓ Watching Player.position (500ms interval)

Review what was changed. Shows undo/redo state and recent GodotIQ action history.

> godotiq_undo_history
  Last: "Move Shelf" — can undo: true, can redo: false

Check GDScript files for compilation/parse errors.

> godotiq_check_errors --scope scene
  ✓ 0 errors in 12 scripts checked

Verify a node property changes over time (proves movement/animation). Takes two snapshots separated by a sleep and compares values.

> godotiq_verify_motion --node Player --duration 2.0
  Verdict: MOVING — position changed (0,1,0) → (3,1,2)

Spatial understanding of a .tscn scene: positions, distances, directions, bounds. Call before placing or moving 3D objects.

> godotiq_scene_map main.tscn --focus Player --radius 10
  Player (0,1,0) → Shelf (2,0,3) 3.2m east → Door (5,0,0) 5.1m east

Automated 3D scene linter: floating objects, scale mismatches, z-fighting, overlapping instances, extreme positions.

> godotiq_spatial_audit main.tscn
  ⚠ 2 floating objects, 1 scale mismatch, 0 z-fighting

Find safe placement positions for new objects. Checks Marker3D slots first, then grid-searches with wall/overlap validation. Up to 3 suggestions with confidence scores.

> godotiq_placement --near Printer --object_type shelf
  Suggestion 1: (4.2, 0, -1.8) confidence: 0.95 ✓ marker slot

Complete dependency graph: signals emitted, listeners, imports, reverse deps, impact rating. Call before refactoring.

> godotiq_dependency_graph Player.gd
  Player.gd → Health.gd → UI/HUD.tscn (impact: high)

Convention check: missing type hints, missing class_name, orphan signals, naming violations.

> godotiq_validate
  ✓ 42 rules passed, ⚠ 2 warnings (missing type hints)

Project-wide signal wiring: who emits, who listens, orphan/missing signals.

> godotiq_signal_map
  health_changed: Player.gd emits → HUD.gd, GameManager.gd

Predict what breaks BEFORE making a change. Returns affected files, callers, risk level, safe alternatives.

> godotiq_impact_check Player.gd
  7 files affected, 3 signals, risk: high

Animation data for any node: tracks, keyframes, length, looping, state machine transitions.

> godotiq_animation_info Player.tscn
  3 animations, 24 keyframes, idle: 1.2s loop, run: 0.8s loop

Find animation problems: broken tracks, missing transitions, wrong loop settings, unreferenced animations.

> godotiq_animation_audit
  ⚠ 1 broken track, 1 missing transition idle→jump

Trace execution flow from a function or signal through the entire codebase. Returns chain of calls, signal emissions, failure points.

> godotiq_trace_flow start_print_job --depth 10
  PrintManager._ready → queue_job → Worker.execute → done signal

Complete asset inventory: find unused assets, missing references, assets by type.

> godotiq_asset_registry
  124 assets: 48 textures, 32 audio, 3 unused, 1 missing ref

Recommend scale + position for a model based on similar assets in the scene.

> godotiq_suggest_scale printer.glb --scene main.tscn
  Recommended: scale (1,1,1), position (4,0,2) based on 3 similar

Architecture overview, autoloads, conventions, file counts. Call FIRST in every session.

> godotiq_project_summary
  48 scripts, 23 scenes, 5 autoloads, 156 signals mapped

Deep context for a file: public API, dependencies, signals, who imports it, scene usage. Call BEFORE editing any file.

> godotiq_file_context Player.gd
  12 deps, 4 signals, used in 3 scenes, 8 importers

Map all UI elements on screen: positions, text, interactivity, visibility. Call BEFORE godotiq_input to know what's on screen.

> godotiq_ui_map
  HUD → HealthBar (10,10) → Label "HP: 100" → Button "Shop"

Live pathfinding via NavigationServer3D. "Can A reach B?" Returns path, distance, reachability, navmesh status.

> godotiq_nav_query --from_node Player --to_node Exit
  ✓ Reachable, distance: 28.4m, 12 waypoints

Health check tool. Returns server status and version.

> godotiq_ping
  GodotIQ v0.5.1
  server: healthy
  tools loaded: 36 (22 community + 14 pro)
  license: pro (active)
  bundle: cached

Autonomous visual inspection via drone camera. Tour mode clusters nodes into areas and captures overview screenshots. Inspect mode visits specific positions.

> godotiq_explore main.tscn --mode tour
  4 areas found, 127 nodes, 8 screenshots captured