Spud Coach — a deterministic theorycrafter for Brotato

What it is

Is this weapon actually better at your stats? Is your build strong, or did you just get lucky? Spud Coach answers with real numbers pulled straight from the game's data — every weapon, item, and stat interaction computed exactly, not remembered off a tier list.

Install

uvx spudcoach

Requires Python 3.11+ and uv — uvx comes bundled with it.

Build your dataset

The game's data files are copyrighted, so nothing pre-built ships with Spud Coach — you generate data/brotato.json yourself, once, from your own Brotato install.

uv run python build_dataset.py

Needs a local extraction first — see extraction-setup.md. Game version and build timestamp are auto-detected; re-run after each game patch to refresh your local copy.

Connect it to Claude

Claude Code

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

Claude Desktop

{
  "mcpServers": {
    "spud-coach": {
      "command": "uvx",
      "args": ["spudcoach", "--data", "/path/to/brotato.json"]
    }
  }
}

Add this to claude_desktop_config.json, then fully restart Claude Desktop. Hitting a "Git executable not found" error on Windows? See the README.

What you get

Data lookups

get_weapon / get_item / get_character — full records: stats, effects, kit
get_weapon_class_set — set bonuses for a weapon class
list_weapons / list_items — filtered summaries
get_filter_options — valid filter values (tags, archetypes, tiers, classes)

DPS & comparison

weapon_dps — one weapon's realized DPS at your stats
compare_weapons — rank several weapons by DPS
compare_merge_paths — which tier-merge order wins, and where it flips

Build evaluation

evaluate_item_for_build — live / wasted / harmful verdict for an item
loadout_set_bonuses — set-bonus progress across a whole loadout
explain_stat — a stat's real mechanics (caps, dead-weight ranges)
stat_display_value — raw stat → what the game displays

Run analysis

evaluate_run — post-mortem a whole run.json in one call
check_dataset_version — which game version the facts are from