Sts2 MCP (Gennadiyev)

An Experimental Research Project to Fully-Automate your Slay the Spire 2 Runs

一个mod for 杀死尖塔2 让AI代理玩游戏。通过本地主机REST API显示游戏状态和操作，并为Claude Desktop/Claude Code集成提供可选的MCP服务器。

支持单人和多人（合作模式），以及完整的菜单和大厅控制：配置文件切换、角色选择（SP和MP主机/客户端）和可选种子、多人主机/Stream好友加入/FastMP本地主机加入、用于恢复已保存的合作模式运行的多人加载大厅、游戏终止、FTUE/教程弹出处理和时间线可见性。已针对STS2进行测试 v0.103.2.

\[！警告\] 这个mod允许外部程序通过本地主机API读取和控制您的游戏。在你不太关心的跑步中使用，风险自负。

\[！小心\] 支持多人游戏 测试版 --期待bug。安装此模组时遇到的任何多人游戏问题都很可能是由模组而不是游戏引起的。在向STS2开发人员报告错误之前，请禁用mod并验证问题是否仍然存在。

对于玩家

1.安装模块

抓住 最新版本 并按照说明进行操作：

1. 复制 STS2_MCP.dll 和 STS2_MCP.json 到 /mods/
2. 启动游戏并在设置中启用模组（首次启动时出现同意对话框）
3. mod在上启动HTTP服务器 localhost:15526 自动地

\[！注意\] 发布DLL与平台无关。NET程序集--相同 STS2_MCP.dll 和 STS2_MCP.json 在Windows、Linux和macOS上工作。不需要单独的构建。

macOS安装

在macOS上，mods目录位于应用程序包中。默认的Steam安装路径为：

~/Library/Application Support/Steam/steamapps/common/Slay the Spire 2/
    SlayTheSpire2.app/Contents/MacOS/mods/

要安装，请右键单击 SlayTheSpire2.app → 显示包装内容，导航到 Contents/MacOS/，并创建一个 mods 文件夹。或者从终端：

GAME_DIR="$HOME/Library/Application Support/Steam/steamapps/common/Slay the Spire 2"
MODS_DIR="$GAME_DIR/SlayTheSpire2.app/Contents/MacOS/mods"
mkdir -p "$MODS_DIR"
cp STS2_MCP.dll "$MODS_DIR/"
cp STS2_MCP.json "$MODS_DIR/"

启动游戏并打开 设置→ Mods。mod应该出现在列表中。首次启动时会出现一个同意对话框——接受它以启用mod加载。启用后，验证HTTP服务器是否正在运行：

curl -s http://localhost:15526/

成功的响应如下：

{"message": "Hello from STS2 MCP v0.3.4", "status": "ok"}

如果你收到“连接被拒绝”，则表示模组未加载——请检查游戏设置中是否启用了模组。

2.给出与游戏互动的AI指令

克隆或下载存储库那么：

MCP服务器设置

安装 紫外线 如果你没有它（macOS： brew install uv).然后运行服务器一次以安装依赖关系：

uv run --directory /path/to/STS2_MCP/mcp python server.py --help

uv 读取 mcp/pyproject.toml，创建一个隔离的虚拟环境，并安装来自的固定依赖项 mcp/uv.lock。后续运行会立即重用环境。

将服务器添加到AI客户端的MCP配置中：

{
  "mcpServers": {
    "sts2": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/STS2_MCP/mcp", "python", "server.py"]
    }
  }
}

克劳德代码：添加到项目的 .mcp.json. 克劳德桌面版：添加到 claude_desktop_config.json 配置与上述相同。 *其他代理应该为自定义MCP服务器提供类似的配置选项。*

\[！提示\] 在macOS上，使用绝对路径 uv （例如。 /opt/homebrew/bin/uv)在 command 现场。GUI启动的应用程序可能不会继承您的shell PATH，这将阻止服务器启动。

添加配置后重新启动Claude会话。要验证MCP服务器是否正常工作，请让Claude致电 get_game_state --随着游戏的运行，它应该返回当前的游戏状态。

MCP服务器接受 --host 和 --port 如果您需要非默认设置，请使用选项。

旗帜 --no-trust-env 可用于禁用 requests 从环境中获取代理设置，如果您在容器中运行服务器，这可能会导致连接问题。

简介和简编数据

HTTP API独立于实时运行状态公开配置文件级进度：

• GET /api/v1/profile 返回活动配置文件的持续进度摘要，包括发现、成就、纪元、角色总数和全局运行总数。
• GET /api/v1/compendium 与游戏中的《简编》进入相同高级部分的组：卡片库、遗迹收藏、药水实验室、Bestiary、角色统计和跑步历史。
• GET /api/v1/wiki?query=... 使用模糊匹配搜索发现的卡片和遗迹维基条目中的活动个人资料。默认情况下，结果限制为10，可以用以下命令覆盖 limit；卡片结果包括基本版和升级版（如有）。
• GET /api/v1/profiles 列出了三个配置文件插槽和活动配置文件。
• POST /api/v1/profiles 通过游戏UI切换或删除配置文件槽。

