MTGDecks Metagame MCP

PoC на Python/MCP, который читает публичные страницы MTGDecks.net и нормализует информацию о метагейме и колодах в единый формат JSON.

Поскольку документированного публичного API не обнаружено, используются публичный HTML сайта и фильтры на основе URL. Вход в браузере или cookies не требуются.

Предоставляемые функции

get_metagame(
    format: str,
    source: str = "all",
)

get_recent_decks(
    format: str,
    platform: str | None = None,
    game_type: str | None = None,
    max_pages: int = 3,
)

get_archetype_decks(
    format: str,
    archetype: str,
    limit: int = 20,
)

get_top_performing_decks(
    format: str,
    platform: str | None = None,
    min_players: int | None = None,
    limit: int = 20,
)

Каждая функция доступна и как функция Python, и как инструмент MCP.

Related MCP server: Mystic Forge

Требования

• Python 3.10 или новее

• Рекомендуется uv

Установка

git clone <repository-url>
cd Metagame-MCP
uv sync

Чтобы установить также зависимости для разработки и тестирования, используйте следующую команду.

uv sync --extra dev

Запуск MCP-сервера

Сервер по умолчанию запускается с транспортом stdio.

uv run mtgdecks-mcp

Пример настройки MCP-хоста приведён ниже. Значение cwd необходимо заменить на фактический абсолютный путь к этому репозиторию.

{
  "mcpServers": {
    "mtgdecks": {
      "command": "uv",
      "args": ["run", "mtgdecks-mcp"],
      "cwd": "C:\\path\\to\\Metagame-MCP"
    }
  }
}

Регистрируются следующие четыре инструмента MCP:

• get_metagame

• get_recent_decks

• get_archetype_decks

• get_top_performing_decks

Использование из Python

from mtgdecks_mcp import (
    get_archetype_decks,
    get_metagame,
    get_recent_decks,
    get_top_performing_decks,
)

metagame = get_metagame("Modern", source="mtgo")

recent = get_recent_decks(
    "Modern",
    platform="mtgo",
    game_type="BO3",
    max_pages=1,
)

archetype = get_archetype_decks(
    "Modern",
    "Boros Energy",
    limit=5,
)

top = get_top_performing_decks(
    "Modern",
    platform="mtgo",
    min_players=64,
    limit=10,
)

При многократных запросах эффективнее использовать клиент напрямую, чтобы переиспользовать HTTP-соединения.

from mtgdecks_mcp import MTGDecksClient

with MTGDecksClient() as client:
    modern = client.get_metagame("Modern")
    pioneer = client.get_metagame("Pioneer")

Аргументы

format

Название формата, используемое на MTGDecks.net. Например: Standard, Pioneer, Modern, Legacy, Pauper, Commander, Duel-Commander.

source

mtgo-events, major-events, recent-major-events также можно использовать как псевдонимы.

platform

• mtgo

• arena

• tabletop

Регистр не учитывается.

game_type

• BO1

• BO3

Регистр не учитывается.

Ограничения диапазона запроса

• max_pages: 1~10

• limit: 1~100

• min_players: положительное целое число

Структура ответа

Метагейм

{
  "format": "Modern",
  "source": "all",
  "url": "https://mtgdecks.net/Modern",
  "selected_deck_count": 10994,
  "updated_at": "2026-08-21 06:47:39",
  "archetypes": [
    {
      "name": "Boros Energy",
      "url": "https://mtgdecks.net/Modern/boros-energy",
      "meta_share_percent": 7.98,
      "trend_percent": -2.85,
      "tier": "A",
      "win_rate_percent": 49.0,
      "top_25_conversion": 0.95,
      "deck_count": 877,
      "price_usd": 1109.0
    }
  ]
}

Список колод

Функции получения колод общим образом возвращают pages и decks. В pages содержатся URL исходных страниц, которые фактически были запрошены.

{
  "format": "Modern",
  "pages": ["https://mtgdecks.net/Modern/decklists/page:1"],
  "decks": [
    {
      "name": "deck",
      "url": "https://mtgdecks.net/Modern/example-decklist-123",
      "author": "Player",
      "archetype": "Boros Energy",
      "game_type": "BO3",
      "platform": "mtgo",
      "event": "MTGO Modern Challenge",
      "event_level": 3,
      "players": 94,
      "spiciness_percent": 30.0,
      "date": "2026-08-20",
      "price_usd": 1112.0,
      "placement": "1st",
      "wins": 5,
      "losses": 0,
      "draws": 0,
      "win_rate_percent": 100.0
    }
  ]
}

Поля, для которых страницы MTGDecks не предоставляют значений, могут быть null. Цены указаны в долларах США по Paper/TCGPlayer со страницы.

get_top_performing_decks не вычисляет собственную оценку результативности, а использует сортировку MTGDecks по возрастанию rank. Поэтому сначала возвращаются колоды с лучшими результатами на событиях — победы, вторые места, Top 8 и т. д.

Тестирование

uv run pytest

Тесты не обращаются к внешним сайтам: используются сохранённые примеры HTML и httpx.MockTransport.

Структура проекта

src/mtgdecks_mcp/
├── __init__.py   # 공개 Python API
├── parsers.py    # MTGDecks HTML 정규화
├── server.py     # MCP 도구 등록과 stdio 서버
└── service.py    # URL 구성, HTTP 클라이언트, 네 가지 기능

tests/
├── test_parsers.py
└── test_service.py

Ограничения и условия использования

• Этот проект зависит от публичной структуры HTML, поэтому при изменении разметки или путей MTGDecks.net может потребоваться доработка парсера.

• Массовый краулинг, параллельный сбор, кэширование/персистентность в базе данных не входят в объём PoC.

• Точность и доступность исходных данных зависят от MTGDecks.net.

• Все нормализованные результаты содержат отслеживаемый исходный URL.

• Условия использования MTGDecks ограничивают контент личным и некоммерческим использованием. Прежде чем расширять проект до коммерческого сервиса или постоянного массового сбора, получите разрешение от MTGDecks или оформите партнёрство по API.

Связанный документ: Условия использования MTGDecks