SagaSmith CoC MCP

中文 · English · Platform Overview

SagaSmithAI's local authoritative MCP service for Call of Cthulhu 7e. It integrates campaign persistence, branch memory, character knowledge, snapshots, module retrieval, and unified Content Pack from sagasmith-core with the d100, sanity, combat, chase, and replayable random streams from sagasmith-coc into a native MCP boundary.

Runtime Boundaries

• MCP is responsible for authoritative campaign state, permissions, revision, idempotency, random stream receipts, and atomic commits of random determinations.

• Each MCP session independently maintains native tool exposure; Lobby, Play, and Combat policies are re-validated at call time.

• The Host must respond to tools/list_changed and refresh the native schema; there is no fixed tool set, text simulation, or exposure_call fallback.

• The Agent is responsible for interpreting sources and making module-specific semantic decisions; the final Pack retains source evidence for these decisions.

Native capability loading flow:

exposure(open) -> exposure(search) -> exposure(set) -> native domain tool

The Keeper recovery interface consists of branch_query/change, snapshot_query/change, and state_revision. All write operations require an explicit revision/branch or history cursor guard and an idempotency_key; checkout, restore, undo, and redo trigger tools/list_changed after changing the authoritative stage. After the Host refreshes the list, it can reload and directly call the legal native tools for that stage.

Snapshot remains a fully independently restorable state document in the public protocol; the underlying schema v8 only compresses each document independently into a zlib-1 record and validates the compressed bytes, document checksum, and node identity. snapshot_query/change, branch checkout, undo/redo, and restart recovery do not depend on ancestor chain replay.

On startup, the service runs Core Alembic migrations and requires the database to conform to the current Snapshot schema v8. Before deployment, back up data/ttrpgbase.db after the service is stopped and the SQLite WAL has been checkpointed; external databases use their native consistent backup. The current format cannot be downgraded; rollback must restore the database, Core, CoC, and MCP to a matching set of versions.

The Play and Combat phases provide two explicitly sourced character state settlements:

• coc_sanity_check atomically completes the SAN roll, loss dice, necessary INT roll, temporary/indefinite/permanent insanity, manic episode, and duration, and commits the campaign random stream and investigator sheet in the same revision group.

• coc_hp_change atomically completes damage or healing; a single major wound uses the authoritative random stream to perform the necessary CON roll, and persists major wound, unconscious, dying, dead, and healing states. Pure HP changes without random draws do not fabricate a campaign revision.

Both tools require character control permission, campaign/character revision, and an idempotency key; exact retries return the original response and cannot re-draw or re-settle.

Authoritative combat uses task-based native tools rather than letting the caller directly modify campaign.state:

combat_start -> combat_query
             -> combat_action(move|join|end_turn)
             -> combat_attack(open -> resolve|abort)
             -> combat_end

combat_start validates the participant character revisions and enters Combat with DEX, DEX+50 for readied firearms, and a stable tie-breaking order. Attacks are persisted as pending response choices first; the target controller then chooses to dodge, counterattack, dive for cover, or not respond. resolve settles attacks, defenses, extreme/impaling damage, ammunition, CON, HP, and wounds from the campaign random stream, and writes the campaign and affected characters into the same revision group. In Grid mode, the engine stores coordinates and validates movement/melee distances; Agent mode does not generate coordinates and only accepts spatial facts explicitly provided by the Agent. combat_end returns to Play and lists any characters still needing near-death recovery processing.

Real stdio host regression has covered Lobby → Play → Combat → Play: after each phase change, the Host refreshes the native list, old phase tools disappear immediately, and new phase tools can be loaded and called directly.

Chases are managed within Play by chase_start/query/action/end and are strictly mutually exclusive with Combat. When a chase begins, the MCP reads the explicitly specified CON, Drive Auto, or Pack skill from the character sheet, uses the campaign random stream to settle the speed roll, and then calculates action points per round from the slowest effective MOV. chase_action authoritatively maintains DEX order, action point expenditure, route position, obstacle rolls, and round resets; the position changes and provenance for obstacle success/failure must be explicitly provided by the Pack or Agent, and the MCP does not guess narrative terrain. Players can only operate authorized characters; starting/ending a chase is open only to the Keeper. All random and state changes carry a revision and an exact-idempotency receipt.

Investigation continuity uses three ledgers separated from one another, and narrative cannot automatically be treated as fact known to all characters:

• campaign_event writes to the timeline within the branch, must explicitly give a dm, party, public, or actor audience, and can mark speaker/listener/witness/target participants.

• continuity_context returns branch context constrained by a unified character budget. Non-Keeper calls always enforce a player projection and can only read the private knowledge of their authorized characters.

• memory_change(action="commit") atomically settles an event, objective fact revisions, per-character knowledge revisions, and an optional snapshot; derived facts and knowledge reference the same source event by default. Exact retries return the original response, and any sub-item failure rolls back the whole operation.

Objective memory_query and all continuity writes are open only to the Keeper; players cannot use the objective-fact ledger to bypass clues, secrets, false beliefs, or party boundaries. Safe continuity reads are retained during Combat, but timeline and memory writes are disabled and restored after returning to Play; real stdio regression verifies that these native tools appear and disappear correctly with the phase schema.

