内容
# STS2 AI MCP
适用于杀戮尖塔2的AI安全MCP和本地HTTP控制界面。
本仓库是旧版STS2-Agent分叉的v2版本继承者。目标是为代理提供稳定的决策窗口，而不是原始的UI按钮调用。
## 包含内容
- `STS2AIMCP/`：游戏内模组HTTP API。
- `mcp_server/`：FastMCP包装器，默认配置文件为`ai_safe_v2`。
- `scripts/`：构建和MCP启动助手。
- `docs/`：v2协议、兼容性和构建说明。
私人游戏知识不会被包含在此仓库中。运行时日志和本地策略笔记应位于`agent_knowledge/`、`run_logs/`或外部路径，如`~/.local/share/sts2-ai-mcp/knowledge`。
## 当前状态
v2协议仍处于实验阶段，但可用于本地测试：
- `GET /v2/decision/current`
- `POST /v2/decision/wait`
- `POST /v2/decision/act`
- `POST /v2/data/lookup`
正常MCP游戏应仅使用：
- `health_check`
- `wait_for_decision`
- `get_current_decision`
- `take_action`
- `lookup_game_data`
- `append_decision_note`
## 兼容性
杀戮尖塔2仍在不断变化，因此模组构建可能不会在游戏更新后保持兼容。发布产物应始终标识测试的游戏版本和Godot/MegaDot版本。
已知引擎约束：
- 当前目标：Godot/MegaDot `4.5.1.m.12`。
- 不要使用Godot `4.6.x`打包`STS2AIMCP.pck`，否则游戏可能会拒绝它。
参见 [docs/compatibility.md](docs/compatibility.md) 了解兼容性政策。
## 构建
Windows PowerShell：
```powershell
powershell -ExecutionPolicy Bypass -File ".\scripts\build-mod.ps1" `
-GameRoot "D:\steam\steamapps\common\Slay the Spire 2" `
-GodotExe "D:\steam\steamapps\common\Slay the Spire 2\SlayTheSpire2.exe" `
-Configuration Release
```
macOS/Linux：
```bash
./scripts/build-mod.sh \
--game-root "/path/to/Slay the Spire 2" \
--godot-exe "/path/to/game-or-godot-4.5.1" \
--configuration Release
```
参见 [docs/building.md](docs/building.md) 了解详细信息。
如果您是从旧分叉迁移而来，请在测试`STS2AIMCP`之前删除或禁用游戏`mods`目录下的旧`STS2AIAgent`文件。
## Steam Workshop
Workshop项目应仅包含游戏侧模组。MCP服务器仍然是此仓库的单独本地安装。
打包Workshop内容和SteamCMD VDF：
```powershell
powershell -ExecutionPolicy Bypass -File ".\scripts\package-workshop.ps1" `
-GameRoot "D:\steam\steamapps\common\Slay the Spire 2" `
-Configuration Release `
-OutputRoot "D:\steam\sts2-ai-mcp-workshop" `
-PreviewFile "C:\path\to\workshop-preview.png"
```
然后使用SteamCMD上传或更新：
```powershell
steamcmd +login <steam_user> +workshop_build_item "D:\steam\sts2-ai-mcp-workshop\sts2-ai-mcp-workshop.vdf" +quit
```
在首次上传后使用`-PublishedFileId <id>`更新相同的Workshop项目。参见 [docs/workshop.md](docs/workshop.md)。
## 发布ZIP
对于GitHub Releases，手动安装ZIP：
```bash
./scripts/package-release.sh \
--game-root "/mnt/d/steam/steamapps/common/Slay the Spire 2" \
--godot-exe "/mnt/d/steam/steamapps/common/Slay the Spire 2/SlayTheSpire2.exe"
```
产物写入`dist/release/`，仅包含游戏侧`STS2AIMCP`模组。参见 [docs/release.md](docs/release.md)。
## 运行MCP
标准输入MCP：
```bash
./scripts/start-mcp-stdio.sh
```
HTTP MCP：
```bash
./scripts/start-mcp-network.sh --host 127.0.0.1 --port 8765 --path /mcp
```
## 验证
```bash
dotnet build STS2AIMCP/STS2AIMCP.csproj -c Release \
"/p:Sts2DataDir=/path/to/Slay the Spire 2/data_sts2_windows_x86_64"
cd mcp_server
.venv/bin/python -m pytest -q
```
如果安装了`uv`:
```bash
cd mcp_server
uv sync
uv run pytest -q
```
## 许可证
AGPL-3.0-only。参见 [LICENSE](LICENSE)。
