CarpioCarpio/commander-deck-assistant-mcp

🎯 Commander Deck Assistant MCP Server

MCP server that helps build Commander format decks using The Command Zone's deck building template

🚀 Overview

An MCP server that integrates with Claude Desktop to help build Commander format decks. Uses The Command Zone's deck building template to categorize cards and suggest improvements.

✨ Key Features

• 🎯 Deck Template: Uses The Command Zone's 108→100 card optimization approach
• 🧠 Card Classification: Automatically categorizes cards into template roles
• 📊 Commander Database: Searchable database of commander-legal cards
• 🏗️ Archetype Support: Recognizes common Commander deck strategies
• 🔌 Claude Integration: Works as an MCP server with Claude Desktop

🎲 What It Does

Here's how it helps with deck building:

🤖 "Help me build a Kess, Dissident Mage spellslinger deck"

✅ Analyzes commander → Suggests spellslinger/control archetype
✅ Recommends cards by category → Smart ramp/card advantage options
✅ Finds multi-role cards → Smothering Tithe (ramp + card advantage, 90% versatility)
✅ Optimizes 108→100 → Helps trim down to final 100 cards

📦 Quick Start

Prerequisites

• Node.js 18+
• Claude Desktop with MCP support
• 4GB+ RAM (for card database)

Installation

1. Clone & Install

git clone https://github.com/CarpioCarpio/commander-deck-assistant-mcp.git
cd commander-deck-assistant-mcp
npm install

2. Setup Database

npm run setup

Downloads Scryfall data (~400MB) and initializes SQLite database

3. Build the Server

npm run build

4. Configure Claude Desktop

Add to your Claude Desktop MCP settings (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "commander-deck-assistant": {
      "command": "node",
      "args": ["/absolute/path/to/commander-deck-assistant-mcp/dist/server/index.js"]
    }
  }
}

5. Start Building Decks!

Open Claude Desktop and try:

"Help me analyze Atraxa, Praetors' Voice as a commander"
"Find ramp cards that work well with artifacts"
"Optimize this deck list for better performance"

🛠️ Tools Available

📚

🎯 The Science Behind It

Command Zone Template Methodology

Built on the proven deck building framework from The Command Zone podcast:

Multi-Category Intelligence

Cards often serve multiple roles. Our classifier identifies these overlaps:

{
  "card": "Smothering Tithe",
  "categories": [
    {"category": "ramp", "confidence": 0.95},
    {"category": "card_advantage", "confidence": 0.75}
  ],
  "versatilityScore": 90,
  "reasoning": "Creates treasure tokens for ramp while providing resource advantage"
}

🎯 How It Works

The server uses The Command Zone's deck building template to categorize cards:

• Lands (38): Your mana base
• Ramp (10): Mana acceleration
• Card Advantage (12): Card draw and value engines
• Targeted Disruption (12): Spot removal
• Mass Disruption (6): Board wipes
• Plan (30): Your win conditions and strategy

Start with 108 cards, then optimize down to 100 by finding cards that serve multiple roles.

⚠️ Important Limitations

Templates are starting points, not final answers. As The Command Zone notes in their "Problems with Templates" episode:

• Not one size fits all: Korvold wants different cards than Atraxa, even with the same template
• Your deck teaches you more: Play your deck, then adjust based on what actually works
• Archetype matters: Stax, Combo, and Aggro decks may need very different ratios
• Meta dependent: Casual vs competitive playgroups need different approaches

This tool helps with: ✅ Getting to a playable first draft ✅ Identifying card roles and overlaps ✅ Finding cards you might have missed

This tool can't: ❌ Know your specific playgroup's meta ❌ Understand your personal playstyle preferences ❌ Replace testing and iteration

Use this as a starting point, then tune based on actual play experience!

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Claude        │────│   MCP Server    │────│   SQLite DB     │
│   Desktop       │    │   (8 tools)     │    │   (92k cards)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                               │
                       ┌───────┴───────┐
                       │  Classification│
                       │    Engine      │
                       │  (27archetypes)│
                       └───────────────┘

Key Components:

