Scryfall MCP-Server

Ein umfassender Model Context Protocol (MCP)-Server, der in die Scryfall-API integriert ist, um KI-Assistenten Magic: The Gathering-Kartendaten und -Funktionen bereitzustellen.

Dieses Repository unterstützt derzeit:

• stdio als stabilen Standard-Transport für lokale MCP-Clients

• experimentelles Streamable HTTP als additiven Transport für Local-First-HTTP-Workflows

Das Kernprodukt bleibt in beiden Modi gleich: Scryfall-gestützte Suche, Regeln und Deckbau-Workflows für MTG.

Funktionen

🔧 MCP-Tools

Abfrage-Erstellung

• build_scryfall_query: Konvertiert natürlichsprachliche Anfragen in optimierte Scryfall-Suchanfragen

  • Eingabe: Natürlichsprachliche Beschreibung, Formatpräferenzen, Optimierungsstrategie

  • Ausgabe: Optimierte Scryfall-Abfrage mit Erklärung und Alternativen

  • Beispiel: "rote Kreaturen unter 5 $ für aggressive Decks" → "c:r t:creature usd<=5 pow>=2 cmc<=3"

Kern-Suchtools

• search_cards: Suche nach Karten mit der leistungsstarken Suchsyntax von Scryfall

• get_card: Detaillierte Informationen zu bestimmten Karten abrufen

• get_card_prices: Aktuelle Preisdaten für Karten abrufen

• random_card: Zufällige Karten mit optionalen Filtern abrufen

• search_sets: Magic-Sets suchen und filtern

Entdeckungs- und Analysetools

• query_rules: Die umfassenden MTG-Regeln mit Kontext durchsuchen

• search_format_staples: Staples, Rollenspieler und Meta-Karten für ein Format finden

• search_alternatives: Budget-Ersatz, Upgrades oder ähnliche Karten finden

• find_synergistic_cards: Synergie-Teile für eine Karte, ein Thema oder einen Archetyp entdecken

• batch_card_analysis: Mehrere Karten auf Legalität, Preise, Synergie oder Zusammensetzung analysieren

Deckbau-Tools

• validate_brawl_commander: Prüfen, ob eine Karte ein legaler Brawl- oder Standard-Brawl-Commander ist

• analyze_deck_composition: Manakurve, Kartenmix, Farben und Empfehlungen aus einer Deckliste bewerten

• suggest_mana_base: Landanzahl und Mana-Fixing-Pakete basierend auf Farbanforderungen empfehlen

📚 MCP-Ressourcen

• card-database://bulk: Vollständige Scryfall-Bulk-Kartendatenbank mit täglichen Updates

• set-database://all: Alle Magic-Sets mit Metadaten und Symbolen

💡 MCP-Prompts

• analyze_card: Umfassende Kartenanalyse erstellen, einschließlich Wettbewerbsfähigkeit, Synergien und Meta-Positionierung

• build_deck: Deckbau-Anleitungen rund um bestimmte Karten erstellen

⚡ Leistungsmerkmale

• Ratenbegrenzung: Respektiert die API-Limits von Scryfall mit einem Mindestintervall von 100 ms

• Intelligentes Caching: Reduziert API-Aufrufe um >70 % mit konfigurierbarer TTL

• Fehlerbehandlung: Elegante Behandlung aller API-Fehlerbedingungen

• Circuit Breaker: Verhindert kaskadierende Ausfälle bei API-Ausfällen

🔍 Einfaches Validierungssystem

• Leichte Validierung: Grundlegende Validierung der Abfragesyntax mit hilfreichen Fehlermeldungen

• Wesentliche Prüfungen: Ausgewogene Klammern, Anführungszeichen und häufige Syntaxfehler

• Operator-Erkennung: Validiert bekannte Scryfall-Operatoren mit Vorschlägen bei Tippfehlern

• Leistungsoptimiert: Schnelle Validierung mit minimalem Overhead

