STS2 模组制作助手 MCP

STS2 模组制作助手 MCP

STS2 模组制作助手 MCP

游戏玩法

STS2 模组制作助手 MCP预览查看大图

STS2 模组制作 MCP

一个由 LLM 驱动的《杀戮尖塔 2》模组制作工具包。这个 模型上下文协议 服务器可以连接任何兼容 MCP 的 AI 助手——Claude Code、Claude Desktop、Cursor、Windsurf 等等——为其提供 151 个工具，用于逆向工程游戏、生成模组代码、构建和部署模组、检查实时游戏引擎，并通过让 AI 亲自游玩游戏来自动化测试你的模组。

即使你不是程序员也能使用它（尽管有编程经验会很有帮助）。对于经验丰富的开发者，它可以作为一个强大的工具；如果你是初学者，可以尝试用简单的英语描述你的需求，让 LLM 来处理代码（务必让它进行全面的测试、调试和加固。这是非常重要的一步）。

重要提示： 你的使用体验会因所使用的 AI 模型而异。我使用 Claude Opus 4.6 和 ChatGPT Codex 5.4 的体验最佳——使用这些模型，我还没有遇到过它们无法独立创建、测试和调试的代码相关模组。

这个项目对我个人来说也是一个有趣的实验。如果你遇到任何问题、有搞不明白的地方、想建议新功能或发现错误，请联系我！

环境要求

  • 《杀戮尖塔 2》（Steam）
  • Python 3.11+ — python.org/downloads（Windows 安装时请勾选“添加到 PATH”）
  • .NET 9.0 SDK — dotnet.microsoft.com
  • 兼容 MCP 的 AI 客户端（Claude Code、Claude Desktop、Cursor、Windsurf 等）

可选：

  • GDRE Tools — 用于从游戏 PCK 中提取 Godot 资源（下载）
  • ilspycmd — 用于 C# 反编译：dotnet tool install -g ilspycmd

安装

  1. 将下载的 zip 文件解压到一个你将长期保留的文件夹中（例如 C:\sts2-modding-mcp）
  2. 在该文件夹中打开一个终端
  3. 创建并激活一个虚拟环境：
python -m venv venv

# Windows (PowerShell):
venv\Scripts\Activate.ps1
# Windows (cmd):
venv\Scripts\activate.bat
# Windows (Git Bash):
source venv/Scripts/activate
# macOS / Linux:
source venv/bin/activate
  1. 安装：pip install .
  2. 运行首次设置：python -m sts2mcp.setup

设置向导将自动检测你的游戏安装位置，在需要时安装 ilspycmd，反编译游戏的 C# 程序集，并构建/部署桥接模组到游戏的模组文件夹。

如果你的游戏未被自动检测到，请编辑安装文件夹中的 sts2mcp_config.json：

{ "game_dir": "D:\\Games\\Slay the Spire 2" }

连接 AI 客户端

MCP 服务器需要与 AI 客户端通信。请将其指向虚拟环境的 Python，这样依赖项就始终可用。

Claude Desktop

编辑你的配置文件：

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

添加：

{
  "mcpServers": {
    "sts2-modding": {
      "command": "C:\\sts2-modding-mcp\\venv\\Scripts\\python.exe",
      "args": ["C:\\sts2-modding-mcp\\run.py"]
    }
  }
}

将路径替换为你解压下载文件的位置。然后重启 Claude Desktop。

Claude Code (CLI)

claude mcp add sts2-modding C:\sts2-modding-mcp\venv\Scripts\python.exe -- C:\sts2-modding-mcp\run.py

Cursor / Windsurf / 其他

大多数 MCP 客户端使用类似的 JSON 配置。将命令指向虚拟环境的 Python，并将参数指向 run.py。请查阅你编辑器的 MCP 文档。

要验证连接，可以询问 AI “有哪些可用的模组制作指南？” 或 “显示游戏信息。”

