Commander Workshop MCP

Commander Workshop — это локально-ориентированный MCP-сервер для сборки, проверки, сравнения и комплектации колод Magic: The Gathering Commander. Он объединяет закреплённые правила и данные о картах с вашей явно импортированной коллекцией, отделяет намерение собрать колоду от владения и превращает готовый план в извлечения, замены, субституты, прокси или покупки.

Сервер полезен для свободного бревинга, конструирования с учётом инвентаря, планирования для Bracket 3 и апгрейдов преконов с фиксированным бюджетом. Он оценивает ограниченные полные кандидаты и сообщает лучший найденный при данных ограничениях, а не претендует на универсальную оценку силы или математически идеальную колоду.

Возможности

Related MCP server: MTG-MCP

Обещание конфиденциальности

Ваши коллекции, названия папок, местоположения и распределения физических колод по умолчанию остаются локальными. Локальный импорт ограничен настроенными корневыми каталогами. Сервер не отправляет колоды, не изменяет коллекции, не резервирует карты, не добавляет товары в корзину маркетплейса и не завершает покупки. Опциональное ценообразование маркетплейса отправляет только минимальные требования к тиражам и читает учётные данные из окружения или защищённого хранилища MCP-хоста.

Установка

Commander Workshop требует Python 3.11 или новее. Из клонированного репозитория:

python -m venv .venv
. .venv/bin/activate
python -m pip install -e .

V1 в настоящее время поддерживает только файловые системы POSIX. Его неизменяемые пути публикации требуют дескрипторов каталогов, O_DIRECTORY, O_NOFOLLOW, жёстких ссылок, fsync и консультативных блокировок; Windows не поддерживается. Сервер stdio также ожидает проверенные локальные входные данные, подготовленные далее.

Настройка каталога и правил

V1 намеренно не выполняет сетевых запросов при запуске сервера. Загрузите gzip Scryfall Default Cards JSONL через документированный API массовых данных Scryfall, подготовьте пакет правил из пяти файлов, указанный в docs/rules-bundle.md, затем выполните проверенную команду офлайн-загрузки:

.venv/bin/commander-workshop-bootstrap \
  --data-dir /absolute/path/to/commander-workshop-data \
  --catalog-jsonl-gz /absolute/path/to/default-cards.jsonl.gz \
  --catalog-url https://data.scryfall.io/default-cards.jsonl.gz \
  --catalog-retrieved-at 2026-08-15T12:00:00+00:00 \
  --rules-bundle /absolute/path/to/rules-bundle

Используйте фактический URL загрузки и время получения. --data-dir — это безопасный корень установки; он может уже содержать посторонние файлы, которые загрузчик никогда не удаляет и не перезаписывает. Команда проверяет gzip и правила, создаёт среду с адресацией по содержимому в environments/<sha256> и публикует атомарный маркер READY только после того, как полное представление станет долговечным. Повторная попытка восстанавливает точную неполную среду и возвращает ту же версию. Опубликованные файлы каталога и правил являются эксклюзивными байтовыми копиями без сохранённых псевдонимов стадий. Символические ссылки во входных данных, псевдонимы жёстких ссылок, неожиданные побочные файлы и конфликтующее существующее содержимое приводят к отказу.

Перед сборкой загрузчик обнаруживает полностью проверенную среду READY по её версионированной идентичности входных данных, поэтому обычные повторные попытки с теми же входными данными не создают новую стадию. Неудачные стадии инертны и могут оставаться для ручной проверки; загрузчик никогда рекурсивно не удаляет содержимое стадии, которое он больше не может подтвердить как своё.

Выведенный каталог данных остаётся изменяемым корнем установки, где записи MCP записываются в records/. Выведенные пути к каталогу и правилам указывают на подтверждённую готовую версию. Используйте все три значения вместе; каталоги без действительного маркера READY являются неполным состоянием загрузки и никогда не возвращаются.

После загрузки установите COMMANDER_WORKSHOP_IMPORT_ROOTS в один или несколько существующих абсолютных каталогов и используйте выведенные значения для остальных переменных. Отсутствующий, устаревший или недействительный критический источник приводит к отказу. См. руководство по архитектуре для описания потока данных.

Конфигурация для Claude, Codex и общего stdio

Для Claude Desktop или другого хоста, использующего общую JSON-форму, скопируйте examples/mcp-config.json и замените его абсолютные пути-заполнители.

Codex может использовать тот же исполняемый файл из config.toml:

[mcp_servers.commander_workshop]
command = "/absolute/path/to/commander-workshop-mcp/.venv/bin/commander-workshop-mcp"
args = []

