tome-mtg 1.3.6
MTG Deck Analyzer - Multi-format analysis for Commander, Standard, Modern, and Limited
License: MIT
Requires Python: >=3.9
Keywords: mtg, magic-the-gathering, commander, edh, standard, modern, limited, draft, sealed, deck-analyzer, deck-building

# Tome - MTG Deck Analyzer

**Tome** is a Python CLI tool that analyzes Magic: The Gathering decklists across multiple formats (Commander, Standard, Modern, Limited), combining format-specific rule-based heuristics with LLM-powered strategic analysis using the Scryfall API for card data and Claude API for intelligent recommendations.

## Features

### Multi-Format Support
- **Commander (100 cards)**: Singleton format with multiplayer-focused analysis
- **Standard (60 cards)**: Recent sets with creature-heavy meta guidance
- **Modern (60 cards)**: Turn 4 rule and fast-format optimization
- **Limited 40-card**: Draft/Sealed with BREAD framework analysis

### Deck Analysis
- **Decklist Parsing**: Supports multiple common formats (Moxfield, MTGO, simple text)
- **Moxfield URL Support**: Analyze decks directly from Moxfield URLs
- **Smart Format Detection**: Automatically detects format or prompts you to choose
- **Archetype Detection**: Identifies aggro, midrange, control, or combo strategies
- **Scryfall Integration**: Automatic card data retrieval with 30-day local caching

### Format-Specific Heuristic Validation
Checks your deck against format-specific best practices:

**Commander:**
- Land count: 37-39 lands
- Ramp: 8-12 spells
- Card draw: 10+ sources
- Removal: ~8 pieces
- Board wipes: 3-5
- Instant interaction: 8+

**Standard/Modern:**
- Lands: 23-27 (Standard) or 19-24 (Modern)
- Creatures: Format and archetype-specific ranges
- Removal: 4-16 pieces (varies by archetype)
- Rule of 9 analysis: Checks for 4-of playsets and consistency
- Color pip requirements: Validates mana base for pip intensity

**Limited (40-card):**
- Lands: 16-18 (17 is standard)
- Creatures: 13-18
- Removal: 5-7 pieces (premium in Limited)
- BREAD framework: Bombs, Removal, Evasion, Attackers, Duds analysis

### Budget Analysis
- Total deck cost calculation
- Identifies expensive cards (>10% of budget)
- Budget category classification (Ultra-Budget to No-Budget)

### LLM Strategic Analysis
- **Format-specific guidance**: Claude provides analysis tailored to your deck's format and archetype
- **Commander**: Multiplayer dynamics, politics, singleton synergies
- **Modern**: Turn 4 rule, fast combo awareness, efficient interaction
- **Standard**: Creature combat focus, planeswalker strategies
- **Limited**: BREAD framework evaluation, vanilla test, curve optimization
- Interactive chat mode for follow-up questions
- Context-aware recommendations based on your deck's strengths and weaknesses

### Interactive Deck Modification
- Add cards: `add Sol Ring` or `add Rhystic Study x2`
- Remove cards: `remove Temple of the False God`
- Swap cards: `swap Diabolic Tutor for Demonic Tutor`
- Batch add/remove: paste multiple card names at once
- Export updated decklist in Moxfield-compatible format

### Collection Comparison
- Compare your deck against your existing card collection
- AI-powered swap suggestions that understand card synergies
- Find budget savings: cards you own that could replace expensive cards
- Find upgrades: better cards you already have
- Interactive swap acceptance: `accept 1` or `accept all budget`

## Installation

### Quick Install (Recommended)

```bash
pip install tome-mtg
```

### API Key Setup

When you first run Tome without an API key, it will prompt you to paste one and offer to save it for future sessions.

Or set it manually:

```bash
# On Windows (PowerShell)
$env:ANTHROPIC_API_KEY = "your_api_key_here"

# On macOS/Linux
export ANTHROPIC_API_KEY=your_api_key_here
```

Or create a `.env` file in your working directory:

```
ANTHROPIC_API_KEY=your_api_key_here
```

Get your API key from: https://console.anthropic.com/

### Install from Source

```bash
git clone https://github.com/kliszaj/tome.git
cd tome
pip install -e .
```

## Usage

### Basic Analysis

```bash
tome analyze my_deck.txt
```

When you run this command, Tome will:
1. **Prompt for deck type**: Choose Commander (100), Constructed 60-card, or Limited 40-card
2. **Prompt for format** (if 60-card): Choose Standard or Modern
3. **Detect archetype**: Auto-detects and asks you to confirm (aggro, midrange, control, combo)
4. **Run analysis**: Provides format-specific heuristics and strategic insights