Related MCP server: API Tester MCP Server

Installation

Voraussetzungen

• Node.js 18+

• npm oder yarn

Einrichtung

1. Repository klonen

   git clone https://github.com/bmurdock/scryfall-mcp.git
   cd scryfall-mcp

2. Abhängigkeiten installieren

   npm install

3. Umgebung konfigurieren (optional)

   cp .env.example .env
   # Edit .env with your preferences

4. Projekt bauen

   npm run build

Verwendung

Transportmodi

STDIO (stabiler Standard)

Verwenden Sie stdio für lokale MCP-Clients wie Claude Desktop, Codex und MCP Inspector. Dies bleibt der primäre und am besten unterstützte Transport.

npm run dev

npm start

Streamable HTTP (experimentell)

Ein additiver HTTP-Einstiegspunkt ist für die Local-First-Nutzung von Streamable HTTP verfügbar.

npm run dev:http

npm run start:http

Testen

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

MCP Inspector

npm run inspector

HTTP-Transportstatus

HTTP-Unterstützung ist derzeit experimentell.

Was das bedeutet:

• stdio bleibt der empfohlene Standard

• HTTP ist additiv, kein Ersatz

• die Implementierung folgt dem offiziellen MCP Streamable HTTP-Transportpfad

• die erste Implementierung ist bewusst Local-First und im Umfang konservativ

Aktuelles HTTP-Verhalten:

• bindet standardmäßig an 127.0.0.1

• stellt POST|GET|DELETE /mcp bereit

• stellt GET /health bereit

• lehnt standardmäßig browserartige Origin-Header ab, die nicht vom Loopback stammen

• kann mit HTTP_ALLOWED_ORIGINS konfiguriert werden, wenn eine andere Origin-Richtlinie beabsichtigt ist

Aktuelle Nicht-Ziele:

• Anleitung für die Bereitstellung im öffentlichen Internet

• Auth-Middleware oder gehärtete Produktionsumgebungen

• Ersetzen der stdio-Beispiele im gesamten Repository

Wenn Sie ein Bereitstellungsmodell für die Öffentlichkeit benötigen, betrachten Sie die aktuelle HTTP-Unterstützung eher als Grundlage denn als fertige Hosting-Lösung.

Projektdokumentation

• CONTRIBUTING.md

• SECURITY.md

• SCRYFALL_COMPLIANCE.md

Claude Desktop-Integration

Fügen Sie Folgendes zu Ihrer Claude Desktop-Konfigurationsdatei hinzu:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

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

Ersetzen Sie /absolute/path/to/scryfall-mcp durch den tatsächlichen Pfad zu Ihrer Installation.

HTTP-Konfiguration

Optionale HTTP-Umgebungsvariablen:

• HTTP_HOST Standard 127.0.0.1

• HTTP_PORT Standard 3000

• HTTP_MCP_PATH Standard /mcp

• HTTP_HEALTH_PATH Standard /health

• HTTP_ALLOWED_ORIGINS optionale, durch Kommas getrennte Liste erlaubter Origins

Beispiel für einen lokalen HTTP-Start:

HTTP_HOST=127.0.0.1 HTTP_PORT=3000 npm run start:http

Dieser Modus ist für lokale oder explizit kontrollierte Umgebungen gedacht. Betrachten Sie den aktuellen HTTP-Einstiegspunkt nicht als produktionsbereit für die öffentliche Nutzung, ohne Authentifizierung und Härtung der Bereitstellung hinzuzufügen.

Beispiele für die Tool-Nutzung

Natürlichsprachliche Abfrage-Erstellung

Konvertieren Sie natürliche Sprache in Scryfall-Syntax:

// Convert natural language to optimized Scryfall query
{
  "tool": "build_scryfall_query",
  "arguments": {
    "natural_query": "blue counterspells in modern under $20",
    "optimize_for": "precision"
  }
}

