[codex] Endpoint audit fixes

[CompleteDotTech]

Summary

Adds endpoint audit fixes and Compendium/Glossary clarifications on top of the upstream sync work.

Changes

• Adds MCP wrappers for read-only HTTP metadata endpoints: settings, bestiary, glossary card/relic/potion/keyword metadata, profile, compendium, profiles, and API index.
• Shapes GET / as a structured API index with status, kind: api_index, version, endpoint_count, bound prefixes, and the advertised endpoint list.
• Adds live API-index schema audits for semantic version, STS2 MCP message, bound-prefix URL shape, endpoint row method/path/description types, and duplicate advertised routes.
• Updates root endpoint descriptions so the API index advertises state response envelopes, active-run context, normalized save context, and glossary profile/save/run context.
• Clarifies the distinction between profile-scoped Compendium data and active-run Glossary data.
• Scopes Glossary responses to the active run/character plus shared run pools, including all shared card pools, shared relics, and shared potions.
• Shapes /api/v1/settings as a null-safe structured object with status, kind, display, audio, gameplay, mod, language, and skip-intro fields.
• Shapes /api/v1/profile and /api/v1/compendium with explicit status/kind envelopes while preserving their profile/save/current-run context.
• Sorts profile and Compendium metadata arrays deterministically, including discovered IDs, stats, achievements, epochs, and nested by-character fight stats.
• Shapes /api/v1/profiles as a structured profile-slot object with status, kind, count, and per-slot profile_id, save paths, profile root, save scope, and data-presence fields.
• Adds live profile-slot schema audits for exactly three slots, current-profile consistency, flag/value types, alias path equality, normalized path fields, and profile root suffixes.
• Returns non-2xx structured HTTP errors for profile action conflicts and invalid requests, including invalid profile IDs, unknown profile actions, active-profile delete attempts, and switch-during-run conflicts.
• Adds live audit coverage that active runs reject profile switch requests with HTTP 409 run_in_progress without changing profile state.
• Adds stable error_code values for POST validation failures such as invalid JSON, missing or non-string actions, missing/non-integer profile IDs, and action payload parsing failures.
• Adds stable route-level error_code values for unsupported methods, unknown paths, and top-level internal handler failures.
• Rejects unsupported singleplayer/multiplayer HTTP methods before run-mode guards, so invalid methods consistently return HTTP 405 method_not_allowed regardless of current game mode.
• Extends the live endpoint audit to verify unsupported PUT requests return HTTP 405 method_not_allowed for every advertised endpoint plus /.
• Rejects unsupported singleplayer/multiplayer HTTP methods before run-mode guards, so invalid methods consistently return HTTP 405 method_not_allowed regardless of current game mode.
• Returns non-2xx structured errors for read endpoint startup/data availability failures, including unavailable save manager, settings data, and profile data cases.
• Adds stable endpoint-specific error_code values for read endpoint exception paths such as settings, profile, compendium, state, glossary, and bestiary build/read failures.
• Returns non-2xx structured HTTP errors for top-level menu/gameplay action dispatch failures such as missing or unknown main-menu options, missing gameplay payload fields, no active run, unknown action, blocking popup overlays, and local-player lookup failure.
• Adds live safe gameplay validation audits for missing play_card.card_index, use_potion.slot, and discard_potion.slot payloads without mutating the run.
• Adds timeline_manual_action_required for Timeline manual-reveal blocks so that menu automation errors remain branchable and return HTTP 409.
• Adds a stable action_error fallback error_code for older generic action failures that previously returned structured error JSON without an error code.
• Ensures failed action results no longer fall through as HTTP 200 error JSON; uncoded failed actions now default to HTTP 400 while coded conflicts keep their specific status.
• Preserves structured non-2xx endpoint error payloads through MCP wrappers by adding http_status instead of flattening HTTPStatusError responses to a text prefix.
• Adds focused MCP bridge tests for structured endpoint error propagation, multiplayer menu_select retry behavior, and profile switch/delete wrappers.
• Adds static MCP route-helper parity checks so mp_ tools cannot regress to singleplayer route helpers, and non-MP tools cannot accidentally call multiplayer helpers.
• Clarifies action docs so generic action errors show error_code: action_error and enemy-targeting card/potion actions document both entity_id and combat ID string targets.
• Clarifies the endpoint error contract so docs no longer imply error_code is optional for action/read/route/validation failures.
• Documents and audits glossary run_state_unavailable HTTP 503 errors alongside no-run HTTP 409 errors, both retaining profile/save context.
• Validates state endpoint format query values so unsupported formats return HTTP 400 with error_code: invalid_format instead of silently falling back to JSON.
• Shapes /api/v1/singleplayer and /api/v1/multiplayer JSON state responses with status: ok and kind (singleplayer_state or multiplayer_state) envelopes while preserving existing state_type and screen-specific data.
• Shapes /api/v1/bestiary as a deterministic metadata object with status, kind, monster_count, encounter_count, sorted monsters, and sorted encounters.
• Adds current-run context to Glossary, Compendium, singleplayer state, and multiplayer state payloads, including run_id, seed, profile_id, progress_path, resolved_progress_path, profile_root, save_scope, net_type, and player roster details where applicable.
• Adds shared live current-run schema audits for profile/save identity, normalized paths, id format, optional save-backed run fields, run ID prefix, and start-time/run-id consistency across profile, compendium, glossary, and state payloads.
• Clarifies that current_run always carries active profile/save identity while run_id and seed are present when current_run.save exposes them, and relaxes live audit accordingly.
• Aligns MCP glossary tool docstrings with the same save-backed current-run identity contract and audits that wording.
• Hardens glossary keyword collection against null or unstable hover-tip sources so transient model state skips bad tips instead of failing the endpoint.
• Refreshes the top-level README API-index example so it matches the current 14-endpoint root response and audits that example.
• Sorts nested Bestiary metadata lists such as monster moves and likely encounter monsters, with static and live audit checks for deterministic nested ordering.
• Adds a focused MCP bridge test proving read-only endpoint tools preserve structured non-2xx endpoint errors with http_status.
• Sorts glossary card, relic, and potion item payloads by ID, and audits live glossary item ordering by ID/name.
• Updates the common state-response current_run example so it shows full profile/save context and save-backed run identity availability.
• Stabilizes glossary keyword ordering with ordinal comparison and first-seen duplicate handling, with static audit coverage.
• Handles missing RunManager.Instance in glossary endpoints as run_not_in_progress instead of allowing startup/teardown 500s.
• Extends live path-normalization audit coverage to legacy profile-slot path and resolved_path fields.
• Expands static and live settings audits to cover nested display, audio, gameplay, and mod fields, including value type/range checks for display, audio, gameplay, language, skip-intro, and mod-loading fields.
• Extends docs audit coverage so raw and MCP docs cannot reintroduce backslash-style profile save paths in JSON examples.
• Adds static and live glossary item schema audits for card, relic, potion, and keyword payloads, including non-empty value/type checks for names, descriptions, IDs, rarity/pool strings, keyword entries, card costs/upgrade fields, and potion target/usage strings.
• Adds live Bestiary entry schema audits for reflected monster HP ranges, encounter room/reward fields, weak flags, source metadata, and nested metadata ordering.
• Adds static and live Compendium run_history section audits, including section shape, entry container type, file-history source/path metadata, entry count consistency, run ID prefix, run file metadata, optional parsed run fields, acts list shape, and player summary counts.
• Adds live profile stats schema audits for character, card, encounter, enemy, ancient, achievement, epoch, global-total, and nested by-character entries, including non-empty ID/state strings and integer counter/timestamp fields.
• Adds live Compendium section contract audits for Card Library, Relic Collection, Potion Lab, Bestiary, Character Stats global totals, and nested fight-stat entries.
• Adds profile/save/current-run context to /api/v1/profile so profile, compendium, glossary, and state endpoints agree on active profile/run identity.
• Adds resolved_progress_path beside progress_path on /api/v1/profile, /api/v1/compendium, and successful /api/v1/glossary/* responses so clients get the absolute local save file path.
• Normalizes exposed save/path context fields with forward slashes, including Windows absolute paths and Compendium run-history paths, while preserving raw paths for internal file lookup.
• Adds matching profile/save context to /api/v1/compendium, including progress_path, profile_root, and save_scope at the top level.
• Adds matching profile/save context to successful /api/v1/glossary/* responses, including profile_id, progress_path, profile_root, and save_scope.
• Adds the same profile/save context to glossary run_not_in_progress errors, and guards net-type lookup so main-menu glossary calls return HTTP 409 instead of 500.
• Updates the HTTP root index and MCP tool docs so profile/compendium advertise their save/run context fields.
• Uses the local mutable event model for event state text so multi-step event body/title data does not fall back to stale canonical text.
• Adds card upgrade metadata to /api/v1/glossary/cards: energy/star costs, upgraded flag, upgradeability, current/max upgrade level, upgraded-preview cost/star cost, and upgraded-preview description.
• Adds live audit coverage that every upgradable card in the active glossary has a non-empty upgraded-preview description, preview cost, and valid current/max upgrade levels.
• Adds the same card upgrade metadata to shared state card serialization, so hand/deck/pile/reward/card-selection/bundle payloads expose upgraded previews consistently.
• Adds requires_target and valid_targets to hand card state for enemy-targeted cards, matching potion target metadata and play-card action requirements.
• Adds prefixed upgrade-preview metadata to shop card items and includes concise upgrade previews in shop markdown.
• Aligns UI-gated state payloads with actual action availability for card selection, hand selection, card rewards, event options, rest options, relic selection, bundle selection, shop/fake merchant purchases, treasure relic claims, Crystal Sphere choices, rewards, map travel, combat/multiplayer end turn, potion use/discard, and enemy targeting.
• Adds live audit coverage for combat state payloads, including battle enemy targetability, hand card targets, draw/discard/exhaust pile schemas and counts, and potion readiness/target metadata.
• Hardens card-grid, choose-card, in-combat hand-selection, and bundle-selection actions so hidden or disabled mounted UI nodes cannot be clicked through stale indexes.
• Gates rewards/rest/shop/fake-merchant/treasure proceed state and actions on visible enabled controls, while preserving the close-inventory-then-proceed behavior for shop screens.
• Keeps /api/v1/bestiary available as model metadata while /api/v1/compendium carries profile encounter/enemy progress where available.
• Updates menu_select in the MCP server to retry through /api/v1/multiplayer when the singleplayer route correctly rejects calls during an active multiplayer run.
• Expands draw/discard/exhaust pile card state to include the same core card fields as hand cards: id, type, rarity, is_upgraded, keywords, and index.
• Hardens save discovery so fallback lookup tries every Steam account root instead of dropping multi-account installs.
• Tightens /api/v1/profiles validation so switch/delete requests missing profile_id return HTTP 400.
• Adds static/live audit guards for endpoint docs, route/index/doc endpoint parity, MCP tool coverage, API index shape/counts/version/response-context descriptions, structured errors, POST validation error codes, route-level error codes, read endpoint availability error codes, read endpoint failure error codes, MCP structured error propagation, MCP route-helper parity, settings shape/startup guard, state format validation, state response envelopes, normalized save/path context, menu/action dispatch HTTP errors, blocking-popup action errors, timeline manual-action error codes, generic action fallback error codes, action target/error docs, endpoint error-code contract wording, uncoded failed-action HTTP errors, profile/compendium envelopes and ordering, profiles shape/save context, profile action HTTP errors, bestiary shape/order/counts, glossary scope, glossary profile context, glossary error context, glossary run-state error docs, resolved progress paths, enriched current-run context, card upgrade metadata, upgraded clone preview paths, shop card upgrade metadata, hand-card target metadata, current-run state context, profile/compendium context, profile/compendium endpoint discovery text, mutable event state text, action-readiness state fields, visible/selectable selection guards, visible proceed guards, profile POST validation, save-root fallback behavior, and documented state surfaces.

Validation

• python3 -m py_compile scripts/audit_endpoints.py scripts/test_mcp_server.py mcp/server.py
• python3 scripts/audit_endpoints.py --skip-live
• uv run --project mcp python scripts/test_mcp_server.py
• python3 scripts/audit_endpoints.py --base-url http://127.0.0.1:15526
• Focused uv run --project mcp python helper test confirmed _handle_error preserves a structured HTTP 409 endpoint error and adds http_status.
• dotnet build STS2_MCP.csproj -c Release -o out/STS2_MCP -p:STS2GameDir="C:\\Program Files (x86)\\Steam\\steamapps\\common\\Slay the Spire 2"
• 58edc32 state-envelope, aa3454a/1698771 path-normalization, 6f80057 API-index descriptions, 5200398 blocking-popup action errors, 71f9dde POST validation error codes, 2e87f86 route-level error codes, 715076b read availability errors, 37c3735 read failure error codes, 5e87785 fallback action error codes, 04f9933 static endpoint manifest parity, a7a8d76 MCP bridge tests, 88885f2 action target/error docs, 09dc7e3 Timeline manual-action errors, 38c6242 endpoint error-code contract docs, 43e6a54 glossary run-state error docs, and 359e846 MCP route-helper parity, and 418b8a7 current-run identity availability, and 01df37b MCP glossary run identity docs, and 2792596 glossary keyword tip hardening, and 2006023 README API-index example coverage, and e7082cb bestiary nested metadata ordering, and 14f6e0f MCP read endpoint error propagation, and df6ba7a glossary item ordering, and 3f28b32 current-run state example docs, and 1b136aa glossary keyword ordering, and ba3bd17 missing RunManager glossary guards, and be1fcde legacy profile path normalization audit, and 3fd3eaf nested settings schema audit, and b5bcd88 docs normalized save-path audit, and f5fdd2d glossary item schema audits, and 56a3640 Compendium run-history section audit, and 2165561 profile stats schema audit, and 82855b2 MCP profile action wrapper tests, and 6ad50db method-before-run-mode route guard coverage, and c4157f6 unsupported-method live audit coverage, and 8dfd275 profile/Compendium schema audit coverage, and 8400282 card upgrade preview audit coverage, and d7a16a7 live combat state payload audit coverage, and 363681e active-run profile switch guard coverage, and a1be21d multiplayer route guard audit coverage, and 1a53acf Bestiary entry schema audit coverage, and e1d2ae5 settings value schema audit coverage, and 13ec7bb glossary value schema audit coverage, and a4f296f profile slot schema audit coverage, and 71f0e68 API-index schema audit coverage, and 3f1eb62 safe gameplay validation audit coverage, and d68eb77 current-run context schema audit coverage, and e51d4a5 profile value schema audit coverage, and 625d9a3 Compendium run-history schema audit coverage are covered by static audit, MCP bridge tests, and dotnet build; live verification requires restarting the game because the running process currently locks mods/STS2_MCP.dll; the latest install attempts through ba3bd17 still failed with permission denied; a live audit against the currently loaded DLL still reports the old backslash progress_path behavior on /api/v1/profile.
• Installed the built DLL into the local Slay the Spire 2 mods directory and restarted the game.
• Live-verified failed action responses use non-2xx status in combat/current-run state as well as menu state.
• Adds live audit coverage for multiplayer route guards: outside multiplayer, GET and safe malformed POST requests to /api/v1/multiplayer return structured not_multiplayer_run; inside multiplayer, malformed POST requests must remain structured validation errors.
• Live-verified GET / returns status: ok, kind: api_index, version: 0.4.0, endpoint_count: 14, and 14 advertised endpoints.
• Live-verified /api/v1/singleplayer returns HTTP 400 with missing_menu_option and unknown_menu_option for invalid main-menu menu_select calls.
• Live-verified /api/v1/singleplayer returns HTTP 409 with error_code: run_not_in_progress for a non-menu gameplay action posted with no active run.
• Live-verified /api/v1/singleplayer?format=xml returns HTTP 400 with error_code: invalid_format, while format=json and format=markdown still work.
• Live-verified /api/v1/settings returns status: ok, kind: settings, and display/audio/gameplay/mods/language fields.
• Live-verified /api/v1/profile returns status: ok, kind: profile, profile/save/current-run context, and sorted metadata arrays.
• Live-verified /api/v1/compendium returns status: ok, kind: compendium, profile/save/current-run context, and sorted metadata arrays.
• Live-verified /api/v1/profiles returns status: ok, kind: profiles, count: 3, and per-slot profile/save context fields.
• Live-verified /api/v1/profiles returns HTTP 400 invalid_profile_id, HTTP 400 unknown_profile_action, and HTTP 409 active_profile_delete for safe validation cases.
• Live-verified /api/v1/bestiary returns status: ok, kind: bestiary, monster_count: 126, encounter_count: 95, and deterministic ID ordering.
• Live-verified main-menu /api/v1/glossary/cards, /api/v1/glossary/relics, /api/v1/glossary/potions, and /api/v1/glossary/keywords return HTTP 409 with run_not_in_progress plus profile/save context instead of 500.
• Resumed the existing run with menu_select: continue to verify glossary success responses in combat.
• Live-tested the read-only endpoints during an active run, during combat, and during rewards/card-reward/shop transitions.
• Live-verified /api/v1/profile and /api/v1/compendium return resolved_progress_path with the absolute local progress save path.
• Live-verified current_run in /api/v1/singleplayer?format=json and /api/v1/glossary/cards includes profile_id, progress_path, resolved_progress_path, profile_root, save_scope, run_id, and seed.
• Live-verified /api/v1/compendium now returns profile_id, progress_path, profile_root, save_scope, and current_run at the top level.
• Live-verified the root endpoint advertises profile/compendium save/run context.
• Live-verified /api/v1/glossary/cards, /api/v1/glossary/relics, /api/v1/glossary/potions, and /api/v1/glossary/keywords now return profile_id, progress_path, resolved_progress_path, profile_root, save_scope, and current_run at the top level.
• Live-verified /api/v1/glossary/cards returns 225 active-run cards with shared pools and upgraded preview metadata.
• Live-verified Strike in both deck state and glossary reports upgraded preview description Deal 9 damage..
• Live-verified card reward state reports upgraded preview metadata, including Armaments previewing Upgrade ALL cards in your Hand..
• Live-verified shop card JSON and markdown expose upgraded-preview metadata, including Anger previewing Deal 8 damage....
• Live-verified shop proceed can leave while inventory is open; state now advertises that via inventory_open, can_close_inventory, and can_proceed.
• Live-verified /api/v1/glossary/relics, /api/v1/glossary/potions, and /api/v1/glossary/keywords return active-run scoped payloads during combat/rewards/shop.
• Live endpoint audit passed against the running game after reinstalling the rebuilt DLL.
• Live-verified unsupported PUT requests to every advertised endpoint plus / return HTTP 405 with error_code: method_not_allowed.

[CompleteDotTech]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[CompleteDotTech]

@codex review

[gemini-code-assist]

Code Review

This pull request introduces several new API endpoints and corresponding MCP tools for accessing game settings, bestiary metadata, and active-run glossary information including cards, relics, potions, and keywords. The menu_select tool has also been updated to automatically retry actions through the multiplayer route when a 409 conflict indicates an active multiplayer run. Feedback suggests improving the robustness of the 409 condition check, which currently relies on a specific string match, and refining the retry logic to avoid nested try-except blocks for better error reporting.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep it up!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[CompleteDotTech]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 👍

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[CompleteDotTech]

@codex review

[CompleteDotTech]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Hooray!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[CompleteDotTech]

@codex review

[CompleteDotTech]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Hooray!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[CompleteDotTech]

@codex review

[CompleteDotTech]

@codex review

[CompleteDotTech]

@codex review

[CompleteDotTech]

@codex review