# GodotIQ PyPI Distribution — Complete Specification

## Overview
Package GodotIQ as a pip-installable Python package on PyPI so that end users can run `pip install godotiq` (or `uvx godotiq`) and get a fully working MCP server with all 35 tools, the Godot editor addon files, and a universal AI agent rules file.

## Architecture Context

GodotIQ has two halves:
1. **Python MCP server** (`src/godotiq/`) — spawned by AI clients (Claude Desktop, Cursor, etc.) as a subprocess via stdio transport
2. **Godot editor addon** (`godot-addon/addons/godotiq/`) — runs inside Godot as a WebSocket server, enabling bridge tools (run, screenshot, node ops, etc.)

The PyPI package ships BOTH halves. The Python server is installed normally. The Godot addon files are bundled as package data and copied into Godot projects via a CLI command.

## Requirements

### R1: pip installable, runnable via entry point
- `pip install godotiq` installs the package
- `godotiq` console_scripts entry point starts the MCP server (`godotiq.server:main`)
- `python -m godotiq` also works (existing `__main__.py`)
- `uvx godotiq` works for isolated execution (automatic — package name matches entry point name)

### R2: CLI subcommands
- `godotiq` (no args) = starts MCP server on stdio (backward compatible, this is what AI clients call)
- `godotiq install-addon /path/to/godot/project` = copies addon files + GODOTIQ_RULES.md to Godot project:
  - Copies `*.gd` + `plugin.cfg` → `<godot_project>/addons/godotiq/`
  - Copies `godot_development.md` → `<godot_project>/GODOTIQ_RULES.md`
- Implementation: argparse in a new `cli.py` module. `__main__.py` and `server.py:main()` route through it.

### R3: Godot addon as package data
- The 6 addon files (5x `.gd` + `plugin.cfg`) from `godot-addon/addons/godotiq/` must be included in the wheel
- Use hatchling's `force-include` to map them into `godotiq/addon/` inside the package
- Add an `__init__.py` to the addon directory inside the package for easy path resolution
- The `.gitkeep` file can be excluded

### R4: Prompts as package data
- `src/godotiq/prompts/godot_development.md` and `godot_development_prompt_v2.md` already live inside the package
- Hatchling includes VCS-tracked files by default — these should auto-include
- Verify they appear in the built wheel

### R5: All dependencies declared
Scan confirmed only 2 runtime dependencies:
- `mcp>=1.0.0`
- `websockets>=14.0`

All other imports are stdlib. Dev dependencies: `pytest>=7.0`, `pytest-asyncio>=0.21`.

Add `build` to dev dependencies for wheel building.

### R6: .mcp.json config pattern
Documented config for AI clients:
```json
{
  "mcpServers": {
    "godotiq": {
      "command": "uvx",
      "args": ["godotiq"],
      "env": {
        "GODOTIQ_PROJECT_ROOT": "/path/to/godot/project"
      }
    }
  }
}
```

### R7: Version 0.1.0
- Single source of truth: `version = "0.1.0"` in `pyproject.toml`
- `__init__.py` exposes `__version__` dynamically via `importlib.metadata.version("godotiq")`

### R8: License MIT
- Already set in pyproject.toml: `license = "MIT"`
- LICENSE file exists at repo root

### R9: Package metadata
- **name:** godotiq
- **author:** Salvatore Farruggio (coolvolve.info@gmail.com)
- **URLs:** github.com/godotiq/godotiq (homepage, repo, issues)
- **keywords:** godot, mcp, game-development, ai, godot-engine
- **classifiers:** Beta, Python 3.10-3.12, MIT, Games/Entertainment

### R10: Build produces working wheel
- `python -m build` must succeed
- Verify wheel contents include: all Python modules, addon files, prompt .md files
- Verify: `unzip -l dist/godotiq-0.1.0-py3-none-any.whl`

### R11: Post-install verification
- Server starts: `godotiq` runs without crash
- Tools register: server responds to MCP tool listing
- Ping responds: basic MCP health check

### R12: All 1128 tests still pass
- `pytest -v` must pass with 0 failures
- New tests for: CLI subcommands, install-addon file copying, __version__ availability

### R13: README update
- Add PyPI installation instructions (`pip install godotiq`)
- Add `.mcp.json` configuration example with `uvx`
- Add `godotiq install-addon` usage
- Keep existing content

### R14: Do NOT upload to PyPI
- Only verify local build + install
- Test with: `pip install dist/godotiq-0.1.0-py3-none-any.whl`

## Files to Create/Modify

| File | Action | Purpose |
|------|--------|---------|
| `pyproject.toml` | Modify | Add metadata, force-include addon, classifiers |
| `src/godotiq/__init__.py` | Modify | Add dynamic `__version__` |
| `src/godotiq/cli.py` | Create | argparse CLI with serve/install-addon subcommands |
| `src/godotiq/__main__.py` | Modify | Route through cli.py |
| `src/godotiq/addon/__init__.py` | Create | Empty init for addon package data path resolution |
| `README.md` | Modify | Add installation + usage instructions |
| `tests/test_cli.py` | Create | Tests for CLI subcommands and install-addon |

## Out of Scope
- Uploading to PyPI
- CI/CD pipeline
- Godot editor panel features (competitor GDAI has this, not relevant here)
- Any changes to existing tool logic or licensing
