Pokémon Champions MCP

LLM이 직접 호출할 수 있는 Pokémon Champions 싱글 배틀용 1:1 매치업 계산기입니다. 턴 단위 시뮬레이션 대신 두 포켓몬의 스탯·스피드 구간·타입 상성·양방향 데미지를 한 번에 구조화된 JSON으로 반환합니다.

이 프로젝트는 비공식 팬 제작 도구이며 Nintendo, The Pokémon Company 또는 GAME FREAK와 제휴하거나 이들로부터 승인·후원받지 않았습니다. Pokémon 및 관련 명칭은 각 권리자의 상표입니다.

현재 MVP는 Pokémon Champions Regulation M-B / Singles / Lv. 50에 고정되어 있습니다.

제공 기능

• Champions 전용 스탯 포인트 계산: 스탯당 0-32, 총합 66 이하

• 현재 세트의 실능 및 랭크 적용 스탯

• 최저속·무보정·준속·최속별 기본 / 구애스카프 / +1 / 구애스카프 +1 스피드

• 마비, 스피드 랭크, 구애스카프, 순풍, 날씨 특성, 트릭룸을 반영한 선공 비교

• 양쪽이 지정한 기술의 16개 데미지 난수와 실제 HP 손실, 1타 확률

• 메가진화, 날씨·필드, 벽, 상태이상, 특성·아이템 상호작용

• 방어 타입 기준 약점·반감·무효 전체 표

• Regulation M-B 개별 세트 적법성 검사

• 포켓몬·폼·기술·특성·도구·성격·타입·배틀 상태의 한국어 입력과 한·영 병기 출력

• 동일 코어를 사용하는 JSON CLI와 MCP 도구 analyze_matchup

• 부분 한국어·영어·별칭으로 게임 데이터를 탐색하는 search_game_data

• 여러 세트와 상대의 교차 매치업을 요약 비교하는 compare_matchups

• 비공식 Champions Battle Data의 기술·도구·동료·성격·스탯 포인트·특성 사용률 조회

계산 흐름은 다음처럼 단순하게 분리되어 있습니다.

LLM / CLI
    ↓
Zod 입력 검증 및 기본값 확정
    ↓
오프라인 한국어 이름 → Showdown 식별자 해석
    ↓
Pokémon Showdown Champions 어댑터
    ↓
스탯 · 스피드 · 타입 · 데미지 결과 집계

Related MCP server: Pokémon MCP Server

실행

Node.js 20 이상과 pnpm이 필요합니다.

pnpm install
pnpm test
pnpm cli -- --file examples/garchomp-vs-charizard-y.json
pnpm cli -- --file examples/korean-matchup.json

JSON을 인자로 직접 넘기거나 표준 입력으로 전달할 수도 있습니다.

pnpm cli -- '{"left":{"species":"Garchomp"},"right":{"species":"Charizard"}}'
pnpm cli -- '{"left":{"species":"한카리아스"},"right":{"species":"리자몽"}}'
pnpm cli < examples/garchomp-vs-charizard-y.json

MCP로 LLM에 연결

Codex에서 이 저장소에만 연결

프로젝트 전용 .codex/config.toml을 로컬에서 만들면 사용자 전역 설정을 변경하지 않고 이 저장소에서만 pokemon-champions-mcp MCP 서버를 사용할 수 있습니다. .codex/는 로컬 절대 경로나 개인 설정이 공개 저장소에 올라가지 않도록 Git에서 제외됩니다.

먼저 의존성을 설치하고 설정 디렉터리를 만듭니다.

pnpm install
mkdir -p .codex

.codex/config.toml을 아래처럼 작성하고 cwd를 클론한 저장소의 실제 절대 경로로 바꿉니다.

[mcp_servers.pokemon-champions-mcp]
command = "node"
args = ["--import", "tsx", "src/mcp.ts"]
cwd = "/absolute/path/to/pokemon-champions-mcp"
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 60

그다음 이 저장소 루트에서 Codex를 새로 시작합니다. 프로젝트를 신뢰해야 프로젝트 전용 설정이 로드됩니다.

cd /path/to/pokemon-champions-mcp
codex

Codex TUI에서는 다음 명령으로 연결 상태와 도구를 확인합니다.

/mcp

터미널에서 설정만 확인하려면 저장소 루트에서 실행합니다.

codex mcp list