[mcp_servers.commander_workshop.env]
COMMANDER_WORKSHOP_DATA_DIR = "/absolute/install-root"
COMMANDER_WORKSHOP_CATALOG_CURRENT = "/absolute/install-root/environments/<printed-sha256>/catalog/current.json"
COMMANDER_WORKSHOP_RULESET = "/absolute/install-root/environments/<printed-sha256>/rules/current.json"
COMMANDER_WORKSHOP_IMPORT_ROOTS = "/absolute/path/to/imports"

Любой клиент MCP v2 может запустить этот абсолютный исполняемый файл виртуального окружения как локальный подпроцесс stdio с этими переменными окружения. В v1 нет HTTP-сервиса или настройки учётной записи. Установка через pipx также возможна: используйте абсолютный путь, возвращаемый pipx environment --value PIPX_BIN_DIR, объединённый с commander-workshop-mcp.

Сквозной пример: свободный бревинг

1. Используйте search_cards для просмотра закреплённого каталога и load_deck для каждой полной колоды-кандидата, созданной в процессе бревинга.

2. Вызовите plan_deck с операцией build, пулом карт all_legal, желаемыми параметрами bracket/theme/proxy и от одной до восьми полных заявок кандидатов. Прочитайте возвращённый ресурс commander://plans/....

3. Опционально загрузите коллекцию, вызовите resolve_availability для выигрышного плана, затем вызовите create_fulfillment_plan. Доступность остаётся гипотетической; комплектация выделяет копию только внутри этого неизменяемого результата.

Этот поток не ограничен инвентарём во время бревинга, но всё же может показать, что есть в наличии и чего не хватает, прежде чем пользователь решит действовать. Полный шаблон запроса plan_deck проверяется по схеме набором приёмочных тестов.

Сквозной пример: конструирование только из своих карт

1. Экспортируйте физическую коллекцию как CSV ManaBox или CSV с явным сопоставлением столбцов, затем вызовите load_collection_snapshot в строгом режиме.

2. Используйте search_library для поиска карт-кандидатов по имени, тиражу, папке или распределению в собранной колоде.

3. Вызовите plan_deck с пулом карт owned_only и идентификатором снимка коллекции. Кандидат с не принадлежащей вам небазовой картой не проходит жёсткое ограничение.

4. Прочитайте ресурсы плана и доступности, чтобы увидеть извлечения из папок и конфликты. Копия, уже выделенная в колоду, сообщается, а не молча считается свободной.

Используйте полный шаблон запроса только из своих карт после замены его идентификаторов колоды и коллекции на результаты предыдущих инструментов.

Сквозной пример: апгрейд прекона Bracket 3 на 50 USD/EUR

1. Экспортируйте или вставьте прекон и вызовите load_deck; это остаётся намерением собрать колоду, а не заявлением о владении.

2. Загрузите полные улучшенные кандидаты и вызовите plan_deck с операцией upgrade, преконом как starting_deck_id, Bracket 3 и семантикой пресета сценария precon-upgrade-50-usd или precon-upgrade-50-eur.

3. Проверьте точные добавления/удаления, датированные доказательства bracket, Game Changers, факты темы и гарантированную границу приобретения в местной валюте. Отсутствие требуемых ценовых доказательств не позволяет пройти лимит как ноль.

4. Опционально разрешите инвентарь, выберите извлечения/замены/субституты/прокси с помощью create_fulfillment_plan, затем вызовите price_purchases для оставшихся позиций покупки. Ценообразование носит информационный характер и никогда не размещает заказ.

Шаблон запроса на 50 USD содержит полный сценарий, доказательства кандидатов, определения оценок, политику bracket и поле начальной колоды. Измените и валюту, и общую политику для пресета EUR.

Поддерживаемые импорты

• CSV коллекции ManaBox, разделяющий физические папки и зарегистрированные колоды от списков желаний или других невладельческих списков.

• Общий CSV коллекции с явным сопоставлением количества и точной идентичности карты, плюс опциональные поля тиража и местоположения.

• Текст колоды в стиле Arena и общий формат количество/название/сет/коллекционный номер.

• Экспортированный пользователем текст колоды из Moxfield, Archidekt, Deckbox, Deckstats, TopDecked и подобных хостов, если он соответствует поддерживаемому диалекту текста.

Вставьте или выберите экспорт, который вы уполномочены использовать. V1 не сканирует страницы учётных записей, не использует повторно куки браузера и не вызывает недокументированные конечные точки хостов колод. Прямые URL-адреса хостов возвращают unsupported_source; экспортируйте колоду и импортируйте её текст.

Инструменты

Публичная поверхность состоит ровно из одиннадцати инструментов:

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

