pokemon-mcp

正確なポケモンデータと第9世代ダメージ計算を提供する MCP サーバー。 Claude Code が Web 検索の代わりにこれを叩くことで、コンテキスト消費を抑えつつ正確な数値を得る。

なぜ RAG ではなく構造化 + 計算ツールか

ポケモンのデータは大半が構造化(種族値・技威力・タイプ相性)で、数値の正確さが命。 embedding 検索は意味的に近いものを返すため数値を取り違えるリスクがある。よって本プロジェクトは embedding を使わず、exact lookup(SQLite/PokeAPI)+ 計算エンジンで構成する。

アーキテクチャ

flowchart LR
    CC[Claude Code] -- MCP/stdio --> S[server.py FastMCP]
    S --> D[damage.py 第9世代計算]
    S --> DB[(SQLite)]
    DB -. 未取得なら遅延フェッチ .-> API[PokeAPI]
    D --> TC[type_chart.py]
    D --> NA[natures.py]

• damage.py — ダメージ式・実数値・多段(トリプルアクセル威力20/40/60)・乱数16通り・KO%(畳み込み)。命中(光の粉等)は別軸。

• type_chart.py — 第6世代以降のタイプ相性。

• natures.py — 性格補正(日本語名エイリアス対応)。

• data.py — SQLite キャッシュ + PokeAPI 遅延フェッチ。

• server.py — FastMCP でツール公開。

公開ツール(MVP)

ポケモン名・技名は英語slug/日本語名どちらも可(日本語名の解決には build_db.py --aliases で索引構築が必要)。 道具(いのちのたま/こだわり系/たつじんのおび/タイプ強化アイテム等)・天候(晴れ/雨/砂/雪)に対応。

セットアップ

uv sync
uv run pytest            # ダメージエンジンの検証(今日の手計算を再現)
uv run pokemon-mcp       # MCPサーバー(stdio)を起動
# 全件オフラインDBを作る場合(任意・数分):
uv run python scripts/build_db.py

Claude Code への登録

# /path/to/pokemon-mcp は clone した実際のパスに置き換える
claude mcp add --scope user pokemon -- uv --directory /path/to/pokemon-mcp run pokemon-mcp

使い方

Claude Code から自然言語で

登録後はそのまま日本語で聞けば、Claude が裏でツールを呼ぶ(Web検索しないのでコンテキストを食わない):

• 「陽気マスカーニャの変幻自在トリプルアクセル、無振りガブは耐える?」

• 「トリプルアクセルが光の粉持ちに3発当たる確率は?」

• 「いのちのたま+晴れのリザードン かえんほうしゃ、フシギバナへのダメージは?」

ツール別の例

calc_damage — 対面ダメージ(撃ごと/累計のレンジ・KO%):

// 入力: 陽気マスカーニャ(変幻自在) A252 トリプルアクセル vs 無振りガブ
{ "attacker": "meowscarada", "defender": "garchomp", "move": "triple-axel",
  "attacker_offense_ev": 252, "attacker_nature": "jolly", "protean": true }

// 出力(抜粋)
{ "per_hit": [ {"hit":1,"min":64,"max":84}, {"hit":2,"min":132,"max":156}, {"hit":3,"min":196,"max":232} ],
  "cumulative": [ {"after_hit":2,"ko_chance":1.0} ],   // 2撃目で確定KO
  "defender_hp": 183, "type_eff": 4.0, "stab": 1.5 }

道具・天候・テラスの例:

{ "attacker":"charizard", "defender":"venusaur", "move":"flamethrower",
  "attacker_offense_ev":252, "attacker_nature":"modest",
  "item":"life-orb", "weather":"sun" }            // 晴れ×いのちのたま ≒ x1.95

calc_accuracy — 命中率・多段の命中回数分布:

{ "move":"triple-axel", "bright_powder": true }
// → per_check_hit_chance 0.81, all_hits_chance 0.531441,
//    hit_count_distribution { "0":0.19, "1":0.1539, "2":0.124659, "3":0.531441 }

calc_stat — 実数値:

{ "base":110, "level":50, "ev":252, "nature":"jolly", "stat":"atk" }   // → 162

type_effectiveness — 相性倍率:

{ "attacking_type":"ice", "defending_types":["ground","dragon"] }      // → 4.0(こうかばつぐん)

get_pokemon / get_move — 素のデータ:

get_pokemon("garchomp")   → base_stats / types / abilities
get_move("triple-axel")   → power 20, accuracy 90, min_hits/max_hits 3, damage_class physical

calc_damage のパラメータ早見

命中(光の粉等)は別軸。calc_damage は命中前提のダメージ・KO%を返す。命中率は calc_accuracy を使う。 可変多段(2-5発)の ko_chance はヒット数分布で重み付け、ko_chance_all_hits は最大ヒット前提(スキルリンク/こだわりサイコロ時)。

日本語名で引くには

技名は取得時に自動で日本語索引へ登録される。ポケモン名を含めて全件を日本語で引くには、一度だけ索引を構築する:

uv run python scripts/build_db.py --aliases   # 数分・一度きり
# → 以後「ガブリアス」「かえんほうしゃ」等でも引ける

仕様の正確さ

tests/test_damage.py が「陽気マスカーニャ(変幻自在)トリプルアクセル vs 無振りガブリアス Lv50」の 手計算(各撃 64-84 / 132-156 / 196-232、2撃目で確定気絶)を再現することでエンジンを検証している。 補正順序は第5世代以降の公式式(天候 → 急所 → 乱数 → タイプ一致 → 相性)に準拠。

ライセンス

本プロジェクトのソースコードは MIT License で公開している。

免責 (Disclaimer)

これは非公式・非営利のファンプロジェクトです。

• Pokémon およびポケモンのキャラクター名・技名は、任天堂 / 株式会社クリーチャーズ / 株式会社ゲームフリーク(The Pokémon Company)の商標です。

• 本プロジェクトは任天堂・The Pokémon Company とは一切関係なく、公認・後援も受けていません。

• ゲームの画像・音声・アートワーク等の著作物は一切含みません。種族値・技・タイプ相性などの 事実データは PokéAPI から実行時に取得するのみで、本リポジトリには 同梱・再配布していません(data/pokedex.db は .gitignore 済み)。

• MIT ライセンスは本プロジェクトのコードにのみ適用され、ポケモンのデータ・名称・商標には 及びません。

• 非営利・個人利用を前提としています。商用利用は権利者の許諾が必要です。