Aetherspark: AI assisted MTG Deck Builder

A modern Magic: The Gathering deck builder desktop application built with Electrobun, React, and TypeScript. Features AI-powered deck assistance with an integrated chat interface for strategy advice, card suggestions, and deck organization.

Features

Deck Management

• Create & Save: Create, save, load, duplicate, and delete decks with local storage
• Multi-Format Support: Standard, Pioneer, Modern, Legacy, Vintage, Commander, and Pauper
• Commander Support: Set commanders for Commander format decks with visual display
• Deck Description: Add summary and detailed description for deck strategy guides
• Card Tagging: Organize cards with custom tags (e.g., "Ramp", "Removal", "Win Condition")
• Grouping: View cards grouped by type or tags

Card Browser

• Scryfall-Powered Search: Search cards with full Scryfall syntax support
• Color & Type Filters: Quick filter buttons for colors and card types
• Grid View: Visual card browser with hover previews
• Click to Add: Click any card to add it to your deck

AI Agent Chat

• Deck Building Advice: Get card suggestions and strategy tips
• Card Search: Ask the agent to find cards matching specific criteria
• Rules Lookup: Query the comprehensive rules for game mechanics
• Deck Modification: Agent can add/remove cards, set tags, and write descriptions
• Card Linking: Card names in chat are clickable to add to deck

Import/Export

• Multiple Formats: Import and export in text, MTGO, and Arena formats
• Clipboard Support: Easy copy/paste for deck sharing

Statistics & Validation

• Mana Curve: Visual distribution of mana values
• Color Distribution: Breakdown of mana symbols in deck
• Type Breakdown: Count of creatures, spells, lands, etc.
• Format Validation: Automatic legality checking with detailed errors

Installation

# Install dependencies
bun install

Development

# Run in development mode
bun run dev

# Run with Vite HMR (in separate terminal)
bun run dev:hmr

Building

# Build for production
bun run build

Environment Variables

The AI assistant uses GitHub Copilot SDK which authenticates automatically via your GitHub login. No API key is required.

Prerequisites

• An active GitHub Copilot subscription
• Github copilot-cli installed and authenticated.

Keyboard Shortcuts

Shortcut	Action
Ctrl+S	Save deck
Ctrl+N	New deck
Ctrl+O	Open deck library
Ctrl+I	Import deck
Ctrl+E	Export deck
Ctrl+F	Focus card search
Escape	Close modal

AI Agent Tools

The integrated AI agent has access to the following capabilities:

Card Search & Lookup

• search_cards - Search for Magic cards using Scryfall syntax
• get_card - Get detailed information about a specific card
• search_rules - Search the comprehensive rules

Deck Management

• get_current_deck - View the current deck contents
• add_card_to_deck - Add a card to the deck
• remove_card_from_deck - Remove a card from the deck
• set_card_quantity - Change the quantity of a card
• set_commander - Set the commander for Commander format

Card Organization

• add_tag - Add a tag to a card
• remove_tag - Remove a tag from a card
• set_card_tags - Set all tags for a card
• get_deck_tags - Get all tags used in the deck

Deck Documentation

• get_deck_description - Read deck summary and description
• set_deck_summary - Set brief deck summary (shown in library)
• set_deck_description - Set detailed deck guide

Analysis

• analyze_deck - Get deck statistics and suggestions
• suggest_cards - Get card recommendations based on deck
• check_legality - Validate deck against format rules

Project Structure

src/
├── main/                    # Electrobun main process
│   ├── tools/              # AI agent tool handlers
│   └── services/           # Card data, rules, agent, validation
├── renderer/               # React frontend
│   ├── components/         # UI components
│   │   ├── CardBrowser/   # Card search and grid
│   │   ├── Chat/          # AI chat interface
│   │   ├── DeckEditor/    # Deck editing views
│   │   ├── DeckLibrary/   # Saved decks browser
│   │   ├── DeckStats/     # Statistics display
│   │   └── common/        # Shared UI components
│   ├── hooks/             # Custom React hooks
│   ├── services/          # API client
│   └── types/             # TypeScript types
└── shared/                 # Shared types and utilities

Tech Stack

• Runtime: Bun
• Desktop Framework: Electrobun
• Frontend: React 19 + TypeScript + Tailwind CSS
• Build Tool: Vite
• AI Integration: GitHub Copilot SDK

Data Sources

• Card Data: Scryfall bulk data with local caching (1 week TTL)
• Rules: MTG Comprehensive Rules (text format)

This application is not affiliated with Wizards of the Coast.

License

MIT