STS2 Modding Assistant MCP

STS2 Modding MCP

An LLM-powered modding toolkit for Slay the Spire 2. This Model Context Protocol server connects to any MCP-compatible AI assistant — Claude Code, Claude Desktop, Cursor, Windsurf, and more — giving it 151 tools to reverse-engineer the game, generate mod code, build and deploy mods, inspect the live game engine, and autonomously playtest your mods by playing the game itself.

You don't need to be a programmer to use it (though that certainly helps). Use it as a powerful tool for seasoned developers or if you're a beginner, try just describing what you want in plain English and let the LLM handle the code (always prompt it to do extensive testing, debugging and hardening. This is a very important step).

Important: Your results will vary depending on the AI model you use. I've had the best experience with Claude Opus 4.6 and ChatGPT Codex 5.4 — with those, I've yet to find a code-related mod they couldn't create, test, and debug on their own.

This project is doubling as a fun experiment for me. Please reach out if you have any issues, can't figure something out, want to suggest a feature, or find a bug!

---

Requirements

• Slay the Spire 2 (Steam)
• Python 3.11+ — python.org/downloads (check "Add to PATH" during install on Windows)
• .NET 9.0 SDK — dotnet.microsoft.com
• An MCP-compatible AI client (Claude Code, Claude Desktop, Cursor, Windsurf, etc.)

Optional:

• GDRE Tools — for extracting Godot assets from the game PCK (download)
• ilspycmd — for C# decompilation: dotnet tool install -g ilspycmd

---

Installation

1. Extract the downloaded zip to a folder you'll keep (e.g. C:\sts2-modding-mcp)
2. Open a terminal in that folder
3. Create and activate a virtual environment:

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

4. Install: pip install .
5. Run first-time setup: python -m sts2mcp.setup

The setup wizard will auto-detect your game install, install ilspycmd if needed, decompile the game's C# assemblies, and build/deploy the bridge mods to the game's mods folder.

If your game isn't auto-detected, edit sts2mcp_config.json in the install folder:
{ "game_dir": "D:\\Games\\Slay the Spire 2" }

---

Connecting to an AI Client

The MCP server needs an AI client to talk to. Point it at the venv's Python so dependencies are always available.

Claude Desktop

Edit your config file:

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

Add:

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

Replace paths with where you extracted the download. Restart 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 / Other

Most MCP clients use a similar JSON config. Point the command at the venv Python and args at run.py. Check your editor's MCP docs.

To verify: ask the AI "What modding guides are available?" or "Show me the game info."

---

Features

• 151 tools exposed to the AI assistant
• Decompiles the game's C# assemblies into fully searchable source with Roslyn syntax trees, call graphs, and inheritance chains
• Extracts and indexes 15,000+ Godot assets (scenes, textures, resources, scripts, audio)
• Catalogs 3,048+ game entities — cards, relics, powers, potions, monsters, encounters, events, enchantments, orbs, and more
• Maps 144 hooks and 175 overridable methods across combat, card, damage, power, turn, and reward systems
• Generates production-ready C# mod code for 30+ entity types
• Scaffolds complete mod projects with .csproj, manifest, localization, and folder structure
• Generates Harmony patches (prefix, postfix, IL transpiler), reflection accessors, network messages, save data, and mod config
• Builds Godot UI panels, combat overlays, floating panels, scrollable lists, animated bars, hover tips, and VFX scenes — all in C#
• Integrates with BaseLib for abstract base classes, auto-registration, config UI, and card variables
• Recommends hooks from natural language (e.g. "make potions heal more")
• Builds mods via dotnet build with structured output
• Builds Godot PCK resource packs with automatic PNG-to-texture conversion
• Deploys built artifacts to the game's mods folder in one step
• Validates localization, asset references, and project structure before shipping
• Watches project files and auto-rebuilds on changes

Live Scene Inspection

• Browses the running game's full Godot scene tree in real time
• Reads and writes node properties on live nodes (position, scale, color, text, visibility)
• Toggles visibility of any visual layer to isolate and inspect UI, VFX, or game elements
• Animates properties with Godot Tweens for live experimentation
• Inspects all loaded .NET assemblies, types, methods, and properties at runtime

Automated Playtesting