Generieren Sie budgetfreundliche Abfragen:

// Budget-focused query generation
{
  "tool": "build_scryfall_query",
  "arguments": {
    "natural_query": "aggressive red creatures for standard",
    "optimize_for": "budget",
    "price_budget": {
      "max": 5,
      "currency": "usd"
    }
  }
}

Entdecken Sie interessante Karten:

// Discovery-optimized search
{
  "tool": "build_scryfall_query",
  "arguments": {
    "natural_query": "legendary artifacts that produce mana",
    "format": "commander",
    "optimize_for": "discovery"
  }
}

Abfrageregeln

{
  "tool": "query_rules",
  "arguments": {
    "query": "state-based actions",
    "context_lines": 2
  }
}

Format-Staples suchen

{
  "tool": "search_format_staples",
  "arguments": {
    "format": "commander",
    "role": "ramp",
    "tier": "competitive",
    "limit": 10
  }
}

Alternativen suchen

{
  "tool": "search_alternatives",
  "arguments": {
    "target_card": "Rhystic Study",
    "direction": "cheaper",
    "format": "commander",
    "max_price": 10
  }
}

Synergistische Karten finden

{
  "tool": "find_synergistic_cards",
  "arguments": {
    "focus_card": "Obeka, Splitter of Seconds",
    "synergy_type": "theme",
    "format": "commander",
    "limit": 12
  }
}

Batch-Kartenanalyse

{
  "tool": "batch_card_analysis",
  "arguments": {
    "card_list": ["Sol Ring", "Arcane Signet", "Command Tower"],
    "analysis_type": "prices",
    "currency": "usd",
    "include_suggestions": true
  }
}

Brawl-Commander validieren

{
  "tool": "validate_brawl_commander",
  "arguments": {
    "card_identifier": "Ashiok, Nightmare Muse",
    "format": "brawl"
  }
}

Deckzusammensetzung analysieren

{
  "tool": "analyze_deck_composition",
  "arguments": {
    "deck_list": "4 Lightning Bolt\n4 Monastery Swiftspear\n20 Mountain",
    "format": "modern",
    "strategy": "aggro"
  }
}

Manabasis vorschlagen

{
  "tool": "suggest_mana_base",
  "arguments": {
    "color_requirements": "WUG",
    "format": "commander",
    "strategy": "midrange",
    "budget": "moderate"
  }
}

Karten suchen

// Basic search
{
  "query": "lightning bolt"
}

// Advanced search with Scryfall syntax
{
  "query": "c:red type:instant cmc:1",
  "limit": 10,
  "format": "json"
}

// Format-specific search
{
  "query": "legal:modern type:creature power>=4",
  "order": "cmc"
}

Kartendetails abrufen

// By name
{
  "identifier": "Lightning Bolt"
}

// By set and collector number
{
  "identifier": "dom/123"
}

// By Scryfall ID
{
  "identifier": "f7a99cc1-2b73-4c9c-8de2-9b6c4c1d8f2a"
}

// With specific set
{
  "identifier": "Lightning Bolt",
  "set": "m21"
}

Kartenpreise abrufen

{
  "card_identifier": "f7a99cc1-2b73-4c9c-8de2-9b6c4c1d8f2a",
  "currency": "usd"
}

Zufällige Karte

// Completely random
{}

// Filtered random card
{
  "query": "type:creature",
  "format": "modern"
}

Sets suchen

// All sets
{}

// Filter by type and date
{
  "type": "expansion",
  "released_after": "2020-01-01"
}

Scryfall-Suchsyntax

Der Server unterstützt die vollständige Suchsyntax von Scryfall:

Grundlegende Operatoren

• c:red - Farbe

• type:creature - Typzeile

• set:dom - Set-Code

• cmc:3 - Umgewandelte Manakosten

• power>=4 - Stärke/Widerstandskraft-Vergleiche