설정 변경은 이미 실행 중인 세션의 도구 목록에 즉시 반영되지 않습니다. 새 Codex 세션을 시작하거나 데스크톱 앱/IDE 확장을 재시작해야 합니다. 공식 설정 형식과 프로젝트 범위 동작은 Codex MCP 문서와 Codex 고급 설정 문서를 참고하세요.

다른 MCP 클라이언트에서 연결

Codex 프로젝트 설정을 읽지 않는 클라이언트에서는 아래 STDIO 명령을 직접 등록합니다. cwd는 이 저장소의 절대 경로로 바꿉니다.

{
  "mcpServers": {
    "pokemon-champions-mcp": {
      "command": "node",
      "args": ["--import", "tsx", "src/mcp.ts"],
      "cwd": "/absolute/path/to/pokemon-champions-mcp"
    }
  }
}

서버는 읽기 전용 도구 네 개를 노출합니다.

• analyze_matchup: 두 포켓몬의 Champions 싱글 매치업을 한 번에 분석

• search_game_data: 포켓몬·폼·기술·특성·도구·성격을 부분 이름으로 검색

• compare_matchups: 여러 세트와 상대를 최대 16개 조합으로 일괄 비교

• get_usage_statistics: 한국어 또는 영어 포켓몬명으로 참고용 싱글 사용 통계 조회

이름이나 폼이 확실하지 않을 때는 먼저 검색 결과의 id 또는 name을 analyze_matchup에 전달합니다. 검색은 오프라인이며 결과 수는 기본 10개, 최대 50개입니다.

compare_matchups는 leftSets × rightSets 조합의 선공, 적법성, 기술별 HP 손실률과 1타 확률을 간결하게 반환합니다. 승자를 단정하거나 턴 진행을 시뮬레이션하지 않으며 조합은 최대 16개로 제한됩니다.

통계 도구는 원격 API를 호출하므로 네트워크가 필요합니다. 응답에는 제공자, 조회 URL, 시즌, 생성 시각과 함께 official: false, upstreamSource: "undisclosed", purpose: "reference-only"가 포함됩니다. 수집 원천과 방법이 공개되지 않은 비공식 통계이므로 정확한 계산 결과와 구분해 참고용으로 사용해야 합니다.

한국어 입력 예시

{
  "left": {
    "species": "한카리아스",
    "ability": "까칠한피부",
    "item": "생명의구슬",
    "nature": "명랑",
    "statPoints": { "atk": 32, "spd": 2, "spe": 32 },
    "boosts": { "spe": 0 },
    "moves": ["지진", "스톤샤워"]
  },
  "right": {
    "species": "리자몽",
    "ability": "맹화",
    "item": "리자몽나이트Y",
    "nature": "겁쟁이",
    "statPoints": { "hp": 2, "spa": 32, "spe": 32 },
    "megaEvolution": true,
    "moves": ["용의파동", "에어슬래시"]
  },
  "field": {
    "weather": "자동",
    "terrain": "자동",
    "trickRoom": false,
    "left": { "reflect": false, "tailwind": false },
    "right": { "lightScreen": false, "tailwind": false }
  }
}

기술은 문자열 또는 크리티컬 여부를 포함한 객체로 입력할 수 있습니다.

{ "name": "Rock Slide", "criticalHit": true }

기본값

• 성격: Serious

• 스탯 포인트와 랭크: 전부 0

• 특성: 해당 폼의 첫 번째 기본 특성

• 아이템: 없음

• 현재 HP: 100%

• 날씨·필드: auto — 등장 및 메가진화 특성으로 생긴 상태를 유지

• 배틀 형식: pokemon-champions / M-B / singles

이름 필드는 한국어 정식명, 지원하는 통용 별칭, 영어 정식명, Pokémon Showdown 식별자를 모두 받습니다. 띄어쓰기와 일부 문장부호는 무시하며, 알로라 나인테일처럼 폼 이름의 자연스러운 한국어 어순도 해석합니다. 결과에는 계산용 영어 정식명과 speciesKo, moveKo, typesKo 같은 한국어 필드가 함께 들어갑니다.

메가진화할 때 ability는 진화 전 포켓몬의 특성을 입력하거나 생략합니다. 진화 후 특성과 폼 이름은 엔진이 자동으로 적용합니다. 동일한 한국어 이름이 여러 폼을 가리킬 수 있으면 임의 선택하지 않고 더 구체적인 폼을 요청하는 오류를 반환합니다.

