MCP The Spire

MCPTheSpire


Slay the Spire mod，使AI代理能够通过模型上下文协议（MCP）玩游戏。这允许像Claude、GPT或其他MCP兼容客户端这样的AI助手以编程方式与Slay the Spire游戏进行交互和控制。

特性

• MCP协议支持：使用流式HTTP传输完全实现模型上下文协议
• 实时游戏控制：AI代理可以打牌、做出选择、使用药水和浏览菜单
• 批处理操作：在一次调用中执行多个操作，以实现高效的游戏体验
• 游戏状态访问：按需全面访问玩家统计数据、手牌、怪物、屏幕信息和卡片详细信息
• 线程安全操作：只读操作立即执行，改变游戏规则的操作在游戏线程上排队等待安全执行
• 可配置服务器：可自定义的主机和端口设置

需求

• Java 8+
• 杀戮尖塔 （基础游戏）
• ModTheSpire （mod加载器）
• 基础模组 （所需依赖性）
• MCP兼容的AI客户端（Claude Desktop、自定义MCP客户端等）

安装

1. 安装 ModTheSpire 遵循安装指南
2. 安装 基础模组 如果尚未安装
3. 下载最新版 MCPTheSpire.jar 从发布页面
4. 将JAR文件放在您的ModTheSpire mods目录中
5. 通过ModTheSpire发布Slay the Spire
6. 在ModTheSpire菜单中启用“MCP the Spire”模式

配置

可以通过以下配置文件配置mod： MCPTheSpire/config.properties:

host=127.0.0.1
port=8080

用法

连接AI客户端

配置您的MCP客户端以连接到：

http://127.0.0.1:8080/mcp

对于Claude Desktop，请在MCP配置中添加：

{
  "mcpServers": {
    "slay-the-spire": {
      "url": "http://127.0.0.1:8080/mcp",
      "transport": "streamable-http"
    }
  }
}

MCP工具参考

状态查询工具（只读，即时响应）

get_game_state

通过可选过滤获取完整的游戏状态。

参数：

• include （可选）：包含以下部分的数组： player, deck, relics, potions, combat, screen
• 注： map 是 默认排除 （大/静态数据）-添加 "map" 如果需要，可以包含数组

例子：

{"include": ["player", "combat", "map"]}

get_screen_state

获取轻量级的当前屏幕状态。 建议用于大多数用例。

退货：

• screen_type：当前屏幕（COMBAT_REWARD、CARD_REWARD、MAP等）
• room_phase：房间阶段（战斗、完成等）
• choice_list：可用选项
• can_proceed / can_cancel：按钮可用性
• hand, monsters, energy：战斗信息（如果在战斗中）

get_available_commands

获取当前屏幕可用工具的上下文感知列表。

退货：

{
  "screen_type": "COMBAT_REWARD",
  "available_tools": [
    {"tool": "choose", "description": "Make a choice from: [gold, card]"},
    {"tool": "proceed", "description": "Click proceed button"}
  ]
}

get_card_info

获取详细的卡信息，包括描述和升级版本。

何时使用： 游戏状态中的卡片对象针对大小进行了优化，不包括描述。当你需要了解卡片的功能时，请使用此工具。

参数：

• card_ids （必填）：要查询的卡ID数组

例子：

{"card_ids": ["Strike_R", "Bash", "Defend_R"]}

退货：

{
  "cards": [
    {
      "id": "Bash",
      "name": "Bash",
      "type": "ATTACK",
      "rarity": "BASIC",
      "cost": 2,
      "description": "Deal !D! damage. Apply !M! Vulnerable.",
      "base_damage": 8,
      "base_magic_number": 2,
      "has_target": true,
      "upgraded": {
        "name": "Bash+",
        "description": "Deal !D! damage. Apply !M! Vulnerable.",
        "base_damage": 10,
        "base_magic_number": 3
      }
    }
  ]
}

批处理操作（推荐）

execute_actions

按顺序执行多个操作。 这是最有效的游戏方式。

动作在每次执行之前等待游戏准备就绪（动画完成，状态更新）。这确保了无需手动计时即可可靠执行。

主要特点：指数稳定 -全部 card_index 和 choice_index 值指的是位置 当你调用该工具时，而不是在每个动作执行后。在打牌或做出选择时，您不需要重新计算指数。

示例-稳定的card_index：

Your hand: [1: Strike, 2: Defend, 3: Bash, 4: Strike, 5: Defend]
You want to play: Strike(1), Bash(3), Strike(4)

CORRECT - use original positions:
  card_index: 1, 3, 4

WRONG - don't recalculate after each play:
  card_index: 1, 2, 2  ← This is incorrect!

示例-稳定choice_index：

Rewards: [1: gold, 2: potion, 3: card, 4: relic]
You want: gold(1) and card(3)

CORRECT: choice_index: 1, 3
WRONG:   choice_index: 1, 2  ← Don't recalculate!