Source-explicit investigation checks use investigation_check(open|spend_luck|push|settle|abort) and investigation_query. The MCP reads the exact named skill, trait, or Luck from the character sheet, rolls using the campaign random stream, and persists incomplete human choices. Spending Luck must be explicitly enabled by the campaign settings; the exact expense and character revision are settled atomically. A pushed roll must provide a new approach and a Keeper-announced failure consequence; no Luck may be spent after the second roll. Pending choices survive restarts and block entering Combat, Chase, or returning to Lobby until settled or aborted by the Keeper; successful skills are marked only once and left for post-session growth.

Checks do not guess clue meaning or audience. settle returns a mechanical receipt, and the Agent then records source-specific narrative, objective facts, per-character knowledge, and pushed-roll failure consequences through memory_change(action="commit"). Obvious or indispensable clues bypass checks entirely and are settled directly through continuity, so a module cannot be blocked by a streak of bad rolls.

Combined checks reuse the same recoverable flow, but a single d100 is simultaneously compared against two to eight skills or traits read from the character sheet. The Keeper must explicitly choose requirement="any" or "all"; spending Luck can only purchase this aggregate requirement exactly, and each successful skill component receives its own growth mark. CoC does not invent D&D-style "majority success" group rules. True group Luck reads the current Luck of all participants present via group_luck_query/check, and only the investigator with the lowest Luck is allowed to represent the group; when the lowest value is tied, the Keeper must explicitly choose.

Post-session growth is available only in Lobby. development_query lists the checked skills, and development_settle completes all growth dice, skill updates, first-time mastery SAN rewards, clearing of check marks, and an audit receipt in one campaign-random-stream transaction; Cthulhu Mythos is explicitly marked as ineligible for ordinary growth and erroneous check marks are cleared. The write boundary simultaneously validates character control, campaign/character revision, branch, and idempotent replay.

Related MCP server: foundry-cli

Module Pack Creation Workflow

CoC modules use the unified sagasmith.content-package schema v2:

module_draft(start)
  -> module_draft(edit, operation="advance")  # 仅在首遍中断时恢复
  -> module_draft(evidence)
  -> module_draft(edit, operation="statblock|content|asset|actor")
  -> module_draft(edit, operation="package")
  -> module_draft(finalize)
  -> content_pack(import)
  -> content_pack(activate)
  -> content_pack(deactivate|remove)

start accepts a PDF, Markdown, or text source_path from the import whitelist, or a name plus content for generated content. Mechanical import produces only inactive drafts; if the process is interrupted after a committed intermediate step, advance continues from that step. evidence provides bounded text blocks, managed PDF page rendering receipts, assets, and content review; edit supports checksum-bound PDF text revisions, CoC content review, validation against the current CoC statblock schema, whitelisted assets, actor bindings, and Pack decisions. A statblock may retain real but incomplete non-combat NPC data from the source; combat-required fields are enforced only when combat_ready is explicitly declared. Modifying source text creates a new inactive mechanical version and invalidates downstream draft decisions. Play configuration and catalog decisions must reference the as-is source receipts returned by evidence. Finalization requires explicit Agent confirmation and produces a .sagasmith-pack that cannot be silently modified; only modules re-imported from that final archive can be activated.

Commercial rulebooks and modules always remain local. Use SAGASMITH_COC_MCP_MODULE_IMPORT_ROOTS to configure the source roots allowed for reading; multiple paths use the system path separator. The repository does not distribute original books, extracted text, or original book assets.

Pack import uses a deterministic recovery protocol: the Pack checksum belongs to the candidate version identity, and each step—module, asset, content review, actor, and binding—converges by content identity or sub-idempotency key. If the process is interrupted before the final receipt, retrying with the original request and idempotency_key simply continues and cannot produce duplicate runtime objects. Activation, deactivation, and deletion each commit precise receipts; the same request after deletion can still replay the original response.

Startup

pip install -e "../sagasmith-core[documents]"
pip install -e ../sagasmith-coc
pip install -e .
sagasmith-coc-mcp

The unified local stack uses a streamable HTTP authoritative service with a sticky-session Workbench gateway:

$env:SAGASMITH_COC_MCP_TRANSPORT = "streamable-http"
$env:SAGASMITH_COC_MCP_HTTP_PORT = "8769"
sagasmith-coc-mcp

# 另一个终端
$env:SAGASMITH_COC_MCP_URL = "http://127.0.0.1:8769/mcp"
$env:SAGASMITH_COC_GATEWAY_PORT = "8768"
sagasmith-coc-gateway

Browsers cannot submit a principal. The Gateway binds identity server-side, preserves a separate MCP session for each browser/campaign, and refreshes the real native tool list after tools/list_changed.

The state is located in .sagasmith-coc-mcp/ by default. Main configuration items:

• SAGASMITH_COC_MCP_HOME

• SAGASMITH_COC_MCP_MODULE_IMPORT_ROOTS

• SAGASMITH_COC_SKILLS_DIR

• SAGASMITH_MODULEGEN_SKILLS_DIR

• SAGASMITH_COC_MCP_BOUND_PRINCIPAL_ID

Development

pip install -e ".[dev]"
pytest
ruff check .

Original code is licensed under Apache-2.0. The rights to Call of Cthulhu and related commercial content belong to their respective owners.