# Headless In The Spire

> Custom headless runner for Slay the Spire 2. Uses real game logic and provides various ways to interact with the game, including MCP and high-level interfaces.

- **Type:** MCP server
- **Install:** `agentstack add mcp-buckfae-headless-in-the-spire`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [BUCKFAE](https://agentstack.voostack.com/s/buckfae)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [BUCKFAE](https://github.com/BUCKFAE)
- **Source:** https://github.com/BUCKFAE/headless-in-the-spire

## Install

```sh
agentstack add mcp-buckfae-headless-in-the-spire
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# headless-in-the-spire

[](https://github.com/BUCKFAE/headless-in-the-spire/actions/workflows/ci.yml)
[](Directory.Build.props)
[](tests)
[](src/GodotStubs)
[](src)

A custom headless runner for **Slay the Spire 2**. It loads the real game logic
out-of-game and drives it programmatically for deterministic testing, automation,
AI experimentation, and replay tooling.

## Features

- **Real game, no reimplementation.** The host loads the shipped `sts2.dll` and drives it as a library. STS2's own C# is the source of behavioral truth.
- **Runs headless, parallelisable.** A .NET subprocess — no Godot window, no input injection, no display server. Scenarios are reproducible on CI and trivially parallel.
- **Schema-first wire protocol.** NDJSON / JSON-RPC over stdio, with an
  OpenRPC schema exported directly from the C# method records. Ships a
  typed pydantic v2 Python client and an MCP server, so any MCP-aware
  assistant (Claude Desktop, Claude Code, …) can drive a full run
  end-to-end.
- **Native replay artefacts.** Per-combat `.mcr` and per-run `.run` files
  are written through the engine's *own* writers — the same format the
  game itself produces. A bundled TypeScript replay viewer renders them
  straight from disk.
- **Tested against the real DLL.** Three-axis test pyramid (unit /
  integration / end-to-end), plus opt-in mechanic sweeps that drive every
  card / relic / event / potion / power / encounter / affliction /
  enchantment id through a minimal fixture.

### Roadmap

- Extend existing wire protocol with more detailed info, like the remaining elite pool for current map
- Better overview of available wire / agent features
- Tooling to better compare performance of different agents across languages
- Support for `Kotlin` and `Rust`
- Improved battle simulator
- CLI runner allowing you to play sts2 when you again accidentally deleted your desktop on linux
- Improved coverage reports, ensure all code paths are covered by tests that fail loudly when the dll changes.
- Create a proper CI runner that has the proprietary sts2 dlls.

#### Replays & Controlling the actual game
The current replay viewer is very crude. I think that sooner or later someone (or Megacrit) will develop a sophisticated replay viewer.
Once a community-established solution for this (and controlling the actual game) is available, I will integrate it.

## Current State
This project is in *very active, early* development. Expect breaking changes.

## Acknowledgements and AI Notice
This repository heavily used [https://github.com/wuhao21/sts2-cli](https://github.com/wuhao21/sts2-cli) as reference point. 
While I reviewed the high-level design choices carefully, most of the implementation was AI-generated and committed without line-by-line review. Treat it accordingly.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [BUCKFAE](https://github.com/BUCKFAE)
- **Source:** [BUCKFAE/headless-in-the-spire](https://github.com/BUCKFAE/headless-in-the-spire)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-buckfae-headless-in-the-spire
- Seller: https://agentstack.voostack.com/s/buckfae
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.