• legal:modern - Format-Legalität

Erweiterte Operatoren

• is:commander - Karteneigenschaften

• year:2023 - Erscheinungsjahr

• rarity:mythic - Seltenheit

• artist:"john avon" - Künstlername

• flavor:"text" - Suche nach Flavour-Text

Boolesche Logik

• red OR blue - Eine der Bedingungen

• creature AND red - Beide Bedingungen

• NOT black - Bedingung ausschließen

• (red OR blue) type:instant - Gruppierung

Fehlerbehandlung

Der Server bietet detaillierte Fehlermeldungen für häufige Probleme:

• 404: Karte/Ressource nicht gefunden

• 422: Ungültige Suchsyntax

• 429: Ratenlimit überschritten (automatischer Wiederholungsversuch)

• Validierungsfehler: Fehler bei der Parameter-Validierung

Leistungsüberwachung

Cache-Statistiken

// Get cache performance
server.getCacheStats()

Status der Ratenbegrenzung

// Check rate limiting status
server.getRateLimiterStatus()

Gesundheitsprüfung

// Overall system health
server.healthCheck()

Konfiguration

Umgebungsvariablen

SCRYFALL_USER_AGENT=ScryfallMCPServer/1.0
RATE_LIMIT_MS=100
LOG_LEVEL=info
NODE_ENV=development
# Optional timeouts and health/deep checks
SCRYFALL_TIMEOUT_MS=15000
HEALTHCHECK_DEEP=false
# Bound the internal rate limiter queue
RATE_LIMIT_QUEUE_MAX=500

Cache-Dauern

• Kartensuche: 30 Minuten

• Kartendetails: 24 Stunden

• Kartenpreise: 6 Stunden

• Set-Daten: 1 Woche

• Bulk-Daten: 24 Stunden

Protokollierungskonfiguration

Der Server verwendet Pino für eine leistungsstarke strukturierte Protokollierung mit umfassender Fehlerverfolgung und Überwachung.

Protokollebenen

# Available log levels (default: info)
LOG_LEVEL=trace    # Most verbose - all operations
LOG_LEVEL=debug    # Debug information and performance metrics
LOG_LEVEL=info     # General information (default)
LOG_LEVEL=warn     # Warnings and degraded performance
LOG_LEVEL=error    # Errors only
LOG_LEVEL=fatal    # Critical errors only

Entwicklung vs. Produktionsprotokollierung

Entwicklungsmodus (NODE_ENV=development):

• Schön formatierte, farbige Ausgabe

• Menschenlesbare Zeitstempel

• Hervorhebung von Request-ID und Tool-Name

• Automatische Protokollformatierung für bessere Lesbarkeit

Produktionsmodus (NODE_ENV=production):

• JSON-strukturierte Protokolle für die maschinelle Verarbeitung

• Optimiert für Protokoll-Aggregationssysteme

• Minimaler Overhead für Hochleistungsszenarien

• Kompatibel mit ELK-Stack, Grafana und Überwachungstools

Strukturierte Protokollformate

Alle Protokolle enthalten strukturierten Kontext für Debugging und Überwachung:

{
  "level": "info",
  "time": "2025-01-17T19:32:53.123Z",
  "pid": 12345,
  "hostname": "server-01",
  "service": "scryfall-mcp",
  "version": "1.0.0",
  "requestId": "req_1737145973123_abc123def",
  "toolName": "search_cards",
  "operation": "tool_execution",
  "duration": 245,
  "msg": "Tool execution completed"
}

Request-Korrelation

Jede Anfrage erhält eine eindeutige Korrelations-ID zur Verfolgung über Operationen hinweg:

• Format: req_{timestamp}_{random}

• Verfolgt Tool-Ausführungen, API-Aufrufe und Fehler

• Ermöglicht End-to-End-Request-Tracing

• Automatische Bereinigung alter Korrelationsdaten

Fehlerbehandlung & Überwachung

