# Sprint 3 Work Plan: First Real MCP Tools

**Created:** 2026-03-02
**Sprint:** Sprint 3 -- "First Real MCP Tools"
**Status:** Not Started

---

## Overview

Sprint 3 introduces the session layer and first four real MCP tools for the GodotIQ server. The session layer bridges existing parsers (tscn, gd, project_index, scene_resolver) into a unified, cached state object. Four tools expose this state through the MCP protocol: project_summary, file_context, dependency_graph, and scene_map.

### Strategy: Horizontal Foundation + Vertical Features

- **Phase 1 (Sections 01-03):** Foundation -- fixtures, session layer, server integration
- **Phase 2 (Sections 04-07):** Features -- each tool is a vertical slice with implementation + tests

---

## Phase Structure Diagram

```mermaid
graph TD
    S01[Section 01: Test Fixtures Enhancement] --> S02[Section 02: Session Layer]
    S02 --> S03[Section 03: Server Integration]
    S03 --> S04[Section 04: G01 Project Summary]
    S03 --> S05[Section 05: G02 File Context]
    S03 --> S06[Section 06: C01 Dependency Graph]
    S03 --> S07[Section 07: B01 Scene Map]

    style S01 fill:#f9f,stroke:#333
    style S02 fill:#f9f,stroke:#333
    style S03 fill:#f9f,stroke:#333
    style S04 fill:#bbf,stroke:#333
    style S05 fill:#bbf,stroke:#333
    style S06 fill:#bbf,stroke:#333
    style S07 fill:#bbf,stroke:#333
```

## Task Dependency Diagram

```mermaid
graph LR
    subgraph "Phase 1: Foundation"
        F1[01 Fixtures]
        F2[02 Session]
        F3[03 Server]
        F1 --> F2 --> F3
    end

    subgraph "Phase 2: Tools (parallel after 03)"
        T1[04 Project Summary]
        T2[05 File Context]
        T3[06 Dependency Graph]
        T4[07 Scene Map]
    end

    F3 --> T1
    F3 --> T2
    F3 --> T3
    F3 --> T4
```

---

## Sections

### Section 01: Test Fixtures Enhancement
- **Status:** [ ] Not Started
- **Dependencies:** None
- **Files to create/modify:**
  - `tests/fixtures/sample_project/project.godot` (MODIFY -- add more autoloads)
  - `tests/fixtures/sample_project/scripts/autoloads/game_manager.gd` (NEW)
  - `tests/fixtures/sample_project/scripts/autoloads/economy_manager.gd` (NEW)
  - `tests/fixtures/sample_project/scripts/entities/printer.gd` (MODIFY -- add real content)
  - `tests/fixtures/sample_project/scripts/entities/worker.gd` (MODIFY -- add real content)
  - `tests/fixtures/sample_project/.godotiq.json` (NEW)
- **Acceptance Criteria:**
  - sample_project has 3+ autoloads in project.godot
  - .gd files contain signals, functions, autoload references, emit calls
  - scan_project() finds all scripts and autoloads
  - Existing Sprint 0+1+2 tests still pass

### Section 02: Session Layer
- **Status:** [ ] Not Started
- **Dependencies:** Section 01
- **Files to create/modify:**
  - `src/godotiq/session.py` (NEW)
  - `tests/test_tools/test_session.py` (NEW)
- **Tests:**
  - test_session_loads_project
  - test_session_finds_autoloads
  - test_session_parses_gd_with_autoloads
  - test_session_autoload_pattern1
  - test_session_caches_scenes
  - test_session_project_root_discovery
- **Acceptance Criteria:**
  - GodotIQSession.load() scans project and parses all .gd files
  - GdScript instances have correct autoload_refs (Pattern 1 detection)
  - get_script() / get_scene() return correct data
  - Cross-reference methods (get_all_signal_*) work correctly
  - Project root discovery finds project.godot via env, config, or walk-up

### Section 03: Server Integration
- **Status:** [ ] Not Started
- **Dependencies:** Section 02
- **Files to create/modify:**
  - `src/godotiq/server.py` (MODIFY -- add lifespan, keep godotiq_ping)
  - `tests/test_server.py` (MODIFY -- update for lifespan, keep existing tests passing)
- **Acceptance Criteria:**
  - FastMCP lifespan creates GodotIQSession and exposes it via context
  - godotiq_ping still works
  - Tool registration pattern established (tools access session via ctx)
  - All existing tests pass

### Section 04: Tool G01 -- Project Summary
- **Status:** [ ] Not Started
- **Dependencies:** Section 03
- **Files to create/modify:**
  - `src/godotiq/tools/memory.py` (NEW -- replaces empty __init__.py content)
  - `tests/test_tools/test_project_summary.py` (NEW)
