Brotato Coach

Brotato Coach

Brotato 向けの決定論的な理論構築ツールです。 MCP サーバーとして提供され、Claude Code（およびその他の MCP クライアント）からチャットで利用できます。

設計原則：決定論的なコアが正確な情報を保持します — 武器・アイテム・キャラクターの データ、DPS の計算式、ステータスの仕組みを管理するため、言語モデルは情報を思い出す（そして 誤って思い出す）のではなく、事実を調べて計算します。各ツールは、検証可能な完成済みの回答か、 構造化されたエラーを返します。組み込みのティアリストや意見はなく、事実と数学だけを扱います。

データセット（data/brotato.json）はコミットされていません — 著作権で保護されたゲーム ファイルから派生するため、ローカルにインストールした Brotato から自分で構築します（ データセットの構築を参照）。Brotato 1.1.15.4 から完全なビルドを 作成すると、武器 202 個、アイテム 197 個、キャラクター 50 体、武器クラスセット 15 個が含まれます。

要件

• Python 3.11+
• 環境／依存関係の管理用の uv

依存関係をインストールします：

uv sync

クイックスタート

データセットを構築し（ローカルでの抽出が必要です — データセットの構築を参照）、 サーバーを起動します：

uv run python build_dataset.py                        # writes data/brotato.json
uv run python -m brotato_coach.server                 # starts the MCP server over stdio

data/brotato.json がない場合、サーバーは起動を拒否し、最初に構築するよう案内します。

テストを実行します（データセットに依存する統合テストは、データセットが構築されていない場合はスキップされます）：

uv run pytest        # 89 tests (88 passed + 1 skipped without a built dataset)

実行

uvx spudcoach --data /path/to/brotato.json

データセットは配布されません — 自分の Brotato インストールから構築してください： uv run python build_dataset.py（docs/extraction-setup.mdを参照）。 ゲームのバージョンは、逆コンパイルされた recovered/singletons/progress_data.gd から自動検出されます。 generated_at のデフォルトは現在の UTC 時刻です。どちらかを上書きするには、 --game-version／--generated-at を明示的に指定してください。SPUDCOACH_DATA は --data の代わりに環境変数として使用できます。

Claude Code プラグインとして使用する

MCP サーバーは plugin/.mcp.json で定義されています：

