Skip to main content
Glama
Sign In
sts1

sts1

by KeiNodens
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

sts1AI

Python checks

Slay the Spireを、人間とAIで協力プレイするためのローカルツールです。Together in SpireとCommunication Modを使い、自作のAutoMP、HTTPブリッジ、MCPサーバー、カード評価器を組み合わせています。

自分のWindows環境で開発した実験的なプロジェクトです。セーブの衝突対策と再接続を含みます。他の利用者による導入や、あらゆるModの互換性は確認していません。ゲームや第三者Modの配布物は含みません。

できること

  • 同一PCの人間側・AI側をlocalhostで接続し、キャラクター指定や出発を補助する。

  • 同一PCでのセーブ衝突を避けるため、AutoMPでプレイヤー別のセーブ名を使う。

  • ゲーム状態を取得し、MCPからカード使用・ターン終了・選択などを行う。

  • カードの効果を構造化して順序と組み合わせを評価し、実行前後の差分を記録する。

AIクライアントが判断する経路と、Pythonの定型処理で動く自動ドライバの両方があります。自動ドライバの結果をLLMのプレイ能力の指標としては扱っていません。

Related MCP server: LorAI MCP

前提と導入

Windows、Python 3.11以降、購入済みのSlay the Spire、ModTheSpire、BaseMod、StSLib、Together in Spire、Communication Modが必要です。Java ModのビルドにはJDKとjarコマンドも必要です。

Together in Spire、Communication Mod、ModTheSpireは提供元から別途取得してください。

このリポジトリだけを取得し、ルートで次を実行します。隣のsts2AIフォルダーは不要です。

py -3.12 -m venv .venv
.venv/Scripts/python.exe -m pip install -c requirements-lock.txt .
.venv/Scripts/python.exe -B -m unittest discover -s tests -v

AutoMPのビルド

ゲームと依存ModのJARへのパスを、自分の環境に置き換えてください。

./scripts/build-mods.ps1 -GameJar '<game>/desktop-1.0.jar' -ModTheSpireJar '<path>/ModTheSpire.jar' -BaseModJar '<path>/BaseMod.jar' -StSLibJar '<path>/StSLib.jar' -TogetherInSpireJar '<path>/TogetherInSpire.jar' -JdkBin '<jdk>/bin'

out/automp.jarをゲームのmodsフォルダーへコピーします。out/testdeck.jarは検証用カード注入Modなので、通常のプレイには不要です。ビルド成果物には依存JARやゲームのクラスを含めません。

Communication Modと起動

Communication Modのconfig.propertiesで、commandをこのリポジトリのPythonとブリッジに向けます。Communication Modはcommandを空白で区切り、引用符を解釈しません。この構成では、リポジトリを空白のないパスへ置いてください。Windowsのpropertiesではバックスラッシュのエスケープが必要なため、スラッシュ表記を使います。既存設定は先にバックアップしてください。

command=<repo>/.venv/Scripts/python.exe <repo>/sts1_bridge.py
runAtGameStart=true

人間側を起動してからAI側を起動します。ゲームのウィンドウが開き、AutoMPが接続を試みます。

./scripts/launch.ps1 -GameDir '<game>' -ModTheSpireJar '<path>/ModTheSpire.jar' -Role host
./scripts/launch.ps1 -GameDir '<game>' -ModTheSpireJar '<path>/ModTheSpire.jar' -Role join

hostのブリッジは15532、AI側は15531、ゲーム同士の接続は49580です。-Characterでキャラクターを指定し、-Embarkで自動出発を有効にできます。セーブ名の変更と自動再接続はゲームに副作用があります。重要なセーブを退避し、テスト用のランで確認してください。

MCPクライアントへの登録

設定例の<repo>を絶対パスに置き換えます。MCPは標準入出力を使います。

{
  "mcpServers": {
    "sts1": {
      "command": "<repo>/.venv/Scripts/python.exe",
      "args": ["-m", "mcp_bridge.server"],
      "env": {"STS1_KB_PATH": "<repo>/card_kb1.json"}
    }
  }
}

主なツールはget_game_state、get_decision_pack、play_card、end_turn、run_turn、flush_observationsです。ゲームを動かすツールは実際のランを進めます。ブリッジの変更先はSTS1_BRIDGE_BASEまたはサーバーの--base-urlで指定できます。

.venv/Scripts/python.exe -m advisor.auto1 --steps 200

これはAIクライアントを使わずに動く定型ドライバです。ゲームを進行させ、観測をカードKBへ書き込みます。

カード効果の知識ベース

生成済みの大規模KBは配布しません。ファイルがなければ、少数の手書きシードとルールで動作します。未知カードの効果を正確に評価できるとは限りません。保存先はSTS1_KB_PATH、既定は実行ディレクトリのcard_kb1.jsonです。

ローカルで用意したJavaソースを解析する場合:

.venv/Scripts/python.exe -m tools.gen_card_kb1 --source '<local-sources>' --out card_kb1.json

任意のMod解析にはCFRを別途取得します。対象Modの条件を確認して自分のローカル環境で利用し、生成されたソースやKBをこのリポジトリへ追加しないでください。

.venv/Scripts/python.exe -m tools.gen_mod_kb1 --cfr '<path>/cfr.jar' --game-dir '<game>' --workshop-dir '<workshop>/646570'

