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은 서버 시작 시 의도적으로 네트워크 요청을 하지 않습니다. Scryfall의 문서화된 대량 데이터 API를 통해 Scryfall Default Cards JSONL gzip을 다운로드하고, docs/rules-bundle.md에 지정된 5개 파일 규칙 번들을 준비한 다음, 테스트된 오프라인 부트스트랩 명령을 실행하세요:

.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 마커를 게시합니다. 재시도는 정확히 불완전한 환경을 복구하고 동일한 버전을 반환합니다. 게시된 카탈로그 및 규칙 파일은 독점 바이트 복사본이며, 유지된 스테이지 별칭이 없습니다. 심볼릭 링크된 입력, 하드 링크 별칭, 예상치 못한 사이드카, 충돌하는 기존 콘텐츠는 실패 시 닫힙니다.

빌드 전에 부트스트랩은 버전이 지정된 입력 ID로 완전히 검증된 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을 호출하고 operation build, card pool all_legal, 원하는 bracket/theme/proxy 차원, 그리고 1~8개의 완전 후보 제출을 포함하세요. 반환된 commander://plans/... 리소스를 읽으세요.

3. 선택적으로 컬렉션을 로드하고, 승리한 계획에 대해 resolve_availability를 호출한 다음 create_fulfillment_plan을 호출하세요. 가용성은 가상으로 유지됩니다. 완성은 해당 불변 결과 내에서만 사본을 할당합니다.

이 흐름은 브루잉 중 인벤토리에 의해 제약되지 않지만, 사용자가 행동을 결정하기 전에 보유한 것과 누락된 것을 보여줄 수 있습니다. 완전한 plan_deck 요청 템플릿은 수용 테스트 스위트에 의해 스키마 검증됩니다.

종단 간 예제: 소유 카드만으로 구성

1. 실제 컬렉션을 ManaBox CSV 또는 명시적 열 매핑이 있는 CSV로 내보낸 다음, 엄격 모드에서 load_collection_snapshot을 호출하세요.

2. search_library를 사용하여 이름, 인쇄, 바인더 또는 조립된 덱 할당으로 후보 카드를 찾으세요.

3. card pool owned_only와 컬렉션 스냅샷 ID로 plan_deck을 호출하세요. 소유하지 않은 기본 카드가 있는 후보는 하드 제약 조건에 실패합니다.

4. 계획 및 가용성 리소스를 읽어 바인더 뽑기와 충돌을 확인하세요. 이미 덱에 할당된 사본은 보고되며, 조용히 무료로 처리되지 않습니다.

이전 도구 결과로 덱 및 컬렉션 ID를 대체한 후 완전한 소유 카드 전용 요청 템플릿을 사용하세요.

종단 간 예제: Bracket 3 USD/EUR 50 프리콘 업그레이드

1. 프리콘을 내보내거나 붙여넣고 load_deck을 호출하세요. 이는 덱 의도로 유지되며 소유권 주장이 아닙니다.

2. 완전한 업그레이드 후보를 로드하고 plan_deck을 호출하되, operation upgrade, starting_deck_id로 프리콘, Bracket 3, 그리고 precon-upgrade-50-usd 또는 precon-upgrade-50-eur 시나리오 프리셋 의미론 중 하나를 사용하세요.

3. 정확한 추가/제거, 날짜가 있는 브래킷 증거, Game Changers, 테마 사실, 보장된 기본 통화 획득 한도를 검사하세요. 필수 가격 증거가 없으면 0으로 상한을 통과할 수 없습니다.

4. 선택적으로 인벤토리를 확인하고, create_fulfillment_plan으로 뽑기/덱 교체/대체/프록시를 선택한 다음, 남은 구매 라인에 대해 price_purchases를 호출하세요. 가격 책정은 정보 제공용이며 주문을 하지 않습니다.

USD 50 요청 템플릿에는 전체 시나리오, 후보 증거, 점수 정의, 브래킷 정책 및 시작 덱 필드가 포함되어 있습니다. EUR 프리셋의 경우 통화와 총 정책을 모두 변경하세요.

지원되는 가져오기

• ManaBox 컬렉션 CSV, 실제 바인더와 등록된 덱을 위시리스트 또는 기타 비소유 목록과 분리합니다.

• 일반 컬렉션 CSV, 수량 및 정확한 카드 ID에 대한 명시적 매핑과 선택적 인쇄 및 위치 필드 포함.

• Arena 스타일 및 일반 수량/이름/세트/수집 번호 덱 텍스트.

• Moxfield, Archidekt, Deckbox, Deckstats, TopDecked 등에서 사용자 내보내기 덱 텍스트 (지원되는 텍스트 방언과 일치하는 경우).

사용할 권한이 있는 내보내기를 붙여넣거나 선택하세요. V1은 계정 페이지를 스크랩하거나, 브라우저 쿠키를 재사용하거나, 문서화되지 않은 덱 호스트 엔드포인트를 호출하지 않습니다. 직접 호스트 URL은 unsupported_source를 반환합니다. 덱을 내보내고 텍스트를 가져오세요.

도구

공개 표면은 정확히 11개의 도구입니다:

모든 도구는 안정적인 결과 ID, 상태, 간결한 요약, 문제, 소스 스탬프 및 일반적으로 리소스 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

레코드는 불변이며 콘텐츠 주소 지정됩니다. 컬렉션 및 광범위한 검색은 제한되고 페이지가 매겨집니다. 도구 요약은 컬렉션 내용을 반향하지 않습니다.

시나리오 차원

계획 시나리오는 다음 독립적인 선택을 구성합니다:

• operation: build, upgrade 또는 analyze;

• bracket: 1~5, 날짜가 있는 턴 및 Game Changer 증거 포함;

• card pool: all_legal, prefer_owned 또는 owned_only;

• budget: 기본 통화 총액 및 선택적 카드당 상한, USD/EUR 50 프리콘 업그레이드 프리셋 포함;

• proxy policy: none, owned-once 또는 unlimited (플레이그룹이 허용하는 경우);

• theme policy: strict contract, flexible preference 또는 strength-oriented;

• 보호된 조립 덱, 고정 규칙 세트 및 결정론적 시드.

브래킷 적합성과 전략적 파워는 하나의 점수로 합쳐지지 않습니다. 공식 커맨더 규칙은 권위를 유지하며, Rule Zero 오버라이드는 명시적이어야 합니다.

가격 의미론

price_purchases는 항목 소계, 공급자 소계, 배송비, 예상 최종 합계를 분리합니다. 알 수 없는 항목이나 배송비는 null로 유지되며, 절대 0이 아닙니다. 보장된 예산은 선택된 정책 하에서 모든 필수 구매가 적격한 알려진 증거를 가질 때만 통과할 수 있습니다.

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 라이선스 하에 배포됩니다. 타사 카드, 규칙 및 마켓플레이스 데이터는 자체 약관 및 라이선스의 적용을 받습니다.