Vizier Yu-Gi-Oh! MCP

유희왕 카드 데이터를 위한 Model Context Protocol 서버: 카드, 가격, 인쇄 정보, 금지 제한 목록(역사적 + 포맷 간), 공식 룰링, 종합 룰, 카드 관계, 덱 도구. 모든 것이 단일 SQLite 데이터베이스와 내장 벡터 검색으로 로컬에서 실행됩니다 — 쿼리 시 네트워크 호출 없음.

기능

• 카드: 정확한 ID 또는 퍼지 매칭 이름으로 조회, 타입/ATK 필터가 있는 키워드 검색, 효과 설명 기반 의미론적(벡터) 검색, 아키타입 목록.

• 가격 및 인쇄 정보: 현재 시장 가격(cardmarket / tcgplayer / ebay / amazon), 레어도와 가격을 포함한 전체 인쇄 이력.

• 금지 제한 목록: tcg, ocg, ocg-ae, ocg-cn, master-duel, rush, genesys, ocg-genesys, goat, edison 포맷의 스냅샷; 모든 포맷에서 카드별 상태, 스냅샷 간 역사적 차이.

• 룰 및 룰링: 공식 종합 룰북(380개 섹션)과 2,650개 이상의 공식 OCG 룰링에 대한 의미론적 검색; 카드별 룰링 조회 및 실시간 가져오기 대체.

• 관계: 카드 텍스트에서 추출한 검색/소환/파괴/대상 관계, 융합/싱크로/엑시즈/링크/의식 소재 요구 사항, 역방향 조회, 아키타입 지원 감지.

• 덱: 포맷의 금지 제한 목록에 대해 덱리스트 검증, 메인/엑스트라 구성 및 아키타입 혼합 분석.

Related MCP server: Scryfall MCP Server

요구 사항

• Python 3.11+

• 임베딩 모델 다운로드를 위한 약 1GB 디스크; 빌드된 데이터베이스는 약 75MB

• 빌드 중 약 2GB RAM(임베딩 모델); 쿼리 시에는 훨씬 적음

데이터베이스 경로와 데이터 디렉터리는 VIZIER_DB_PATH 및 VIZIER_DATA_DIR 환경 변수로 재정의할 수 있습니다(기본값은 <package root>/data/).

설정

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

데이터베이스 빌드

빌드는 캐시된 API 데이터(data/cache/)와 참조 프로젝트(ref/, policy/)를 data/vizier.db로 통합합니다. --fetch를 전달하지 않는 한 네트워크가 필요하지 않습니다.

# full build including embeddings (slow: ~15-20 min CPU for 17.6k vectors)
python scripts/build_db.py

# faster variants
python scripts/build_db.py --no-embed      # skip vector embeddings (no semantic search)
python scripts/build_db.py --skip-cards    # skip card ingestion, re-embed only
python scripts/build_db.py --fetch         # download fresh API payloads first

--fetch는 YGOPRODeck에서 카드 덤프를 다운로드합니다. 참고: 현재 라이브 API는 HTTP 403을 반환하므로 data/cache/의 캐시된 덤프가 권위 있는 소스입니다. API에 연결할 수 없으면 빌드는 캐시를 사용합니다.

서버 실행

python -m vizier_mcp

서버는 stdio를 통해 MCP를 사용합니다. 콘솔 스크립트도 있습니다:

vizier-mcp

클라이언트 구성

설치된 명령을 가리키도록 MCP 클라이언트를 구성하세요. 서버 이름은 vizier-yugioh입니다.

Claude Desktop / Claude Code

{
  "mcpServers": {
    "vizier-yugioh": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "vizier_mcp"]
    }
  }
}

일반 클라이언트

{
  "mcpServers": {
    "vizier-yugioh": {
      "command": "/path/to/.venv/bin/vizier-mcp",
      "args": []
    }
  }
}

venv에 대한 절대 경로를 사용하세요. DB 경로는 패키지 위치(또는 VIZIER_DB_PATH)를 기준으로 해석되며, CWD 기준이 아닙니다.

도구

filter_type 예: monster, spell, trap, effect, fusion, link, pendulum, tuner, normal monster, normal spell, quick-play, counter trap, equip, field, ritual. 여러 단어 필터는 정확한 하위 타입과 일치합니다.

