# GodotIQ — AI Assistant Instructions

## Project Overview
GodotIQ is an MCP server for AI-assisted Godot 4.x development. Python 3.10+, FastMCP API, stdio transport.

## Project Structure
```
src/godotiq/         # Main package (import as: from godotiq.X import Y)
├── server.py        # MCP server entry point (FastMCP)
├── config.py        # .godotiq.json loader
├── parsers/         # .tscn, .gd, .tres parsers
├── cache/           # Hash-based file cache
└── tools/           # 9 tool categories
tests/               # pytest + pytest-asyncio
```

## Commands
```bash
pip install -e ".[dev]"   # Install with dev dependencies
pytest -v                 # Run all tests
python -c "from godotiq.server import mcp; print('OK')"  # Smoke check
```

## Conventions
- Import paths: `from godotiq.module import symbol` (not `from src.`)
- Server API: FastMCP (`from mcp.server.fastmcp import FastMCP`)
- Tool registration: `@mcp.tool()` decorator
- Async tools: `async def tool_name() -> dict:`
- All functions must have type hints and docstrings
- Tests: pytest with `asyncio_mode = "auto"`
- No business logic in Sprint 0 placeholders

## Dependencies
- Runtime: `mcp>=1.0.0` (only dependency)
- Dev: `pytest>=7.0`, `pytest-asyncio>=0.21`
