Skip to main content
Glama
Backpack Battles MCP

Backpack Battles MCP

by 53721222-gif

Backpack Battles MCP

类似 MCPTheSpire 的《背包乱斗 / Backpack Battles》本地 MCP 服务: 在游戏内挂一个轻量 bridge,把职业、回合、重试次数、金币、商店物品与价格、刷新费、背包摆盘、储物箱暴露给大模型,并开放购买、刷新、编辑背包/物品、摆放、旋转、开战等操作。


1. 架构

┌──────────────────────────────┐        TCP 127.0.0.1:8765        ┌──────────────────┐
│  Backpack Battles (Godot 3.6)│  <───────────────────────────>  │  bpb_mcp.server  │
│  McpBridge.gd  (autoload)    │      newline-delimited JSON      │  (Python, stdio) │
│  bpb_api.gd    (game logic)  │                                  └────────┬─────────┘
└──────────────────────────────┘                                           │ MCP JSON-RPC
                                                                           ▼
                                                                    ┌──────────────┐
                                                                    │ LLM / MCP    │
                                                                    │ 客户端        │
                                                                    └──────────────┘
  • 不修改 BackpackBattles.pck,不注入 DLL,不使用 BepInEx。

  • 利用 Godot 3.6 的 override.cfg 在 exe 同目录覆盖 autoload,脚本放在 user://mcp/。

  • 游戏内 bridge 只监听 127.0.0.1:8765;Python 侧提供 MCP stdio 服务(可选 HTTP API)。

  • 已在本机 Backpack Battles 1.1.9b / Godot 3.6 上验证;pck 未被改动,游戏日志仍显示 [integrity_check:ok]。


Related MCP server: game-mcp

2. 功能

分类

工具名

说明

状态

bpb_get_state

完整状态(shop/title);战斗期摘要;含 wins / total_wins / survival

状态

bpb_get_phase

轻量状态:state/round/tries/gold/wins/total_wins/survival,战斗期安全

状态

bpb_get_backpack

完整背包布局:bags/items 位置、cells、shape、rotation、grid、storage,只读

信息

bpb_get_star_slots

星位/受影响格(方向 0/2/4/7)、当前命中物品、extension_cells、宝石 sockets

信息

bpb_get_stamina

玩家 stamina/max/regen、每件物品 stamina_cost/types/伤害,已部署总耗

信息

bpb_get_recipes

base/result/ingredients/催化剂、作为材料配方、牌堆 gated_items

购买

bpb_buy_item

买商店物品并放入储物箱(slot 1-5 或 item_id);会补发 dropped 信号,触发 onDropped 购买效果(如未挖掘潜力);技能商店返回 skill_id

商店

bpb_reserve_item

保留/取消保留商店物品(免费,跨刷新保留)

商店

bpb_refresh_shop

刷新商店(扣金币)

背包

bpb_store_item

把背包物品放回储物箱,腾出格子

背包

bpb_sell_item

出售背包物品,立即获得金币(储物箱物品需先放回背包)

背包

bpb_set_fusion_lock

锁定/解除物品自动融合(item_id + locked=true/false);背包/储物箱物品可用,背包本体不可用

宝石

bpb_socket_gem

把宝石镶到宿主物品的空镶嵌位(host_id + gem_id + socket_index,默认 0)

宝石

bpb_unsocket_gem

从宿主镶嵌位取下宝石;优先放回背包,没空格则进储物箱

编辑

bpb_open_backpack_edit

进入背包层编辑模式(等价 bags)

编辑

bpb_open_item_edit

进入物品层编辑模式(等价 items)

编辑

bpb_edit_items

只编辑物品:背包固定,物品可放到任意格子(包括包外)

编辑

bpb_edit_bags

只编辑背包:物品固定,背包可移动/旋转,不牵连物品

编辑

bpb_edit_all

编辑全部:只规范化落格,不再把跨包/包外物品移走

编辑

bpb_set_edit_mode

兼容别名:all/bags/items/default/bag/item

摆放

bpb_place_item

原生 drop 落格(pickup 当前位置 → drop);物品/全部模式允许包外/跨包

摆放

bpb_place_bag

移动空背包;非空返回 bag_not_empty。背包模式物品绝对位置不变

旋转

bpb_rotate_item

游戏内原子旋转:removeItem→orientItem→addItemByTopLeft,绕过 drop/hotswap;目标需在包内且不重叠;BPB_ROTATE=0 关闭

旋转

bpb_rotate_bag

游戏内原子旋转空背包;非空返回 bag_not_empty;BPB_ROTATE=0 关闭

战斗

bpb_start_battle

开始战斗;开战前只规范化落格,不移走跨包物品

战斗

bpb_wait_for_result

等待结算;自动跳过并回商店;十胜时不会先跳过,返回 survival_choice_required

战斗

bpb_skip_result

手动跳过结算;十胜提示出现前后都被拦截,需先选择

10胜

bpb_enter_survival

选择“进入生存模式”;can_start=true 即可,原生提示延迟时会主动打开

10胜

bpb_stop_here

选择“到此为止”(结束本轮,保留胜场)

10胜

bpb_choose_survival

统一选择:choice=survival/stop

开局

bpb_set_class / bpb_set_loadout

标题界面选择职业 / 初始 loadout

开局

bpb_start_run / bpb_continue

新开一局(可带 class_id/loadout)/ 继续挂起的 run

诊断

bpb_health

检查网桥与当前状态

购买后物品/技能进储物箱,不会自动进背包;需要再调用 bpb_place_item。购买与放置都会补发 dropped 信号,触发 onDropped 类效果(未挖掘潜力、Lootbox、Amulet Unidentified 等)。技能也是 1×1 可摆放 Item。

