Scryfall MCP Server

MCP-сервер на базе Scryfall для поиска карт Magic: The Gathering, просмотра правил, цен, поиска сетов и рабочих процессов по составлению колод.

В настоящее время проект поддерживает:

• stdio в качестве основного транспорта для локальных MCP-клиентов

• локальный потоковый HTTP через src/http.ts

• 14 инструментов MCP, 2 ресурса и 2 промпта

Что он предоставляет

Инструменты

• search_cards: Выполнение поиска карт Scryfall с постраничным выводом, сортировкой и опциональной фильтрацией по цене.

• get_card: Получение одной карты по имени, сету/коллекционному номеру или ID Scryfall.

• get_card_prices: Возврат данных о ценах с опциональным контекстом формата и альтернативами.

• random_card: Получение случайной карты с опциональными фильтрами.

• search_sets: Поиск и фильтрация сетов Magic.

• query_rules: Поиск по локальному файлу полных правил с контекстом.

• build_scryfall_query: Преобразование естественного языка в понятный запрос Scryfall.

• search_format_staples: Поиск стейплов и ключевых карт для формата.

• search_alternatives: Поиск более дешевых, улучшенных или похожих карт.

• find_synergistic_cards: Поиск синергичных карт для конкретной карты, темы или архетипа.

• batch_card_analysis: Анализ нескольких карт на легальность, цены, синергию или состав.

• validate_brawl_commander: Проверка легальности командира в форматах Brawl и Standard Brawl.

• analyze_deck_composition: Оценка списков колод на кривую маны, цвета и структурные проблемы.

• suggest_mana_base: Рекомендация количества земель и пакетов стабилизации на основе цветовых требований.

Ресурсы

• card-database://bulk: Кэшированный полный снимок Oracle.

• set-database://all: Кэшированный снимок списка сетов.

Промпты

• analyze_card

• build_deck

Related MCP server: MTG-MCP

Транспорты

STDIO

Рекомендуется для Claude Desktop, Codex, MCP Inspector и большинства локальных MCP-клиентов.

npm run dev

npm start

Потоковый HTTP

Доступен как отдельная точка входа для локальных или контролируемых сред.

npm run dev:http

npm run start:http

Для локального тестирования MCP:

npm run dev:http:local
npm run smoke:http

Дымовой тест проверяет /health, выполняет initialize в MCP, отправляет notifications/initialized и проверяет tools/list. Он также выполняет репрезентативные вызовы инструментов validate_brawl_commander и search_cards, чтобы проверить локальную HTTP-точку доступа помимо простого обнаружения.

Текущее поведение HTTP:

• по умолчанию привязывается к 127.0.0.1

• обслуживает POST|GET|DELETE по пути /mcp

• обслуживает GET /health

• по умолчанию отклоняет заголовки Origin, не относящиеся к loopback, если не задан HTTP_ALLOWED_ORIGINS

HTTP-точка входа полезна сегодня, но документация по ней пока носит консервативный характер. Она не представлена здесь как решение для публичного хостинга.

Настройка

Предварительные требования

• Node.js 18+

• npm

Установка

git clone https://github.com/bmurdock/scryfall-mcp.git
cd scryfall-mcp
npm install
cp .env.example .env

Проверка

npm run lint
npm run type-check
npm test

Сборка

npm run build

Общие команды

npm run dev
npm run dev:http
npm start
npm run start:http
npm test
npm run test:watch
npm run test:ui
npm run lint
npm run type-check
npm run inspector

Конфигурация

См. .env.example для канонических значений. Основные переменные, используемые в работе:

• SCRYFALL_USER_AGENT

• RATE_LIMIT_MS

• RATE_LIMIT_QUEUE_MAX

• SCRYFALL_TIMEOUT_MS

• CACHE_MAX_SIZE

• CACHE_MAX_MEMORY_MB

• LOG_LEVEL

• NODE_ENV

• HEALTHCHECK_DEEP

• HTTP_HOST

• HTTP_PORT

• HTTP_MCP_PATH

• HTTP_HEALTH_PATH

• HTTP_ALLOWED_ORIGINS

Операционные заметки:

• Вызовы API Scryfall глобально сериализуются общим ограничителем частоты запросов (rate limiter). Пакетные инструменты могут планировать несколько локальных поисков, но завершение запросов к вышестоящему Scryfall по дизайну остается последовательным.

• Ответы HTTP 429 не повторяются автоматически. Сервер записывает окно ограничения Scryfall и задерживает начало следующего запроса, чтобы вызывающая сторона могла решить, стоит ли повторять попытку.

• CACHE_MAX_MEMORY_MB контролирует, могут ли сохраняться большие снимки в памяти, включая card-database://bulk. Слишком большие снимки все еще могут быть возвращены для текущего чтения, но метаданные будут сообщать, что они не были кэшированы.

• Анализ списка колоды сначала точно сопоставляет имена карт, затем переходит к нечеткому поиску при отсутствии точных совпадений и сообщает о любых нечетких разрешениях в ответе.

• Инструменты для работы с колодами могут возвращать частичный анализ или явное сообщение о необходимости повторной попытки, если Scryfall ограничивает базовые поиски карт.

Пример запуска локального HTTP:

HTTP_HOST=127.0.0.1 HTTP_PORT=3000 npm run start:http

Примеры вызова инструментов

build_scryfall_query

{
  "natural_query": "blue counterspells under $20 for modern",
  "optimize_for": "precision"
}

search_cards

{
  "query": "c:r t:instant mv=1",
  "limit": 10,
  "order": "name"
}

search_sets

{
  "type": "expansion",
  "released_after": "2020-01-01"
}

find_synergistic_cards

{
  "focus_card": "Obeka, Splitter of Seconds",
  "synergy_type": "theme",
  "format": "commander",
  "color_identity": "UBR",
  "limit": 12
}

Для рабочих процессов, подобных командиру, передавайте color_identity, когда фокус направлен на тему, а не на конкретную карту. Когда фокус разрешается в карту, инструмент выводит цветовую идентичность этой карты и фильтрует конечные результаты по запрошенной легальности, доступности в Arena и цветовой идентичности.

analyze_deck_composition

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

Интеграция с Claude Desktop

Добавьте собранную точку входа stdio в конфигурацию 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"]
    }
  }
}

Операционные заметки

• Ограничение частоты запросов (rate limiting) принудительно выполняется внутри процесса с минимальным интервалом по умолчанию в 100 мс между запросами к Scryfall.

• Ответы на поиск, детали карт, цены, сеты и полные снимки кэшируются с ограниченными лимитами памяти.

• Ресурс полных карт хранит предварительно сериализованный снимок, чтобы повторные чтения были дешевыми.

• Фильтрация сетов основана на одном каноническом кэшированном наборе данных /sets, чтобы избежать некорректного повторного использования отфильтрованного кэша.

• Проверки работоспособности доступны через ScryfallMCPServer.healthCheck() и HTTP-эндпоинт /health.

• Если коннектор MCP сообщает об ошибке десериализации JSON-RPC/SSE, сравните ее с необработанным путем дымового теста HTTP:

npm run dev:http:local
npm run smoke:http

Если команда дымового теста проходит успешно, захватите текст ошибки коннектора и вывод дымового теста вместе; это отделит локальное формирование эндпоинта от парсинга, специфичного для коннектора.

Карта документации

Текущие источники достоверной информации:

• PURPOSE.md

• CONTRIBUTING.md

• SECURITY.md

• SCRYFALL_COMPLIANCE.md

Лицензия

MIT