• Starts seeded runs with specific characters, ascension, modifiers, and pre-configured decks/relics/gold
• Controls every screen — combat, map, events, rewards, shops, rest sites, treasure, card selection
• Plays cards with targeting, ends turns, uses potions, navigates maps, makes event choices, buys from shops
• Manipulates game state mid-run — set HP/gold/energy, draw cards, add powers and relics
• Runs at up to 20x speed for fast iteration
• Captures screenshots for visual verification

Debugging

• Sets breakpoints on specific game actions or hooks with optional conditions
• Steps through combat one action at a time with full state inspection at each step
• Pauses and resumes action processing while the game continues rendering
• Saves and restores named state snapshots for A/B testing from identical game positions
• Polls unhandled exceptions with full stack traces
• Hot-reloads Harmony patches from a new DLL without restarting the game

Automated Stress Testing (AutoSlay)

• Runs fully autonomous multi-run playthroughs with configurable characters, seeds, and ascension
• Tracks progress across runs — current floor, act, room, elapsed time, and errors
• Configurable timeouts and watchdog behavior for detecting softlocks and crashes

Modding Guides & Reference

• 29 built-in guide topics covering getting started, hooks, localization, Harmony, multiplayer networking, Godot UI, IL transpilers, combat deep dive, save files, RNG/determinism, accessibility, and more
• 15 BaseLib reference docs for custom entities, config, card variables, SpireField, WeightedList, and IL patching
• 39 in-game console commands documented with arguments and descriptions

MCPs like this live and die on how up-to-date and well-written the guides are. The AI will eventually figure things out with self-debugging, but adding to this database is key to efficiency. If you use it for a project, please consider contributing guides back!

---

Tool Highlights

The MCP currently exposes 151 tools. The sections below highlight the main workflows.

Game Data Query

• list_entities — Search/filter entities by type, name, rarity
• get_entity_source — Get full decompiled C# source for any game class
• search_game_code — Search decompiled source using Roslyn indexes or regex
• list_hooks — List game hooks by category and subcategory
• get_modding_guide — Built-in documentation for 29 topics
• browse_namespace — Navigate decompiled namespaces and read individual files
• get_console_commands — All 39 dev console commands with args and descriptions

Core Mod Creation

• create_mod_project — Scaffold a complete mod project
• generate_card — Card class with dynamic vars, OnPlay logic, upgrade logic, and localization
• generate_relic — Relic class with hook methods and localization
• generate_power — Power (buff/debuff) class with hook methods
• generate_potion — Potion class with OnUse logic and localization
• generate_monster — Monster class with move state machine, .tscn scene, and localization
• generate_encounter — Encounter class that spawns specific monsters
• generate_character — Full custom playable character with card/relic/potion pools (BaseLib)
• generate_harmony_patch — Harmony prefix/postfix patch class

Advanced Generators

Inspired by patterns found across 21 community mods:

• generate_net_message — Multiplayer network message scaffold
• generate_godot_ui — Programmatic Godot UI panel (no .tscn required)
• generate_overlay — Auto-injected combat/map overlay
• generate_transpiler_patch — IL bytecode Harmony transpiler
• generate_reflection_accessor — Cached AccessTools field/property accessors
• generate_custom_keyword — CardKeyword with BaseLib
• generate_custom_pile — PileType for custom card destinations
• generate_spire_field — SpireField for attaching data to game models
• generate_dynamic_var — Custom DynamicVar for card/power description variables
• generate_mechanic — Full cross-cutting keyword mechanic (power + card + relic + localization)
• generate_event — Event class with choice tree and handler methods
• generate_orb — Orb with passive/evoke effects
• generate_enchantment — Enchantment that attaches to and modifies cards
• generate_save_data — Persistent JSON save data class
• generate_vfx_scene — Godot .tscn particle effect scene

Build & Deploy

• build_mod — Build via dotnet build with output capture and artifact listing
• install_mod — Copy built artifacts to the game's mods folder
• deploy_mod — Validate, build, optionally pack, and deploy in one step
• validate_mod_project — Check localization and asset references before shipping
• build_project_pck — Build a .pck from the project's manifest/resource layout
• apply_generated_output — Write generated code into a project, merge localization

Live Scene Inspection (GodotExplorer)

• explorer_get_scene_tree — Walk the full Godot scene hierarchy
• explorer_find_nodes — Find nodes by name pattern with type filtering
• explorer_inspect_node — Detailed node info — type, properties, children
• explorer_get_property / explorer_set_property — Read/write any property on any live node
• explorer_toggle_visibility — Show/hide any CanvasItem node
• explorer_tween_property — Animate a property with Godot Tweens
• explorer_call_method — Execute methods on nodes with arguments
• explorer_list_assemblies / explorer_search_types / explorer_inspect_type — .NET runtime type inspection

