mtg-mcp

Минималистичный сервер протокола контекста модели (MCP) на Python, который предоставляет возможности поиска карт Magic: The Gathering (и проверку работоспособности) любому MCP-совместимому LLM-клиенту.

Дополнение к записи в блоге: Учебное пособие по протоколу контекста модели: создайте свой первый сервер

В этой статье подробно рассматривается данный репозиторий: что такое MCP, как работают два инструмента, переход от «фейка первого дня» к «реальному Scryfall второго дня» и как подключить это к Claude Desktop.

Что он делает

Два инструмента, предоставляемые одним процессом Python через MCP stdio:

• health.check — возвращает версию сервера, текущее время UTC и простой счетчик «серии обучения», сохраняемый в streak.json. Самый простой инструмент из возможных. Никаких внешних зависимостей.

• mtg.card_lookup — принимает название карты и возвращает строку типа, текст оракула, мана-стоимость и URL изображения. Вызывает эндпоинт Scryfall для нечеткого поиска по названию.

Контракт для mtg.card_lookup был спроектирован первым; реализация прошла через осознанный переход от фейка к реальности. Полное описание процесса разработки на основе спецификаций см. в docs/01-spec-scryfall-integration.md.

Related MCP server: Scryfall MCP Server

Быстрый старт

git clone https://github.com/jabelk/mtg-mcp.git
cd mtg-mcp
python -m venv .venv
source .venv/bin/activate           # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt
python src/server.py

Сервер по умолчанию работает через stdio и будет ожидать подключения MCP-клиента. Это правильно — укажите клиенту команду python src/server.py (с абсолютными путями), чтобы начать вызов инструментов.

Рекомендуется Python 3.11 или новее. uvloop является опциональным и автоматически пропускается в Windows.

Подключение к Claude Desktop

Добавьте запись в ваш claude_desktop_config.json:

{
  "mcpServers": {
    "mtg": {
      "command": "/absolute/path/to/mtg-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/mtg-mcp/src/server.py"]
    }
  }
}

Используйте абсолютные пути как для интерпретатора, так и для скрипта; Claude Desktop запускает сервер самостоятельно, поэтому ~ или относительный путь не будут распознаны. Полностью закройте Claude Desktop и откройте его снова после сохранения.

Структура репозитория

mtg-mcp/
├── src/
│   ├── server.py            # MCP server entry point — registers the two tools
│   └── tools/
│       ├── __init__.py
│       └── card_lookup.py   # Scryfall integration (Day-2 real implementation)
├── docs/
│   ├── 01-spec-scryfall-integration.md   # spec for the Day-1 → Day-2 swap
│   ├── 02-plan-scryfall-integration.md   # implementation plan
│   └── 03-lessons-learned.md             # retrospective
├── requirements.txt
├── LICENSE
└── README.md

Директория logs/ и файл streak.json создаются во время выполнения.

День 1 → День 2: как развивался этот репозиторий

Первая версия mtg.card_lookup возвращала жестко закодированный фейковый ответ (соответствующий только названию Atraxa). Смысл начала с фейка заключался в проверке связей — того, что MCP-клиент может найти инструмент, вызвать его и разобрать структуру ответа — до отладки любого HTTP-уровня.

Как только связь была подтверждена, та же функция была заменена на вызов Scryfall. Сигнатура функции, схема входных данных и структура возвращаемого значения не изменились. Контракт сохранился. Этот прогресс — главная тема сопутствующей записи в блоге; план замены находится в docs/02-plan-scryfall-integration.md, а ретроспектива — в docs/03-lessons-learned.md.

Зависимости

mcp        # the official MCP Python SDK
uvloop     # faster event loop (skipped on Windows)
httpx      # HTTP client for the Scryfall call

Версии в этом репозитории не зафиксированы. Если вам нужна воспроизводимость, зафиксируйте их при установке.

Лицензия

MIT — Copyright (c) 2026 Jason Belk.

Дополнительное чтение

• Сопутствующая статья: Учебное пособие по протоколу контекста модели: создайте свой первый сервер

• Официальная документация MCP: modelcontextprotocol.io

• Анонс запуска MCP от Anthropic: anthropic.com/news/model-context-protocol

• API Scryfall: scryfall.com/docs/api