Brotato Coach

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:

uv sync

Quick start

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

uv run python build_dataset.py                        # writes data/brotato.json

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

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

Run

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:

{

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

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:

   {

"mcpServers": { "spud-coach": { "command": "uvx", "args": [ "--from", "git+https://github.com/brendanlefebvre/spud-coach", "spudcoach", "--data", "C:\\Users\\ \\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/ /brotato.json.

1. 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 instead of --from git+…:

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

  {

"mcpServers": { "spud-coach": { "command": "uvx", "args": ["--from", "C:\\Users\\ \\src\\spud-coach", "spudcoach", "--data", "C:\\Users\\ \\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:

  "env": {

"PATH": "C:\\Program Files\\Git\\cmd;C:\\Users\\ \\.local\\bin;C:\\Users\\ \\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\ \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,