Servidor MCP de Scryfall

Un servidor completo del Protocolo de Contexto de Modelo (MCP) que se integra con la API de Scryfall para proporcionar datos y funcionalidades de cartas de Magic: The Gathering a asistentes de IA.

Este repositorio actualmente admite:

• stdio como el transporte estable predeterminado para clientes MCP locales

• Streamable HTTP experimental como un transporte aditivo para flujos de trabajo HTTP locales

El producto principal sigue siendo el mismo en ambos modos: búsqueda respaldada por Scryfall, reglas y flujos de trabajo de construcción de mazos para MTG.

Características

🔧 Herramientas MCP

Construcción de consultas

• build_scryfall_query: Convierte solicitudes en lenguaje natural en consultas de búsqueda optimizadas de Scryfall

  • Entrada: Descripción en lenguaje natural, preferencias de formato, estrategia de optimización

  • Salida: Consulta de Scryfall optimizada con explicación y alternativas

  • Ejemplo: "red creatures under $5 for aggressive decks" → "c:r t:creature usd<=5 pow>=2 cmc<=3"

Herramientas de búsqueda principales

• search_cards: Busca cartas usando la potente sintaxis de búsqueda de Scryfall

• get_card: Obtiene información detallada sobre cartas específicas

• get_card_prices: Recupera datos de precios actuales de las cartas

• random_card: Obtiene cartas aleatorias con filtros opcionales

• search_sets: Busca y filtra colecciones de Magic

Herramientas de descubrimiento y análisis

• query_rules: Busca en las reglas completas de MTG con contexto

• search_format_staples: Encuentra cartas básicas, esenciales y del meta para un formato

• search_alternatives: Encuentra reemplazos económicos, mejoras o cartas similares

• find_synergistic_cards: Descubre piezas de sinergia para una carta, tema o arquetipo

• batch_card_analysis: Analiza múltiples cartas en cuanto a legalidad, precios, sinergia o composición

Herramientas de construcción de mazos

• validate_brawl_commander: Comprueba si una carta es un comandante legal en Brawl o Brawl Estándar

• analyze_deck_composition: Evalúa la curva de maná, la mezcla de cartas, los colores y las recomendaciones a partir de una lista de mazo

• suggest_mana_base: Recomienda recuentos de tierras y paquetes de fijación de maná según los requisitos de color

📚 Recursos MCP

• card-database://bulk: Base de datos completa de cartas de Scryfall con actualizaciones diarias

• set-database://all: Todas las colecciones de Magic con metadatos e iconos

💡 Prompts MCP

• analyze_card: Genera un análisis completo de la carta, incluyendo viabilidad competitiva, sinergias y posicionamiento en el meta

• build_deck: Crea guías de construcción de mazos centradas en cartas específicas

⚡ Características de rendimiento

• Limitación de tasa (Rate Limiting): Respeta los límites de la API de Scryfall con intervalos mínimos de 100ms

• Caché inteligente: Reduce las llamadas a la API en más de un 70% con TTL configurable

• Manejo de errores: Manejo elegante de todas las condiciones de error de la API

• Disyuntor (Circuit Breaker): Previene fallos en cascada durante las interrupciones de la API

🔍 Sistema de validación simple

• Validación ligera: Validación básica de la sintaxis de consulta con mensajes de error útiles

• Comprobaciones esenciales: Paréntesis equilibrados, comillas y errores de sintaxis comunes

• Reconocimiento de operadores: Valida operadores conocidos de Scryfall con sugerencias para errores tipográficos

• Optimizado para el rendimiento: Validación rápida con una sobrecarga mínima

Related MCP server: API Tester MCP Server

Instalación

Requisitos previos

• Node.js 18+

• npm o yarn

Configuración

1. Clonar el repositorio

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

2. Instalar dependencias

   npm install

3. Configurar el entorno (opcional)

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

4. Construir el proyecto

   npm run build

Uso

Modos de transporte

STDIO (predeterminado estable)

Utilice stdio para clientes MCP locales como Claude Desktop, Codex y MCP Inspector. Este sigue siendo el transporte principal y mejor soportado.

npm run dev

npm start

Streamable HTTP (experimental)

Un punto de entrada HTTP aditivo está disponible para el uso de Streamable HTTP local.

npm run dev:http

npm run start:http

Pruebas

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

Inspector MCP

npm run inspector

Estado del transporte HTTP