• 🧠 Classification Engine: Pattern-based card analysis
• 🗃️ Card Database: Optimized SQLite with Scryfall data
• ⚡ Caching Layer: High-performance result storage
• 📊 Performance Monitor: Real-time metrics and benchmarks

🔬 Advanced Features

Archetype-Aware Classification

Supports 27 Commander archetypes based on common strategies:

• Aggro & Tempo: Aggro, Infect, Voltron, Counters (+1/+1)
• Value & Control: Control, Mill, Spellslinger, Superfriends, Theft
• Synergy-Based: Affinity, Aristocrats, Blink, Enchantress, Landfall, Lifegain, Typal, Tokens/Go-Wide
• Combo & Engine: Cascade, Paradox, Graveyard, Wheel
• Political & Disruptive: Chaos, Group Hug, Group Slug, Stax
• Ramp & Big Mana: Ramp
• Tribal: Legends Matter

Multi-Role Optimization

Identifies cards serving multiple template categories:

🎯 Multi-Role Examples:
• Sol Ring: Ramp that goes in every deck
• Rhystic Study: Card advantage with political elements
• Beast Within: Removal that works on any permanent
• Cultivate: Ramp that also thins your deck

🧪 Development

Project Structure

commander-deck-assistant-mcp/
├── 📋 README.md           # This file
├── 📊 CLAUDE.md           # Development status
├── 🎯 IMPLEMENTATION_PLAN.md
├── 📚 docs/               # Documentation
│   ├── api-documentation.md
│   └── reference/         # MTG rules & templates
├── 🗃️ database/           # Card data & setup
├── 🧠 src/                # TypeScript source
│   ├── server/            # MCP server
│   ├── utils/             # Classification engine
│   ├── data/              # Database layer
│   └── types/             # Type definitions
├── 🏗️ dist/               # Built JavaScript
└── 🧪 tests/              # Test suites

Building from Source

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests (optional)
npm test

# Start MCP server (for testing)
npm start

🔒 Development & CI/CD

Quality Assurance Pipeline: This project uses comprehensive CI/CD to prevent breaking changes on main branch.

Local Development Protection

# Set up pre-commit hooks (run once)
chmod +x setup-dev-tools.sh
./setup-dev-tools.sh

# Pre-commit hooks will automatically run on every commit:
# ✅ TypeScript compilation verification
# ✅ Build process validation
# ✅ Test suite execution
# ✅ File formatting checks

GitHub Actions CI/CD

Automated checks run on every push to main:

• 🛡️ Security: Attribution verification, dependency audit
• 🔨 Build: Multi-node testing (18.x, 20.x), TypeScript compilation
• 🧪 Test: Testing, integration checks
• 📊 Quality: Code formatting, merge conflict detection

Result: Cannot push broken code to main branch! 🎯

Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Merge Request

See for detailed guidelines.

📜 Data Sources & Attribution

• Card Data: Scryfall API (used with permission)
• Deck Template: The Command Zone methodology
• MTG Rules: Wizards of the Coast Comprehensive Rules
• Classification: Original pattern-based analysis

Magic: The Gathering is a trademark of Wizards of the Coast LLC.

🤝 Community

• 🐛 Issues: Found a bug? Report it
• 💡 Features: Have an idea? Suggest it
• 🗣️ Discussions: Join the conversation in Issues
• 📧 Contact: Create an issue for questions

🏆 Recognition

This project demonstrates:

• ✅ MCP server implementation with multiple tools
• ✅ Card classification using pattern matching
• ✅ Database integration with SQLite
• ✅ Commander format knowledge built-in

Useful for:

• 🎯 Commander Players: Building better decks
• 🤖 MCP Developers: Learning server implementation
• 🎲 Developers: Understanding card game data structures

📈 Roadmap

• Web Interface: Browser-based deck builder
• More Formats: Legacy, Modern, Pioneer support
• AI Recommendations: GPT-powered synergy suggestions
• Community Features: Deck sharing and rating
• Performance: Sub-millisecond classification times

📄 License

MIT License - see file for details.

Built with ❤️ for the Commander community