MCP服务器通过以下方式公开相同的配置文件数据 get_profile(), get_compendium(), search_wiki(query, item_type, limit), list_profiles(), switch_profile(profile_id)，以及 delete_profile(profile_id).

get_compendium() 适用于需要当前房间或当前运行之外的持久上下文的代理。它从主菜单工作，包括 current_run 当运行处于活动状态时进行阻止，并总结已保存的内容 saves/history/*.run 活动配置文件的文件。运行历史记录限制为响应中的20个最新文件，因此长期配置文件不会创建无限制的工具输出。

search_wiki() 是持久卡和遗迹文本的选择性查找路径。它从不返回完整的游戏目录：mod首先过滤活动配置文件中发现的卡和遗迹ID，然后只返回最佳的模糊匹配。使用 item_type="card" 或 item_type="relic" 当查询已知时，并引发 limit 仅当默认的10个结果不够时。

对于开发者

构建和安装

需要 .NET 9 SDK 以及基础游戏。

PowerShell （推荐）：

# Pass game path directly:
.\build.ps1 -GameDir "D:\SteamLibrary\steamapps\common\Slay the Spire 2"

# Or set it once and forget:
$env:STS2_GAME_DIR = "D:\SteamLibrary\steamapps\common\Slay the Spire 2"
.\build.ps1

脚本构建 STS2_MCP.dll 进入 out/STS2_MCP/。将其与清单JSON一起复制到 /mods/ 要安装：

out/STS2_MCP/STS2_MCP.dll           ->  /mods/STS2_MCP.dll
mod_manifest.json                   ->  /mods/STS2_MCP.json

macOS的构建说明

安装.NET来编译mod：

brew install dotnet@9
export DOTNET_ROOT="/opt/homebrew/opt/dotnet@9/libexec"
export PATH="$DOTNET_ROOT:$PATH"

Homebrew安装 dotnet@9 仅作为桶，因此本届会议需要上述出口。将它们添加到 ~/.zshrc 在会议期间坚持下去。

建立 dotnet 直接（PowerShell脚本仅适用于Windows）：

dotnet build STS2_MCP.csproj -c Release -o out/STS2_MCP \
  -p:STS2GameDir="$HOME/Library/Application Support/Steam/steamapps/common/Slay the Spire 2"

在macOS上，游戏作为应用程序捆绑包发布。这 .csproj 检测macOS并将数据目录解析为 SlayTheSpire2.app/Contents/Resources/data_sts2_macos_arm64 自动。

macOS上的mods目录位于应用程序包中 SlayTheSpire2.app/Contents/MacOS/mods/.Finder默认隐藏捆绑包内容——要在GUI中浏览它，请右键单击 SlayTheSpire2.app → 显示包装内容。或从终端复制：

GAME_DIR="$HOME/Library/Application Support/Steam/steamapps/common/Slay the Spire 2"
MODS_DIR="$GAME_DIR/SlayTheSpire2.app/Contents/MacOS/mods"
mkdir -p "$MODS_DIR"
cp out/STS2_MCP/STS2_MCP.dll "$MODS_DIR/"
cp mod_manifest.json "$MODS_DIR/STS2_MCP.json"

\[！注意\] mod_manifest.json 已重命名为 STS2_MCP.json 在复制时——游戏的mod加载器希望清单文件名与mod ID匹配。

许可证

麻省理工学院

常见问题

为什么让AI为我玩游戏？

我开始构建这个模组，希望能与AI玩家合作。Singleplayer最初只是为了验证而构建的。

你没有回答这个问题！

首先，我玩很多游戏，包括有每日/每周任务的服务游戏。我真的希望现代人工智能能把我从磨难中拯救出来，如果你尝试过一个或多个GUI代理，它就永远不会真正实现。让我们面对现实吧：现代人工智能在游戏方面仍然很糟糕，因为没有人关心。

关于我的意图，作为一名喜欢玩游戏的研究人员，STS2MCP的目的是在一个很少探索的（我们称之为非分布）领域测试人工智能模型和代理。最终，这可能会成为评估不同语言模型推理和决策能力的基准。

STS2只是一个例子，展示了当前人工智能代理在玩此类游戏方面有多好（或有多坏）。 我无意用人工智能取代人类玩家，我肯定更愿意自己玩STS2 作为游戏的忠实粉丝。

这是作弊模组吗？

可以，但不一定。模组本身不会改变游戏玩法。它只是一个允许外部程序与游戏交互的界面。如何使用该界面取决于您。

一次跑步消耗多少代币？

我对Ironclad进行了评估。Claude Sonnet 4.6在完整运行中使用了略多于800万个令牌（包括输入、输出和工具响应）。GPT-5.4平均有734万个代币。根据您的提示和型号选择，它可能或多或少。

你有未来功能的路线图吗？

该项目现在制定明确的路线图还为时过早。我目前的重点是确保核心功能稳定且记录良好。然而，我对社区的建议和贡献持开放态度。

• 巩固多人游戏功能和修复漏洞是当务之急
• 在与AI代理协作时，添加对多人游戏运行中游戏内通信的支持
• 自我反思，从过去的跑步中学习，以提高未来的表现
• 我也在考虑对不同的模型和代理进行基准测试