Metadata-Version: 2.4
Name: mcpreordain
Version: 0.1.0
Summary: MCP server for Magic: The Gathering card search and deck building via Scryfall API
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp>=1.27.0
Description-Content-Type: text/markdown

# MCPreordain

An MCP (Model Context Protocol) server that enables LLMs to search for Magic: The Gathering cards and help users build decks. Wraps the [Scryfall API](https://api.scryfall.com) to provide card data, search, deck construction, validation, and pricing tools.

## Features

- Card search by name and full [Scryfall search syntax](https://scryfall.com/docs/syntax) (color, type, mana cost, format legality, oracle text, regex, boolean operators, and more)
- Full card details including multi-face cards, rulings, and pricing
- Deck creation and management with import/export support
- Deck validation against format rules (Standard, Modern, Commander, Pioneer, Legacy, Vintage, Pauper)
- Commander-specific rule enforcement (color identity, singleton, commander eligibility)
- Random card retrieval for discovery and inspiration
- Rate-limited, cached access to Scryfall with proper API etiquette

## Prerequisites

- Python 3.11+
- [uv](https://docs.astral.sh/uv/getting-started/installation/) — used exclusively for dependency management

## Setup

```bash
# Bootstrap the project (from repo root)
uv init . --app

# Add dependencies
uv add mcp httpx
uv add --group dev pytest pytest-asyncio hypothesis

# Install everything
uv sync
```

## Usage

Run the MCP server:

```bash
uv run mcpreordain
```

### MCP Client Configuration

Add to your MCP client config (e.g., `.kiro/settings/mcp.json`):

```json
{
  "mcpServers": {
    "mtg": {
      "command": "uv",
      "args": ["run", "mcpreordain"],
      "env": {}
    }
  }
}
```

## Available Tools

| Tool | Description |
|---|---|
| `search_cards` | Search cards by name |
| `search_cards_advanced` | Search with raw [Scryfall query syntax](https://scryfall.com/docs/syntax) — colors (`c:`), types (`t:`), oracle text (`o:`), mana value (`mv:`), stats (`pow:`, `tou:`), rarity (`r:`), sets (`s:`), format (`f:`), price (`usd:`), `is:`/`has:` predicates, regex, boolean operators, and more |
| `get_card` | Get full card details by name or Scryfall ID |
| `get_card_rulings` | Get official rulings for a card |
| `get_card_price` | Get USD pricing for a card |
| `get_random_card` | Get a random card, optionally filtered with a Scryfall query |
| `create_deck` | Create a new deck for a format |
| `add_card_to_deck` | Add a card to a deck (main or sideboard) |
| `remove_card_from_deck` | Remove a card from a deck |
| `set_commander` | Designate a commander for a Commander deck |
| `validate_deck` | Validate deck legality against format rules |
| `export_deck` | Export deck as a text list |
| `import_deck` | Import a deck from a text list |
| `get_deck_price` | Get total deck price estimate |

## Development

```bash
# Run tests
uv run pytest

# Run tests with verbose output
uv run pytest -v
```

## API Etiquette

This server respects [Scryfall's rate limits](https://scryfall.com/docs/api/rate-limits):

- Search endpoints (`/cards/search`, `/cards/named`, `/cards/random`, `/cards/collection`): 2 requests/sec
- All other endpoints: 10 requests/sec
- 30-second backoff on HTTP 429 responses
- Card data cached for 24 hours
- Proper `User-Agent` and `Accept` headers on all requests

## Key Constraints

- Decks are in-memory only — they do not persist across server restarts
- All Scryfall communication is HTTPS-only
- The server never uses pip — `uv` is the only package manager

## CI/CD

Releases are fully automated with [python-semantic-release](https://python-semantic-release.readthedocs.io/):

Push to `main` triggers `.github/workflows/release.yml`, which bumps the version based on [Conventional Commits](https://www.conventionalcommits.org/) (`feat:` → minor, `fix:`/`perf:` → patch), creates a GitHub Release, then builds with `uv build` and publishes to PyPI via [trusted publishers](https://docs.pypi.org/trusted-publishers/) (OIDC, no API tokens).

```bash
# Install from PyPI
uv pip install mcpreordain
```

## References

- [Scryfall API Documentation](https://scryfall.com/docs/api)
- [Scryfall Search Syntax](https://scryfall.com/docs/syntax)
- [Scryfall API Changelog](https://scryfall.com/blog/feed)
- [MCP Protocol](https://modelcontextprotocol.io)

## License

This project uses Scryfall data under the [Wizards of the Coast Fan Content Policy](https://company.wizards.com/en/legal/fancontentpolicy). Card data and images are provided by Scryfall free of charge for creating Magic software.
