mystic-forge: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

Mystic Forge is an MCP (Model Context Protocol) server for Magic: The Gathering. It exposes 46 tools that wrap several public MTG APIs (Scryfall, EDHRec, Archidekt, Commander Spellbook, MTGJSON) behind a unified FastMCP server, plus a deck simulator and a price watchlist of its own.

All tool declarations live in server.py at the repo root; supporting code lives in the mystic_forge/ package: mystic_forge/rulebook.py (Comprehensive Rules parsing), mystic_forge/watchlist/ (db.py / ingest.py / pages.py / sidecar.py / mtgstocks.py), mystic_forge/goldfish/ (simulation engine), and mystic_forge/data/ (vendored assets: MagicCompRules.txt, watchlist_words.txt, og.png). The @mcp.tool(name=...) declarations must stay in root server.py — mcp-servers/scripts/check_release.py greps that exact path at the pinned commit; moving them breaks the release gate. There is no build step, but there is a SQLite database backing the watchlist — path from MYSTIC_FORGE_DB, defaulting to mystic_forge.db.

Commands

# Run locally (HTTP transport, http://localhost:8000/mcp)
python server.py

# Run over stdio (for local MCP clients that spawn the process)
python server.py --stdio

# Run in Docker
docker compose up -d          # serves http://localhost:8000/mcp

# Install deps
pip install -r requirements.txt -r requirements-dev.txt

# Run the test suite (784 tests; -m "not slow" skips the long acceptance runs)
python -m pytest -q -m "not slow"

There is a real test suite (tests/, pytest.ini, asyncio_mode = auto) and .github/workflows/ci.yml runs it on every push and PR. There is still no linter config.

Tools themselves are mostly covered by offline tests; to smoke-test something uncovered, run the server and call it from an MCP client, or add a throwaway asyncio.run(...) against the tool's underlying _<api>_get helper.