融合锁定:state.backpack.items[].fusion_locked / storage[].fusion_locked 表示物品是否锁定自动融合;state.backpack.fusion_locked_count 是背包内数量。用 bpb_set_fusion_lock 切换,锁定后不能用该物品自动合成,解锁后恢复;背包本体不可锁定。

宝石镶嵌:state.backpack.items[].sockets / storage[].sockets 是每个镶嵌位的 {index, occupied, gem_id, gem_name};is_gem=true 的物品是散装宝石。用 bpb_socket_gem 镶入、bpb_unsocket_gem 取下;socketed_gems_count 是已镶数量。

购买后编辑流程:bpb_edit_items(物品可放包外)→ bpb_edit_bags(移动背包覆盖物品,物品固定)→ bpb_edit_all(规范化落格;跨包物品保留)。

标题界面先看 state.title.classes[].loadouts,用 bpb_set_class / bpb_set_loadout 选择,再 bpb_start_run。

10 胜提示:原生提示有约 1 秒延迟;检测到 wins=10 且 survival.can_start=true 就应准备选择,不要先 bpb_skip_result。用 bpb_enter_survival 或 bpb_stop_here 明确选择;bpb_skip_result / bpb_wait_for_result 在提示出现前后都会被拦截,不会先结算奖杯。


3. 环境要求

  • Windows 10/11

  • 已安装 Backpack Battles(Steam AppID 2427700)

  • Python 3.8+(本项目无第三方依赖)

  • 游戏必须正在运行(bridge 在游戏进程内)

本项目在以下环境验证:

  • 游戏版本 1.1.9b

  • Godot 3.6.stable.custom_build

  • Python 3.9.1(64 位)

  • 游戏目录:D:\Steam\steamapps\common\Backpack Battles


4. 安装

在项目目录(例如 D:\mcpbpb)执行:

cd /d D:\mcpbpb
python -m bpb_mcp.cli install
python -m bpb_mcp.cli doctor

安装器会:

  1. 自动定位 Steam 游戏目录(注册表 / libraryfolders.vdf,也可 --game-dir 指定);

  2. 复制 mod/McpBridge.gd、mod/bpb_api.gd 到:

    %APPDATA%\Godot\app_userdata\Backpack Battles\mcp\
  3. 在 BackpackBattles.exe 同目录创建 / 合并 override.cfg:

    [autoload]
    McpBridge="*user://mcp/McpBridge.gd"

    已有 override.cfg 会先备份为 override.cfg.bak.<时间戳>,并保留其他 section / autoload。

为什么不用改 pck?

Godot 3.6 在启动时会读取 exe 同目录的 override.cfg,并据此注册 autoload;脚本从 user:// 加载。因此:

  • 不触碰 314MB 的 BackpackBattles.pck;

  • 不需要 BepInEx / DLL 注入;

  • 游戏更新后通常只需重新 install;

  • 不会影响 pck 的完整性校验。

卸载

python -m bpb_mcp.cli uninstall

移除 override.cfg 中的 McpBridge autoload 和 user://mcp/ 下的两个脚本;备份文件保留。


5. 启动与验证

  1. 启动游戏(Steam 或 python -m bpb_mcp.cli launch)。

  2. 进入标题界面,点击「继续 / 新游戏」,进入商店。

  3. 验证:

python -m bpb_mcp.cli health
python -m bpb_mcp.cli state

health 正常输出示例:

{
  "ok": true,
  "bridge": {"pong": true, "uptime_ms": 12345, "version": "0.1.0"},
  "game_state": "shop",
  "round": 2,
  "gold": 18,
  "version": "1.1.9"
}

6. 接入 MCP 客户端

Claude Desktop

编辑 claude_desktop_config.json:

{
  "mcpServers": {
    "backpack-battles": {
      "command": "python",
      "args": ["-m", "bpb_mcp.server"],
      "cwd": "D:\\mcpbpb"
    }
  }
}

如果客户端找不到 python,把 command 换成 Python 绝对路径,例如:

"command": "C:\\Users\\<你>\\AppData\\Local\\Programs\\Python\\Python39\\python.exe"

Cursor / Cline / 其他 MCP 客户端

同样是 stdio 方式:

  • command: python

  • args: ["-m", "bpb_mcp.server"]

  • cwd: D:\mcpbpb

仓库里也提供了 start_mcp.bat,可直接作为 command 使用。


7. 典型工作流

0. 标题界面(可选)
   bpb_get_state → state.title.classes[].loadouts
   bpb_set_class {"class_id":2,"loadout":0}
   bpb_start_run {"force_new":true}

1. bpb_get_state
   → 看 state=shop、shop.items(slot/price/size/id/kind)、shop.choose_one、
     shop.reserved、backpack.grid、storage

2. bpb_buy_item {"slot": 1}
   → 普通商店:金币扣减,物品进 storage
   → 技能商店(choose_one=true):选择技能,金币扣减,技能进 storage,返回 skill_id

3. bpb_get_state
   → 从 storage[].id 或 buy_item 返回的 skill_id 拿到 id

4. bpb_place_item {"item_id": 123456, "x": 3, "y": 3}
   → 放进背包某个包覆盖的格子;返回 cells/top_left
   → 背包满了先 bpb_store_item {"item_id": 旧物品id} 腾格
   → 想换金币用 bpb_sell_item {"item_id": 旧物品id}

5. bpb_reserve_item {"slot": 1, "reserved": true}
   → 保留商品(免费);reserved:false 取消保留

6. bpb_refresh_shop
   → 刷新(看 shop.reroll_cost);保留项仍会保留

7. bpb_start_battle
   → 等待真正进入 combat 后返回

