# Scryfall MCP Server

MCP server that exposes Scryfall (Magic: The Gathering) through simple, typed tools for MCP-compatible clients (Claude Desktop, Cursor, Continue, Zed, etc.). Now includes Commander Spellbook (combo database) integration.

## Highlights

- High-level server API via `McpServer` with typed inputs/outputs
- Tools for common queries: full-text search, by colors/CMC/format, and Tagger-based searches
- SSE or stdio transports
- Polite rate limiting and 429 backoff (Scryfall and Commander Spellbook)
- Optional local cache of Tagger tag lists
- Optional local index mapping Scryfall oracle_id → Commander Spellbook card id

## Requirements

- Node.js >= 18.17

## Install & Build

- Install: `npm install`
- Build: `npm run build`

## Run (stdio)

- `node dist/index.js`

## Run (SSE HTTP)

- `npm run start:sse`
- Env: `PORT=3000` (default), `CORS_ORIGIN=*` (optional)

## Docker

- Build: `docker build -t scryfall-mcp:latest .`
- Run (SSE): `docker run --rm -p 3000:3000 -v mcp_data:/data scryfall-mcp:latest`
- Override env:
  - `SCRYFALL_INTERVAL_MS=100` (rate limiter)
  - `TAGGER_CACHE_PATH=/data/tagger-tags.json`
  - `SCRYFALL_BASE_URL=https://api.scryfall.com`
  - `CSB_INTERVAL_MS=100` (rate limiter for Commander Spellbook)
  - `CSB_BASE_URL=https://backend.commanderspellbook.com`
  - `CSB_CARD_INDEX_PATH=/data/csb-card-index.json`
  - `CSB_CARD_INDEX_TTL_MS=86400000`
- Stdio transport: `docker run --rm -it scryfall-mcp:latest node dist/index.js`

## MCP Client Example (Claude Desktop)

```json
{
  "mcpServers": {
    "scryfall": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "SCRYFALL_INTERVAL_MS": "100",
        "TAGGER_CACHE_PATH": "C:/path/to/cache/tagger-tags.json"
      }
    }
  }
}
```

## Environment Variables

- `SCRYFALL_BASE_URL`: API base URL (default `https://api.scryfall.com`)
- `SCRYFALL_INTERVAL_MS`: Minimum ms between requests (default `100`)
- `SCRYFALL_MAX_RETRIES`: Max retries on 429 (default `3`)
- `SCRYFALL_RETRY_BASE_MS`: Base backoff ms (default `250`)
- `TAGGER_CACHE_PATH`: Local JSON path for Tagger tag lists (default `./cache/tagger-tags.json`, Docker default `/data/tagger-tags.json`)

Commander Spellbook (CSB):
- `CSB_BASE_URL`: API base URL (default `https://backend.commanderspellbook.com`)
- `CSB_INTERVAL_MS`: Minimum ms between requests (default `100`)
- `CSB_MAX_RETRIES`: Max retries on 429 (default `3`)
- `CSB_RETRY_BASE_MS`: Base backoff ms (default `250`)
- `CSB_CARD_INDEX_PATH`: Cache file path for oracleId→CSB id index (default `./cache/csb-card-index.json`)
- `CSB_CARD_INDEX_TTL_MS`: TTL for index reuse in ms (default `86400000` = 24h)

## Tools (Scryfall)

- `search_cards` — Full-text search using Scryfall `q` syntax.
- `get_card` — Fetch a card by `id` or `name` (`fuzzy` optional).
- `random_card` — Random card, optional `q` filter.
- `autocomplete` — Autocomplete card names.
- `list_sets` — All sets.
- `get_rulings` — Rulings by card `id`.

Guided search tools (structured results):
- `search_by_colors` — Params: `colors`, `mode` (`exact|contains|at_most`), `identity`, `include_colorless`, `page`.
- `search_by_cmc` — Params: `min`, `max`, `colors`, `type`, `page`.
- `search_by_format` — Params: `format`, `status` (`legal|banned|restricted`), `colors`, `page`.

Tagger-powered tools:
- `list_tagger_tags` — Returns `{ function: string[], art: string[] }` from docs page (cached).
- `search_by_function_tag` — Params: `tags[]`, `match` (`any|all`), `colors?`, `format?`, `page?` (uses `otag:`).
- `search_by_art_tag` — Params: `tags[]`, `match` (`any|all`), `colors?`, `type?`, `page?` (uses `arttag:`).
- `read_tagger_cache` — Read cached tags without network.
- `refresh_tagger_tags` — Force refresh tags and write cache.

Notes:
- Many tools return `structuredContent` with compact card summaries: `name`, `mana_cost`, `type_line`, `oracle_text`, `set`, `collector_number`, `scryfall_uri`, `image`, `prices`.
- Some basic tools return `content` text (JSON stringified) for compatibility.

## Commander Spellbook Tools

- `csb_parse_deck_text` — Parse plain-text decklist to cards via CSB.
  - Input: `{ text: string }`
- `csb_find_combos_by_card_ids` — Find combos included/almost-included by CSB numeric card IDs.
  - Input: `{ ids: number[], limit?: number, offset?: number }`
- `csb_variants_search` — Search variants (combos) by filters like `uses` (card id) or `produces` (feature id).
  - Input: `{ uses?: number, produces?: number, of?: number, limit?: number, offset?: number }`
- `csb_card` — Fetch CSB card by numeric id.
  - Input: `{ id: number }`
- `csb_build_card_index` — Build and cache oracleId→CSB id index (paginates `/cards`).
- `csb_read_card_index` — Read the cached index without network.
- `csb_lookup_by_oracle_ids` — Map Scryfall `oracle_id` UUIDs to CSB numeric ids using the cached index.
  - Input: `{ oracleIds: string[] }`
- `csb_find_combos_by_names` — Resolve names via Scryfall → `oracle_id`, map via cached index, then call `find-my-combos`.
  - Input: `{ names: string[], fuzzy?: boolean, limit?: number, offset?: number }`

Notes:
- CSB’s `card-list-from-text` expects `Content-Type: text/plain` (handled by the tool).
- The `csb_find_combos_by_names` tool benefits from building the index first: run `csb_build_card_index` once per day or set a custom TTL.

## API Etiquette

- All requests send a descriptive `User-Agent`.
- Default limiter targets ~10 req/s (100ms between starts) and backs off on HTTP 429, honoring `Retry-After` (applies to both Scryfall and CSB).

## Development

- Build: `npm run build`
- StdIO dev: `npm run start:stdio`
- SSE dev: `npm run start:sse`

- `random_card`:
  - Input: `{ q?: string }`
- `autocomplete`:
  - Input: `{ q: string }`
- `list_sets`:
  - Input: none
- `get_rulings`:
  - Input: `{ id: uuid }`

## Notes

- Scryfall rate limits: be respectful (they suggest up to ~10 requests/sec). This server does not add extra rate limiting; your client should avoid flooding requests.
- Responses are returned as JSON content for maximum fidelity; clients can post-process or render summaries.

### SSE Transport Endpoints

- Events stream (server -> client via EventSource): `GET /sse`
- Messages endpoint (client -> server): `POST /messages`

Point your MCP client’s SSE transport at these endpoints on your configured host/port.

## Development

- Build: `npm run build`
- Start (built): `npm start`
- Edit source in `src/` and rebuild.

## License

No license specified. Add one if you plan to distribute.