功能特性

  • 向 AI 助手暴露 151 个工具
  • 将游戏的 C# 程序集反编译为完全可搜索的源代码，并具有 Roslyn 语法树、调用图和继承链
  • 提取并索引 15,000+ 个 Godot 资源（场景、纹理、资源、脚本、音频）
  • 编目 3,048+ 个游戏实体——卡牌、遗物、能力、药水、怪物、遭遇、事件、附魔、充能球等等
  • 映射战斗、卡牌、伤害、能力、回合和奖励系统中的 144 个钩子 和 175 个可覆写方法
  • 为 30 多种实体类型 生成可用于生产的 C# 模组代码
  • 使用 .csproj、清单、本地化和文件夹结构搭建完整的模组项目
  • 生成 Harmony 补丁（前缀、后缀、IL 转译器）、反射访问器、网络消息、存档数据和模组配置
  • 使用 C# 构建 Godot UI 面板、战斗覆盖层、浮动面板、可滚动列表、动画条、悬停提示和 VFX 场景
  • 与 BaseLib 集成，提供抽象基类、自动注册、配置 UI 和卡牌变量
  • 从自然语言中推荐钩子（例如“让药水治疗更多”）
  • 通过 dotnet build 构建模组，并输出结构化结果
  • 构建 Godot PCK 资源包，并自动将 PNG 转换为纹理
  • 一步将构建产物部署到游戏的模组文件夹
  • 在发布前验证本地化、资源引用和项目结构
  • 监视项目文件并在更改时自动重新构建

实时场景检查

  • 实时浏览运行中游戏的完整 Godot 场景树
  • 读取和写入活动节点上的节点属性（位置、缩放、颜色、文本、可见性）
  • 切换任何视觉图层的可见性，以隔离和检查 UI、VFX 或游戏元素
  • 使用 Godot 补间动画属性，用于实时实验
  • 在运行时检查所有已加载的 .NET 程序集、类型、方法和属性

自动化游戏测试

  • 使用特定角色、进阶等级、修饰符和预配置的卡组/遗物/金币开始带种子的游戏
  • 控制每个界面——战斗、地图、事件、奖励、商店、休息点、宝箱、卡牌选择
  • 可以指定目标打出卡牌、结束回合、使用药水、地图导航、做出事件选择、从商店购买
  • 在游戏过程中操纵游戏状态——设置生命值/金币/能量、抽卡、添加能力和遗物
  • 以最高 20倍速 运行，实现快速迭代
  • 捕获截图进行视觉验证

调试

  • 在特定游戏动作或钩子上设置带可选条件的断点
  • 在战斗中逐步执行每个动作，并在每个步骤检查完整状态
  • 在游戏继续渲染时暂停和恢复动作处理
  • 保存和恢复命名状态快照，用于从相同游戏位置进行 A/B 测试
  • 轮询包含完整堆栈跟踪的未处理异常
  • 无需重启游戏即可从新的 DLL 热重载 Harmony 补丁

自动化压力测试 (AutoSlay)

  • 使用可配置的角色、种子和进阶等级运行完全自主的多轮游戏
  • 跟踪多轮游戏中的进度——当前楼层、幕数、房间、已用时间和错误
  • 可配置的超时和看门狗行为，用于检测软锁和崩溃

模组制作指南与参考

  • 29 个内置指南主题，涵盖入门、钩子、本地化、Harmony、多人游戏网络、Godot UI、IL 转译器、战斗深入探讨、存档文件、RNG/确定性、可访问性等等
  • 15 份 BaseLib 参考文档，涵盖自定义实体、配置、卡牌变量、SpireField、WeightedList 和 IL 补丁
  • 39 个游戏内控制台命令，附带参数和说明

这类 MCP 的成败取决于指南的更新程度和编写质量。AI 最终可以通过自我调试来解决问题，但往这个数据库添加内容对于提高效率至关重要。如果你用它来做项目，请考虑回馈指南！

工具亮点

MCP 目前暴露了 151 个工具。以下部分重点介绍了主要工作流程。

游戏数据查询

  • list_entities — 按类型、名称、稀有度搜索/过滤实体
  • get_entity_source — 获取任何游戏类的完整反编译 C# 源代码
  • search_game_code — 使用 Roslyn 索引或正则表达式搜索反编译的源代码
  • list_hooks — 按类别和子类别列出游戏钩子
  • get_modding_guide — 获取 29 个主题的内置文档
  • browse_namespace — 浏览反编译的命名空间并读取单个文件
  • get_console_commands — 获取全部 39 个开发控制台命令，含参数和说明

核心模组创建

  • create_mod_project — 搭建完整的模组项目
  • generate_card — 生成带动态变量、OnPlay 逻辑、升级逻辑和本地化的卡牌类
  • generate_relic — 生成带钩子方法和本地化的遗物类
  • generate_power — 生成带钩子方法的能力（增益/减益）类
  • generate_potion — 生成带 OnUse 逻辑和本地化的药水类
  • generate_monster — 生成带移动状态机、.tscn 场景和本地化的怪物类
  • generate_encounter — 生成可生成特定怪物的遭遇类
  • generate_character — 生成带卡牌/遗物/药水池的完整自定义可玩角色（BaseLib）
  • generate_harmony_patch — 生成 Harmony 前缀/后缀补丁类