8. bpb_wait_for_result {"timeout_seconds": 90}
   → 等待结算界面,自动跳过,返回下一回合 shop 状态
   → 战斗期间 bpb_get_state 只返回摘要,不读背包;用 bpb_get_phase 轮询

模型不需要关心鼠标、拖拽、动画;所有操作都是确定性的格子/ID 操作。

购买后编辑顺序

1. bpb_edit_items
   → 背包固定;bpb_place_item 可把物品放到任意格子,包括包外(outside_bag=true)

2. bpb_edit_bags
   → 物品固定;bpb_place_bag 移动**空背包**去覆盖物品(非空包先移出内容);背包放置强制 face=0/rotation=0,避免显示与 cells 差 90°
   → 移动背包不会牵连物品的绝对格子

3. bpb_edit_all
   → 物品/背包都可编辑;物品可以同时覆盖多个背包,不会被自动移动
   → 返回 moved_to_storage(物品 id/name 列表)
  • bpb_edit_bags 下调 bpb_place_item 返回 items_fixed_in_bag_mode。

  • bpb_edit_items 下调 bpb_place_bag 返回 bags_fixed_in_item_mode;bpb_rotate_bag 对空背包原子旋转,非空返回 bag_not_empty。

  • bpb_edit_all 是最终化步骤;之后检查 backpack.floating_count == 0,并确认关键物品仍在背包中。跨包允许。

10 胜提示

bpb_get_state
  → state.wins=10, state.survival.was_max_wins=true
  → state.survival.can_start=true(即使 prompt_visible 还在 1 秒延迟中)
  → prompt_visible=true 时显示界面

选择一:
bpb_enter_survival          # 进入生存模式(不会先结算奖杯)
或
bpb_stop_here               # 到此为止
或
bpb_choose_survival {"choice":"survival"|"stop"}

注意:
bpb_skip_result / bpb_wait_for_result 在十胜提示出现前后都返回
survival_choice_required;不会 auto-skip 到 endRun/奖杯结算。
进入后 state.survival.just_started=true;等切回 shop 再进行下一回合。

8. 状态结构

bpb_get_state 返回的核心字段:

{
  "state": "shop",
  "state_id": 1,
  "round": 2,
  "max_rounds": 18,
  "tries": 4,
  "gold": 18,
  "wins": 10,
  "current_run_wins": 10,
  "total_wins": 112,
  "survival": {
    "prompt_visible": false,
    "can_start": false,
    "can_stop_here": false,
    "was_max_wins": false,
    "survival_mode": false
  },
  "class": {"id": 0, "name": "Ranger", "name_localized": "游侠"},
  "mode": {"id": 1, "name": "Unranked"},
  "hp": {"current": 35, "max": 35},
  "edit_mode": {"id": 0, "name": "all"},
  "can_start_battle": true,
  "run_started": true,
  "last_result": "loss",
  "combat": {"visible": false, "post_combat_visible": false},
  "can_skip_result": false,
  "version": "1.1.9",

  "shop": {
    "reroll_cost": 1,
    "rerolls": 0,
    "items_bought": 1,
    "choose_one": false,
    "reserved_count": 1,
    "reserved_items": [{"id": 2483562, "name": "Customer Card", "name_localized": "会员卡"}],
    "items": [
      {
        "slot": 1,
        "kind": "item",
        "reserved": false,
        "can_reserve": true,
        "id": 124371,
        "name": "Lump of Coal",
        "name_localized": "一坨煤炭",
        "price": 2,
        "sell_price": 1,
        "rarity": "普通",
        "size": [1, 1],
        "cells_count": 1,
        "rotation": 0,
        "on_sale": false,
        "affordable": true,
        "description": "……"
      }
    ]
  },

  "backpack": {
    "width": 9,
    "height": 7,
    "bags": [
      {
        "id": 81202,
        "name": "Vineweave Basket",
        "name_localized": "藤条编织篮",
        "top_left": [2, 2],
        "cells": [[2,2],[3,2],[4,2],[2,3],[3,3],[4,3],[2,4],[3,4],[4,4]],
        "size": [3, 3],
        "rotation": 0
      }
    ],
    "items": [
      {
        "id": 81297,
        "name": "Healing Herbs",
        "name_localized": "治疗草药",
        "top_left": [2, 2],
        "cells": [[2, 2]],
        "rotation": 0,
        "price": 4,
        "sell_price": 2,
        "rarity": "普通",
        "is_bag": false,
        "bag_id": 81202,
        "bag_name": "藤条编织篮",
        "size": [1, 1]
      }
    ],
    "grid": [
      [null, null, null, ...],
      [null, null, {"bag_id":81202,"bag":"藤条编织篮"}, ...]
    ]
  },

  "storage": [
    {"id": 124371, "name": "Lump of Coal", "name_localized": "一坨煤炭", "price": 2, "sell_price": 1, "size": [1,1]}
  ]
}

标题界面

{
  "state": "title",
  "title": {
    "selected_class": 0,
    "configured_loadout": "0",
    "classes": [
      {
        "id": 0,
        "name": "Ranger",
        "name_localized": "游侠",
        "loadouts": [
          {"index": 0, "items": ["Ranger Bag", "Leather Bag", "Leather Bag", "Lucky Clover", "Wooden Sword"]},
          {"index": 1, "items": ["Vineweave Basket", "Leather Bag", "Healing Herbs", "Stone"]},
          {"index": 2, "items": ["Random Loadout Bag"]}
        ]
      }
    ]
  }
}

战斗期

