# Usage Guide — Sprint 3: MCP Tools

## Quick Start

GodotIQ provides 4 MCP tools for AI-assisted Godot project analysis. Start the server:

```bash
cd /path/to/godot-project
python -m godotiq.server
```

Or configure as an MCP server in your AI tool's settings.

## Tools

### godotiq_project_summary

Complete project overview for context recovery.

```json
{"tool": "godotiq_project_summary", "arguments": {"detail": "normal"}}
```

**Parameters:**
- `detail`: `"brief"` | `"normal"` | `"full"` — level of detail

**Returns:** Project name, counts, autoloads, architecture, scene structure. Full detail adds autoload analysis, file tree, and detected patterns.

### godotiq_file_context

Deep context for a single file. Call before editing to understand dependencies.

```json
{"tool": "godotiq_file_context", "arguments": {"file": "res://scripts/entities/printer.gd"}}
```

**Parameters:**
- `file`: `res://` path or relative path to a `.gd` or `.tscn` file

**Returns:** For `.gd`: class info, public API, signals, dependencies, impact. For `.tscn`: nodes, instances, scripts, connections.

### godotiq_dependency_graph

Dependency graph for a `.gd` file with signal cross-referencing.

```json
{"tool": "godotiq_dependency_graph", "arguments": {"file": "res://scripts/entities/printer.gd", "depth": 2}}
```

**Parameters:**
- `file`: Path to `.gd` file
- `depth`: `1`–`3` — how many levels deep to trace (default 1)

**Returns:** Autoload refs, preloads, signal emitters/listeners, referenced-by list, impact rating (low/medium/high/critical).

### godotiq_scene_map

Spatial intelligence — complete 3D map of a scene.

```json
{"tool": "godotiq_scene_map", "arguments": {"scene": "res://scenes/main.tscn", "detail": "normal"}}
```

**Parameters:**
- `scene`: Path to `.tscn` file
- `focus`: Optional node name to center the view on
- `radius`: Distance filter around focus (default 5.0m)
- `include`: Optional list of node types or groups to filter
- `detail`: `"brief"` | `"normal"` | `"full"`

**Returns:** All nodes with world-space positions, rotation, scale. Normal adds bounds, center, groups summary. Full adds distance matrix and type summary. Focus mode adds distance and cardinal direction from focus node.

## Example Output

### Scene Map (normal detail)

```json
{
  "scene": "res://scenes/equipment/fdm_printer.tscn",
  "root_type": "Node3D",
  "total_nodes": 4,
  "nodes": [
    {
      "name": "FDMPrinter",
      "type": "Node3D",
      "full_path": "",
      "position": [0.0, 0.0, 0.0],
      "rotation_deg": [0.0, 0.0, 0.0],
      "scale": [1.0, 1.0, 1.0],
      "depth": 0,
      "is_instance": false,
      "groups": ["interactable"],
      "script": "ExtResource(\"1_iqbk5\")"
    }
  ],
  "spatial_summary": {
    "bounds": {"min": [0.0, 0.0, 0.0], "max": [0.0, 0.65, 1.2]},
    "center": [0.0, 0.244, 0.3]
  },
  "groups_summary": {"interactable": 1}
}
```

## Session Architecture

The tools share a `GodotIQSession` initialized at server startup via FastMCP lifespan:

1. `discover_project_root()` finds the nearest `project.godot`
2. `GodotIQSession.load()` scans the project, parses all `.gd` files
3. Session is stored in lifespan context, accessed by all tools
4. Scenes are lazily resolved with spatial transforms on first request

## Running Tests

```bash
uv run pytest tests/ -v          # All 306 tests
uv run pytest tests/test_tools/  # Tool-specific tests only
```
