{"id":"5900cf6b-7555-4193-9902-4f9c01eb8968","slug":"sts2-mcp-server","kind":"mcp","name":"sts2-mcp-server","summary":"Thin MCP tool adapter that maps approved calls to the authenticated gateway API without bypassing it.","owner":"AI-Ascension","repoUrl":"https://github.com/AI-Ascension/sts2-mcp-server","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-09-02T05:59:57.000Z","addedAt":"2026-10-21T05:04:01.965Z","logoUrl":"https://avatars.githubusercontent.com/u/323904551?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","memory-knowledge","utilities"],"tags":["ai-ascension","rust","ai-agents","slay-the-spire-2","tool-calling"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T07:13:01.470Z","sample":false,"url":"https://conduits.dev/tools/sts2-mcp-server","language":"Rust","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<picture>\n  <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/AI-Ascension/.github/main/profile/assets/banner-dark.svg\">\n  <img alt=\"AI-Ascension — Inspect how AI requests to a game get fenced, one Rust contract at a time. Bounded runtime host trace confirmed. Deterministic tests: confirmed.\" src=\"https://raw.githubusercontent.com/AI-Ascension/.github/main/profile/assets/banner-light.svg\" width=\"100%\">\n</picture>\n\n# Slay the Spire 2 MCP\n\nPart of [Ascension](https://github.com/AI-Ascension/sts2-harness), the AI\nAscension flagship toolkit. The repository slug remains `sts2-mcp-server`;\n**The Climb — by AI Ascension** does not broaden this adapter's authority.\n\n> **AI-Ascension · tier 3: thin MCP adapter** — Thin MCP tool adapter that maps approved calls to the authenticated gateway API without bypassing it.\n>\n> **Status:** deterministic tests, the bounded `runtime-v1` host trace, the runtime-v3 gameplay adapter path, the read-only `coop-synchronization-v1` executable profile, and the additive `seeded-run-v1` and `coop-native-v1` source/component profiles are `confirmed` for the recorded STS2 v0.107.1 evidence · native multiplayer, live seeded-run settlement, and broader compatibility `unverified`.\n> **Proof:** [45-second browser replay](https://ai-ascension.github.io/proof.html) · [Evidence ledger](https://ai-ascension.github.io/evidence.html) · [This repository on the map](https://ai-ascension.github.io/repositories.html#sts2-mcp-server)\n> **Seam tests:** [crates/mcp-server/tests/seam.rs](crates/mcp-server/tests/seam.rs) — one tool call maps to one gateway request; malformed frames are rejected before the gateway.\n> **Owner:** `sts2-mcp-server` owns the external MCP process boundary: framing, server identity and capabilities, tool schemas, bounded validation, and the versioned mapping to the gateway API.\n> **Contribute:** [Organization guide](https://github.com/AI-Ascension/.github/blob/main/CONTRIBUTING.md) · [First tasks](https://ai-ascension.github.io/contributing.html)\n>\n> AI-Ascension is an independent project. It is not affiliated with or endorsed by Mega Crit or Valve and grants no rights to game files, assets, or marks.\n\nStatus: Wave 2 codebase initialization plus bounded runtime seams. The target-owned MCP seam includes\nthe two-tool `poc-v1` mapping, the separate `runtime-v1` process profile, the deterministic\n`runtime-v2` gameplay-operation mapping, and the six-tool runtime-v3 gameplay mapping. Dated\nWindows/Linux campaign and replay records confirm the MCP path for the named v0.107.1 fixtures.\nThe separate `coop-synchronization-v1` profile is read-only coordinator reporting; it is not native\nmultiplayer gameplay. The additive `seeded-run-v1` profile maps one bounded start and one read-only\nreconciliation tool through the leased gateway; its source/component checks do not establish a live\nnative seeded run, profile/save isolation, or release compatibility.\n\nThe additive `coop-native-v1` profile is selected with `STS2_RUNTIME_PROFILE=coop-native-v1`. It\nexposes seven typed tools for native observation, legal catalogs, local actions, shared votes, peer\nrejoin, same-operation recovery, and response-only effect projection. Observation uses the bodyless\n`GET /v1/instances/{id}/coop/native/observation` route; the other gateway calls use fixed POST routes\nfor `legal-catalog`, `action`, `vote`, `rejoin`, and `recover`. The profile consumes the checked-in\n`coop-native-v1` artifact at schema digest\n`2f3bc99e53080fa11b39592b64fb0ab964a16f568719a2622d0b2caf766ab629`, validates receipt/effect/\nobservation generation and identity relations, and rejects status or route drift. These are\nsource/component and synthetic gateway-boundary checks; a disposable two-peer host-backed native\nsession, provider participation, deployment, and release support remain unverified. See\n[ADR 0018](docs/decisions/0018-coop-native-component-consumer.md).\n\nThe native profile also requires `STS2_COOP_NATIVE_PEER_TOKEN` and\n`STS2_COOP_NATIVE_PEER_ID` together. The peer ID is the canonical `peer:…` identity used by the\ntyped tools; the token is a distinct private route credential. MCP never exposes the token in a\ncatalog, tool argument, envelope, or response projection, and injects it only as the trusted\n`x-sts2-peer-token` gateway header after it validates the configured peer binding. The executable\nadapter necessarily reads that credential from trusted runtime configuration for this header step;\nit is not protocol-visible or model-facing identity.\n\nThe additive `game-information-query-v1` profile is selected with\n`STS2_RUNTIME_PROFILE=game-information-query-v1`. It exposes six bounded read-only tools for\ncapabilities, static definition list/search/get, live detail, and availability. Calls map only to the\nfixed gateway capabilities GET and query POST routes and consume the pinned\n`game-information-query-v1` artifact. Definitions and live instance references remain distinct;\nfield availability, snapshot/cursor fences, provenance, and result limits are validated before\ncontent reaches MCP. The artifact is pinned to merged `sts2-protocol/main` commit\n`34f68b182c09472c3a0573ff478e17e6ed53c91f` (schema `376845b0…`). Gateway #52, game-mod extraction,\nlive snapshots, and host compatibility remain unverified; see\n[ADR 0020](docs/decisions/0020-game-information-query-profile.md).\n\nThe opt-in `negotiated-composition-v1` profile combines the existing runtime-map gameplay/map\ncatalog with the game-information lookup catalog after negotiating unique operation names,\nrevision compatibility, producer/gateway/MCP/caller scope intersection, and bounded per-tool\nlimits. It adds the local read-only `sts2.capabilities` discovery tool; unavailable features carry\nmachine-readable reasons instead of being silently enabled. Producer restart, content reload,\npermission, and tool-set revision events invalidate tracked snapshots, queue the MCP\n`notifications/tools/list_changed` signal, and require reinitialization before forwarding calls.\nThe profile is a source/component composition seam; dynamic producer capability discovery, gateway\nreadiness, host extraction, and live snapshot freshness remain unverified. See\n[ADR 0021](docs/decisions/0021-negotiated-composition-profile.md).\n\nThe additive `save-profile-v1-mcp` profile is selected with\n`STS2_RUNTIME_PROFILE=save-profile-v1`. It exposes five bounded tools:\n`sts2.save_profile_list`, `sts2.save_profile_current`, `sts2.save_profile_select`,\n`sts2.save_profile_create_disposable`, and `sts2.save_profile_status`. List/current/status are\nread-only; select and create-disposable are explicit mutations. Calls map only to the fixed\ngateway list/current/select/create-disposable/operation routes. Selection requires a bounded\nprofile ID and baseline; disposable creation returns only gateway-owned opaque user-data provenance.\n`STS2_SAVE_PROFILE_CAPABILITY` defaults to `unsupported`, accepts `read` or `read-write`, and\ncontrols which descriptors are advertised; unsupported owners publish no usable save-profile tools.\nTimeouts preserve the MCP operation identity as `unknown`, and status reconciles it without replay.\nGateway PR #53 supplies the source/component route contract. Launch-profile wiring, game-mod\nsave-slot readback, host settlement, and integrated readiness remain unverified; see\n[ADR 0025](docs/decisions/0025-save-profile-mcp-tools.md).\n\n## Owner and consumers\n\n`sts2-mcp-server` owns the external MCP process boundary: framing, server identity and capabilities,\ntool schemas, bounded validation, and the versioned mapping from approved MCP calls to the authenticated\ngateway API. Its consumers are MCP clients/agents and the Rust harness coordinator. The gateway is the\ndownstream contract owner; the game-mod and host remain behind it.\n\n## Boundary\n\n```text\nMCP client or harness --MCP--> sts2-mcp-server --authenticated gateway API--> sts2-gateway\n                                                                            --> sts2-game-mod --> game host\n```\n\nThe adapter does not own game rules, host objects, saves, game listeners, gateway lifecycle or registry\nstate, model/provider calls, trajectory/artifact storage, or harness orchestration. It must never route\naround the gateway or accept arbitrary downstream paths, headers, or methods.\n\nThe current build-completion decision recognizes `sts2-protocol` as the sixth target, but that target is\nlimited to genuinely shared language- and transport-neutral contracts. This repository owns MCP wire and\ntool schemas; it consumes a checked-in copy of the `sts2-protocol/poc-v1` release-like artifact and\nversioned gateway descriptions without making the protocol target a second source of boundary behavior.\nThe checked-in `protocol-artifact/runtime-v2` package is the byte-verified Runtime-v2 release-like copy;\nits digest is pinned in one owner-local metadata module.\n\n## Evidence and provenance\n\nThe controlled component and co-op executable checks provide no provider-call, release, or deployment\nevidence. The controlled component lane exercises the real MCP process against the attached gateway and\na synthetic downstream; the authorized runtime lane additionally exercised the exact packaged host path.\nDated runtime-v3 campaign/replay records and the separate co-op executable check exercised the real MCP\nprocess with reviewed gateway binaries. The local seam and fake-gateway tests remain deterministic\nbuild/test evidence and cover fixed mappings, copied-artifact identity, and bounded projections.\nDocumentation, policy tooling, and fixtures must be original or carry explicit provenance and\nredistribution rights.\nProprietary game files, saves, credentials, personal paths, and copied implementation source do not\nbelong here.\n\n## Local validation\n\nThe workspace contains the target-owned sts2-mcp-server crate and Rust repo-policy tool. From this\ndirectory run:\n\n```bash\ncargo metadata --locked --no-deps --format-version 1\nfor profile in poc-v1 runtime-v1 runtime-v2 runtime-v3-gameplay runtime-v4-expert runtime-v4-expert-action runtime-v4-expert-rest-action runtime-map-v1 coop-synchronization-v1 coop-receipt-query-v1 seeded-run-v1 coop-native-v1 game-information-query-v1; do\n  (cd \"protocol-artifact/$profile\" && sha256sum -c SHA256SUMS)\ndone\ncargo test --locked --package sts2-mcp-server --test artifact\ncargo test --locked --package sts2-mcp-server --test runtime_v2_artifact --test runtime_v2_mapping\ncargo test --locked --package sts2-mcp-server --test save_profile_mapping\ncargo fmt --all --check\ncargo clippy --workspace --all-targets --all-features --locked -- -D warnings\ncargo test --workspace --all-targets --all-features --locked\ncargo run --locked --package repo-policy -- --strict\n```\n\nThese commands prove local framing/mapping tests and repository policy only. They do not prove a live MCP\ntransport, gateway readiness, host behavior, lifecycle, model behavior, or end-to-end readiness.\n\n## Runtime process profile\n\nThe `sts2-mcp-server` runtime binary reads one bounded newline-delimited JSON-RPC request per stdin\nline and writes one response per stdout line. In its `runtime-v1` profile it exposes exactly\n`get_state` and `submit_action`, maps them to fixed gateway paths, injects the configured bearer and\nlease identity, and projects only allowlisted runtime results. It is a real MCP-to-gateway TCP\nadapter, not an MCP provider and not a direct game client.\n\nThe executable defaults to `runtime-v1`; setting `STS2_RUNTIME_PROFILE=runtime-v2` selects the\nseparate `runtime-v2-mcp` catalog, and any other profile value fails closed. Runtime-v2 exposes\n`get_state`, `submit_action`, and `reconcile_action`: state maps to `GET /v2/instances/{id}/state`,\nsubmission maps to `POST /v2/instances/{id}/action`, and reconciliation maps to\n`GET /v2/instances/{id}/operations/{operation_id}` with no mutation-bearing body. Submission admits\nexactly `end_turn` with a required stable `operation_id`, lease epoch, and expected generation; the\nreconcile call uses that same operation identity without dispatching another mutation. Both profiles\nkeep their existing v1/v2 mapping paths isolated. Runtime-v2 gateway timeout/disconnect uncertainty\nis surfaced as `unknown` with no automatic retry. `accepted` is admission only; MCP reports `settled`\nonly when the downstream result contains a fresh post-action observation and the\n`turn_end_settled` witness. MCP does not infer settlement from an acknowledgement or a state read.\n\nThe fixed `runtime-v1` action is the safe host-visible `show_runtime_probe`, with a fresh effect\nwitness and stable stale-generation rejection. Runtime artifact metadata is checked before\nprojection. Local Rust and mapping tests are confirmed; the authorized host trace confirms the\ngateway/mod path for STS2 v0.107.1 on Windows x86-64. The separate runtime-v3 mapping has been\nused in the recorded Windows/Linux campaign and replay runs; model-played Victory, native\nmultiplayer, and broader compatibility remain `unverified`.\n\nThe additive `seeded-run-v1` profile is selected with `STS2_RUNTIME_PROFILE=seeded-run-v1`. It\nexposes exactly `start_seeded_run` and `reconcile_seeded_run`, mapping to the fixed gateway paths\n`POST /v2/instances/{id}/seeded-run` and bodyless\n`GET /v2/instances/{id}/seeded-operations/{operation_id}`. Start accepts only the bounded standard\nIronclad, ascension-0, no-modifier context with ordered acts, profile baseline, save policy, and\ncompatibility identities; reconciliation uses the original operation identity and never resubmits a\nseed mutation.\n\nThe copied `sts2-protocol/seeded-run-v1` artifact is schema digest\n`5c659f344be78f84e8d783986925d462714f933cac95d18943358992f7d3e2b8`, aligned with protocol main\n`d3ab5fca7d9d74bb31eeb3e5b343d8024ee44404`. Source/component tests cover catalog, fixed mapping,\nidentity/context validation, canonical seed and `run_started` witness projection, unknown outcomes,\nand artifact checksums. They do not prove native host settlement, profile/save isolation, gameplay,\ndeployment, or release support.\n\nThe additive `runtime-v4-expert` profile is selected with `STS2_RUNTIME_PROFILE=runtime-v4-expert`.\nHistorical source/component evidence (2026-09-07) at MCP source head\n`901c9edd94833fca6bfe322e0c515f91c8b2b281`,\nintegrated in merge `5fc337b880b6c38389661c865003e304a02d1136`, binds action and reconcile\nresponses to the request's correlation, instance, gateway session, lease/epoch, and operation\nidentities; dispatch also checks any returned action against the request. Settled responses bind\nnested observation `state_id` and `generation` to the outer response; settled dispatch responses\nalso require `before_generation` to match the dispatch generation. The copied artifacts pin schema\nIDs and digests\n`sts2-runtime-v4-expert` / `0ee034d5da83f34e9fa0ba23038738d56ef8cfccb1c6e752af3ab63d212c8e42` and\n`sts2-runtime-v4-expert-action` / `393318bda8c3522c0ecbacc78b95471a9f4dc3f825169d2048f4c74a7b7f2929`.\nIndependent source/component checks passed; native host legality, settled effects, provider\nexecution, deployment, and release remain `unverified`.\n\nCurrent default-main source/component update (2026-09-10): MCP main\n[`b5a9262f1c76da76ea6f84fca0f1ee821ff67001`](https://github.com/AI-Ascension/sts2-mcp-server/commit/b5a9262f1c76da76ea6f84fca0f1ee821ff67001)\ncontains the Runtime-v4 expert state/action mapping and merged REST expert-action selector recovery.\nThe copied admitted expert artifacts retain the digests above; the separate REST-action artifact\nremains a candidate at digest\n`bb3555fae28eb1f79d08a15e9884696a579e4c20836f5016509f17e0f4c36fbd`. These source/component and\nbounded synthetic checks do not establish native host legality, settled effects, provider execution,\ndeployment, release, or live cross-consumer compatibility.\n\nFor the gateway's coordinator-reported peer agreement, select\n`STS2_RUNTIME_PROFILE=coop-synchronization-v1`. Its only tool is\n`sts2.coop_synchronization`, with explicit `instance_id`, `mcp_session_id`, `lease_id`, and\n`lease_epoch`. It reads the current generation; no generation guess is required. The gateway\nmust have a configured roster and active lease. The MCP credential needs read scope only.\nSee [ADR 0015](docs/decisions/0015-executable-coop-synchronization.md) and\n[executable verification](docs/TESTING.md#co-op-synchronization-verification) for exact scope.\n\nThe synchronization profile returns only the gateway's `gateway_peer_reports` response. Its\nexecutable verification covered missing and partial reports, convergence, disagreement,\ndisconnect/recovery, stale lease fencing, and rejected unknown or regressing reports, with zero\ndownstream game connections. It provides no action, vote, shared-effect, or peer-game authority;\nnative multiplayer observation and actuation remain unverified. See the\n[dated executable evidence](docs/evidence/coop-synchronization-20260906.md).\n\nThe additive `runtime-map-v1` profile selects the six Runtime-v3 gameplay tools plus the read-only\n`sts2.map_snapshot` tool. It maps a bodyless GET to the gateway's fixed map snapshot route, validates\nthe corrected visible-map artifact and generation-bound graph projection, and uses 256 KiB frame,\nresponse, and projected-content limits. Legacy profiles remain unchanged; host map freshness and\nvisualizer rendering remain unverified. See [ADR 0016](docs/decisions/0016-runtime-map-profile.md).\n\nHistorical source/component map update (2026-09-08): MCP main\n`10c4532167fcb91d577ddf3a71cb4759c28bef08` contains the additive\n`runtime-map-v1` profile and copied-artifact consumer. Its producer pin is merged protocol main\n`b3d3034f32e68d70c9e681f906ee37d74db153c4` at schema digest\n`ceab0d2dfc471d1ec36d12edaf4654b8c7fdced06548bf47265e11c63f98115b`. This records\nsource/component and artifact-copy scope; host extraction, live map freshness, visualizer\nvalidation, native map visibility, navigation, gameplay, release, and publication remain\nunverified.\n\nCurrent default-main map source/component update (2026-09-10): MCP main\n[`b5a9262f1c76da76ea6f84fca0f1ee821ff67001`](https://github.com/AI-Ascension/sts2-mcp-server/commit/b5a9262f1c76da76ea6f84fca0f1ee821ff67001)\nretains the additive `runtime-map-v1` profile and copied-artifact consumer, aligned with current\nprotocol main `d3ab5fca7d9d74bb31eeb3e5b343d8024ee44404` at schema digest\n`ceab0d2dfc471d1ec36d12edaf4654b8c7fdced06548bf47265e11c63f98115b`. This is source/component\nand artifact-copy evidence; host extraction, map freshness, visualizer validation, native map\nvisibility, navigation, gameplay, deployment, release, and publication remain unverified.\n\nThe additive `runtime-v4-expert-rest-action` profile is selected with\n`STS2_RUNTIME_PROFILE=runtime-v4-expert-rest-action`. It exposes exactly `sts2.expert_state`,\n`sts2.expert_rest_action`, and `sts2.expert_rest_reconcile`, using fixed routes\n`GET /v4/instances/{id}/expert-state`, `POST /v4/instances/{id}/expert-rest-action`, and\n`GET /v4/instances/{id}/expert-rest-actions/{operation_id}`. The candidate artifact is pinned to\nschema digest `bb3555fae28eb1f79d08a15e9884696a579e4c20836f5016509f17e0f4c36fbd` and contains 16\ngoldens, 22 mutation fixtures, and Smith/Mend producer fixtures. Operation identity and action\nbindings survive accepted, unknown, and transport-failure outcomes; reconciliation uses the same\noperation identity. Selector admission allows 128 active or pending entries, rejects the 129th before\nforwarding, and reclaims terminal entries. Per-operation admission and terminal state lets a late\nprogress receipt remain valid after selector-key eviction without reactivating a completed selector.\nHTTP 404/408/502/504 are `unknown` and 499 is `cancelled`; structured 503 handling remains\ngateway-owned. These are source/component and synthetic contract claims; native host legality,\nprovider execution, deployment, and release remain unverified.\n\nThe additive `coop-receipt-query-v1` profile is selected with\n`STS2_RUNTIME_PROFILE=coop-receipt-query-v1`. Its only tool is `sts2.coop_receipt_query`, mapped to\n`POST /v1/instances/{id}/coop/receipt-query`. The proposed-unadmitted artifact pins schema digest\n`3e3eaedb93926b26025abb09d8028491e2632896753688c1182c698fed7d3f7c`, uses canonical compact\nordered UTF-8 bytes, and keeps the request/response body within 16 KiB. It performs a retained\nreceipt lookup only and does not observe, reconcile, retry, or mutate. The artifact has no admitted\nconsumers; native producer, host, provider, deployment, and release compatibility remain unverified.\n"}