Brotato Coach

io.github.brendanlefebvre由 GitHub 账号 brendanlefebvre 发布v0.14.1更新于 Oct 24, 2026

Deterministic Brotato theorycrafter MCP server: facts and math, not guesses.

概览

AI 生成的概览

本地运行的 MCP 服务器,基于自行构建的游戏数据集回答《Brotato》配装问题:武器与道具查询、DPS 计算和存档复盘。

可以做什么
  • 查询武器、道具、角色、武器类别套装和敌人,支持筛选与批量名称列表
  • 计算随属性变化的武器 DPS,比较武器与合成路径,并排序下一步该提升哪项属性
  • 判断某道具对指定角色和属性面板是生效、浪费还是有害,并显示整套配装的套装加成进度
  • 解释属性机制,并按角色修正把原始属性换算为显示值
  • 查看敌人在各波次的属性与波次构成
  • 一次调用复盘整份 run.json 存档,并检查数据集的游戏版本与 schema 版本
适用场景
适合希望获得基于数据挖掘数值而非模型记忆的《Brotato》建议时使用:判断道具是否契合当前对局、在当前属性下比较武器,或根据存档复盘已结束的对局。它是玩家自制的理论计算辅助工具,并非通用游戏攻略。
运行要求
以 PyPI 包 spudcoach 通过 uvx 在本地以 stdio 运行,或从代码仓库用 uv 和 Python 3.11+ 运行。需要本地构建的 brotato.json 数据集,通过 --data 参数或 SPUDCOACH_DATA 环境变量指定;缺少数据集时服务器拒绝启动。构建数据集需要自有的《Brotato》游戏安装和提取步骤。
安装前请注意
数据集由受版权保护的游戏文件派生,不随项目分发;需用自己拥有的游戏副本自行构建,且不应提交到仓库。evaluate_run 会读取存档文件或粘贴的存档 JSON,仅作只读处理,不会修改。建议基于数据挖掘数值计算,可能不完整或有误。本项目为非官方作品,与游戏开发商无关联。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Brotato Coach,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

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+
  • uv for environment/dependency management

Install dependencies:

bash
uv sync

Quick start

Build the dataset (needs a local extraction — see Building the dataset), then start the server:

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

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):

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

Run

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

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:

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

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.:

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

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.

  1. Install uv on the machine running Claude Desktop (winget install astral-sh.uv on Windows, or the standalone installer).

  2. Open the config file and add the spud-coach server:

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

    Fetch-from-repo form:

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

    Point --data at your built dataset (SPUDCOACH_DATA works as an env-var alternative). On macOS use a POSIX path like /Users/<you>/brotato.json.

  3. 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+…:

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

    Update later with git pull in that folder, then restart Desktop.

  • Or force the tools onto the server's PATH. Keep the git+https form and add an env block that hands the child an explicit PATH — git, plus uv's bin and the winget-links dir:

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

    If uvx itself still isn't found, also set "command" to its absolute path (Get-Command uvx to 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

ToolArgumentsReturns
read_me—Session-start primer: how Brotato's core loop works, the source-verified stat mechanics, and what every precomputed field assumes. Call once, before anything else

Data lookups

ToolArgumentsReturns
get_weaponname, tier?Weapon record incl. raw stat-aware fields, on-hit effects, and weapon-class sets; {matches:[...]} if tier omitted and several tiers match
get_itemnameItem record: effects, tags, archetype, frozen_stat
get_characternameCharacter kit: wanted_tags, banned_item_groups, flat_bonuses, gain_modifiers, special_effects, class_bonuses, starting_weapon_pool
get_weapon_class_setclass_nameWeapon-class set bonuses (Blade, Gun, Elemental, …), by equipped count
list_weaponsscaling_stat?, tier?{weapons:[...]} filtered summaries
list_itemstag?, scaling_stat?, archetype?, tier?{items:[...]} filtered summaries
list_charactersscaling_stat?, wanted_tag?, banned_item_group?, special_effect?, class_bonus_set?, can_start_with?, detail?{characters:[...]} — full records, not summaries (see below)
get_filter_options—Valid filter values in the dataset: item tags, archetypes, scaling stats, tiers, weapon-class names, enemy abilities / attack kinds / zones, and the character filter vocabularies

DPS & comparison

ToolArgumentsReturns
weapon_dpsname, tier, stats, aoe_enemies_hit?, character?, weapon_count?, engagement_distance?, loadout?, apply_set_bonuses?Realized, stat-aware DPS at your build, split into base_dps + proc_dps, with a cadence breakdown and the assumptions baked in
compare_weaponsnames_with_tiers, stats, plus the same optional arguments as weapon_dps{ranking:[...]} sorted by DPS descending, at one shared stat block
compare_merge_pathsweapon_name, path_a, path_b, stats?Winner or crossover_rd for two tier-merge paths (lists of tiers)
stat_gradientweapons, stats, step?, character?, aoe_enemies_hit?, engagement_distance?Which stat to buy next: stats ranked by the DPS gain from +step of each. DPS only — survivability is out of scope

Build evaluation

ToolArgumentsReturns
evaluate_item_for_builditem_name, character_name, current_statsPer-effect verdict — live / wasted / harmful — with reasons, plus a summary
loadout_set_bonusesweapon_namesPer-class set progress across a whole loadout: equipped count, active bonuses, and next threshold
explain_statstatVerified stat mechanics: caps, special behavior, neglectable / never-negative flags
stat_display_valuecharacter, stat, raw_valueDisplayed value after the character's gain modifiers (e.g. Ranger RD 6 → 9)

Bestiary

ToolArgumentsReturns
get_enemyname, wave?Enemy record: base stats, per-wave stat slopes, attack profile, ability tags. Pass wave (1-20) to also resolve effective stats at that wave
list_enemiesappears_in?, ability?, attack_kind?{enemies:[...]} filtered summaries
wave_compositionwave, danger?Base-game (Crash Zone) composition for a wave: enemy groups, base counts, first-spawn timing, repeats

Run analysis & metadata

ToolArgumentsReturns
evaluate_runpath? or run_json?One-call post-mortem of a whole Brotato run.json save: run context (character, wave, danger), realized stats, weapon-DPS ranking, set progress, and per-item verdicts
check_dataset_version—game_version, generated_at, schema_version

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:

bash
uv run python build_dataset.py

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

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 startupbrotato_coach.server (FastMCP)                  16 tools over the pure functions     │     ▼   connected as a pluginClaude Code / Desktop / Web                     chat frontend
  • brotato_coach/tres.py — a minimal Godot .tres parser.
  • brotato_coach/builders/ — turn parsed .tres into enriched records (weapons with precomputed DPS lines, items with archetype flags, characters with gain modifiers, sets, and the verified stat_mechanics table).
  • 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 Brotato run.json save into a build (character, weapons, items, realized stats) for evaluate_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
SourceWeft 尚未在沙箱中启动过该软件包,因此其工具未知。

版本历史

1
  1. v0.14.1最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分