El soporte HTTP es actualmente experimental.

Lo que significa:

• stdio sigue siendo el predeterminado recomendado

• HTTP es aditivo, no un reemplazo

• la implementación sigue la ruta de transporte oficial Streamable HTTP de MCP

• la primera implementación es intencionalmente local y de alcance conservador

Comportamiento HTTP actual:

• se vincula a 127.0.0.1 por defecto

• expone POST|GET|DELETE /mcp

• expone GET /health

• rechaza encabezados Origin de estilo navegador que no sean de bucle local (loopback) por defecto

• se puede configurar con HTTP_ALLOWED_ORIGINS cuando se necesite intencionalmente una política de origen diferente

Objetivos no actuales:

• guía de despliegue en internet público

• middleware de autenticación o endurecimiento de producción alojado

• reemplazar ejemplos de stdio en todo el repositorio

Si necesita un modelo de despliegue público, trate el soporte HTTP actual como una base en lugar de una solución de alojamiento terminada.

Documentación del proyecto

• CONTRIBUTING.md

• SECURITY.md

• SCRYFALL_COMPLIANCE.md

Integración con Claude Desktop

Agregue lo siguiente a su archivo de configuración de Claude Desktop:

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"]
    }
  }
}

Reemplace /absolute/path/to/scryfall-mcp con la ruta real a su instalación.

Configuración HTTP

Variables de entorno HTTP opcionales:

• HTTP_HOST predeterminado 127.0.0.1

• HTTP_PORT predeterminado 3000

• HTTP_MCP_PATH predeterminado /mcp

• HTTP_HEALTH_PATH predeterminado /health

• HTTP_ALLOWED_ORIGINS lista de permitidos de origen opcional separada por comas

Ejemplo de inicio de HTTP local:

HTTP_HOST=127.0.0.1 HTTP_PORT=3000 npm run start:http

Este modo está destinado a entornos locales o controlados explícitamente. No trate el punto de entrada HTTP actual como una exposición pública lista para producción sin agregar autenticación y endurecimiento de despliegue.

Ejemplos de uso de herramientas

Construcción de consultas en lenguaje natural

Convertir lenguaje natural a sintaxis de Scryfall:

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

Generar consultas económicas:

// 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"
    }
  }
}

Descubrir cartas interesantes:

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

Reglas de consulta

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

Buscar cartas básicas de formato

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

Buscar alternativas

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

Encontrar cartas sinérgicas

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

Análisis de cartas por lotes

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

Validar comandante de Brawl

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

Analizar composición de mazo

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

Sugerir base de maná

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

Buscar cartas

// 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"
}

Obtener detalles de la carta

// 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"
}

Obtener precios de la carta

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

Carta aleatoria

// Completely random
{}

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

Buscar colecciones

// All sets
{}

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

Sintaxis de búsqueda de Scryfall

El servidor admite la sintaxis de búsqueda completa de Scryfall:

Operadores básicos

• c:red - Color

• type:creature - Línea de tipo

• set:dom - Código de colección

• cmc:3 - Coste de maná convertido

• power>=4 - Comparaciones de fuerza/resistencia

• legal:modern - Legalidad de formato

Operadores avanzados

• is:commander - Propiedades de la carta

• year:2023 - Año de lanzamiento

• rarity:mythic - Rareza

• artist:"john avon" - Nombre del artista

• flavor:"text" - Búsqueda de texto de ambientación

Lógica booleana

• red OR blue - Cualquiera de las condiciones

• creature AND red - Ambas condiciones

• NOT black - Excluir condición

• (red OR blue) type:instant - Agrupación

Manejo de errores

El servidor proporciona mensajes de error detallados para problemas comunes:

• 404: Carta/recurso no encontrado

• 422: Sintaxis de búsqueda no válida

• 429: Límite de tasa excedido (reintento automático)

• Errores de validación: Fallos en la validación de parámetros

Monitoreo de rendimiento

Estadísticas de caché

// Get cache performance
server.getCacheStats()

Estado del limitador de tasa

// Check rate limiting status
server.getRateLimiterStatus()

Verificación de estado (Health Check)

// Overall system health
server.healthCheck()

Configuración

Variables de entorno

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

Duraciones de caché

• Búsqueda de cartas: 30 minutos

• Detalles de cartas: 24 horas

• Precios de cartas: 6 horas

• Datos de colecciones: 1 semana

• Datos masivos: 24 horas