Ресурсы

commander://cards/{oracle_id}
commander://searches/{result_id}
commander://collections/{snapshot_id}
commander://decks/{deck_id}
commander://plans/{plan_id}
commander://availability/{resolution_id}
commander://prices/{snapshot_id}
commander://fulfillment/{plan_id}
commander://rules/current
commander://presets

Записи неизменяемы и адресуются по содержимому. Коллекции и широкие поиски ограничены и разбиты на страницы; сводки инструментов избегают повторения содержимого коллекций.

Измерения сценария

Планируемый сценарий объединяет следующие независимые выборы:

• операция: build, upgrade или analyze;

• bracket: от 1 до 5, с датированными доказательствами хода и Game Changer;

• пул карт: all_legal, prefer_owned или owned_only;

• бюджет: общая сумма в местной валюте и опциональный лимит на карту, включая пресеты апгрейда прекона на 50 USD/EUR;

• политика прокси: none, owned-once или unlimited, если игровая группа это разрешает;

• политика темы: strict contract, flexible preference или strength-oriented;

• защищённые собранные колоды, закреплённый набор правил и детерминированное зерно.

Соответствие скобкам и стратегическая сила не сводятся к одной оценке. Официальные правила Commander остаются авторитетными, а переопределения Rule Zero должны быть явными.

Семантика ценообразования

price_purchases разделяет промежуточную сумму товаров, промежуточную сумму поставщика, стоимость доставки и расчетную итоговую стоимость с учетом доставки. Неизвестные товары или стоимость доставки остаются null, никогда не ноль. Гарантированный бюджет может быть пройден только тогда, когда каждая необходимая покупка имеет подходящие известные доказательства в рамках выбранной политики.

Значения каталога Scryfall являются ориентировочными наблюдениями PriceEstimate, а не ценами при оформлении заказа. Списки CardTrader — это наблюдения PurchaseQuote только для чтения. Плановые оценки используют заявленное окно свежести не более 24 часов; CardTrader может использовать более короткий срок жизни списка. Частичные и устаревшие наблюдения содержат явные проблемы unknown_price, аутентификации, сбоя или ограничения скорости.

Ограничения провайдеров

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

• CardTrader является опциональным, требует CARDTRADER_API_TOKEN, использует только фиксированные документированные конечные точки GET, не следует перенаправлениям и не оптимизирует идеальную корзину от нескольких продавцов.

• Cardmarket и TCGplayer не включены по умолчанию; любые будущие адаптеры должны соблюдать ограничения доступа и условия провайдеров.

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

Обычные тесты и CI не выполняют запросов к живым торговым площадкам или хостингам колод.

Разработка

python -m pip install -e '.[test]'
python scripts/check_public_tree.py
ruff check src tests scripts
pytest -q
python -m build

Сканер конфиденциальности проверяет отслеживаемое дерево на наличие частных путей, учетных данных, баз данных, небезопасных экспортов данных, символических ссылок и недокументированных/чрезмерно больших фикстур. Все тестовые данные являются синтетическими и детерминированными.

Архитектура

Смотрите docs/architecture.md для получения информации о границах компонентов, неизменяемом хранилище, границах доверия, потоке планирования/выполнения и точках расширения.

Сообщение об уязвимостях

Следуйте SECURITY.md. Используйте частное уведомление о безопасности и минимальное синтетическое воспроизведение; никогда не прикрепляйте экспорт коллекции, инвентарь папок, токен или другие личные данные.

Атрибуция

Названия карт, текст правил и метаданные каталога могут быть получены из Scryfall, чьи требования к данным и атрибуции применяются. Правила Magic: The Gathering и политика скобок Commander опубликованы Wizards of the Coast. Названия провайдеров и данные торговых площадок остаются собственностью их соответствующих владельцев.

Отсутствие аффилиации

Commander Workshop MCP — это неофициальное фанатское программное обеспечение. Оно не аффилировано, не одобрено, не спонсировано и не утверждено Wizards of the Coast, Scryfall, CardTrader или любым другим хостингом колод или торговой площадкой. Magic: The Gathering, Commander и связанные с ними товарные знаки принадлежат Wizards of the Coast и их соответствующим владельцам.

Commander Workshop MCP — это неофициальный фанатский контент, разрешенный в соответствии с Политикой фанатского контента. Не одобрено/не поддержано Wizards. Части используемых материалов являются собственностью Wizards of the Coast. ©Wizards of the Coast LLC.

Лицензия

Программное обеспечение выпущено под лицензией MIT. Сторонние данные о картах, правилах и торговых площадках остаются подчиненными своим собственным условиям и лицензиям.