
Brotato Coach
io.github.brendanlefebvre由 GitHub 帳號 brendanlefebvre 發布v0.14.1更新於 Oct 24, 2026
Deterministic Brotato theorycrafter MCP server: facts and math, not guesses.
概覽
在本機執行的 MCP 伺服器,依自行建置的遊戲資料集回答《Brotato》配裝問題:武器與道具查詢、DPS 計算和存檔檢討。
- 可以做什麼
- 查詢武器、道具、角色、武器類別套裝和敵人,支援篩選與批次名稱清單
- 計算隨屬性變化的武器 DPS,比較武器與合成路徑,並排序下一步該提升哪項屬性
- 判斷某道具對指定角色和屬性面板是生效、浪費還是有害,並顯示整套配裝的套裝加成進度
- 解釋屬性機制,並依角色修正把原始屬性換算成顯示值
- 查看敵人在各波次的屬性與波次組成
- 一次呼叫檢討整份 run.json 存檔,並檢查資料集的遊戲版本與 schema 版本
- 適用情境
- 適合想要基於資料探勘數值、而非模型記憶的《Brotato》建議時使用:判斷道具是否適合目前這局、在目前屬性下比較武器,或依存檔檢討已結束的一局。它是玩家自製的理論計算輔助工具,並非通用遊戲攻略。
- 執行需求
- 以 PyPI 套件 spudcoach 透過 uvx 在本機以 stdio 執行,或從程式碼倉庫用 uv 和 Python 3.11+ 執行。需要本機建置的 brotato.json 資料集,透過 --data 參數或 SPUDCOACH_DATA 環境變數指定;缺少資料集時伺服器會拒絕啟動。建置資料集需要自有的《Brotato》遊戲安裝和擷取步驟。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 Brotato Coach,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。
其他 MCP 客戶端
參照 儲存庫 中的啟動說明。
README
Brotato Coach
A deterministic theorycrafter for Brotato, delivered as an MCP server you can chat with from Claude Code (and other MCP clients).
The design principle: a deterministic core holds the ground truth — weapon/item/character data, DPS formulas, stat mechanics — so the language model looks facts up and computes instead of recalling (and misremembering) them. Every tool returns a finished, verifiable answer or a structured error; there are no baked-in tier lists or opinions, only facts and math.
The dataset (data/brotato.json) is not committed — it is derived from copyrighted game
files, so you build it yourself from a local Brotato install (see Building the dataset).
A full build from Brotato 1.1.15.4 contains 202 weapons, 197 items, 50 characters, and 15
weapon-class sets.
Requirements
- Python 3.11+
uvfor environment/dependency management
Install dependencies:
Quick start
Build the dataset (needs a local extraction — see Building the dataset), then start the server:
The server refuses to start without data/brotato.json and tells you to build it first.
Run the tests (the dataset-dependent integration test is skipped when no dataset is built):
Run
The dataset is never distributed — build your own from your Brotato install:
uv run python build_dataset.py (see docs/extraction-setup.md).
Game version auto-detects from the decompiled recovered/singletons/progress_data.gd, and
generated_at defaults to the current UTC time — pass --game-version/--generated-at
explicitly to override either. SPUDCOACH_DATA works as an env-var alternative to --data.
Use as a Claude Code plugin
The MCP server is described by plugin/.mcp.json:
The server reads the (locally built) data/brotato.json relative to its working directory, so
it must run with the repository root as its cwd (the manifest handles this via
${CLAUDE_PLUGIN_ROOT} when bundled as a plugin), and you must
build the dataset first.
To register it directly in Claude Code without packaging, add the server pointed at your checkout, e.g.:
Once connected, just ask in natural language — the model routes your question to the tools below:
- "Does Handcuffs fit my Ranger run? I'm at 7 ranged damage, 65 HP."
- "Minigun T4 vs Revolver T4 at 20 ranged damage — which hits harder?"
- "Is attack speed ever dead weight? Can I let knockback go negative on a gun build?"
- "What does the Ranger's ranged-damage bonus do to a raw stat of 6?"
- "Here's my run.json — how's this build doing?" (post-mortem a whole save at once)
Use with Claude Desktop
Claude Desktop can launch the server with uvx in two forms: fetch
straight from this repo (auto-updates on restart, but needs git reachable — see the Windows note
below), or point at a local checkout (nothing fetched at runtime; the most reliable form on
Windows). Either way you supply your own locally built brotato.json — the dataset is never
distributed.
-
Install
uvon the machine running Claude Desktop (winget install astral-sh.uvon Windows, or the standalone installer). -
Open the config file and add the
spud-coachserver:- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Fetch-from-repo form:
Point
--dataat your built dataset (SPUDCOACH_DATAworks as an env-var alternative). On macOS use a POSIX path like/Users/<you>/brotato.json. - Windows:
-
Fully restart Claude Desktop (quit from the tray, not just close the window).
Windows: "Git executable not found" (or uvx not found)
The git+https://… form makes uv shell out to a git executable. Claude Desktop does not pass
your shell — or even your System PATH — to the MCP subprocess; it spawns servers with its own
trimmed environment. (The PATH it prints in the logs is its command-resolution list, not what
the child process receives.) So a git that runs fine in PowerShell, installed in a System-PATH
directory, can still come back "not found" here — and a bare "command": "uvx" can fail to resolve
for the same reason. Two fixes:
-
Point at a local checkout — no runtime git (recommended). Clone once in a terminal where git works, then use
--from <folder>instead of--from git+…:Update later with
git pullin that folder, then restart Desktop. -
Or force the tools onto the server's
PATH. Keep thegit+httpsform and add anenvblock that hands the child an explicitPATH— git, plus uv's bin and the winget-links dir:If
uvxitself still isn't found, also set"command"to its absolute path (Get-Command uvxto locate it, e.g.C:\Users\<you>\AppData\Local\Microsoft\WinGet\Links\uvx.exe).
Available tools
All tools return a JSON object. Lookups that miss return {"error": "not_found", "did_you_mean": [...]}.
22 tools. Arguments marked ? are optional.
Start here
Data lookups
DPS & comparison
Build evaluation
Bestiary
Run analysis & metadata
Batch lookups. get_weapon, get_item and get_character accept name as
either a string or a list of strings. A list returns {"results": [...]} in
the order given, each entry a record or its own not_found — so detail on
several entities costs one round-trip, not N.
list_characters returns full records, unlike list_weapons / list_items,
which return summaries. The whole 50-character corpus is only ~7.7K tokens, so a
survey answers in a single call with no follow-up get_character; pass
detail="summary" for {id, name} rows instead. Its scaling_stat filter is a
derived union — characters have no scaling-stat field — matching a positive
stat-gain modifier, a positive flat bonus, or a matching wanted_tag. Each
matched record carries a scaling_match object naming which signal fired, e.g.
Engineer {"gain_pct": 25, "flat": 10, "wanted": true} vs Technomage
{"wanted": true}, so the derivation is visible rather than asserted.
Characters penalised in that stat are excluded from the match.
starting_weapon_pool is the run-start weapon-selection pool, not a fixed
starting weapon: most characters offer a dozen or more, Arms Dealer offers only
the Pistol, and Beast Master and Bull offer none.
stats / current_stats are objects keyed by short stat name (e.g. {"ranged_damage": 7, "max_hp": 65}).
names_with_tiers is a list of [name, tier] pairs. path_a / path_b are lists of tier numbers.
Note the two stat-name forms: stats / current_stats use the short name (ranged_damage), while the stat argument of explain_stat and stat_display_value uses the stat_-prefixed form (stat_ranged_damage). get_filter_options returns the valid filter values so you don't have to guess (all filters are case-sensitive exact matches).
evaluate_run takes exactly one input: pass the save's contents as run_json (e.g. an uploaded/pasted run.json) or its location as path (e.g. a file in your Brotato save directory). The save is read-only — it is never modified. Ids the loaded dataset doesn't recognize (e.g. content newer than your build) are listed under notes rather than dropped; a malformed save returns {"error": "bad_run_file", ...}.
Building the dataset
The dataset is not committed — it is built from an extraction of a real game install. The raw
extracted/, the decompiled recovered/, the copyrighted game_files/, and the derived
data/brotato.json are all gitignored (see docs/extraction-setup.md
for how the extraction is produced). Once extracted/ is present at the repo root:
This writes data/brotato.json. Game version auto-detects from the decompiled
recovered/singletons/progress_data.gd (its VERSION constant), and generated_at defaults to
the current UTC time. Pass --game-version <ver> or --generated-at <iso8601> explicitly to
override either — e.g. if recovered/ isn't present, or to pin a reproducible value for a test
or release script. Re-run after each patch to refresh your local copy — it stays gitignored, so
don't commit it.
How it works
brotato_coach/tres.py— a minimal Godot.tresparser.brotato_coach/builders/— turn parsed.tresinto enriched records (weapons with precomputed DPS lines, items with archetype flags, characters with gain modifiers, sets, and the verifiedstat_mechanicstable).brotato_coach/calc.py— pure DPS / merge math (no I/O), unit-tested against hand-verified values.brotato_coach/{query,answers,evaluate}.py— pure functions that produce finished answers.brotato_coach/runfile.py— pure parser that normalizes a Brotatorun.jsonsave into a build (character, weapons, items, realized stats) forevaluate_run; the only I/O is reading the save file.brotato_coach/server.py— thin FastMCP wrappers over those functions.
Reference material on the game mechanics the coach encodes lives in docs/
(extraction setup, weapon-merge DPS methodology, run post-mortem methodology, stat mechanics).
Disclaimer
This is an unofficial, fan-made tool. It is not affiliated with, endorsed by, or sponsored by Blobfish, the developer of Brotato, or any of its partners. Brotato and all related names, marks, and assets are the property of their respective owners.
This project ships no game assets and no game data. The stat dataset it operates on is
generated locally, by you, from a copy of the game you already own (build_dataset.py reads an
extraction of your own install). Nothing derived from the game's copyrighted files is distributed
in this repository.
The software is provided "as is", without warranty of any kind (see LICENSE). Its recommendations are computed from datamined values and may be incomplete or wrong; use your own judgment.
License
MIT © 2026 Brendan LeFebvre. This license covers the code and documentation in this repository only — it does not grant any rights to Brotato or its assets.
來源:README.md,提交 9e02315
工具
0版本歷史
1- v0.14.1最新Sep 16, 2026
評分
已滿足適用檢查項的 50%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式10 分
請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分