高级生成器

灵感来自 21 个社区模组中的模式：

  • generate_net_message — 多人游戏网络消息搭建
  • generate_godot_ui — 程序化 Godot UI 面板（无需 .tscn）
  • generate_overlay — 自动注入的战斗/地图覆盖层
  • generate_transpiler_patch — IL 字节码 Harmony 转译器
  • generate_reflection_accessor — 缓存 AccessTools 字段/属性访问器
  • generate_custom_keyword — 使用 BaseLib 的 [CustomEnum] CardKeyword
  • generate_custom_pile — 用于自定义卡牌目标的 [CustomEnum] PileType
  • generate_spire_field — 用于向游戏模型附加数据的 SpireField
  • generate_dynamic_var — 用于卡牌/能力描述变量的自定义 DynamicVar
  • generate_mechanic — 完整的跨领域关键词机制（能力 + 卡牌 + 遗物 + 本地化）
  • generate_event — 带选择树和处理方法的事件类
  • generate_orb — 带被动/ evoke 效果的能量球
  • generate_enchantment — 附着并修改卡牌的附魔
  • generate_save_data — 持久化的 JSON 存档数据类
  • generate_vfx_scene — Godot .tscn 粒子效果场景

构建与部署

  • build_mod — 通过 dotnet build 构建，并捕获输出和产物列表
  • install_mod — 将构建产物复制到游戏的模组文件夹
  • deploy_mod — 一步完成验证、构建、可选打包和部署
  • validate_mod_project — 在发布前检查本地化和资源引用
  • build_project_pck — 根据项目的清单/资源布局构建 .pck
  • apply_generated_output — 将生成的代码写入项目，合并本地化

实时场景检查 (GodotExplorer)

  • explorer_get_scene_tree — 遍历完整的 Godot 场景层次结构
  • explorer_find_nodes — 通过名称模式查找节点，支持类型过滤
  • explorer_inspect_node — 详细的节点信息——类型、属性、子节点
  • explorer_get_property / explorer_set_property — 读取/写入任何活动节点上的任何属性
  • explorer_toggle_visibility — 显示/隐藏任何 CanvasItem 节点
  • explorer_tween_property — 使用 Godot Tweens 动画化属性
  • explorer_call_method — 在节点上执行带参数的方法
  • explorer_list_assemblies / explorer_search_types / explorer_inspect_type — .NET 运行时类型检查

游戏测试与调试

  • bridge_start_run — 使用固定装置设置开始带种子的游戏
  • bridge_play_card — 使用目标打出卡牌
  • bridge_execute_action — 地图导航、获取奖励、从商店购买、选择宝箱、选择事件
  • bridge_wait_for_screen — 等待特定界面激活并稳定
  • bridge_get_combat_state / bridge_get_player_state — 查询完整游戏状态
  • bridge_manipulate_state — 在游戏过程中设置生命值/金币/能量、抽卡、添加能力
  • bridge_set_game_speed — 0.1倍速至20倍速
  • bridge_capture_screenshot — 视觉验证
  • bridge_debug_pause / bridge_debug_resume / bridge_debug_step — 动作级调试
  • bridge_debug_set_breakpoint — 在动作类型或钩子上设置带条件的断点
  • bridge_save_snapshot / bridge_restore_snapshot — 从相同位置进行 A/B 测试
  • bridge_autoslay_start / bridge_autoslay_status — 自动化多轮压力测试

代码智能

  • suggest_hooks — 根据自然语言意图推荐钩子
  • suggest_patches — 建议 Harmony 补丁目标
  • analyze_method_callers — 通过 Roslyn 调用图追踪调用者/被调用者
  • check_mod_compatibility — 根据当前游戏 API 检查模组
  • analyze_build_output — 将编译器输出解析为结构化错误

游戏资源提取 (GDRE Tools)

  • list_game_assets — 列出游戏 PCK 中的所有 15,000+ 个文件
  • search_game_assets — 在所有资源路径中快速内存搜索
  • extract_game_assets — 使用 glob 过滤器提取文件
  • recover_game_project — 通过 GDScript 反编译实现完整的 Godot 项目恢复