{
  "state": "combat",
  "combat_only": true,
  "inventory_available": false,
  "round": 3,
  "tries": 4,
  "gold": 21,
  "wins": 10,
  "current_run_wins": 10,
  "total_wins": 112,
  "survival": {
    "prompt_visible": true,
    "can_start": true,
    "can_stop_here": true,
    "was_max_wins": true,
    "survival_mode": false
  },
  "can_skip_result": true,
  "last_result": "loss",
  "shop": {"items": [], "reroll_cost": 0, "rerolls": 0, "items_bought": 0,
           "choose_one": false, "reserved_count": 0, "reserved_items": []},
  "backpack": null,
  "storage": []
}

战斗期间 bpb_get_state 不访问背包/商店,避免游戏在战斗过渡时崩溃。需要完整背包请在 state=shop 时读取;等待结算用 bpb_get_phase / bpb_wait_for_result。

字段说明

  • state:title / shop / combat。

  • inventory_available:false 表示当前是战斗摘要,backpack 为 null、shop.items 为空。

  • combat_only:战斗摘要标记。

  • title:仅标题界面出现;含职业、当前选择、loadout 及其初始物品。

  • tries:剩余重试次数(失败会减少)。

  • round:当前回合(1-18)。

  • wins / current_run_wins:当前 run 胜场(10 胜触发提示)。

  • total_wins:累计胜场(来自游戏 getRunWins())。

  • survival:

    • prompt_visible:10 胜“到此为止 / 进入生存模式”提示是否出现;

    • can_start:是否可选择进入生存;

    • can_stop_here:是否可选择到此为止;

    • was_max_wins:是否达到 10 胜上限;

    • survival_mode:当前是否已在生存模式;

    • just_started:生存模式刚确认、仍在切回商店的过渡中;此时不要跳过结算。

  • shop.items[].price:当前价格(含折扣);on_sale 表示是否打折。

  • shop.choose_one:当前是否为五选一技能商店(第 3/10 回合)。

  • shop.items[].kind:item 或 skill(技能商店时)。

  • shop.items[].reserved / can_reserve:是否已保留 / 是否可保留。

  • shop.reserved_count / reserved_items:当前保留的商品数量与列表。

  • script:物品脚本路径(可用于区分技能/普通 Exclusive 物品)。

  • shape:物品当前朝向的归一化占用格(相对左上角)。

  • sell_price:出售价格;用 bpb_sell_item 卖出。

  • fusion_locked / locked:该物品是否锁定自动融合;用 bpb_set_fusion_lock 切换。

  • backpack.fusion_locked_count:背包内已锁定自动融合的物品数量。

  • is_gem:该物品是否宝石类(可镶嵌)。

  • sockets:该物品的镶嵌位列表 {index,occupied,gem_id,gem_name};用 bpb_socket_gem / bpb_unsocket_gem。

  • backpack.socketed_gems_count:已镶入宿主物品的宝石数量(背包 + 储物箱宿主)。

  • edit_mode:all / bags / items。

  • backpack.outside_count:当前不在任何背包内的物品数量。

  • backpack.invalid_count:兼容字段,当前不把跨包/包外算非法;正常为 0。

  • backpack.items[].outside_bag:该物品是否在包外(物品模式可临时这样放)。

  • backpack.items[].in_one_bag:该物品所有格是否属于同一个背包;false 不代表非法,游戏允许跨包。

  • backpack.items[].placed_by_player:是否走玩家落格流程(影响星位/触发)。

  • backpack.items[].position / bbox_center / float_offset:视觉位置、目标包围盒中心、偏移。

  • backpack.items[].floating:该物品是否浮空(偏移 > 0.75px)。

  • backpack.floating_count:浮空物品数量;正常应为 0。

  • backpack.grid[y][x]:

    • null:空格(不在任何包内);

    • {"bag_id","bag"}:只被背包覆盖,可放物品;

    • {"bag_id","bag","item_id","item"}:已被物品占用;

    • {"item_id","item"}:物品在包外(仅物品模式会出现)。

  • top_left:该物品/背包占据格子的最小 (x, y)。

  • cells:精确占用格列表。

  • storage:储物箱物品(购买后先到这里;全部模式放不下的物品也会自动到这里)。

  • can_skip_result:结算界面是否已出现(只有此时才能 bpb_skip_result / bpb_wait_for_result 跳过)。

  • last_result:上一回合结果(win / loss / draw);不是当前战斗的实时结果。

坐标:x 为列 0-8,y 为行 0-6。正常摆放要求物品在背包覆盖的格子里;items 模式允许临时放在包外,all 模式会把不落在同一背包内的物品自动移入储物箱。

技能商店:第 3/10 回合 shop.choose_one=true,shop.items[].kind="skill"。技能在内部也是 RigidBody2D 的 Item(1×1、有价格/描述),可以摆放:bpb_buy_item 会选择技能并放入储物箱(返回 skill_id),购买/放置都补发 dropped,未挖掘潜力会正常识别;再调用 bpb_place_item 摆进背包;技能会随背包一起持久化,重启后仍在。

保留商店物品:bpb_reserve_item 可保留/取消保留商品(免费)。shop.items[].reserved、shop.reserved_count、shop.reserved_items 会反映保留状态;保留项在刷新商店后仍保留。


9. 工具参数速查

工具

参数

bpb_get_state

无(战斗期返回摘要;含 wins/total_wins/survival)

bpb_get_phase

无(含 wins/total_wins/survival)

bpb_get_backpack

无(只读,不 normalize)

bpb_get_star_slots

item_id(可选;只查一件)

bpb_get_stamina

无

bpb_get_recipes

item_id(可选;可传商店物品 id;全量默认只查背包/储物箱)

bpb_buy_item

slot(1-5)或 item_id;技能商店时选择技能并放入储物箱,返回 skill_id

bpb_reserve_item

slot 或 item_id;reserved(默认 true,false=取消保留)

bpb_store_item