콤보 생성

서버에는 라인 구축을 결정적 너비 우선 프로세스로 바꾸는 내장 콤보 생성 플레이북이 포함되어 있습니다: 가능한 모든 행동 열거, 확장, 심화, 가지치기, 기록, 반복.

1. combo_guide() — 플레이북 로드(combo 프롬프트로도 사용 가능). 콤보 상태 JSON 스키마, 6단계 프로토콜, 카드별 열거 체크리스트, 도구 라우팅, 하드/소프트 OPT 규율, 락 감지, 종료 기준을 정의합니다.

2. card_combo_profile() — 고려하는 모든 카드에 대해: 소환 옵션(일반/제물/펜듈럼/자기 특수 소환), 활성화 종류 + 턴당 사용 횟수 + 행동 동사가 있는 모든 효과, 락/제한 문장, 전체 관계 그래프(검색/소환/파괴/대상/소재), 필요한 소재, 소재가 될 수 있는 몬스터(이름 지정 + 아키타입 전체).

3. board_options() — 현재 보드에서 가능한 모든 합법적 다음 플레이를 반환하는 한 번의 호출, 아키타입 무관: 모든 엑스트라 덱 소환(덱의 아키타입뿐만 아니라 전체 약 2,300몬스터 풀), 모든 패 몬스터의 플레이(일반 소환 / 자기 특수 소환 / 펜듈럼 스케일), 대상이 있는 모든 검색/추가 효과(아키타입 대상 목록은 상위 멤버 순위), 펜듈럼 소환 범위, 활성/대기 락. 이는 터널 비전 방지 도구입니다: 모델은 아키타입 내 후보로 자신을 제한해서는 안 됩니다.

4. line_search() — 현재 보드에서 목표(field_levels, field_count, no_locks, reach_field, reach_hand)까지 서버 측 제한 너비 우선 검색. 완전한 다단계 라인을 반환하므로 모델은 한 번에 한 수가 아닌 여러 단계를 계획합니다.

5. extra_deck_options() — 현재 필드(패/묘지/엑스트라 덱 및 포맷 포함)를 붙여넣으면 소재 요구 사항이 충족되는 모든 융합/싱크로/엑시즈/링크/의식 몬스터를 정확한 소재 추론과 함께 반환합니다.

예 — 필드에 레벨 4 D/D 몬스터 두 장:

extra_deck_options(field=["D/D Savant Copernicus", "D/D Ark"], summon_types="xyz")
→ options include D/D/D Wise King Solomon ("2 Level 4 D/D monsters")

최선 노력 소재 확인은 전체 관계 그래프에 대해 검증됩니다. 라인을 확정하기 전에 항상 get_card_materials로 경계 후보를 확인하세요.

리소스

공백이 포함된 리소스 매개변수는 URL 인코딩하세요 (rules://damage%20step).

데이터베이스 구조

data/vizier.db — sqlite-vec 확장이 포함된 SQLite. 주요 테이블:

• cards — 계산된 유형 플래그(is_monster, is_quickplay_spell, ...)가 포함된 카드별 행

• card_sets, card_prices — 인쇄물 및 시장 가격

• card_ban_status, banlist_history — 포맷별 현재 상태 + 과거 스냅샷

• relations — 유형이 포함된 카드 간 효과 관계

• rulebook_chunks, rulings — 룰 및 재정 텍스트

• card_vec, rule_vec, ruling_vec — 의미 기반 검색용 임베딩 테이블

• meta — 빌드 타임스탬프 및 개수

데이터 소스

• 카드 / 가격 / 금지 제한 목록: YGOPRODeck 벌크 API(data/cache/에 캐시됨)

• 규칙: 공식 종합 룰북(ref/yugioh_comprehensive_rulebook/)

• 규정: 공식 OCG 규정 Q&A 목록 + YGOPEDIA 대체 소스

• 정책: 대회 정책 문서(policy/)

테스트

python -m pytest tests/ -q

인프로세스 서버 클라이언트를 대상으로 32개의 스모크 테스트를 실행하여 모든 도구와 리소스를 검증합니다.