{
  "mcpServers": {
    "spudcoach": {
      "command": "uv",
      "args": ["run", "python", "-m", "brotato_coach.server"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

サーバーは（ローカルで構築した）data/brotato.json を作業ディレクトリからの相対パスで読み込むため、 リポジトリのルートを cwd に指定して実行する必要があります（プラグインとしてバンドルされる場合、 マニフェストは ${CLAUDE_PLUGIN_ROOT} を使ってこれを設定します）。また、最初に データセットを構築する必要があります。

パッケージ化せずに Claude Code に直接登録するには、チェックアウト先を指定してサーバーを追加します。 例：

claude mcp add spudcoach -- uv run --directory /path/to/spud-coach python -m brotato_coach.server

接続したら、自然な言葉で質問するだけです — モデルが質問に応じて以下のツールを使います：

• 「Handcuffs は Ranger のランに合いますか？遠距離ダメージ 7、HP 65 です。」
• 「遠距離ダメージ 20 のとき、Minigun T4 と Revolver T4 ではどちらの攻撃力が高いですか？」
• 「攻撃速度がまったく役に立たなくなることはありますか？銃ビルドでノックバックをマイナスにしてもいいですか？」
• 「Ranger の遠距離ダメージボーナスは、基本ステータス 6 にどう影響しますか？」
• 「これが私の run.json です — このビルドの調子はどうですか？」（セーブ全体を一度に事後分析）

Claude Desktop で使用する

Claude Desktop は uvx を使って、2 つの方法でサーバーを起動できます。 このリポジトリから直接取得する方法（再起動時に自動更新されますが、git にアクセスできる必要があります — 下記の Windows に関する注意を参照）と、ローカルのチェックアウトを指定する方法（実行時に取得が不要で、 Windows で最も確実な方法）です。どちらの場合も、ローカルで構築した brotato.json を用意してください — データセットは配布されません。

1. Claude Desktop を実行するマシンに uv をインストールします（Windows では winget install astral-sh.uv、 またはスタンドアロンインストーラーを使用します）。

2. 設定ファイルを開き、spud-coach サーバーを追加します：

   • Windows： %APPDATA%\Claude\claude_desktop_config.json
   • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

   リポジトリから取得する場合：

   {
     "mcpServers": {
       "spud-coach": {
         "command": "uvx",
         "args": [
           "--from", "git+https://github.com/brendanlefebvre/spud-coach",
           "spudcoach",
           "--data", "C:\\Users\\<you>\\path\\to\\brotato.json"
         ]
       }
     }
   }
   

   --data に構築済みのデータセットを指定してください（SPUDCOACH_DATA は環境変数として代わりに使用できます）。 macOS では /Users/<you>/brotato.json のような POSIX パスを使用します。

3. Claude Desktop を完全に再起動します（ウィンドウを閉じるだけでなく、トレイから終了してください）。

Windows：「Git executable not found」（または uvx が見つからない）

git+https://… 形式を使うと、uv は git 実行ファイルをシェルから呼び出します。**Claude Desktop はシェルの環境変数を渡さず、System PATH さえも MCP サブプロセスに渡しません。**サーバーは、独自に整理された環境で起動されます。（ログに表示される PATH はコマンド解決用のリストであり、子プロセスが受け取る値ではありません。）そのため、PowerShell では正常に実行でき、System-PATH のディレクトリにインストールされている git でも、ここでは「見つからない」と返されることがあります。同じ理由で、"command": "uvx" だけでは解決に失敗する場合があります。対処方法は2つあります。

• **ローカルのチェックアウトを指定する — 実行時に git は不要です（推奨）。**git が動作するターミナルで一度クローンし、--from git+… の代わりに --from <folder> を使います。

  git clone https://github.com/brendanlefebvre/spud-coach C:\Users\<you>\src\spud-coach
  

  {
    "mcpServers": {
      "spud-coach": {
        "command": "uvx",
        "args": ["--from", "C:\\Users\\<you>\\src\\spud-coach", "spudcoach",
                 "--data", "C:\\Users\\<you>\\path\\to\\brotato.json"]
      }
    }
  }
  

  後で更新するときは、そのフォルダーで git pull を実行してから、Desktop を再起動します。

• または、ツールがサーバーの PATH を使うようにします。git+https 形式を維持し、子プロセスに明示的な PATH を渡す env ブロックを追加します。ここには git、uv の bin、winget-links ディレクトリを含めます。

  "env": {
    "PATH": "C:\\Program Files\\Git\\cmd;C:\\Users\\<you>\\.local\\bin;C:\\Users\\<you>\\AppData\\Local\\Microsoft\\WinGet\\Links;C:\\Windows\\System32"
  }
  

  それでも uvx 自体が見つからない場合は、"command" に絶対パスも設定します（場所を調べるには Get-Command uvx を実行します。例：C:\Users\<you>\AppData\Local\Microsoft\WinGet\Links\uvx.exe）。

利用可能なツール

すべてのツールは JSON オブジェクトを返します。該当するものがない検索では、{"error": "not_found", "did_you_mean": [...]} が返されます。

22個のツールがあります。? が付いた引数は省略可能です。

まずはこちら

ツール	引数	戻り値
read_me	—	セッション開始時のガイド：Brotato のコアループ、ソースで検証済みのステータスの仕組み、事前計算された各フィールドの前提条件を説明します。ほかの操作より先に一度呼び出してください

データ検索

ツール	引数	戻り値
get_weapon	name、tier?	生のステータス対応フィールド、ヒット時の effects、武器クラスの sets を含む武器レコード。tier を省略して複数のティアが該当する場合は {matches:[...]}
get_item	name	効果、タグ、archetype、frozen_stat を含むアイテムレコード
get_character	name	wanted_tags、banned_item_groups、flat_bonuses、gain_modifiers、special_effects、class_bonuses、starting_weapon_pool を含むキャラクターのキット
get_weapon_class_set	class_name	装備数別の武器クラスセットボーナス（Blade、Gun、Elemental など）
list_weapons	scaling_stat?、tier?	フィルター済みの要約 {weapons:[...]}
list_items	tag?、scaling_stat?、archetype?、tier?	フィルター済みの要約 {items:[...]}
list_characters	scaling_stat?、wanted_tag?、banned_item_group?、special_effect?、class_bonus_set?、can_start_with?、detail?	{characters:[...]} — 要約ではなく完全なレコード（下記参照）
get_filter_options	—	データセット内の有効なフィルター値：アイテムタグ、アーキタイプ、スケーリングステータス、ティア、武器クラス名、敵の能力／攻撃の種類／ゾーン、キャラクターフィルターの語彙

DPS と比較

ツール	引数	戻り値
weapon_dps	name、tier、stats、aoe_enemies_hit?、character?、weapon_count?、engagement_distance?、loadout?、apply_set_bonuses?	ビルドに応じた実効 DPS。base_dps と proc_dps に分けられ、cadence の内訳と組み込まれた assumptions を含みます
compare_weapons	names_with_tiers、stats、および weapon_dps と同じ省略可能な引数	DPS の降順に並んだ {ranking:[...]}。共通のステータス構成を使用します
compare_merge_paths	weapon_name、path_a、path_b、stats?	2つのティア合成経路（ティアのリスト）の勝者、または crossover_rd
stat_gradient	weapons、stats、step?、character?、aoe_enemies_hit?、engagement_distance?	次に上げるステータスを提示します。各ステータスを +step した場合の DPS 増加量で順位付けします。DPS のみが対象で、生存能力は対象外です

ビルド評価

ツール	引数	戻り値
evaluate_item_for_build	item_name、character_name、current_stats	効果ごとの判定 — 有効／無駄／有害 — とその理由、および概要
loadout_set_bonuses	weapon_names	ロードアウト全体におけるクラス別セット進捗：装備数、有効なボーナス、次のしきい値
explain_stat	stat	検証済みのステータスの仕組み：上限、特殊な挙動、無視可能／負の値にならないフラグ
stat_display_value	character、stat、raw_value	キャラクターの増加補正を適用した後の表示値（例：レンジャーの RD 6 → 9）

敵図鑑

ツール	引数	戻り値
get_enemy	name、wave?	敵のレコード：基本ステータス、ウェーブごとのステータス変化量、攻撃プロファイル、能力タグ。wave（1～20）を指定すると、そのウェーブでのeffectiveステータスも解決します
list_enemies	appears_in?、ability?、attack_kind?	フィルタリングされた概要{enemies:[...]}
wave_composition	wave、danger?	そのウェーブの基本ゲーム（Crash Zone）の構成：敵グループ、基本数、初回出現タイミング、再出現

ラン分析とメタデータ

ツール	引数	戻り値
evaluate_run	path? または run_json?	Brotato のrun.jsonセーブ全体をワンコールで事後分析：ランのコンテキスト（キャラクター、ウェーブ、危険度）、実現したステータス、武器のDPSランキング、セット進捗、アイテムごとの判定
check_dataset_version	—	game_version、generated_at、schema_version

一括検索。 get_weapon、get_item、get_characterは、nameに文字列または文字列のリストを指定できます。リストを指定すると、与えた順序で各エンティティのレコードまたは個別のnot_foundを含む{"results": [...]}が返されるため、複数エンティティの詳細を取得するのに必要なのはN回ではなく1回の往復です。

list_charactersは概要ではなく、完全なレコードを返します。一方、list_weapons／list_itemsは概要を返します。50キャラクターのコーパス全体でも約7.7Kトークンにすぎないため、追加のget_characterを呼び出さずに、1回の呼び出しで全体を確認できます。代わりにdetail="summary"を指定すると、{id, name}の行が返されます。scaling_statフィルターは派生した統合条件です。キャラクターにはスケーリングステータスのフィールドがないため、正のステータス増加補正、正の固定ボーナス、または一致するwanted_tagのいずれかに該当するキャラクターを照合します。一致した各レコードには、どのシグナルが該当したかを示すscaling_matchオブジェクトが含まれます。たとえば、エンジニアは{"gain_pct": 25, "flat": 10, "wanted": true}、テクノメイジは{"wanted": true}となり、根拠が明示されます。そのステータスにペナルティを受けるキャラクターは一致対象から除外されます。

starting_weapon_poolはラン開始時の武器選択プールであり、固定の初期武器ではありません。ほとんどのキャラクターには12個以上の候補がありますが、アームズディーラーの候補はピストルのみで、ビーストマスターとブルには候補がありません。

stats／current_statsは、短いステータス名（例：{"ranged_damage": 7, "max_hp": 65}）をキーとするオブジェクトです。names_with_tiersは[name, tier]のペアのリストです。path_a／path_bはティア番号のリストです。ステータス名には2つの形式がある点に注意してください。stats／current_statsでは短い名前（ranged_damage）を使いますが、explain_statとstat_display_valueのstat引数では、stat_を付けた形式（stat_ranged_damage）を使います。get_filter_optionsは有効なフィルター値を返すため、値を推測する必要はありません（すべてのフィルターで大文字と小文字を区別し、完全一致します）。

evaluate_runが受け取る入力は1つだけです。セーブの内容をrun_json（アップロードまたは貼り付けたrun.jsonなど）として渡すか、保存場所をpath（Brotatoのセーブディレクトリ内のファイルなど）として渡してください。セーブは読み取り専用で、変更されることはありません。読み込んだデータセットで認識されないID（ビルドより新しいコンテンツなど）は破棄されず、notesに記載されます。不正な形式のセーブでは{"error": "bad_run_file", ...}が返されます。

データセットの構築

データセットはコミットされていません。実際のゲームのインストールデータから抽出して構築します。生データの extracted/、逆コンパイルしたrecovered/、著作権で保護されたgame_files/、派生データの data/brotato.jsonはすべてGitの追跡対象外です（抽出データの作成方法については docs/extraction-setup.mdを参照してください）。リポジトリのルートにextracted/が用意できたら、次を実行します。

uv run python build_dataset.py

これによりdata/brotato.jsonが書き出されます。ゲームのバージョンは、逆コンパイルした recovered/singletons/progress_data.gd（VERSION定数）から自動検出され、generated_atのデフォルト値は 現在のUTC時刻になります。いずれかを上書きする場合は、--game-version <ver>または--generated-at <iso8601>を明示的に 指定します。たとえば、recovered/がない場合や、テストまたはリリーススクリプトで再現可能な値を固定する場合に使用します。 各パッチの適用後に再実行してローカルコピーを更新してください。引き続きGitの追跡対象外となるため、 コミットしないでください。

仕組み

extracted/  (gitignored, regenerable)          raw .tres game data
     │
     ▼   build_dataset.py   (offline, per patch)
data/brotato.json  (gitignored, built locally)  the deterministic core artifact
     │
     ▼   loaded at startup
brotato_coach.server (FastMCP)                  16 tools over the pure functions
     │
     ▼   connected as a plugin
Claude Code / Desktop / Web                     chat frontend

• brotato_coach/tres.py — 最小限のGodot .tresパーサーです。
• brotato_coach/builders/ — 解析した.tresを、拡張情報を含むレコードに変換します（事前計算したDPS ラインを含む武器、アーキタイプのフラグを含むアイテム、獲得修正値を含むキャラクター、セット、および検証済みの stat_mechanicsテーブル）。
• brotato_coach/calc.py — DPSと合成の計算を行う純粋関数です（I/Oなし）。手作業で検証した値と照合して単体テストしています。
• brotato_coach/{query,answers,evaluate}.py — 完成した回答を生成する純粋関数です。
• brotato_coach/runfile.py — Brotatoのrun.jsonセーブデータを解析し、ビルド（キャラクター、武器、アイテム、実際のステータス）に正規化する 純粋パーサーです。I/Oを行うのはセーブファイルの読み込みのみです。
• brotato_coach/server.py — これらの関数を呼び出す薄いFastMCPラッパーです。

コーチが扱うゲームメカニクスの参考資料はdocs/にあります （抽出のセットアップ、武器合成時のDPS算出方法、ランの事後分析方法、ステータスメカニクス）。

免責事項

これは非公式のファンメイドツールです。Brotatoの開発元であるBlobfishや、そのパートナーとは提携関係になく、推奨や後援も受けていません。Brotatoおよび関連するすべての名称、商標、アセットは、それぞれの所有者に帰属します。

このプロジェクトにはゲームのアセットもゲームデータも含まれていません。このツールが扱うステータスデータセットは、お客様が所有するゲームのコピーから、お客様自身がローカルで生成するものです（build_dataset.pyは、お客様自身のインストールデータから抽出した内容を読み込みます）。ゲームの著作権保護対象ファイルから派生したものが、このリポジトリで配布されることはありません。

本ソフトウェアは「現状有姿」で提供され、いかなる種類の保証もありません（LICENSEを参照）。推奨内容はデータマイニングした値に基づいており、不完全または誤っている可能性があります。ご自身の判断でご利用ください。

ライセンス

MIT © 2026 Brendan LeFebvre。このライセンスの適用対象は、このリポジトリ内のコードとドキュメントのみです。Brotatoまたはそのアセットに関する権利は付与されません。