item_id(把背包物品放回储物箱)

bpb_sell_item

item_id(出售背包物品)

bpb_refresh_shop

无

bpb_open_backpack_edit

无(等价 bpb_edit_bags)

bpb_open_item_edit

item_id(可选;等价 bpb_edit_items)

bpb_edit_items

无(只编辑物品,背包固定)

bpb_edit_bags

无(只编辑背包,物品固定)

bpb_edit_all

无(全部;只规范化落格,不移走跨包物品)

bpb_set_edit_mode

mode: all/bags/items(兼容 default/bag/item)

bpb_set_class

class_id(0-6), loadout(0-2,可选)

bpb_set_loadout

loadout(0-2)

bpb_place_item

item_id, x, y(原生 drop;允许跨包/包外)

bpb_place_bag

item_id, x, y(仅空包;非空返回 bag_not_empty)

bpb_rotate_item

item_id, direction(原子旋转,目标需在包内且不重叠)

bpb_rotate_bag

item_id, direction(原子旋转,空背包)

bpb_start_battle

无(开战前只规范化落格,不移走跨包物品)

bpb_skip_result

无(10 胜提示下返回 survival_choice_required)

bpb_wait_for_result

timeout_seconds(默认 90), auto_skip(默认 true;提示下不自动选)

bpb_enter_survival

无(选择进入生存模式)

bpb_stop_here

无(选择到此为止)

bpb_choose_survival

choice: survival/stop

bpb_start_run

mode: unranked/ranked;force_new: 强制新开;class_id/loadout(可选)

bpb_continue

无

bpb_health

无


10. 可选 HTTP API

给非 MCP 客户端(脚本、网页、其他 Agent 框架):

python -m bpb_mcp.cli http --port 8766

方法

路径

说明

GET

/health

网桥 + 游戏状态摘要

GET

/state

完整状态(战斗期自动返回摘要)

GET

/phase

轻量状态(战斗期安全)

GET

/tools

工具 schema

POST

/action

{"action":"buy_item","args":{"slot":1}}

示例(PowerShell):

