# Slay the Spire Copilot

使用 Claude Code 辅助游玩杀戮尖塔（Slay the Spire）。AI 能读取游戏状态，在每一步给出策略建议或自动操作，辅助通关游戏。

## 架构

```
Slay the Spire (游戏)
    ↕ MCPTheSpire mod (HTTP, localhost:8080)
Python MCP Bridge Server (stdio)
    ↕ MCP 协议
Claude Code (AI 决策)
```

## 前置条件

1. **Slay the Spire** — Steam 版本
2. **ModTheSpire** — mod 加载器（Steam Workshop 订阅或手动安装）
3. **BaseMod** — 基础 mod 库（Steam Workshop 订阅或手动安装）
4. **MCPTheSpire** — MCP 通信 mod（[GitHub](https://github.com/ifree/MCPTheSpire)）
5. **Python 3.10+** — 运行 MCP bridge server
6. **Claude Code** — Anthropic 的 CLI 工具

## 安装步骤

### 1. 安装游戏 Mod

#### 方式 A: Steam Workshop（推荐）
1. 在 Steam Workshop 订阅 **ModTheSpire**
2. 在 Steam Workshop 订阅 **BaseMod**
3. 手动安装 **MCPTheSpire**:
   ```bash
   # 从 GitHub Releases 下载 MCPTheSpire.jar
   # 放入: <Steam>/steamapps/common/SlayTheSpire/mods/
   ```

#### 方式 B: 手动安装
1. 下载 [ModTheSpire](https://github.com/kiooeht/ModTheSpire/releases)
2. 下载 [BaseMod](https://github.com/daviscook477/BaseMod/releases)
3. 下载 [MCPTheSpire](https://github.com/ifree/MCPTheSpire/releases)
4. 将所有 `.jar` 文件放入 `<Steam>/steamapps/common/SlayTheSpire/mods/` 目录

### 2. 安装 Python 依赖

```bash
cd slay-the-spire-copilot
pip install -r requirements.txt
```

### 3. 配置 Claude Code

项目已包含 `.mcp.json` 配置文件。在此目录启动 Claude Code 即会自动加载 MCP server：

```bash
cd slay-the-spire-copilot
claude
```

或手动添加到全局配置 `~/.claude/settings.json`：
```json
{
  "mcpServers": {
    "slay-the-spire": {
      "command": "python",
      "args": ["C:/Users/PC/slay-the-spire-copilot/src/server.py"],
      "env": {
        "SPIRE_URL": "http://127.0.0.1:8080/mcp"
      }
    }
  }
}
```

## 使用方法

### 1. 启动游戏
- 通过 ModTheSpire 启动杀戮尖塔
- 确保 MCPTheSpire mod 已勾选启用
- 等待游戏加载完成（MCPTheSpire 会在 8080 端口启动 MCP 服务）

### 2. 启动 Claude Code
```bash
cd slay-the-spire-copilot
claude
```

### 3. 开始游玩

**顾问模式**（推荐）：
```
> 帮我看看当前局势，应该怎么打？
> 这三张卡选哪张好？
> 地图应该走哪条路？
> 这个事件选哪个选项？
```

**自动游玩模式**：
```
> 帮我开一局铁甲战士，0级升阶，自动打
> 自动帮我打完这场战斗
> 帮我做出这个选择并继续
```

**分析模式**：
```
> 分析一下我当前的牌组强度
> 我的牌组缺什么？需要找什么卡？
> 接下来的boss要注意什么？
```

## 工具列表

| 工具 | 功能 |
|------|------|
| `check_connection` | 检查游戏连接状态 |
| `get_game_state` | 获取完整游戏状态 |
| `get_screen_state` | 获取当前屏幕快照 |
| `get_available_actions` | 获取当前可用操作 |
| `get_card_info` | 查询卡牌详情 |
| `execute_actions` | 批量执行操作 |
| `play_card` | 出牌 |
| `end_turn` | 结束回合 |
| `choose` | 做出选择 |
| `use_potion` | 使用药水 |
| `discard_potion` | 丢弃药水 |
| `proceed` | 继续/确认 |
| `skip` | 跳过 |
| `start_game` | 开始新游戏 |
| `continue_game` | 继续存档 |
| `abandon_run` | 放弃当前游戏 |

## 备选方案：CommunicationMod 后端

如果不想安装 MCPTheSpire，可以使用更经典的 [CommunicationMod](https://github.com/ForgottenArbiter/CommunicationMod)。

### 安装步骤
1. 在 Steam Workshop 订阅 CommunicationMod，或从 [GitHub Releases](https://github.com/ForgottenArbiter/CommunicationMod/releases) 下载
2. 启动一次游戏，生成配置文件
3. 编辑 `SlayTheSpire/SlayTheSpire_Data/SpireConfig`，设置：
   ```
   command=D:/Develop/Anaconda/python.exe
   argument=C:/Users/PC/slay-the-spire-copilot/src/comm_bridge.py
   ```
4. 修改 `.mcp.json`，添加环境变量：
   ```json
   {
     "mcpServers": {
       "slay-the-spire": {
         "command": "D:/Develop/Anaconda/python.exe",
         "args": ["src/server.py"],
         "env": {
           "SPIRE_BACKEND": "comm"
         }
       }
     }
   }
   ```
5. 启动游戏后，CommunicationMod 会自动启动 `comm_bridge.py`
6. 在 Claude Code 中照常使用

### 两种后端对比

| 特性 | MCPTheSpire | CommunicationMod |
|------|-------------|-------------------|
| 协议 | MCP over HTTP | stdin/stdout + TCP |
| 批量操作 | 支持（稳定索引） | 逐条命令 |
| 卡牌查询 | 支持 | 不支持 |
| 成熟度 | 较新 | 经典，广泛使用 |
| 安装难度 | 需要手动安装 | Steam Workshop 直接订阅 |

## 配置

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `SPIRE_URL` | `http://127.0.0.1:8080/mcp` | MCPTheSpire 地址 |
| `SPIRE_BACKEND` | `mcp` | 后端选择：`mcp` 或 `comm` |
| `COMM_HOST` | `127.0.0.1` | CommunicationMod bridge 地址 |
| `COMM_PORT` | `38765` | CommunicationMod bridge 端口 |

## 故障排查

| 问题 | 解决方案 |
|------|---------|
| 连接失败 | 确认游戏已启动且 MCPTheSpire mod 已启用 |
| 端口冲突 | 修改 MCPTheSpire 配置中的端口，同步修改 `SPIRE_URL` |
| mod 加载失败 | 确认 ModTheSpire 和 BaseMod 版本兼容 |
| Python 依赖错误 | 运行 `pip install -r requirements.txt` |

## 参考项目

- [MCPTheSpire](https://github.com/ifree/MCPTheSpire) — MCP 游戏通信 mod
- [STSAgent](https://github.com/ifree/STSAgent) — LLM 游戏内助手 mod
- [STS-AISlayer](https://github.com/patient1234/STS-AISlayer) — AI 控制 mod
- [CommunicationMod](https://github.com/ForgottenArbiter/CommunicationMod) — 经典外部进程通信 mod

## 协议

MIT License