中文版说明请见 README.zh-CN.md.

STS2 AI Agent is a Slay the Spire 2 mod + MCP server bundle:

• STS2AIAgent: exposes game state and actions through a local HTTP API
• mcp_server: wraps that local API as an MCP server for AI clients

Detailed MCP tool documentation lives in mcp_server/README.md. If you want an agent workflow on top of it, start with skills/sts2-mcp-player/SKILL.md.

After downloading and extracting the release package, copy these files into your game's mods/ directory:

STS2AIAgent.dll
STS2AIAgent.pck
mod_id.json

The default Steam install path is usually:

C:\Program Files (x86)\Steam\steamapps\common\Slay the Spire 2

Your final layout should look like this:

Slay the Spire 2/
  mods/
    STS2AIAgent.dll
    STS2AIAgent.pck
    mod_id.json

Launch the game normally so the mod can load with it.

Then open:

http://127.0.0.1:8080/health

If the endpoint responds, the mod is running.

Prepare the environment first:

1. Install Python 3.11+
2. Install uv

Install uv on Windows:

powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"

On macOS:

brew install uv

Then start the default stdio MCP server.

Windows:

powershell -ExecutionPolicy Bypass -File ".\scripts\start-mcp-stdio.ps1"

macOS / Linux:

./scripts/start-mcp-stdio.sh

This is the recommended default. Most desktop AI clients prefer stdio MCP integration.

If your client supports command-based MCP startup, point its working directory at mcp_server/ and use:

uv run sts2-mcp-server

If your client works better over HTTP, start the network server instead.

Windows:

powershell -ExecutionPolicy Bypass -File ".\scripts\start-mcp-network.ps1"

macOS / Linux:

./scripts/start-mcp-network.sh

Default MCP endpoint:

http://127.0.0.1:8765/mcp

The current main branch provides a playable MCP integration for STS2, including:

• reading live game state
• listing currently legal actions
• driving combat, rewards, shops, map routing, events, rest sites, chests, capstone selection, and bundle selection
• enriched combat and run payloads (Ascension, act/boss ID, enemy/move ID) for AlphaZero training
• resolve_rewards atomic action for controlled reward resolution
• reducing polling through SSE events
• exposing MCP over stdio or HTTP
• serving live game metadata for cards, relics, monsters, potions, and events via the Mod API
• supporting layered planner / combat agent handoff flows
• increase_ascension / decrease_ascension controls in character select

See mcp_server/README.md for the detailed tool surface.

Check these first:

1. The game is actually running
2. STS2AIAgent.dll, STS2AIAgent.pck, and mod_id.json are all inside the game's mods/ directory
3. The files were not duplicated or renamed by the OS
4. You copied them into the Steam game directory, not the repository directory

That usually means mcp_server is running, but the in-game mod is not connected. Confirm:

1. The game is running
2. http://127.0.0.1:8080/health is reachable
3. The MCP server is still pointing at http://127.0.0.1:8080

Usually no.

Developer-only actions such as run_console_command are disabled by default and should stay disabled in normal use and releases.

If you are building from source instead of using a release package:

Windows:

powershell -ExecutionPolicy Bypass -File ".\scripts\build-mod.ps1" -Configuration Release

macOS / Linux:

./scripts/build-mod.sh --configuration Release

More complete environment, path-discovery, and validation notes are in build-and-env.md.

• STS2AIAgent/: game mod source
• mcp_server/: MCP server source
• scripts/: startup, build, and validation scripts
• docs/: supporting documentation
• skills/: companion skills

This project is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only).