SagaSmith CoC MCP

中国語 · English · プラットフォーム概要

SagaSmithAI の Call of Cthulhu 7e ローカル権威 MCP サービス。sagasmith-core のキャンペーン永続化、ブランチ記憶、キャラクター知識、スナップショット、モジュール検索、統一 Content Pack を、sagasmith-coc の d100、正気度、戦闘、追跡、リプレイ可能なランダムストリームと統合して、ネイティブ MCP 境界とする。

実行時境界

• MCP は、権威キャンペーン状態、権限、revision、冪等性、ランダムストリームレシート、ランダム判定のアトミックコミットを担当する。

• 各 MCP セッションはネイティブツール公開を独立して維持する。Lobby、Play、Combat の各フェーズは呼び出し時にも再検証される。

• Host は tools/list_changed に応答し、ネイティブスキーマを更新しなければならない。固定ツール全集、テキストシミュレーション、exposure_call フォールバックはない。

• Agent は出典の解釈とモジュール固有の意味的決定を行う責任を負う。最終 Pack はこれらの決定の出典証拠を保持する。

ネイティブ機能のロードフロー：

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

Keeper 復元インターフェースは branch_query/change、snapshot_query/change、state_revision で構成される。すべての書き込み操作は、明示的な revision/ブランチまたは履歴カーソルガードと idempotency_key を要求する。checkout、restore、undo、redo が権威フェーズを変更すると tools/list_changed がトリガーされる。Host がリストを更新した後、そのフェーズの正当なネイティブツールを再ロードして直接呼び出すことができる。

Snapshot は公開プロトコルにおいて、独立して復元可能な完全な状態ドキュメントのままである。基盤の schema v8 は各ドキュメントを独立に zlib-1 レコードに圧縮し、圧縮バイト、ドキュメント checksum、ノード ID を検証する。snapshot_query/change、branch checkout、undo/redo、再起動時の復元は祖先チェーンのリプレイに依存しない。

サービス起動時に Core Alembic マイグレーションが実行され、データベースが現在の Snapshot schema v8 に準拠していることが要求される。デプロイ前には、サービスを停止し SQLite WAL が収束した後に data/ttrpgbase.db をバックアップしなければならない。外部データベースはそのネイティブな整合性バックアップを使用する。現在のフォーマットはダウングレード不可。ロールバックするには、データベース、Core、CoC、MCP を一致したバージョンセットに復元する必要がある。

Play と Combat フェーズでは、出典が明確な2つのキャラクター状態解決を提供する：

• coc_sanity_check は SAN 判定、喪失ダイス、必要な INT 判定、一時的/不定期/永続的狂気、狂乱発作と持続時間をアトミックに完了し、同じ revision group でキャンペーンランダムストリームと探索者シートをコミットする。

• coc_hp_change はダメージまたは治療をアトミックに完了する。単一の重傷は権威ランダムストリームを使用して必要な CON 判定を実行し、major wound、unconscious、dying、dead、治療状態を永続化する。ランダム抽出のない純粋な HP 変更はキャンペーン revision を偽造しない。

両ツールはキャラクター制御権限、campaign/character revision、冪等キーを要求する。正確なリトライは元のレスポンスを返し、抽出自体や解決を重複させない。

権威戦闘は、呼び出し側が campaign.state を直接書き換えるのではなく、タスク型ネイティブツールを使用する：

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

combat_start は参加者のキャラクター revision を検証し、DEX、準備済み銃器の DEX+50、安定した同値順序で Combat に入る。攻撃はまず応答待ちの選択を永続化する。目標のコントローラーは、回避、反撃、身を伏せて遮蔽を取る、または応答しない、を選択する。resolve はキャンペーンランダムストリームから攻撃、防御、極難/貫通ダメージ、弾薬、CON、HP、負傷を解決し、キャンペーンと影響を受けたキャラクターを同じ revision group に書き込む。Grid モードではエンジンが座標を保存し、移動/近接距離を検証する。Agent モードでは座標を生成せず、Agent が明示的に与えた空間的事実のみを受け入れる。combat_end は Play に戻し、瀕死回復処理が必要なキャラクターをリストする。