参数：

• actions：动作对象数组

支持的操作：

动作参数详细信息：

play_card -用手打牌

choose -在当前屏幕上进行选择

select_cards -在HAND_Select屏幕上选择卡片

use_potion -使用药水

discard_potion -丢弃药水

wait -等待动画/状态

示例-按名称打牌（推荐）：

{
  "actions": [
    {"action": "play_card", "card_name": "Defend"},
    {"action": "play_card", "card_name": "Strike", "target_index": 1},
    {"action": "play_card", "card_name": "Bash", "target_index": 1},
    {"action": "end_turn"}
  ]
}

建议使用card_name -它会自动找到你当前手中的卡片，所以你不需要跟踪索引的变化。

替代方案-按指数播放（指数稳定）：

{
  "actions": [
    {"action": "play_card", "card_index": 1},
    {"action": "play_card", "card_index": 3},
    {"action": "play_card", "card_index": 5},
    {"action": "end_turn"}
  ]
}

指数是 自动稳定 - card_index: 1, 3, 5 在这些位置打牌 当你调用该工具时。打牌时不需要考虑手牌的变化。

示例-领取奖励并继续（指数稳定）：

{
  "actions": [
    {"action": "choose", "choice_index": 1},
    {"action": "choose", "choice_index": 2},
    {"action": "proceed"}
  ]
}

示例-为HAND_select屏幕选择卡（例如，在Survivor之后）：

{
  "actions": [
    {"action": "play_card", "card_name": "Survivor"},
    {"action": "select_cards", "drop": ["Strike"]}
  ]
}

这 select_cards action支持两种模式：

• drop：选择这些卡（要丢弃/受影响）
• keep：保留这些卡，选择所有其他卡

注： select_cards 选择后自动确认。无需单独 confirm 行动。

卡片可以通过以下方式指定：

• 索引: [1, 3] （1-索引，使用稳定的初始位置）
• 名字: ["Strike", "Defend"]
• ID: ["Strike_R", "Defend_G"]
• 混合: [1, "Bash", "Defend_R"]

示例-赌徒芯片（保留特定卡，丢弃其余卡）：

{
  "actions": [
    {"action": "select_cards", "keep": ["Bash", "Inflame"]},
    {"action": "play_card", "card_name": "Bash"}
  ]
}

退货：

{
  "success": true,
  "message": "Executed 4 actions",
  "screen": "NONE",
  "hand_size": 2,
  "energy": 0,
  "can_proceed": false
}

出现错误时：

{
  "success": false,
  "executed": 2,
  "failed_at": 2,
  "failed_action": "play_card",
  "error": "Card not playable"
}

个人行动工具

这些执行单个操作。使用 execute_actions 尽可能提高效率。

play_card

用手打牌。指定以下选项之一：

• card_name：卡片显示名称（例如，“Strike”、“Strike+”、“Defend”）
• card_id：卡内部ID（例如“Strike_R”、“Defend_g”）
• card_index：1-索引卡位置

可选：

• target_index：1索引怪物目标（针对目标卡）

示例： {card_name:'Bash',target_index:1}, {card_index:3,target_index:1}, {card_name:'Defend'}

end_turn

结束当前回合的战斗。

choose

从当前屏幕进行选择。

• choice_index （必填）：1-索引选择位置

use_potion

使用药水。

• potion_slot （必填）：1-索引药水槽
• target_index （可选）：1-索引目标

discard_potion

丢弃药水。

• potion_slot （必填）：1-索引药水槽

导航工具

游戏管理工具

start_game

开始一个新游戏。

• character （必填）：裂纹、沉默、缺陷或守望者
• ascension （可选）：0-20
• seed （可选）：字母数字种子

continue_game

从保存文件继续。

abandon_run

放弃当前跑步。

save_game

保存并返回菜单。

屏幕类型参考

数据结构

游戏状态对象被优化为最小大小。字段仅在有意义时才包括在内。

卡片对象

注： 不包括卡片描述。使用 get_card_info 查询描述。

怪物对象

从源头构建

# Clone repository
git clone 
cd MCPTheSpire

# Set up dependencies in lib/
# - desktop-1.0.jar (from Slay the Spire)
# - ModTheSpire.jar
# - BaseMod.jar

# Build
mvn clean package

# Output: target/MCPTheSpire.jar

建筑

• MCPServer：具有流式HTTP传输的HTTP服务器
• MCPToolHandler：工具定义和执行
• GameStateConverter：游戏状态序列化
• CommandExecutor：在游戏线程上安全执行命令
• 补丁：SpirePatch挂钩用于游戏活动

许可证

MIT许可证-请参阅 许可证 文件。

致谢

• 通信模块 -设计灵感
• TelnetTheSpire -设计灵感
• ModTheSpire -模块加载框架
• 基础模组 -基本建模库