jita-mcp

Remote MCP server that gives Claude and Gemini ground truth on EVE Online ship fittings: stat validation, effective DPS/EHP with skills and bonuses applied, and live market prices. The LLM brings EVE meta knowledge (what's good for what content); this server answers "does this fit actually work and what does it cost."

Architecture

Claude / Gemini (web)
  └── MCP connector (Streamable HTTP)
        ├── SDE      — static data export (ships, modules, dogma, skills)
        ├── eos      — dogma / fitting calculation engine (TBD: vendored Pyfa)
        └── ESI      — live market prices, cached

Three independent inputs (our code, the engine, the SDE) get baked into one runtime container via a multi-stage Dockerfile. Each input has its own cache layer so a change in one doesn't invalidate the others.

Tools

Dev setup

Requires Python 3.12+ and uv. On macOS:

brew install uv

Bootstrap

git clone --recurse-submodules <repo-url> jita-mcp
cd jita-mcp
git submodule update --init --recursive    # only if you forgot --recurse-submodules
uv sync                                    # creates .venv, installs deps
python3 scripts/fetch_sde.py               # downloads + decompresses SDE (~130MB)

Day-to-day

uv is the entry point for everything — no task runner, no Makefile.

SDE

The Static Data Export (~700MB uncompressed) is sourced from Fuzzwork and pinned by MD5 in sde.checksum so dev/CI/prod builds are reproducible. python3 scripts/fetch_sde.py is idempotent — it skips the download when the local file already matches the pinned MD5. To pull whatever is currently live upstream (useful for the SDE-watch workflow), run:

python3 scripts/fetch_sde.py --version latest

Submodule (Pyfa)

The fitting engine lives at vendor/pyfa/ as a git submodule pinned to a specific Pyfa commit. The pin moves only via an explicit git submodule update --remote vendor/pyfa && git commit — automated by a scheduled GitHub Action that opens a PR when upstream advances.

Project layout

jita_mcp/
  server.py             MCP entry point, tool registration
  config.py             env-driven settings
  tools/                one module per MCP tool (stubbed)
  engine/               dogma / fitting engine wrapper (eos, TODO)
  db/sde.py             SDE query helpers (all SQL lives here)
  esi/                  ESI client + price cache
tests/
  fixtures/             tiny synthetic SDE for unit tests
scripts/
  fetch_sde.py          idempotent SDE downloader
vendor/
  pyfa/                 git submodule → pyfa-org/Pyfa (we use vendor/pyfa/eos)
Dockerfile              4-stage build (sde, eos, app, runtime)
sde.checksum            pinned Fuzzwork SDE MD5

License

GPL-3.0-or-later. Required because the project links the eos fitting engine, which is GPL-3.0.