- **Tests:**
  - test_summary_brief
  - test_summary_normal
  - test_summary_full
  - test_summary_has_required_fields
- **Acceptance Criteria:**
  - godotiq_project_summary callable via MCP
  - brief: returns project name, engine, type, file counts, autoload names
  - normal: adds architecture overview, scene structure, key systems
  - full: adds per-autoload summary, file tree, detected patterns
  - Correct file counts from session._index

### Section 05: Tool G02 -- File Context
- **Status:** [ ] Not Started
- **Dependencies:** Section 03
- **Files to create/modify:**
  - `src/godotiq/tools/memory.py` (MODIFY -- add file_context)
  - `tests/test_tools/test_file_context.py` (NEW)
- **Tests:**
  - test_context_gd_file
  - test_context_gd_autoload
  - test_context_gd_dependencies
  - test_context_tscn_file
  - test_context_missing_file
  - test_context_res_path
  - test_context_relative_path
- **Acceptance Criteria:**
  - godotiq_file_context callable via MCP
  - .gd output: file, class_name, extends, is_autoload, public_api, signals, dependencies
  - .tscn output: file, total_nodes, root_type, ext_resources, instances, scripts_used
  - Handles both res:// and relative paths
  - Returns error dict for missing files

### Section 06: Tool C01 -- Dependency Graph
- **Status:** [ ] Not Started
- **Dependencies:** Section 03
- **Files to create/modify:**
  - `src/godotiq/tools/code.py` (NEW -- replaces empty __init__.py content)
  - `tests/test_tools/test_dependency_graph.py` (NEW)
- **Tests:**
  - test_graph_basic
  - test_graph_autoload_refs
  - test_graph_referenced_by
  - test_graph_signal_listeners
  - test_graph_depth_1
  - test_graph_impact_rating
- **Acceptance Criteria:**
  - godotiq_dependency_graph callable via MCP
  - Shows emits_signals with cross-referenced listeners
  - Shows references_autoloads and referenced_by
  - depth parameter controls trace depth
  - impact_rating computed from dependency count

### Section 07: Tool B01 -- Scene Map
- **Status:** [ ] Not Started
- **Dependencies:** Section 03
- **Files to create/modify:**
  - `src/godotiq/tools/spatial.py` (NEW -- replaces empty __init__.py content)
  - `tests/test_tools/test_scene_map.py` (NEW)
- **Tests:**
  - test_map_basic
  - test_map_with_focus
  - test_map_radius_filter
  - test_map_direction
  - test_map_groups_summary
  - test_map_brief
  - test_map_full
  - test_map_missing_scene
- **Acceptance Criteria:**
  - godotiq_scene_map callable via MCP
  - Returns spatial data with 3D positions and distances
  - focus parameter filters to specific node and its neighborhood
  - radius parameter controls distance filtering
  - detail levels (brief/normal/full) control output verbosity
  - Returns error dict for missing scenes

---

## Completion Criteria (Sprint Level)

- [ ] `pytest tests/ -v` -- ALL pass (Sprint 0+1+2+3)
- [ ] All 4 tools callable via MCP
- [ ] Session correctly loads sample_project with autoload-aware .gd parsing
- [ ] `godotiq_project_summary` returns correct file counts and autoloads
- [ ] `godotiq_file_context` returns dependencies and public API for any .gd file
- [ ] `godotiq_dependency_graph` correctly cross-references signals and autoloads
- [ ] `godotiq_scene_map` returns spatial data with positions and distances
- [ ] No existing tests broken

---

## Risk Assessment

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| FastMCP lifespan API incompatibility | High | Medium | Verify lifespan pattern with minimal test first; fallback to lazy init |
| Context.request_context access pattern differs from spec | High | Medium | Check FastMCP docs/source for exact context access pattern |
| Existing test breakage from server.py changes | Medium | Low | Keep godotiq_ping unchanged; add lifespan as additive change |
| sample_project fixture changes break Sprint 1+2 tests | Medium | Low | Only ADD files/content; do not modify existing fixture structure |
| Session load performance on large projects | Low | Low | Cache is already implemented; session is loaded once at startup |

---

## Constraints

- DO NOT modify any existing parser files (gd_parser.py, tscn_parser.py, scene_resolver.py, project_index.py, value_parser.py)
- DO NOT modify existing tests (only add new test files)
- DO NOT add external dependencies beyond mcp>=1.0.0
- DO NOT implement bridge tools (A01-A08)
- Imports: `from godotiq.X import Y` (not `from src.`)