可以尝试的示例提示词

  • “创建一个模组，添加一张名为能量涌动的卡牌——一张 1 费铁甲战士攻击牌，造成 8 点伤害并抽 1 张牌”
  • “添加一个遗物，在每次战斗开始时给予 1 点力量”
  • “创建一个药水，对所有敌人施加 5 层易伤”
  • “生成一个拥有自己卡池的自定义角色”
  • “构建并部署我的模组，然后开始一局游戏并测试它”
  • “我应该使用哪些钩子来增加额外抽牌？”
  • “显示打击这张卡的源代码”
  • “列出所有稀有攻击牌”
  • “Harmony IL 转译器是如何工作的？”
  • “解释 STS2 中的伤害系统是如何运作的”

BaseLib 集成

所有代码生成默认使用 BaseLib，它提供：

  • 抽象基类 — CustomCardModel、CustomRelicModel、CustomPowerModel、CustomPotionModel、CustomCharacterModel
  • 自动注册 — ICustomModel 类型自动获得带前缀的 ID 和卡池注册
  • 配置系统 — 带自动生成游戏内 UI 的 SimpleModConfig
  • 卡牌变量 — ExhaustiveVar、PersistVar、RefundVar
  • CommonActions — 用于伤害、格挡、抽牌、施加能力的辅助方法
  • 实用工具 — SpireField、WeightedList、IL 补丁工具

在任何生成工具上设置 use_baselib: false，改用原始游戏 API 代码。

生成的模组结构

当你使用 create_mod_project 时，它会创建：

MyMod/
  MyMod.csproj                 -- .NET 9.0 + BaseLib + Harmony
  mod_manifest.json            -- Mod metadata
  Code/
    ModEntry.cs                -- [ModInitializer] entry point
    Cards/                     -- Custom cards
    Relics/                    -- Custom relics
    Powers/                    -- Custom powers
    Potions/                   -- Custom potions
    Monsters/                  -- Custom monsters
    Encounters/                -- Custom encounters
    Events/                    -- Event scaffolds
    Characters/                -- Custom characters (BaseLib)
    Patches/                   -- Harmony patches
    Networking/                -- Multiplayer net messages
    UI/                        -- Custom Godot UI panels
    Overlays/                  -- Combat/map overlays
    ...and more
  MyMod/
    localization/eng/          -- Localization JSON files
    images/                    -- Entity images
    MonsterResources/          -- Monster scenes and sprites

游戏更新后的操作

当《杀戮尖塔 2》更新时：

  • C# 源代码 — 让 AI 运行 decompile_game，或手动重新运行 ilspycmd。Roslyn 索引会在下次查询时自动重建。
  • Godot 资源 — 让 AI 运行 recover_game_project 以从更新的 PCK 中重新提取。

故障排除

  • “找不到 Python” / “找不到 pip” — 确保已安装 Python 3.11+ 并将其添加到 PATH。在 Windows 上，重新运行 Python 安装程序并勾选“将 Python 添加到 PATH”。
  • “找不到 dotnet” — 安装 .NET 9.0 SDK。安装后，重启你的终端。
  • 桥接无法连接 — 确保游戏正在运行，MCPTest 出现在游戏的模组列表中（主菜单 > 模组），并且没有其他程序占用 TCP 端口 21337。让 AI 执行：“检查桥接诊断”
  • 游戏找不到模组 — 模组文件夹应位于 <游戏安装目录>/mods/。MCP 服务器会自动创建此文件夹。让 AI 执行：“显示游戏信息” 以验证路径。
  • 构建错误 — 让 AI “分析构建输出” —— 它会将编译器错误解析为结构化诊断信息，并且通常可以自动修复。

下载内容包含什么

sts2-modding-mcp/
  run.py               -- Entry point: starts the MCP server
  sts2mcp/
    server.py          -- 151 tool definitions and request handling
    mod_gen.py         -- Code generators (cards, relics, powers, etc.)
    game_data.py       -- Game source indexer
    analysis.py        -- Code intelligence (hooks, patches, call graphs)
    bridge_client.py   -- TCP client to the in-game bridge mod
    templates/         -- 43 C# code templates
    docs/guides/       -- 29 modding guide topics
    docs/baselib/      -- 15 BaseLib reference docs
  test_mod/            -- Bridge mod (runs inside the game, port 21337)
  explorer_mod/        -- Scene inspector mod (runs inside the game, port 27020)
  tools/               -- Roslyn analyzer for deep C# parsing

贡献

这个项目是开源的，非常欢迎贡献！无论是新的模组制作指南、错误修复、生成器改进还是新工具——都鼓励贡献。

MIT 许可证