Brotato Coach

Brotato 教练

一款用于 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 点远程伤害和 65 点生命值。”
• “20 点远程伤害时，T4 Minigun 和 T4 Revolver 哪个伤害更高？”
• “攻击速度什么时候会变成无用属性？枪械流派可以让击退变成负数吗？”
• “Ranger 的远程伤害加成会如何影响 6 点基础属性？”
• “这是我的 run.json——这个构筑表现如何？”（一次性对整个存档进行复盘）

搭配 Claude Desktop 使用

Claude Desktop 可以通过 uvx 以两种方式启动服务：直接从此仓库获取（重启时自动更新，但需要能访问 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 不会将你的 shell，甚至 System PATH，传递给 MCP 子进程；**它会使用经过精简的环境启动服务。（它在日志中打印的 PATH 是用于命令解析的列表，并非子进程实际接收的内容。）因此，即使 git 在 PowerShell 中运行正常，且安装在 System PATH 目录下，在这里仍可能返回“未找到”；同样，单独使用 "command": "uvx" 也可能因相同原因无法解析。有两种解决方法：

• **指向本地检出目录——无需运行时调用 git（推荐）。**在 git 可正常运行的终端中克隆一次，然后使用 --from <folder> 代替 --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\\<you>\\src\\spud-coach", "spudcoach",
                 "--data", "C:\\Users\\<you>\\path\\to\\brotato.json"]
      }
    }
  }
  

  之后在该文件夹中运行 git pull 更新，然后重启 Desktop。

• **或者强制工具使用服务的 PATH。**保留 git+https 形式，并添加一个 env 块，向子进程传入明确的 PATH——包括 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 相同的可选参数	{ranking:[...]}，按 DPS 从高到低排序，并使用同一组属性
compare_merge_paths	weapon_name, path_a, path_b, stats?	对两条等级合并路径（等级列表）给出胜者或 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	应用角色增益修正后的显示值（例如 Ranger 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 参数既可传入字符串，也可传入字符串列表。传入列表时会按给定顺序返回 {"results": [...]}，每个条目都是一条记录或对应的 not_found——查询多个实体只需一次往返，而不是 N 次。

list_characters 会返回完整记录，不同于只返回摘要的 list_weapons / list_items。全部 50 个角色的数据仅约 7.7K 个 token，因此一次调用即可完成概览，无需后续调用 get_character；若传入 detail="summary"，则会返回 {id, name} 行。其 scaling_stat 筛选器是一个派生并集——角色没有 scaling-stat 字段——匹配具有正向属性增益修正、正向固定加成或匹配的 wanted_tag 的角色。每条匹配记录都包含一个 scaling_match 对象，说明触发匹配的信号，例如 Engineer {"gain_pct": 25, "flat": 10, "wanted": true}，与 Technomage {"wanted": true}，因此派生依据是可见的，而非仅作断言。该属性受到惩罚的角色不会纳入匹配结果。

starting_weapon_pool 是对局开始时的武器选择池，并非固定的初始武器：大多数角色可选十几种或更多武器，Arms Dealer 只有 Pistol，而 Beast Master 和 Bull 则没有武器。

stats / current_stats 是以简短属性名为键的对象（例如 {"ranged_damage": 7, "max_hp": 65}）。 names_with_tiers 是由 [name, tier] 对组成的列表。path_a / path_b 是由等级数字组成的列表。 请注意两种属性名称格式：stats / current_stats 使用简短名称（ranged_damage），而 explain_stat 和 stat_display_value 的 stat 参数使用带 stat_ 前缀的格式（stat_ranged_damage）。get_filter_options 会返回有效的筛选值，因此你无需猜测（所有筛选值都区分大小写且必须完全匹配）。

evaluate_run 接受且仅接受一个输入：将存档内容作为 run_json 传入（例如上传或粘贴的 run.json），或将其位置作为 path 传入（例如 Brotato 存档目录中的文件）。存档只读，不会被修改。已加载的数据集无法识别的 ID（例如内容比你的游戏版本更新）会列在 notes 下，而不会被丢弃；格式错误的存档会返回 {"error": "bad_run_file", ...}。

构建数据集

数据集不会提交到仓库，而是从真实游戏安装文件的提取内容构建。原始的 extracted/、反编译后的 recovered/、受版权保护的 game_files/，以及派生文件 data/brotato.json 均已加入 gitignore（提取过程请参阅 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/ 不存在时，或需要为测试或发布脚本固定一个可复现的值时。每次补丁更新后都要重新运行，以刷新本地副本；该文件会一直被 gitignore，因此不要提交。

工作原理

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 存档规范化为一套配置（角色、武器、物品、实际属性），供 evaluate_run 使用；唯一的 I/O 是读取存档文件。
• brotato_coach/server.py — 封装这些函数的轻量 FastMCP 包装器。

有关该工具编码的游戏机制的参考资料位于 docs/（提取设置、武器合并 DPS 方法、对局复盘方法、属性机制）。

免责声明

这是一款非官方的粉丝自制工具。它与 Blobfish（Brotato 的开发者）及其任何合作伙伴无关联、未经其认可或赞助。Brotato 及所有相关名称、标记和素材均为其各自所有者的财产。

本项目不提供任何游戏素材或游戏数据。本项目使用的属性数据集由你从自己拥有的游戏副本中在本地生成（build_dataset.py 会读取你自己安装文件的提取内容）。本仓库不会分发任何从游戏受版权保护的文件中派生的内容。

本软件按“原样”提供，不作任何形式的保证（参见 LICENSE）。其建议基于从游戏数据中提取的数值计算，可能不完整或有误；请自行判断。

许可证

MIT © 2026 Brendan LeFebvre。本许可证仅适用于本仓库中的代码和文档，不授予任何关于 Brotato 或其素材的权利。