Backpack Battles MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Backpack Battles MCP show me the current shop items and my gold"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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. 功能
分类 | 工具名 | 说明 |
状态 |
| 完整状态(shop/title);战斗期摘要;含 wins / total_wins / survival |
状态 |
| 轻量状态:state/round/tries/gold/wins/total_wins/survival,战斗期安全 |
状态 |
| 完整背包布局:bags/items 位置、cells、shape、rotation、grid、storage,只读 |
信息 |
| 星位/受影响格(方向 0/2/4/7)、当前命中物品、extension_cells、宝石 sockets |
信息 |
| 玩家 stamina/max/regen、每件物品 stamina_cost/types/伤害,已部署总耗 |
信息 |
| base/result/ingredients/催化剂、作为材料配方、牌堆 gated_items |
购买 |
| 买商店物品并放入储物箱( |
商店 |
| 保留/取消保留商店物品(免费,跨刷新保留) |
商店 |
| 刷新商店(扣金币) |
背包 |
| 把背包物品放回储物箱,腾出格子 |
背包 |
| 出售背包物品,立即获得金币(储物箱物品需先放回背包) |
背包 |
| 锁定/解除物品自动融合( |
宝石 |
| 把宝石镶到宿主物品的空镶嵌位( |
宝石 |
| 从宿主镶嵌位取下宝石;优先放回背包,没空格则进储物箱 |
编辑 |
| 进入背包层编辑模式(等价 bags) |
编辑 |
| 进入物品层编辑模式(等价 items) |
编辑 |
| 只编辑物品:背包固定,物品可放到任意格子(包括包外) |
编辑 |
| 只编辑背包:物品固定,背包可移动/旋转,不牵连物品 |
编辑 |
| 编辑全部:只规范化落格,不再把跨包/包外物品移走 |
编辑 |
| 兼容别名:all/bags/items/default/bag/item |
摆放 |
| 原生 drop 落格(pickup 当前位置 → drop);物品/全部模式允许包外/跨包 |
摆放 |
| 移动空背包;非空返回 |
旋转 |
| 游戏内原子旋转:removeItem→orientItem→addItemByTopLeft,绕过 drop/hotswap;目标需在包内且不重叠; |
旋转 |
| 游戏内原子旋转空背包;非空返回 |
战斗 |
| 开始战斗;开战前只规范化落格,不移走跨包物品 |
战斗 |
| 等待结算;自动跳过并回商店;十胜时不会先跳过,返回 |
战斗 |
| 手动跳过结算;十胜提示出现前后都被拦截,需先选择 |
10胜 |
| 选择“进入生存模式”; |
10胜 |
| 选择“到此为止”(结束本轮,保留胜场) |
10胜 |
| 统一选择: |
开局 |
| 标题界面选择职业 / 初始 loadout |
开局 |
| 新开一局(可带 class_id/loadout)/ 继续挂起的 run |
诊断 |
| 检查网桥与当前状态 |
购买后物品/技能进储物箱,不会自动进背包;需要再调用
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.9bGodot
3.6.stable.custom_buildPython
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安装器会:
自动定位 Steam 游戏目录(注册表 /
libraryfolders.vdf,也可--game-dir指定);复制
mod/McpBridge.gd、mod/bpb_api.gd到:%APPDATA%\Godot\app_userdata\Backpack Battles\mcp\在
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. 启动与验证
启动游戏(Steam 或
python -m bpb_mcp.cli launch)。进入标题界面,点击「继续 / 新游戏」,进入商店。
验证:
python -m bpb_mcp.cli health
python -m bpb_mcp.cli statehealth 正常输出示例:
{
"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:
pythonargs:
["-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. 工具参数速查
工具 | 参数 |
| 无(战斗期返回摘要;含 wins/total_wins/survival) |
| 无(含 wins/total_wins/survival) |
| 无(只读,不 normalize) |
|
|
| 无 |
|
|
|
|
|
|
|
|
|
|
| 无 |
| 无(等价 |
|
|
| 无(只编辑物品,背包固定) |
| 无(只编辑背包,物品固定) |
| 无(全部;只规范化落格,不移走跨包物品) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 无(开战前只规范化落格,不移走跨包物品) |
| 无(10 胜提示下返回 |
|
|
| 无(选择进入生存模式) |
| 无(选择到此为止) |
|
|
|
|
| 无 |
| 无 |
10. 可选 HTTP API
给非 MCP 客户端(脚本、网页、其他 Agent 框架):
python -m bpb_mcp.cli http --port 8766方法 | 路径 | 说明 |
GET |
| 网桥 + 游戏状态摘要 |
GET |
| 完整状态(战斗期自动返回摘要) |
GET |
| 轻量状态(战斗期安全) |
GET |
| 工具 schema |
POST |
|
|
示例(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 launch12. 故障排查
game_not_running / 连接被拒绝
游戏没启动;先启动游戏。
override.cfg没放到BackpackBattles.exe同目录。游戏是旧进程:必须重启游戏后 autoload 才生效。
端口 8765 被占用:改
mod/McpBridge.gd的PORT,并同步 PythonBridge端口(或设置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 installbridge 在下一次 api 调用时按 MD5 重新编译;不需要重启游戏。修改 McpBridge.gd 才需要重启。
添加新操作
在
mod/bpb_api.gd增加func my_action(ctx, args): ...;在
bpb_mcp/api.py增加方法;在
bpb_mcp/server.py的TOOLS和call_tool中注册;python -m bpb_mcp.cli install。
测试
python -m unittest discover -s tests -v
python tools\smoke_live.py15. 已知限制
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 toolsbpb_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
Scored across 35 tools
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.
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.
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.
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
Related MCP Connectors
Live competitive-game predictions, meta data and decision tools for AI agents.
Create, test and play AI-native games through server-authoritative contracts.
Run your Krtuworks apps from an AI agent: setup, remote config, stats, players, bug reports.
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceEnables 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-
- AlicenseNot gradedqualityDmaintenanceBridges AI assistants to running game instances for testing, debugging, and verification. Works with any game engine via a simple TCP protocol.14 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseAqualityCmaintenanceEnables 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.8MIT