ygoprodeck-mcp

The Problem: The PSCT Grounding Dilemma in AI Reasoning

Large Language Models (Claude, GPT-4, Gemini) possess immense strategic reasoning, but suffer from chronic syntactic hallucinations when evaluating Yu-Gi-Oh! card mechanics:

• Punctuation Inversion: LLMs routinely confuse colons (:) representing activation conditions with semicolons (;) representing costs and targeting. In competitive play, misinterpreting a cost as an effect fundamentally invalidates ruling decisions.
• Conjunction Ambiguity: Subtle timing differences between "and if you do", "then", and "also" determine whether optional triggers miss timing. LLMs frequently misquote phrasing, creating illegal rulings.
• Scraper Coupling & Rate-Limiting: Earlier tooling coupled card databases with fragile, regex-based HTML tournament web scraping. Upstream rate limits (HTTP 429) would lock users out for 70 minutes, rendering card verification completely unavailable.

Core Architectural Guarantees

1. Zero Outbound HTTP at Runtime (Air-Gapped)

The active MCP server process contains zero network code. All queries execute against an embedded local SQLite database (in strict read-only WAL mode) with response times under 2 milliseconds.

2. FTS5 Full-Text Search Engine

Features an integrated SQLite FTS5 virtual table with synchronized triggers. Agents can execute fast keyword and concept queries directly across unabridged card text (e.g. "negate that effect" or "Special Summon from your Deck") without loading massive token payloads into LLM context.

3. Token-Lean DTO Output

Every tool response is structured with strict token-lean DTO contracts. Search results return concise snippets and essential stats, reserving verbose card descriptions exclusively for deep inspection tools.

4. Circuit-Breaker Conditional Sync

The dedicated database hydrator uses HTTP If-None-Match (ETag) conditional requests. Ingests ~13,000 cards in a single atomic transaction in approximately 1.5 seconds, respecting upstream bandwidth and caching.

Model Context Protocol (MCP) Tool Contract

When launched via stdio, ygoprodeck-mcp exposes 5 production tools and 2 resources directly to agent environments:

1. search_cards
   Inputs: query (FTS5 text), name, type, attribute, race, archetype, level, atk, def, limit
   Outputs: Token-compact summary array with card passcodes, stats, and text snippets

2. get_card_details
   Inputs: name_or_id (exact name or 8-digit passcode)
   Outputs: Verbatim PSCT text, full stats, banlist statuses across all formats, and Genesys points

3. check_banlist
   Inputs: format ("tcg", "ocg", "masterduel", "edison", "goat", "genesys"), cards: string[]
   Outputs: Batch legality status: Forbidden, Limited, Semi-Limited, or Unlimited

4. get_genesys_points
   Inputs: cards: string[]
   Outputs: 100-point budget verification, total points spent, and mechanical legality flags

5. get_database_info
   Outputs: Total indexed cards, sync timestamp, and database file path

Zero-Install Integration via npx

Published to the global npm registry under the MIT license, developers and agents can connect immediately without cloning any repositories:

Cursor IDE Configuration (.cursor/mcp.json)

{
  "mcpServers": {
    "ygoprodeck": {
      "command": "npx",
      "args": ["-y", "ygoprodeck-mcp"],
      "trust": true
    }
  }
}

Claude Code & Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "ygoprodeck": {
      "command": "npx",
      "args": ["-y", "ygoprodeck-mcp"]
    }
  }
}

Comparative Architecture Benchmark