Invoke-RestMethod http://127.0.0.1:8766/state
Invoke-RestMethod http://127.0.0.1:8766/action -Method Post `
  -ContentType 'application/json' `
  -Body '{"action":"buy_item","args":{"slot":1}}'

默认只绑定 127.0.0.1;不要暴露到公网。


11. 命令行

python -m bpb_mcp.cli state
python -m bpb_mcp.cli phase
python -m bpb_mcp.cli health
python -m bpb_mcp.cli buy --slot 1
python -m bpb_mcp.cli reserve --slot 1
python -m bpb_mcp.cli reserve --slot 1 --unreserve
python -m bpb_mcp.cli store --item-id 123456
python -m bpb_mcp.cli sell --item-id 123456
python -m bpb_mcp.cli refresh
python -m bpb_mcp.cli edit --mode bags
python -m bpb_mcp.cli edit-items
python -m bpb_mcp.cli edit-bags
python -m bpb_mcp.cli edit-all
python -m bpb_mcp.cli set-class --class-id 2 --loadout 0
python -m bpb_mcp.cli set-loadout --index 0
python -m bpb_mcp.cli place --item-id 123456 --x 3 --y 3
python -m bpb_mcp.cli place-bag --item-id 81202 --x 2 --y 2
python -m bpb_mcp.cli rotate --item-id 123456
python -m bpb_mcp.cli battle
python -m bpb_mcp.cli wait-result
python -m bpb_mcp.cli enter-survival
python -m bpb_mcp.cli stop-here
python -m bpb_mcp.cli choose-survival --choice survival
python -m bpb_mcp.cli start-run --mode unranked
python -m bpb_mcp.cli start-run --mode unranked --force-new
python -m bpb_mcp.cli start-run --class-id 2 --loadout 0
python -m bpb_mcp.cli continue
python -m bpb_mcp.cli install
python -m bpb_mcp.cli doctor
python -m bpb_mcp.cli launch

12. 故障排查

game_not_running / 连接被拒绝

  • 游戏没启动;先启动游戏。

  • override.cfg 没放到 BackpackBattles.exe 同目录。

  • 游戏是旧进程:必须重启游戏后 autoload 才生效。

  • 端口 8765 被占用:改 mod/McpBridge.gd 的 PORT,并同步 Python Bridge 端口(或设置 BPB_BRIDGE_PORT,需自行扩展)。

api_load_failed

游戏内 user://mcp/bpb_api.gd 编译失败。查看:

%APPDATA%\Godot\app_userdata\Backpack Battles\logs\godot.log

搜索 Parse Error。修改 mod/bpb_api.gd 后重新 install;bridge 会按文件 MD5 热加载,无需重启游戏。

override.cfg 看起来没生效

游戏日志应有:

[McpBridge] bridge starting pid=...
[McpBridge] listen 127.0.0.1:8765 err=0

没有则检查:

  • 文件是否在 exe 同目录(不是 Backpack Battles_Data,游戏是 Godot 不是 Unity);

  • 文件编码是否为 UTF-8;

  • 是否被其他工具覆盖(安装器会备份并合并)。

can_start_battle=false

刚回到商店的 1-2 秒内,转场动画尚未结束。等一会儿再读状态,或使用 bpb_wait_for_result(它会等到 can_start_battle=true)。

刚启动游戏时 start_run 返回 title_not_ready

标题界面 / 职业资源还没加载完。等 3-5 秒后重试;GameAPI.start_run / continue_run 会自动重试约 6 秒。

skip_result 报 result_screen_not_visible

结算界面还没出现。不要提前调用;用 bpb_wait_for_result,它只在 can_skip_result=true 时跳过。

游戏更新后失效

内部类/方法名可能变化。用 tools/pck_inspect.py / tools/pck_extract.py 重新检查 pck,调整 mod/bpb_api.gd。当前验证版本 1.1.9b。

安装器找不到游戏

python -m bpb_mcp.cli install --game-dir "D:\Steam\steamapps\common\Backpack Battles"

13. 安全声明

  • 游戏内 bridge 只绑定 127.0.0.1:8765。

  • bridge 会加载并执行 user://mcp/bpb_api.gd 中的 GDScript;任何能写这个文件的人都能在游戏进程内执行代码。请勿把该目录共享给不可信程序。

  • HTTP API 默认只绑定 localhost;不要改成 0.0.0.0 暴露到公网。

  • 本工具用于单机/私人对局的状态读取与操作自动化;在线排位请自行遵守游戏规则。


14. 开发

目录

mcpbpb/
├─ bpb_mcp/
│  ├─ bridge.py        TCP 客户端(127.0.0.1:8765)
│  ├─ api.py           高层 API + wait/轮询
│  ├─ server.py        MCP stdio 服务(无第三方依赖)
│  ├─ http_api.py      可选 HTTP API
│  ├─ installer.py     override.cfg / user:// 安装、doctor、launch
│  └─ cli.py           命令行
├─ mod/
│  ├─ McpBridge.gd     游戏内 TCP 网桥 + 热加载
│  └─ bpb_api.gd       游戏内状态序列化与操作逻辑
├─ tools/
│  ├─ pck_inspect.py   解析 Godot pck
│  ├─ pck_extract.py   提取 pck 文件
│  ├─ bpb_tcp.py       原始 TCP 客户端
│  └─ smoke_live.py    实时状态 smoke test
├─ tests/test_offline.py
├─ start_mcp.bat
├─ start_http.bat
└─ README.md

热加载

修改 mod/bpb_api.gd 后:

python -m bpb_mcp.cli install

bridge 在下一次 api 调用时按 MD5 重新编译;不需要重启游戏。修改 McpBridge.gd 才需要重启。

添加新操作

  1. 在 mod/bpb_api.gd 增加 func my_action(ctx, args): ...;

  2. 在 bpb_mcp/api.py 增加方法;

  3. 在 bpb_mcp/server.py 的 TOOLS 和 call_tool 中注册;

  4. python -m bpb_mcp.cli install。

测试

python -m unittest discover -s tests -v
python tools\smoke_live.py

15. 已知限制

  • 10 胜选择:state.survival.prompt_visible=true 时必须用 bpb_enter_survival / bpb_stop_here / bpb_choose_survival 明确选择;bpb_skip_result / bpb_wait_for_result 会返回 survival_choice_required,不会自动选择。

  • 胜场:wins / current_run_wins 是当前 run 胜场(10 胜触发提示);total_wins 来自 getRunWins(),是累计胜场。

  • 编辑模式:items 只编辑物品(包固定,物品可临时在包外);bags 只编辑背包(物品绝对格固定);all 全部可编辑。物品可以同时覆盖多个背包,游戏没有单一背包限制。

  • 背包移动/旋转:只允许移动空背包;非空包返回 bag_not_empty。放置会强制 faceDirection=0 / rotation=0,按基础 shape 落格。旋转使用游戏内原子链:校验目标格全部在包内且无重叠,然后 removeItem → orientItem → addItemByTopLeft,不调用 drop/tryAddItem/hotswap。Pan 等 L 形已验证 4 连转、开战、重启。目标非法返回 cannot_rotate_in_place;BPB_ROTATE=0 可关闭。

  • 并发限制:同一游戏同时只应有一个 MCP 客户端/服务在操作;两个窗口并发调用会交错修改背包/商店,造成浮空或闪退。

  • 落格/浮空:bpb_place_item 使用游戏原生 pickup(当前位置) → 设目标包围盒中心 → drop(),触发正常落格回调并写回包围盒位置;跨包不拒绝。位置/朝向由游戏 drop 校验。

  • 开战前最终化:bpb_start_battle 只规范化位置/placedByPlayer,不会把跨包物品移入储物箱。

  • 战斗期状态:为避免战斗过渡时访问背包导致游戏崩溃,bpb_get_state 在 state=combat 只返回摘要(combat_only=true、inventory_available=false、backpack=null、shop.items=[])。战斗期用 bpb_get_phase / bpb_wait_for_result,回到 shop 再读完整状态。

  • 出售:bpb_sell_item 只出售背包内物品;储物箱物品需先 bpb_place_item 放回背包。出售会立即移除物品并加金币;非空背包不能直接出售(bag_not_empty)。

  • 物品 id:id 是游戏运行时的 instance id;游戏重启/continue 后会变化,操作前重新 bpb_get_state。

  • 技能:技能是 1×1 可摆放 Item,会占背包格;背包满时先用 bpb_store_item 腾格,再 bpb_place_item。技能随背包持久化。

  • 保留项:bpb_reserve_item 免费;保留项在刷新商店后仍会保留。取消保留传 reserved=false。

  • 存档写入时机:购买/摆放/旋转会在商店关闭或回合推进时由游戏写入 run 存档;不要在商店界面直接退出游戏,否则本次修改可能尚未保存。

  • 物品形状/旋转:普通矩形/常见 L 形物品已验证;带自定义旋转逻辑的物品若原地放不下会回滚并返回 cannot_rotate_in_place,换个位置再试。

  • 描述文本:游戏返回的 description 含 $t[...]、[sc ...] 等富文本标记,模型可自行忽略。

  • last_result 是上一回合结果,不是当前战斗实时结果;用 can_skip_result 判断结算是否出现。

  • 游戏版本:内部方法名基于 1.1.9b;更新后可能需要调整。

  • 仅本地:依赖游戏进程与 127.0.0.1,不支持远程/云游戏。

  • 不修改 pck:如果游戏未来移除 override.cfg 支持,需要改为 pck 注入方案。


16. License

MIT

Available Tools

35 tools
bpb_buy_itemA

购买商店物品并放入储物箱。若 state.shop.choose_one=true(第 3/10 回合的技能商店),则选择一个技能并放入储物箱(返回 skill_id);技能是 1×1 可摆放物品,再用 bpb_place_item 摆进背包。购买后会补发 dropped 信号,触发 Unidentified Skill 等 onDropped 购买效果。用 slot(1-5)或 item_id 指定。

Inputs: slot, item_id.

bpb_choose_survivalA

统一处理 10 胜提示:choice=survival 等价 bpb_enter_survival,choice=stop 等价 bpb_stop_here。

Inputs: choice (required).

bpb_continueB

从标题界面继续挂起的 run(等价于点击“继续”)。

Inputs: no named parameters.

bpb_edit_allB

进入“编辑全部”模式并规范化落格;不会把跨包/包外物品移入储物箱。物品可以同时被多个背包覆盖,游戏没有单一背包限制。

Inputs: no named parameters.

bpb_edit_bagsA

进入“只编辑背包”模式:物品固定不动,背包可以移动/旋转,移动背包不会牵连物品。用于把背包移动到覆盖物品的位置。

Inputs: no named parameters.

bpb_edit_itemsA

进入“只编辑物品”模式:背包固定不动,物品可以放到任意格子(包括包外)。用于购买后先把物品摆到理想位置。

Inputs: no named parameters.

bpb_enter_survivalA

十胜时选择“进入生存模式”。state.survival.can_start=true 即可调用;若原生提示仍在 1 秒延迟中,会主动打开提示后再进入。不会先结算奖杯。

Inputs: no named parameters.

bpb_get_backpackA

读取当前完整背包布局:所有已部署背包(位置/cells/shape/rotation)、所有已放置物品(位置/cells/shape/rotation/bag_id/floating/fusion_locked/is_gem/sockets)、grid、储物箱,以及 bags/items/floating/outside/fusion_locked/socketed_gems 计数。只读,不触发 normalize 或存档写入。

Inputs: no named parameters.

bpb_get_phaseA

轻量状态:state/round/tries/gold/wins/total_wins/survival/can_skip_result/last_result。战斗期间可安全调用,不会触碰背包;用于等待结算或判断是否进入下一阶段。

Inputs: no named parameters.

bpb_get_recipesA

读取合成配方:每件背包/储物箱物品的 recipes(base/result/ingredients/all_ingredients/catalyst)、as_ingredient(作为材料的配方)、gated_items(牌堆可生成卡牌)。全量只查背包/储物箱;商店物品用 item_id 单查(全量遍历个别 shop 配方不稳定)。

Inputs: item_id.

bpb_get_staminaA

读取耐力信息:玩家 stamina/max_stamina/stamina_regen(游戏未暴露时对应字段为 null 且 available=false)、每件物品的 stamina_cost/stamina_factor/types/伤害/冷却,以及已部署物品的总耐力消耗。

Inputs: no named parameters.

bpb_get_star_slotsA

读取星位/受影响格与宝石插槽。返回每件已放置物品的 affected_cells(按方向 0/2/4/7)、current_affected_items(当前命中物品)、extension_cells 和 sockets(index/位置/occupied/gem_id/gem_name)。可选 item_id 只查一件。

Inputs: item_id.

bpb_get_stateA

获取当前完整状态:state(title/shop/combat)、职业、回合、剩余重试次数、金币、当前 run 胜场 wins、累计胜场 total_wins、生存模式状态 survival、商店物品/技能及价格、保留项、刷新费、背包 9x7 摆盘(bags/items/grid)、储物箱、战斗结算是否可跳过。战斗期间只返回摘要(inventory_available=false),不会触碰背包/商店;结算后回到 shop 再读取完整状态。返回的 id 字段用于后续 buy/place/rotate/store/reserve/socket 操作;item.fusion_locked / item.locked 是融合锁定状态;item.is_gem 与 item.sockets 用于宝石镶嵌。

Inputs: no named parameters.

bpb_healthA

检查游戏内网桥是否在线,返回 ping 与当前状态摘要。

Inputs: no named parameters.

bpb_open_backpack_editB

进入背包层编辑模式(inventoryEditMode=bag),用于移动/旋转背包本体。

Inputs: no named parameters.

bpb_open_item_editB

进入物品层编辑模式(inventoryEditMode=item);可选 item_id 聚焦某件物品。

Inputs: item_id.

bpb_place_bagA

移动背包到指定左上角格子 (x,y)。只允许移动空背包;非空背包返回 bag_not_empty,需先用 bpb_place_item/bpb_store_item 把内容移出,再移动空包。物品模式返回 bags_fixed_in_item_mode。

Inputs: x (required), y (required), item_id (required).

bpb_place_itemB

原生落格:pickup(当前物品位置) → 设目标包围盒中心 → Item.drop(),成功返回的 cells 精确等于目标格,并触发游戏正常的落格/放置回调。物品/全部模式下允许放到包外(outside_bag=true);物品可以同时覆盖多个背包,不要求属于单一背包;位置/朝向由游戏 drop 校验。

Inputs: x (required), y (required), item_id (required).

bpb_refresh_shopA

刷新商店(消耗金币,费用见 state.shop.reroll_cost)。

Inputs: no named parameters.

bpb_reserve_itemB

保留/取消保留商店物品(reserve)。保留后该物品会留在商店,跨刷新/下回合仍可购买;reserved=false 表示取消保留。用 slot(1-5)或 item_id 指定。

Inputs: slot, item_id, reserved.

bpb_rotate_bagA

游戏内原子旋转空背包(已启用):目标格全在包内且无重叠时,removeItem → orientItem → addItemByTopLeft;非空背包返回 bag_not_empty。BPB_ROTATE=0 可关闭。

Inputs: item_id (required), direction.

bpb_rotate_itemB

游戏内原子旋转(已启用):目标格全在包内且无重叠时,直接 removeItem → orientItem → addItemByTopLeft,不经过 drop/tryAddItem/hotswap。支持矩形和 L 形;目标不合法返回 cannot_rotate_in_place。BPB_ROTATE=0 可关闭。

Inputs: item_id (required), direction.

bpb_sell_itemA

出售背包里的物品,立即获得金币(价格见 state.backpack.items[].sell_price)。储物箱里的物品需先 bpb_place_item 放回背包再出售。

Inputs: item_id (required).

bpb_set_classA

标题界面选择职业(0=Ranger,1=Reaper,2=Berserker,3=Pyromancer,4=Mage,5=Adventurer,6=Engineer);可同时指定 loadout(0-2),随后用 bpb_start_run 开局。

Inputs: class_id (required), loadout.

bpb_set_edit_modeB

切换编辑模式:all(全部)/bags(只背包)/items(只物品);兼容 default/bag/item 别名。

Inputs: mode.

bpb_set_fusion_lockA

锁定或解除物品的自动融合。locked=true 锁定(阻止自动合成),locked=false 解除;背包和储物箱物品可用,背包本体不可用。state 中 item.fusion_locked 反映结果。

Inputs: locked (required), item_id (required).

bpb_set_loadoutA

标题界面选择初始 loadout(0-2);具体物品见 state.title.classes[].loadouts。

Inputs: loadout (required).

bpb_skip_resultA

跳过战斗结算界面回到商店(仅在 state.can_skip_result=true 时调用)。十胜时即使 state.survival.prompt_visible 仍为 false,也会返回 survival_choice_required;必须先 bpb_choose_survival / bpb_enter_survival / bpb_stop_here 做出选择。

Inputs: no named parameters.

bpb_socket_gemA

把宝石类物品镶到宿主物品的空镶嵌位。host_id 的 state.sockets 提供 socket_index、occupied、gem_id;宝石可以是背包或储物箱中的散装宝石。镶嵌是原子的,不走 drop/hotswap。

Inputs: gem_id (required), host_id (required), socket_index.

bpb_start_battleA

开始战斗;开战前只规范化物品位置/placedByPlayer,不会把跨包物品移入储物箱。随后用 bpb_wait_for_result 等待结算。

Inputs: no named parameters.

bpb_start_runA

开始新的一局。默认优先恢复挂起的 run;force_new=true 会删除挂起的 run 并强制全新开局(适用于旧存档损坏、continue 崩溃的情况)。mode=unranked/ranked。新局第一回合生命上限强制重置为 25(不继承上一局),返回 hp。可选 class_id/loadout:开局前先选择职业与初始 loadout。

Inputs: mode, loadout, class_id, force_new.

bpb_stop_hereA

十胜提示时选择“到此为止”。仅在 state.survival.prompt_visible=true 时可用;结束本轮并保留胜场。

Inputs: no named parameters.

bpb_store_itemA

把背包里的物品放回储物箱(腾出格子)。不能用于背包本体;用于给技能/新物品腾位置。

Inputs: item_id (required).

bpb_unsocket_gemA

从宿主物品的镶嵌位取下宝石。优先放回背包空格;没有空格时放储物箱。

Inputs: host_id (required), socket_index.

bpb_wait_for_resultA

等待战斗结算界面出现;auto_skip=true 时自动跳过并返回下一回合商店状态。十胜时不会先跳过结算(包括原生提示的 1 秒延迟窗口);会返回 survival_choice_required,等待选择生存模式或到此为止。

Inputs: auto_skip, timeout_seconds.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 35 tools

    Disambiguation2/5

    Several tools overlap heavily, especially the edit-mode family (bpb_open_backpack_edit, bpb_open_item_edit, bpb_edit_items, bpb_edit_bags, bpb_edit_all, bpb_set_edit_mode) and the survival-choice family (bpb_enter_survival, bpb_stop_here, bpb_choose_survival). The descriptions explain differences, but an agent can easily misselect among these redundant entry points.

    Naming Consistency5/5

    All tools use the bpb_ prefix with snake_case and generally follow a verb_noun pattern (e.g. bpb_buy_item, bpb_place_item, bpb_get_state). Minor bare verbs like bpb_health and bpb_continue are still clearly readable and consistent with the overall convention.

    Tool Count2/5

    35 tools is heavy for any server, and the set includes multiple redundant edit-mode and survival-choice wrappers that inflate the count. While the game domain is complex, the surface could be consolidated to a much tighter set without losing capability.

    Completeness4/5

    The surface covers the core game lifecycle well: title/class/loadout, shop buying/reserving/refreshing, inventory placement/rotation/storage/selling, gem sockets, battle start/result, and survival branching. There are minor gaps around consolidated inventory editing and item inspection, but agents can work around them using the existing state and item tools.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to play Slay the Spire 2 by exposing game state and actions through an MCP server, supporting combat, rewards, and run management.
      361
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables an MCP agent to observe and command Slay the Spire 2 game state via HTTP, and optionally autopilot combat with a local deterministic policy, without LLM in the critical path.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to interact with running games in real time — introspecting game state, simulating keyboard and mouse input to actually play, capturing screenshots, executing Lua code, hot-reloading files, and receiving push notifications when state changes.
      8
      MIT