Configuración de registro (Logging)

El servidor utiliza Pino para un registro estructurado de alto rendimiento con seguimiento y monitoreo integral de errores.

Niveles de registro

# 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

Registro de desarrollo vs producción

Modo de desarrollo (NODE_ENV=development):

• Salida impresa y coloreada

• Marcas de tiempo legibles por humanos

• Resaltado de ID de solicitud y nombre de herramienta

• Formato de registro automático para legibilidad

Modo de producción (NODE_ENV=production):

• Registros estructurados en JSON para procesamiento por máquina

• Optimizado para sistemas de agregación de registros

• Sobrecarga mínima para escenarios de alto rendimiento

• Compatible con ELK Stack, Grafana y herramientas de monitoreo

Formato de registro estructurado

Todos los registros incluyen contexto estructurado para depuración y monitoreo:

{
  "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"
}

Correlación de solicitudes

Cada solicitud obtiene un ID de correlación único para el seguimiento a través de las operaciones:

• Formato: req_{timestamp}_{random}

• Rastrea ejecuciones de herramientas, llamadas a la API y errores

• Permite el seguimiento de solicitudes de extremo a extremo

• Limpieza automática de datos de correlación antiguos

Manejo de errores y monitoreo

Clasificación de errores

El servidor implementa un manejo integral de errores con clases de error estructuradas:

Tipos de error base:

• MCPError - Clase base con soporte para registro estructurado

• ToolExecutionError - Fallos de ejecución específicos de la herramienta

• ResourceError - Fallos de acceso a recursos

• PromptError - Fallos de generación de prompts

Errores específicos del dominio:

• ScryfallAPIError - Errores relacionados con la API de Scryfall

• RateLimitError - Limitación de tasa y estrangulamiento

• ValidationError - Fallos de validación de entrada

Características de monitoreo de errores

Seguimiento automático de errores:

• Monitoreo de frecuencia de errores por tipo

• Recopilación de métricas de rendimiento

• Seguimiento de correlación de solicitudes

• Patrón de disyuntor para fallos de API

Acceso a datos de monitoreo:

// 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

Monitoreo de verificación de estado

Verificaciones de estado mejoradas con estado detallado del servicio:

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

Configuración de monitoreo de producción

Stack de monitoreo recomendado:

1. Agregación de registros: ELK Stack (Elasticsearch, Logstash, Kibana)

2. Métricas: Grafana con Prometheus

3. Seguimiento de errores: Sentry con contexto de error estructurado

4. Alertas: Basadas en tasas de error y tiempos de respuesta

Métricas clave a monitorear:

• Tasas de éxito/fallo de ejecución de herramientas

• Distribuciones de tiempo de respuesta de la API

• Frecuencias de tipo de error

• Ratios de aciertos/fallos de caché

• Estado del limitador de tasa

Estrategias de recuperación de errores

Recuperación automática:

• Retroceso exponencial para fallos de API

• El disyuntor evita fallos en cascada

• Lógica de reintento inteligente con fluctuación (jitter)

• Degradación elegante durante las interrupciones

Recuperación manual:

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

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

Solución de problemas

Problemas comunes

"Rate limit exceeded"

• El servidor maneja automáticamente la limitación de tasa

• Espere un momento e inténtelo de nuevo

• Compruebe si está realizando demasiadas solicitudes simultáneas

"Network error: Unexpected token" o errores relacionados con gzip

• Esto se solucionó en v1.0.2 deshabilitando la compresión gzip

• Asegúrese de estar utilizando la última compilación: npm run build

• Reinicie Claude Desktop después de reconstruir

• El servidor ahora solicita respuestas sin comprimir para evitar problemas de análisis

"Card not found"

• Verifique la ortografía del nombre de la carta

• Intente usar el formato de código de colección + número de coleccionista

• Compruebe si la carta existe en Scryfall

"Invalid search syntax"

• Revise la documentación de sintaxis de búsqueda de Scryfall

• Compruebe si hay paréntesis sin cerrar

• Evite comenzar las consultas con operadores booleanos

La integración de Claude Desktop no funciona

• Verifique la ruta absoluta en la configuración

• Asegúrese de que el servidor se compile correctamente

• Compruebe los registros de Claude Desktop en busca de errores

Modo de depuración

LOG_LEVEL=debug npm run dev

Borrar caché

# Programmatically
server.clearCaches()

# Or restart the server

Contribución

1. Bif