実際の stdio ホスト回帰テストは Lobby → Play → Combat → Play をカバーしている。各フェーズ変更後、Host がネイティブリストを更新し、旧フェーズのツールは即座に消え、新フェーズのツールは直接ロードして呼び出すことができる。

追跡は Play 内で chase_start/query/action/end によって管理され、Combat と厳密に排他される。追跡開始時、MCP はキャラクターシートから明示的に指定された CON、Drive Auto、または Pack スキルを読み取り、キャンペーンランダムストリームでスピード判定を解決し、最も遅い有効 MOV に基づいて毎ラウンドのアクションポイントを計算する。chase_action は DEX 順序、アクションポイント消費、ルート位置、障害判定、ラウンドリセットを権威的に維持する。障害の成功/失敗に対応する位置変化と出典は Pack または Agent が明示的に提供しなければならず、MCP は物語上の地形を推測しない。プレイヤーは許可されたキャラクターのみ操作でき、追跡の開始/終了は Keeper のみに開放される。すべてのランダムと状態変更には revision と正確な冪等レシートがある。

調査の連続性は、互いに分離された3種類の台帳を使用し、ナラティブを自動的に全キャラクターが知っている事実として扱うことはできない：

• campaign_event はブランチ内のタイムラインに書き込み、dm、party、public、actor のいずれかのオーディエンスを明示的に指定しなければならない。speaker/listener/witness/target の参加者をマークすることもできる。

• continuity_context は統一された文字予算の制約を受けるブランチコンテキストを返す。非 Keeper 呼び出しは常にプレイヤープロジェクションを強制され、自分が許可されたキャラクターのプライベート知識のみを読むことができる。

• memory_change(action="commit") は、1つのイベント、客観的事実の改訂、キャラクターごとの知識改訂、オプションのスナップショットをアトミックに解決する。派生事実と知識はデフォルトで同じ出典イベントを参照する。正確なリトライは元のレスポンスを返し、いずれかの子項目が失敗すると全体がロールバックする。

客観的な memory_query とすべての連続性書き込みは Keeper のみに開放される。プレイヤーは客観的事実台帳を使って、手がかり、秘密、誤った信念、分隊境界を迂回できない。Combat 中は安全な連続性読み取りが保持されるが、タイムラインと記憶への書き込みは無効になり、Play に戻ると再開される。実際の stdio 回帰テストは、これらのネイティブツールがフェーズスキーマに従って正しく出現・消滅することを検証する。

出典が明確な調査判定は、investigation_check(open|spend_luck|push|settle|abort) と investigation_query を使用する。MCP はキャラクターシートから正確に命名されたスキル、特徴、または Luck を読み取り、キャンペーンランダムストリームでダイスを振り、未完了の人間の選択を永続化する。Spending Luck はキャンペーン設定で明示的に有効化されなければならない。正確な消費とキャラクター revision はアトミックに解決される。プッシュは新しい行動方法と Keeper が予告する失敗の代償を与えなければならず、2回目のダイスロール後に Luck を使うことはできない。保留中の選択は再起動をまたいで復元でき、解決されるか Keeper が中止するまで Combat、Chase への進入や Lobby への復帰をブロックする。成功したスキルは1回だけマークされ、セッション後の成長に残される。

判定は手がかりの意味やオーディエンスを推測しない。settle は機械的なレシートを返し、その後 Agent が memory_change(action="commit") を通じて、出典固有のナラティブ、客観的事実、キャラクターごとの知識、プッシュ失敗の代償を記帳する。明らかな、または不可欠な手がかりは判定を完全に迂回し、直接連続性で解決されるため、連続した悪いダイスがモジュールを妨げることはない。

