# Sprint 4a — Complete Specification

## Objective

Create the GodotIQ Godot addon (pure GDScript) and the Python bridge layer that connects the MCP server to the addon via WebSocket. Implement 4 bridge tools: `godotiq_screenshot`, `godotiq_run`, `godotiq_perf_snapshot`, `godotiq_editor_context`.

After this sprint: 17 MCP tools total (13 Phase 1 + 4 bridge).

## Architecture

```
Python MCP Server <--WebSocket--> Godot Editor Addon <--EngineDebugger--> Running Game
```

Three layers:
1. **Godot Addon** (5 GDScript files) — EditorPlugin + WebSocket server (TCPServer + WebSocketPeer.accept_stream) + EngineDebugger bridge + Game runtime autoload
2. **Python Bridge Layer** (4 files) — Async WebSocket client + message protocol (JSON dataclasses) + lazy session manager
3. **Bridge MCP Tools** (5 files) — 4 tool implementations + package init, registered via `@mcp.tool()` decorator

## Key Design Decisions

- WebSocket server on port 6007 (configurable via `.godotiq.json`), bound to 127.0.0.1 only (no auth needed)
- Godot 4 pattern: `TCPServer` + `WebSocketPeer.accept_stream()` (WebSocketServer removed)
- Game-side IPC via `EngineDebugger` with `"godotiq:"` message prefix
- Lazy bridge connection (connects on first tool use, auto-reconnects on next call if dropped)
- Screenshot retry: 3 attempts with 0.5s delay (viewport may not be ready)
- editor_context graceful fallback (works without addon connected)
- All bridge errors return dicts, never raise to MCP client

## Interview Decisions

1. **websockets version**: Target `websockets>=14.0` with new asyncio API. Verify compatibility, resolve where needed.
2. **ctx parameter**: All bridge tools include `ctx: Context = None` for consistency with existing tools.
3. **max_size**: Set `max_size=16*1024*1024` (16MB) on WebSocket connection for large screenshots.
4. **Spec fidelity**: Follow spec code exactly as written.
5. **Security**: Localhost-only binding is sufficient.
6. **Reconnect**: Auto-reconnect lazily on next tool call.
7. **Run API**: Keep play/stop separate, no toggle.

## Protocol

Request (Python → Godot): `{"id": "req_001", "method": "screenshot", "params": {"scale": 0.5}}`
Response (Godot → Python): `{"id": "req_001", "status": "ok", "result": {...}}`
Error: `{"id": "req_001", "status": "error", "error": {"code": "GAME_NOT_RUNNING", "message": "..."}}`
Event (push): `{"event": "game_started", "data": {}}`

## Constraints

- DO NOT TOUCH: parsers/, tools/code/, tools/spatial/, tools/animation/, tools/assets/, tools/memory/, resolvers/, index.py, project_index.py, session.py, existing tests
- Add `websockets>=14.0` to pyproject.toml dependencies
- Add `from godotiq.tools import bridge` to server.py imports
- GDScript: English comments/variables. Python: English code/docstrings.

## Files

### Create (18 files)
1. `godot-addon/addons/godotiq/plugin.cfg` — Plugin metadata
2. `godot-addon/addons/godotiq/godotiq_plugin.gd` — EditorPlugin lifecycle
3. `godot-addon/addons/godotiq/godotiq_server.gd` — WebSocket server + dispatch
4. `godot-addon/addons/godotiq/godotiq_debugger.gd` — EngineDebugger bridge
5. `godot-addon/addons/godotiq/godotiq_runtime.gd` — Game autoload
6. `src/godotiq/bridge/__init__.py` — Package init
7. `src/godotiq/bridge/protocol.py` — Message protocol
8. `src/godotiq/bridge/connection.py` — Async WebSocket client
9. `src/godotiq/bridge/session.py` — Shared connection manager
10. `src/godotiq/tools/bridge/__init__.py` — Package init + tool registration
11. `src/godotiq/tools/bridge/screenshot.py` — godotiq_screenshot
12. `src/godotiq/tools/bridge/run.py` — godotiq_run
13. `src/godotiq/tools/bridge/perf_snapshot.py` — godotiq_perf_snapshot
14. `src/godotiq/tools/bridge/editor_context.py` — godotiq_editor_context
15. `tests/test_bridge/__init__.py` — Test package
16. `tests/test_bridge/test_protocol.py` — Protocol tests
17. `tests/test_bridge/test_connection.py` — Connection mock tests
18. `tests/test_bridge/test_tools.py` — Tool validation tests

### Modify (2 files)
- `pyproject.toml` — Add `websockets>=14.0`
- `src/godotiq/server.py` — Add `from godotiq.tools import bridge` import

## Tool Specifications

### godotiq_screenshot
- Params: viewport ("game"), scale (0.5), format ("webp"/"png"/"jpg")
- Returns: base64 image + dimensions
- Requires game running, retries 3x with 0.5s delay

### godotiq_run
- Params: action ("play"/"stop"), scene ("main"/"current"/path)
- Returns: action confirmation

### godotiq_perf_snapshot
- No params
- Returns: fps, draw_calls, triangles, objects, memory, node counts
- Requires game running

### godotiq_editor_context
- No params
- Returns: editor version, open scenes, selected nodes, game state
- Fallback: works without addon (returns filesystem info)
