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

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

Game Simulation

Related MCP server: mtg-oracle

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.

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