複合判定は同じ復元可能なフローを再利用するが、1回の d100 でキャラクターシートから読み取った2つから8つのスキルまたは特徴を同時に比較する。Keeper は requirement="any" か "all" を明示的に選択しなければならない。Luck の消費はこの集約要件を正確に購入することのみができ、成功した各スキル要素はそれぞれ成長マークを得る。CoC は D&D式の「多数成功」グループルールを捏造しない。真のグループ Luck は group_luck_query/check が現場の全参加者の現在の Luck を読み取り、最低 Luck の探索者だけが代表として許可される。最低値が並んだ場合は Keeper が明示的に選択しなければならない。

セッション後の成長は Lobby でのみ開放される。development_query はチェック済みスキルを一覧表示し、development_settle は1つのキャンペーンランダムストリームトランザクション内で、すべての成長ダイス、スキル更新、初回 mastery SAN ボーナス、チェックのクリア、監査レシートを完了する。Cthulhu Mythos は通常の成長が適用されないと明示的にマークされ、誤ったチェックはクリアされる。書き込み境界はキャラクター制御権、キャンペーン/キャラクター revision、ブランチ、冪等リプレイを同時に検証する。

Related MCP server: foundry-cli

Module Pack 制作フロー

CoC モジュールは統一された 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 はインポートホワイトリスト内の PDF、Markdown、テキストの source_path、または生成コンテンツの name と content を受け付ける。機械的なインポートは未アクティブなドラフトのみを生成する。プロセスがコミット済みの中間ステップの後に中断された場合、advance はそのステップから続行する。evidence は有界テキストブロック、管理された PDF ページレンダリングレシート、アセット、コンテンツレビューを提供する。edit は checksum バインドされた PDF テキスト改訂、CoC コンテンツレビュー、現在の CoC statblock schema 検証、ホワイトリストアセット、アクターバインディング、Pack 決定をサポートする。statblock は出典に実在するが不完全な非戦闘 NPC データを保持できる。combat_ready を明示的に宣言した場合にのみ、戦闘必須フィールドが強制される。出典テキストの変更は新しい未アクティブな機械バージョンを作成し、下流のドラフト決定を無効にする。プレイ設定とカタログ決定は evidence が返すそのままの出典レシートを参照しなければならない。ファイナライズには Agent の明示的な確認が必要で、静かに変更できない .sagasmith-pack を生成する。この最終アーカイブから再インポートしたモジュールのみがアクティブ化できる。

商業ルールブックとモジュールは常にローカルに保持される。SAGASMITH_COC_MCP_MODULE_IMPORT_ROOTS で読み取り可能なソースルートディレクトリを設定し、複数パスにはシステムのパス区切り文字を使用する。リポジトリは原書、抽出テキスト、原書アセットを配布しない。

Pack インポートは決定論的リカバリプロトコルを使用する：Pack checksum は候補バージョンの ID に属し、module、asset、content review、actor、binding の各ステップはコンテンツ ID または子冪等キーで収束する。最終レシートの前にプロセスが中断された場合、元のリクエストと idempotency_key で再試行すれば続行でき、重複するランタイムオブジェクトは生成されない。アクティブ化、非アクティブ化、削除はそれぞれ正確なレシートをコミットする。削除後も同じリクエストは元のレスポンスをリプレイできる。

起動

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

統一ローカルスタックは、streamable HTTP 権威サービスとスティッキーセッション 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

ブラウザは principal を送信できない。Gateway はサーバー側で ID をバインドし、ブラウザ/キャンペーンごとに独立した MCP セッションを保持し、tools/list_changed の後に実際のネイティブツールリストを更新する。

状態はデフォルトで .sagasmith-coc-mcp/ に配置される。主な設定項目：

• SAGASMITH_COC_MCP_HOME

• SAGASMITH_COC_MCP_MODULE_IMPORT_ROOTS

• SAGASMITH_COC_SKILLS_DIR

• SAGASMITH_MODULEGEN_SKILLS_DIR

• SAGASMITH_COC_MCP_BOUND_PRINCIPAL_ID

開発

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

オリジナルコードは Apache-2.0 を採用する。Call of Cthulhu および関連する商業コンテンツの権利は各権利者に帰属する。