R2 D2

A Star Wars Unlimited MCP server built with FastMCP. Search cards, build decks, validate formats, analyze the meta, and simulate two-player games — all through Claude Code, Claude Desktop, or any MCP-compatible client.

Card data comes from the live SWU DB API first and automatically falls back to the bundled local catalog when the API is unavailable.

Capabilities

Card Database

Tool	What it does
swu_search_cards	Natural text search with typed structured filters (aspect/type/arena/rarity/set as enums; cost/power/hp as {op, value} comparators). Returns a typed SearchResult.
swu_lookup_card	Exact lookup by name or set/number. Returns a typed CardDetail.
swu_random_card	Random card from a filtered pool. Returns a typed CardSummary.
swu_get_image	Front or back art URL for any card.

Typed search filters (v0.3.0)

swu_search_cards, swu_lookup_card, and swu_random_card now return Pydantic models instead of opaque dicts. FastMCP serializes them as both content (human-readable text) and structuredContent (typed JSON) — agents can read .cards[0].cost directly without parsing string keys.

Filters are typed too. Aspect/type/arena/rarity/set are Literal[...] enums, so the agent sees the valid options in the tool schema and typos like aspect="Cunninng" are rejected before the API call. Numeric stats use a structured {op, value} instead of magic strings:

swu_search_cards(
    query="Vader",
    filters={"aspect": "Villainy", "type": "Leader",
             "cost": {"op": ">=", "value": 5}},
)

Deck and game tools still return dict — that refactor is staged for a follow-up.

Deck Building

Tool	What it does
swu_upload_deck	Parse a decklist into a stateful session
swu_validate_deck	Check legality for Premier or Twin Suns (leaders, base, copy limits, aspect penalties)
swu_analyze_deck	Resource curve, aspect breakdown, synergy score, role analysis
swu_suggest_cards	Targeted card suggestions for a stated goal or matchup
swu_generate_deck	First-pass brew from a theme, leaders, and format
swu_export_deck	Export a session to a shareable decklist

Game Simulation

Tool	What it does
swu_start_game	Two-player setup with deck loading
swu_get_game_state	Current board state, hand, resources, damage
swu_get_legal_actions	Available actions with targeting options
swu_take_game_action	Execute an action (play, attack, pass, etc.)
swu_take_ai_turn	Let the AI pilot take a full turn
swu_draw_card / swu_view_hand / swu_view_board	Card management
swu_play_card / swu_move_card / swu_defeat_card / swu_set_card_state	Direct board manipulation
swu_mulligan / swu_resource_phase / swu_sideboard	Phase management

Quick Start

uv sync
uv run python scripts/start_stdio.py

Claude Code / Claude Desktop Config

Add to ~/.mcp.json:

{
  "mcpServers": {
    "r2-d2": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/r2-d2",
        "run",
        "python",
        "scripts/start_stdio.py"
      ]
    }
  }
}

Offline Catalog

A bundled card catalog (data/catalog/cards.json) is auto-discovered at startup. The server uses it as a fallback whenever the live API is unavailable — no configuration needed.

To rebuild the catalog from the latest API data:

uv run python scripts/build_catalog.py

Environment Variables

All optional — sensible defaults are built in.

Variable	Default	Purpose
SWU_MCP_API_BASE_URL	https://api.swu-db.com	Live card data API
SWU_MCP_CARD_CATALOG_PATH	Auto-discovered from data/catalog/	Local JSON fallback
SWU_MCP_CACHE_DIR	.swu-mcp-cache	Per-card response cache
SWU_MCP_DEFAULT_LIMIT	10	Default search result limit

Format Support

Premier — 1 leader, 1 base, 50+ main deck (3x copy limit), 10-card sideboard, off-aspect penalty reporting.

Twin Suns — 2 leaders sharing Heroism or Villainy, 1 base, 80+ singleton main deck, no sideboard.

Game Engine

The simulator supports two-player games with:

• Resource turns, unit/event play, leader deployment, combat, base damage
• Stack/priority loop with targeting and responses
• Ambush, Sentinel, Saboteur, Overwhelm, Shielded, Restore, Raid, Hidden
• When Played / On Attack / When Defeated trigger patterns
• Upgrade attachment with static buffs and keyword grants
• Basic AI pilot for sparring

This is a pragmatic rules engine for playtesting and AI sparring, not a comprehensive rules simulator. Edge cases around complex upgrade conditions, nested optional triggers, and deep timing interactions are not fully covered.

Example Prompts

• "Search for all Cunning leaders from Legends of the Force"
• "Generate a Twin Suns deck with Cad Bane and Jabba the Hutt"
• "Upload this decklist, analyze it, and suggest swaps for an aggro-heavy meta"
• "Start a game with my Qui-Gon deck against a generated Villainy aggro deck"
• "Take my action to play Boba Fett, then let the AI respond"

License

MIT