Playtesting & Debugging

• bridge_start_run — Seeded runs with fixture setup
• bridge_play_card — Play cards with targeting
• bridge_execute_action — Navigate maps, take rewards, buy from shops, pick treasure, choose events
• bridge_wait_for_screen — Wait until a specific screen is active and stable
• bridge_get_combat_state / bridge_get_player_state — Query full game state
• bridge_manipulate_state — Set HP/gold/energy, draw cards, add powers mid-run
• bridge_set_game_speed — 0.1x to 20x speed
• bridge_capture_screenshot — Visual verification
• bridge_debug_pause / bridge_debug_resume / bridge_debug_step — Action-level debugging
• bridge_debug_set_breakpoint — Break on action types or hooks with conditions
• bridge_save_snapshot / bridge_restore_snapshot — A/B testing from identical positions
• bridge_autoslay_start / bridge_autoslay_status — Automated multi-run stress testing

Code Intelligence

• suggest_hooks — Recommend hooks from natural language intent
• suggest_patches — Suggest Harmony patch targets
• analyze_method_callers — Trace callers/callees via Roslyn call graph
• check_mod_compatibility — Check a mod against the current game API
• analyze_build_output — Parse compiler output into structured errors

Game Asset Extraction (GDRE Tools)

• list_game_assets — List all 15,000+ files in the game PCK
• search_game_assets — Fast in-memory search across all asset paths
• extract_game_assets — Extract files with glob filters
• recover_game_project — Full Godot project recovery with GDScript decompilation

---

Example Prompts to Try

• "Create a mod that adds a card called Power Surge — a 1-cost Ironclad attack that deals 8 damage and draws 1 card"
• "Add a relic that gives 1 strength at the start of each combat"
• "Create a potion that applies 5 vulnerable to all enemies"
• "Generate a custom character with their own card pool"
• "Build and deploy my mod, then start a run and test it"
• "What hooks should I use to add extra card draw?"
• "Show me the source code for the Bash card"
• "List all rare attack cards"
• "How do Harmony IL transpilers work?"
• "Explain how the damage system works in STS2"

---

BaseLib Integration

All code generation defaults to using BaseLib, which provides:

• Abstract base classes — CustomCardModel, CustomRelicModel, CustomPowerModel, CustomPotionModel, CustomCharacterModel
• Auto-registration — ICustomModel types get prefixed IDs and pool registration automatically
• Config system — SimpleModConfig with auto-generated in-game UI
• Card variables — ExhaustiveVar, PersistVar, RefundVar
• CommonActions — Helper methods for damage, block, draw, apply powers
• Utilities — SpireField, WeightedList, IL patching tools

Set use_baselib: false on any generation tool to get raw game API code instead.

---

Generated Mod Structure

When you use create_mod_project, it creates:

MyMod/
MyMod.csproj -- .NET 9.0 + BaseLib + Harmony
mod_manifest.json -- Mod metadata
Code/
ModEntry.cs -- 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

---

Updating After Game Patches

When STS2 updates:

• C# source — ask the AI to run decompile_game or manually re-run ilspycmd. The Roslyn index automatically rebuilds on the next query.
• Godot assets — ask the AI to run recover_game_project to re-extract from the updated PCK.

---

Troubleshooting

• "Python not found" / "pip not found" — Make sure Python 3.11+ is installed and on your PATH. On Windows, re-run the Python installer and check "Add Python to PATH".
• "dotnet not found" — Install the .NET 9.0 SDK. After installing, restart your terminal.
• Bridge won't connect — Make sure the game is running, MCPTest appears in the game's mod list (main menu > Mods), and nothing else is using TCP port 21337. Ask the AI: "Check bridge diagnostics"
• Game can't find mods — The mods folder should be at <game install>/mods/. The MCP server creates this automatically. Ask: "Show game info" to verify the path.
• Build errors — Ask the AI to "analyze the build output" — it parses compiler errors into structured diagnostics and can usually fix them automatically.

---

What's Inside the Download

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

---

Contributing

This project is open source and contributions are very welcome! Whether it's new modding guides, bug fixes, generator improvements, or new tools — all contributions are encouraged.

• GitHub Repository — source code, contributions, and development
• Bug Reports & Feature Requests
• Full Getting Started Guide

MIT License