# Phase 1 — Foundation

> Project scaffold, tooling, and server skeleton.

## Status: Complete

## Goals

Get the project buildable and runnable with an empty MCP server (no tools yet).
Establish all developer tooling so subsequent phases only add features.

## Tasks

- [x] Create `pyproject.toml` (hatchling build, uv dev-deps)
- [x] Scaffold `src/grafeo_mcp/` package with `__init__.py` files
- [x] Implement `server.py` — `FastMCP` instance + `app_lifespan` (open/close GrafeoDB)
- [x] Create `.gitignore`
- [x] Set up prek (`.pre-commit-config.yaml` with ruff + ty hooks)
- [x] Create `tests/conftest.py` with shared GrafeoDB fixture
- [x] Create `tests/test_server.py` — server lifecycle smoke test
- [x] Verify `uv sync && uv run grafeo-mcp` boots without errors
- [x] Verify `uv run pytest` runs — 75 tests passing

## Design Decisions

### MCP SDK version: v1.x FastMCP (not v2 MCPServer)

The design spec referenced `mcp.server.mcpserver.MCPServer` which is a v2-dev API not yet
released on PyPI. We use `mcp.server.fastmcp.FastMCP` from v1.x (stable, `>=1.20,<2`).
The decorator API is identical — upgrading to v2 will be a one-line import change.

### Query language: GQL only (with Cypher auto-normalization)

The original spec included GQL, Cypher, and Gremlin. Simplified to GQL only:

- GQL is the ISO standard and always available via `db.execute()`
- Lightweight regex normalizer translates common Cypher keywords (`CREATE` → `INSERT`)
- Single query tool reduces agent confusion (no "which query tool?" problem)
- Gremlin and native Cypher dropped — can be added later if there's demand

### Git hooks: prek (not pre-commit)

Using prek — a Rust-based drop-in replacement for pre-commit.
Faster execution, no Python dependency for the hook runner itself.
