# PyPI Distribution Research

## Codebase Analysis

### Current Packaging Setup
- **Build system:** Hatchling (`hatchling.build`)
- **Version:** 0.1.0 (in pyproject.toml only, not in `__init__.py`)
- **License:** MIT (LICENSE file exists)
- **Python requirement:** >=3.10

### Runtime Dependencies (only 2)
1. `mcp>=1.0.0` — FastMCP server framework
2. `websockets>=14.0` — bridge WebSocket client (lazy import in `bridge/connection.py`)

All other imports are stdlib or internal godotiq modules.

### Dev Dependencies
- `pytest>=7.0`
- `pytest-asyncio>=0.21`

### Entry Points (Already Configured)
```toml
[project.scripts]
godotiq = "godotiq.server:main"
```
- `main()` in `server.py` calls `mcp.run(transport="stdio")`
- `__main__.py` exists, enables `python -m godotiq`
- **Both entry point patterns already work**

### Package Structure (src-layout)
```
src/godotiq/
├── __init__.py          # Just docstring, no __version__
├── __main__.py          # Module entry: from godotiq.server import main; main()
├── server.py            # FastMCP instance, lifespan, main()
├── session.py           # Project discovery
├── config.py            # .godotiq.json loader
├── license.py           # PRO licensing
├── bridge/              # WebSocket bridge to Godot
├── cache/               # Hash-based file cache
├── parsers/             # .tscn, .gd, .tres parsers
├── prompts/             # MCP prompts (godot_development.md, v2)
│   ├── godot_development.md         # 483 lines, loaded at runtime
│   └── godot_development_prompt_v2.md  # 406 lines
└── tools/               # 9 tool categories, 35 tools total
```

### Files That MUST Ship in the Wheel
1. **Prompts** (`src/godotiq/prompts/*.md`) — loaded at runtime via `Path(__file__).parent / "prompts"`. Already inside src/godotiq, should auto-include.
2. **Godot addon** (`godot-addon/addons/godotiq/`) — 7 files: plugin.cfg, 5x .gd, .gitkeep. **Outside** src/godotiq, needs explicit inclusion.

### Godot Addon Files (7 files)
```
godot-addon/addons/godotiq/
├── plugin.cfg           # Plugin metadata
├── godotiq_plugin.gd    # Plugin entry point
├── godotiq_runtime.gd   # Runtime API
├── godotiq_debugger.gd  # Debugger integration
├── godotiq_server.gd    # WebSocket server
├── godotiq_logger.gd    # Logging
└── .gitkeep             # Marker (can exclude)
```

### No Existing .mcp.json
Users create their own. Current docs show `uv run --project /path/to/godotiq godotiq`. After PyPI, this becomes `uvx godotiq`.

### Missing from pyproject.toml
- No `keywords` or `classifiers`
- No `authors`/`maintainers`
- No `[project.urls]`
- No package_data config for addon files

---

## Web Research: Best Practices

### Build Backend: Keep Hatchling
Hatchling is the PyPA-recommended default for pure-Python packages. Already configured. No reason to switch.

### Package Data with Hatchling
Hatchling includes all VCS-tracked files by default. For files outside the package directory (godot-addon/), use `force-include`:

```toml
[tool.hatch.build.targets.wheel]
packages = ["src/godotiq"]

[tool.hatch.build.targets.wheel.force-include]
"godot-addon/addons/godotiq" = "godotiq/addon"
```

This maps `godot-addon/addons/godotiq/` to `godotiq/addon/` inside the wheel. At runtime, access via `importlib.resources.files('godotiq.addon')` or `Path(__file__).parent / "addon"`.

**Prompts** already live inside `src/godotiq/prompts/` — hatchling should include them automatically. Verify with `unzip -l dist/*.whl`.

### MCP Server Packaging Pattern (from official servers)
All official MCP Python servers follow:
```toml
[project.scripts]
server-name = "package.server:main"
```
Plus a `__main__.py` for `python -m package`. **GodotIQ already does this.**

### uvx Compatibility
`uvx godotiq` will work out of the box because:
1. Package name = "godotiq"
2. Console script name = "godotiq"
3. These match (no `--from` needed)

No special config needed. Just publish to PyPI.

### Recommended .mcp.json for End Users
```json
{
  "mcpServers": {
    "godotiq": {
      "command": "uvx",
      "args": ["godotiq"],
      "env": {
        "GODOTIQ_PROJECT_ROOT": "/path/to/godot/project"
      }
    }
  }
}
```

### Verifying the Wheel
```bash
python -m build --wheel
unzip -l dist/godotiq-0.1.0-py3-none-any.whl
# or
check-wheel-contents dist/godotiq-0.1.0-py3-none-any.whl
```

### Accessing Addon Files at Runtime
For a `godotiq scaffold` or similar install command:
```python
from importlib.resources import files
addon_path = files('godotiq.addon')
```
Or simpler: `Path(__file__).resolve().parent / "addon"` if the addon dir has `__init__.py`.

### Testing Setup
- pytest with `asyncio_mode = "auto"`
- Tests in `tests/` outside `src/` — naturally excluded from wheel
- 1128 tests currently passing

### Sources
- Python Packaging User Guide: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
- Hatch build config: https://hatch.pypa.io/latest/config/build/
- MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk
- create-python-server template: https://github.com/modelcontextprotocol/create-python-server
- uv tools docs: https://docs.astral.sh/uv/guides/tools/