構成と検証

advisor/に評価・観測、mcp_bridge/にMCP、sts1_bridge.pyにゲームとの標準入出力の橋渡し、automp/とtestdeck/に自作Java Modがあります。tests/fixturesの小さな合成データでテストし、本番のKBは読みません。

公開用の確認結果と実機検証の区別はVALIDATION.md、データと操作の注意点はSECURITY.md、出典はNOTICE.mdを参照してください。自作部分はMIT Licenseです。

各プロジェクトは別々の仮想環境へ導入してください。検証済みの依存バージョンはrequirements-lock.txtに固定しています。

Available Tools

12 tools
cancelA

Cancel/back out of the current overlay.

Inputs: no named parameters. Returns: result

chooseB

Pick choice_list/screen option by 0-based index (events, map nodes, Neow, card rewards).

Inputs: option_index (required). Returns: result

confirmC

Confirm the current selection (grid confirm etc.).

Inputs: no named parameters. Returns: result

end_turnB

End the current combat turn.

Inputs: no named parameters. Returns: result

flush_observationsA

Write accumulated card-play observations into card_kb1.json.

play_card / run_turn record before/after state diffs; this tool aggregates them (median per effect) and persists entries with prov="observed" (conf 0.65-0.85). Entries with higher confidence (dll/static) are not overwritten — a disagreeing observation is stashed under the entry's "obs" field instead.

Inputs: no named parameters. Returns: result

get_decision_packA

Get a compact decision pack — the primary LLM feed.

Contains NO free-text fields: cards are identified by id and expressed as structured effects (damage/block/draw/apply_power ops from static card analysis + curation rules), plus advisor output: incoming damage, max damage, lethal targets, and a suggested action sequence. Custom mod mechanics appear as separate resources (e.g. hsr toughness is mod_damage pool=toughness, never mixed into HP lethal math).

Inputs: no named parameters. Returns: result

get_game_stateB

Get the current game state (sanitized — no raw card/monster name text).

Card/relic/potion/monster entries keep their id (e.g. "Strike_R", "HSRMod:Danheng0") which is the stable lookup key. Raw name fields are stripped since they are Japanese text the LLM does not need.

Inputs: no named parameters. Returns: result

leaveA

Leave the current room/shop (out of combat only).

Inputs: no named parameters. Returns: result

play_cardA

Play a card by its id from hand (re-resolves the hand index).

Args: card_id: card id field from state/decision_pack (e.g. "Strike_R"). target_index: 0-based enemy index for targeted attacks (omit for non-targeted cards like Defend).

Inputs: card_id (required), target_index. Returns: result

proceedB

Press the generic proceed/continue button.

Inputs: no named parameters. Returns: result

run_turnB

Autonomously play one combat turn via the advisor.

Builds the decision pack, then executes advice.plan through Communication Mod (re-resolves hand indices by card id). Returns the pack plus the execution log. In co-op the command may take a few seconds to apply.

Inputs: sleep. Returns: result

send_commandA

Send a raw Communication Mod command line.

Commands: PLAY <1-based hand index> [0-based enemy index], END, CHOOSE , CONFIRM, PROCEED, SKIP, CANCEL, RETURN, LEAVE, POTION <use|discard> , STATE, KEY , CLICK , WAIT , START . Prefer the dedicated tools (play_card / end_turn / choose / proceed) — they are easier to get right. PLAY hand index is 1-based, enemy index is 0-based.

Inputs: line (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.6/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools target clearly distinct actions (play_card, end_turn, choose, confirm, leave), but send_command duplicates nearly every dedicated tool and run_turn overlaps with play_card/end_turn, creating some selection ambiguity. The descriptions explicitly guide agents to prefer dedicated tools, which mostly resolves the confusion.

    Naming Consistency4/5

    All names are snake_case and verb-first, with most following a verb_noun pattern (get_game_state, play_card, run_turn, flush_observations). A few are bare verbs (proceed, choose, confirm, cancel, leave), which is a minor deviation from a single predictable pattern.

    Tool Count5/5

    12 tools is well within the sweet spot for this domain. The set covers combat actions, screen navigation, turn automation, state retrieval, and observation logging without obvious bloat, and each tool appears to earn its place.

    Completeness4/5

    Core gameplay (playing cards, ending turns, choosing options, confirming, cancelling, leaving) and autonomous turn execution are covered, with send_command as a raw fallback. However, common actions like potion usage lack a dedicated convenience tool and must go through send_command, leaving a minor gap.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • STS2 AI Agent

      CharTyr
      F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to play Slay the Spire 2 by exposing game state and actions through an MCP server, supporting combat, rewards, and run management.
      357
      -

    • gap

      lonexreb
      A
      license
      A
      quality
      C
      maintenance
      Enables any local AI agent to play turn-based games over MCP by exposing reset, observe, and act verbs with structured observations and validated legal actions.
      6
      MIT

    • sts2-mcp-bridge

      brmarcosbr
      A
      license
      Not graded
      quality
      C
      maintenance
      Enables an MCP agent to observe and command Slay the Spire 2 game state via HTTP, and optionally autopilot combat with a local deterministic policy, without LLM in the critical path.
      MIT