결과 읽기

• pokemon: 최종 폼, 타입, 특성, HP, 표시 스탯, 랭크 적용 스탯, 적법성

• field: 요청한 필드와 특성까지 반영된 실제 날씨·필드·벽

• speed.actual: 현재 세트끼리의 실효 스피드와 선공 측

• speed.leftProfiles/rightProfiles: 최저속·무보정·준속·최속 벤치마크

• typeMatchups: 방어 타입만으로 본 4배·2배·반감·무효

• damage.leftToRight/rightToLeft: 각 기술의 양방향 계산

데미지에는 두 범위가 함께 들어갑니다.

• rawDamage: 데미지 공식 결과. 최대 HP를 넘는 값도 그대로 보여 줌

• hpLoss: 현재 HP 상한과 물흡수·기합의띠·옹골참 같은 실제 명중 처리까지 반영한 HP 감소량

기술은 명중한 상황을 전제로 계산하므로 명중률 자체는 확률에 섞지 않습니다. ohkoChancePercent는 16개 데미지 난수 중 실제로 쓰러뜨리는 비율입니다.

MVP 범위와 한계

• 연속기 데미지 범위는 부정확하게 근사하지 않고 unsupported로 반환합니다.

• 변화기 효과는 턴 진행 없이 non-damaging으로 분류합니다.

• 우선도 기술끼리의 행동 순서는 비교하지 않습니다. 스피드 비교는 동일 우선도 구간 기준입니다.

• 교체, 엔트리 해저드, 매 턴 회복, 이전 턴 카운터 등 턴 히스토리는 모델링하지 않습니다.

• 타입 약점 표는 타입 상성만 보여 주며, 특성·아이템에 의한 무효화는 실제 데미지 결과에 반영됩니다.

• 현재 Champions Dex에서 사용 가능한 정식 항목의 한국어명은 포함하지만, 커뮤니티 은어·축약어는 자주 쓰는 일부만 지원합니다. 정식명이 가장 안정적입니다.

• 과거 세대 전용·G-Max 등 Champions에서 사용할 수 없는 비표준 폼은 한국어 완전성 보장 대상이 아닙니다.

데이터와 재현성

계산 엔진은 pokemon-showdown@0.11.11과 그 버전에 포함된 champions 모드, [Gen 9 Champions] BSS Reg M-B 규칙을 고정해서 사용합니다. 규정이나 게임 데이터가 바뀌면 패키지 버전, 기대값 테스트, engine 메타데이터를 함께 갱신해야 합니다.

한국어명은 PokéAPI 저장소의 고정 커밋 17dd3092872cabcb7c008051771d2a2fd8c8c260에서 생성한 정적 테이블입니다. Champions에만 존재하는 메가폼·메가스톤·특성은 별도 보정합니다. 따라서 일반 계산과 MCP 호출 중에는 외부 API나 RPC를 호출하지 않습니다.

단, MCP의 get_usage_statistics는 Champions Battle Data의 비공식 원격 API를 호출합니다. 이 제공자는 원천 데이터의 수집 경로와 방법을 공개하지 않았으며, API 응답의 source 값은 제공자 내부 CSV 경로입니다.

데이터를 새로 생성하려면 네트워크가 가능한 환경에서 실행합니다.

pnpm sync:korean

• Pokémon Champions 공식 Gameplay

• Pokémon Champions Regulation M-B 공식 소개

• Pokémon Showdown Champions 모드

• PokéAPI API 문서

• 고정한 PokéAPI 데이터 커밋

재배포되는 한국어 데이터의 라이선스는 THIRD_PARTY_NOTICES.md에 기록했습니다.

검증

pnpm check
pnpm test
pnpm build

테스트는 Champions 스탯 공식, 준속·최속 구간, 메가진화와 날씨, 16개 난수, 흡수 특성, 기합의띠, 스카프·랭크·트릭룸, 잘못된 스탯 포인트를 고정 검증합니다. 또한 완전한 한국어 매치업, 한국어 폼·상태·날씨, Champions 전용 메가폼, 현재 Champions 표준 Dex 전체의 한국어 이름 누락 여부를 검사합니다.

라이선스

프로젝트 코드는 MIT License로 배포됩니다. 별도로 고지된 제3자 데이터와 상표에는 THIRD_PARTY_NOTICES.md의 조건이 적용됩니다.