Fehlerklassifizierung

Der Server implementiert eine umfassende Fehlerbehandlung mit strukturierten Fehlerklassen:

Basis-Fehlertypen:

• MCPError - Basisklasse mit Unterstützung für strukturierte Protokollierung

• ToolExecutionError - Tool-spezifische Ausführungsfehler

• ResourceError - Fehler beim Ressourcenzugriff

• PromptError - Fehler bei der Prompt-Generierung

Domänenspezifische Fehler:

• ScryfallAPIError - Fehler im Zusammenhang mit der Scryfall-API

• RateLimitError - Ratenbegrenzung und Drosselung

• ValidationError - Fehler bei der Eingabevalidierung

Funktionen zur Fehlerüberwachung

Automatische Fehlerverfolgung:

• Überwachung der Fehlerhäufigkeit nach Typ

• Erfassung von Leistungsmetriken

• Verfolgung der Request-Korrelation

• Circuit-Breaker-Muster für API-Fehler

Zugriff auf Überwachungsdaten:

// Get comprehensive monitoring report
const status = server.getStatus();
console.log(status.monitoring);

// Output includes:
// - Error counts by type
// - Performance metrics (avg response times)
// - Request correlation data
// - Health check status

Überwachung der Gesundheitsprüfung

Erweiterte Gesundheitsprüfungen mit detailliertem Servicestatus:

# Health check includes:
# - Cache service status
# - Rate limiter status
# - Scryfall API connectivity
# - Error monitoring metrics
# - Performance statistics

Einrichtung der Produktionsüberwachung

Empfohlener Überwachungs-Stack:

1. Protokoll-Aggregation: ELK-Stack (Elasticsearch, Logstash, Kibana)

2. Metriken: Grafana mit Prometheus

3. Fehlerverfolgung: Sentry mit strukturiertem Fehlerkontext

4. Alarmierung: Basierend auf Fehlerraten und Antwortzeiten

Wichtige zu überwachende Metriken:

• Erfolgs-/Fehlerraten bei der Tool-Ausführung

• Verteilungen der API-Antwortzeiten

• Häufigkeiten von Fehlertypen

• Cache-Treffer-/Fehlverhältnisse

• Status der Ratenbegrenzung

Strategien zur Fehlerwiederherstellung

Automatische Wiederherstellung:

• Exponentielles Backoff bei API-Fehlern

• Circuit Breaker verhindert kaskadierende Ausfälle

• Intelligente Wiederholungslogik mit Jitter

• Elegante Verschlechterung bei Ausfällen

Manuelle Wiederherstellung:

// Reset error monitoring
server.resetRateLimiter();
server.clearCaches();

// Check system health
const health = await server.healthCheck();

Fehlerbehebung

Häufige Probleme

"Rate limit exceeded"

• Der Server handhabt die Ratenbegrenzung automatisch

• Warten Sie einen Moment und versuchen Sie es erneut

• Prüfen Sie, ob Sie zu viele gleichzeitige Anfragen stellen

"Network error: Unexpected token" oder gzip-bezogene Fehler

• Dies wurde in v1.0.2 durch Deaktivierung der gzip-Komprimierung behoben

• Stellen Sie sicher, dass Sie den neuesten Build verwenden: npm run build

• Starten Sie Claude Desktop nach dem Neuerstellen neu

• Der Server fordert jetzt unkomprimierte Antworten an, um Parsing-Probleme zu vermeiden

"Card not found"

• Überprüfen Sie die Schreibweise des Kartennamens

• Versuchen Sie das Format Set-Code + Sammlernummer

• Prüfen Sie, ob die Karte in Scryfall existiert

"Invalid search syntax"

• Überprüfen Sie die Dokumentation der Scryfall-Suchsyntax

• Prüfen Sie auf nicht geschlossene Klammern

• Vermeiden Sie es, Abfragen mit booleschen Oper