### Options

```bash
tome analyze my_deck.txt --collection cards.txt  # Compare against collection
tome analyze my_deck.txt -c cards.txt            # Short form
```

### Decklist Format

The analyzer supports multiple formats:

```text
// Commander deck (100 cards)
Commander:
1 Korvold, Fae-Cursed King

Deck:
1 Sol Ring
1x Arcane Signet
1 x Command Tower
Blasphemous Act

// 60-card deck with sideboard
Deck:
4 Lightning Bolt
4x Monastery Swiftspear
4 Boros Charm

Sideboard:
3 Rest in Peace
2 Wear // Tear

// 40-card Limited deck
Deck:
17 Mountain
1 Shivan Dragon
2 Lightning Strike

// Comments are supported
// Lines starting with // or # are ignored
```

Supported quantity formats:
- `4x Card Name` or `4 x Card Name`
- `4 Card Name`
- `Card Name` (assumes quantity 1)

**Note**: Sideboards are supported for 60-card formats (Standard/Modern)

### Example Output

```
What type of deck are you analyzing?
  1) Commander/EDH (100 cards, singleton)
  2) Constructed 60-card (Standard, Modern, etc.)
  3) Limited 40-card (Draft or Sealed)

Enter 1, 2, or 3: 2

Which 60-card format?
  1) Standard (recent sets)
  2) Modern (8th Edition forward)

Enter 1 or 2: 2

Which archetype best describes your deck?
  1) Aggro (fast, creature-heavy, wins turn 4-6)
  2) Midrange (balanced threats and answers)
  3) Control (answers and card advantage)
  4) Combo (wins via specific card combinations)

Enter 1, 2, 3, or 4: 1

Format: modern
Archetype: aggro

DECK OVERVIEW
Total Cards: 60
Average CMC: 1.8 (non-land)
Color Identity: R/W

HEURISTIC CHECKLIST
┌──────────────┬────────┬──────────┬────────┐
│ Category     │ Count  │ Expected │ Status │
├──────────────┼────────┼──────────┼────────┤
│ Lands        │ 20     │ 19-24    │   ✓    │
│ Creatures    │ 24     │ 20-28    │   ✓    │
│ Removal      │ 8      │ 4-16     │   ✓    │
│ Card Draw    │ 4      │ 4+       │   ✓    │
└──────────────┴────────┴──────────┴────────┘

MANA CURVE
  1 | ████████████ 12
  2 | ████████████████ 16
  3 | ████████ 8
  4 | ████ 4

Average CMC: 1.8

═══ Rule of 9 Analysis (Constructed) ═══
Playsets (4-ofs): 8
Effect types: 12
✓ Meets Rule of 9 (8+ playsets)

═══ Color Pip Requirements ═══
✓ Red: 20/16 sources for RR pips (OK)
✓ White: 12/12 sources for W pips (OK)

STRATEGIC ANALYSIS
[Claude AI analysis of your Modern aggro deck]
```

### Collection Comparison

Compare your deck against cards you already own:

```bash
tome analyze my_deck.txt --collection my_collection.txt
```

The collection file uses the same format as deck files. Tome will suggest:
- Budget swaps: expensive cards that can be replaced with cheaper cards you own
- Upgrades: better cards you already have

### Interactive Commands

After analysis, you enter interactive mode:

```
> add Sol Ring              # Add a card
> remove Island             # Remove a card
> swap Card A for Card B    # Swap cards
> show swaps                # Show collection swap suggestions
> accept 1                  # Accept swap suggestion #1
> accept all budget         # Accept all high-confidence budget swaps
> summary                   # Show modifications made
> export                    # Export updated decklist
> quit                      # Exit
```

You can also ask questions about your deck:

```
> What cards should I cut for more draw?
> Is this deck too slow?
> Should I add more ramp or cut lands?
```

## Cost Estimates

- **Scryfall API**: Free (with rate limiting)
- **Claude Analysis**: ~$0.05 per deck analysis
- **Interactive Questions**: ~$0.01-0.02 per question

## Troubleshooting

### "Card not found in Scryfall"
The tool uses fuzzy matching, but some card names may not be recognized. Double-check spelling or try the exact name from Scryfall.

### Import errors
Make sure you've installed the package correctly:
```bash
pip install tome-mtg
```

## License

MIT License - Free to use and modify.

## Credits

- **Scryfall**: Card data provided by [Scryfall API](https://scryfall.com/)
- **Anthropic**: LLM analysis powered by Claude API