SagaSmith CoC MCP

中文 · English · Plattform-Übersicht

Der lokale maßgebliche MCP-Dienst von SagaSmithAI für Call of Cthulhu 7e. Er integriert die Kampagnen-Persistenz, verzweigte Erinnerungen, Charakterwissen, Snapshots, Modul-Retrieval und das einheitliche Content Pack von sagasmith-core mit d100, geistiger Gesundheit, Kampf, Verfolgungsjagden und wiedergebbaren Zufallsströmen von sagasmith-coc in eine native MCP-Grenze.

Laufzeitgrenzen

• Der MCP übernimmt den atomaren Commit für den maßgeblichen Kampagnenzustand, Berechtigungen, Revisionen, Idempotenz, Zufallsstrombelege und zufällige Ermittlungen.

• Jede MCP-Sitzung verwaltet die native Tool-Exposition unabhängig; die Lobby-, Play- und Combat-Strategien validieren außerdem bei jedem Aufruf erneut.

• Der Host muss auf tools/list_changed reagieren und das native Schema aktualisieren; es gibt keine feste Tool-Menge, Textsimulation oder exposure_call-Fallback.

• Der Agent ist für die Quelleninterpretation und modulspezifische semantische Entscheidungen verantwortlich; das endgültige Pack bewahrt die Quellennachweise dieser Entscheidungen.

Ablauf des Ladens nativer Fähigkeiten:

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

Die Keeper-Wiederherstellungsschnittstelle besteht aus branch_query/change, snapshot_query/change und state_revision. Alle Schreiboperationen erfordern explizite Revisions-/Zweig- oder Verlaufscursor-Wächter sowie einen idempotency_key; Checkout, Restore, Undo, Redo lösen nach einer Änderung der maßgeblichen Phase tools/list_changed aus. Nachdem der Host die Liste aktualisiert hat, kann er die zulässigen nativen Werkzeuge der Phase neu laden und direkt aufrufen.

Snapshot bleibt im öffentlichen Protokoll ein vollständiges, unabhängig wiederherstellbares Zustandsdokument; das zugrunde liegende Schema v8 komprimiert jedes Dokument unabhängig als zlib-1-Datensatz und validiert komprimierte Bytes, Dokument-Checksumme und Knotenidentität. snapshot_query/change, Branch-Checkout, Undo/Redo und Neustart-Wiederherstellung hängen nicht von der Wiedergabe einer Ancestor-Kette ab.

Beim Dienststart werden die Core-Alembic-Migrationen ausgeführt, und die Datenbank muss dem aktuellen Snapshot-Schema v8 entsprechen. Vor der Bereitstellung muss data/ttrpgbase.db gesichert werden, nachdem der Dienst gestoppt und das SQLite-WAL konvergiert ist; für externe Datenbanken wird deren native konsistente Sicherung verwendet. Das aktuelle Format kann nicht herabgestuft werden; ein Rollback erfordert, dass Datenbank, Core, CoC und MCP auf einen Satz passender Versionen zurückgesetzt werden.

Die Phasen Play und Combat bieten zwei quellenklare Abrechnungen des Charakterzustands:

• coc_sanity_check führt atomar die SAN-Probe, Verlustwürfel, erforderliche INT-Probe, vorübergehenden/unspezifischen/permanenten Wahnsinn, Tobsuchtsanfall und Dauer aus und committet den Kampagnen-Zufallsstrom und das Investigatorenblatt in derselben Revisionsgruppe.

• coc_hp_change führt Schaden oder Heilung atomar aus; eine einzelne schwere Verletzung verwendet den maßgeblichen Zufallsstrom für die erforderliche CON-Probe und persistiert die Zustände schwere Wunde, bewusstlos, sterbend, tot und Heilung. Reine HP-Änderungen ohne Zufallsziehung erzeugen keine künstliche Kampagnen-Revision.

Beide Tools erfordern die Charakterkontrollberechtigung, die Kampagnen-/Charakterrevision und den Idempotenzschlüssel; exakte Wiederholungen geben die ursprüngliche Antwort zurück und dürfen weder Ziehungen noch Abrechnungen duplizieren.

Maßgeblicher Kampf verwendet aufgabenorientierte native Tools, anstatt dem Aufrufer zu erlauben, campaign.state direkt zu modifizieren:

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

combat_start validiert die Rollenrevision der Teilnehmer und betritt den Kampf in der Reihenfolge DEX, DEX+50 für vorbereitete Feuerwaffen und stabile Gleichstandsfälle. Angriffe persistieren zunächst die ausstehende Reaktionsauswahl; der Zielkontrollierende wählt dann Ausweichen, Gegenangriff, In-Deckung-Gehen oder keine Reaktion. resolve wickelt Angriff, Verteidigung, extreme/Impale-Schäden, Munition, CON, HP und Verletzungen über den Kampagnen-Zufallsstrom ab und schreibt Kampagne und betroffene Charaktere in dieselbe Revisionsgruppe. Der Grid-Modus speichert Koordinaten und validiert Bewegung/Nahkampfreichweite; der Agent-Modus erzeugt keine Koordinaten und akzeptiert nur räumliche Tatsachen, die der Agent explizit angibt. combat_end kehrt zu Play zurück und listet die Charaktere auf, die noch eine Behandlung im Sterbezustand benötigen.

Ein echter Stdio-Host-Regressionstest deckt Lobby → Play → Combat → Play ab: Nach jeder Phasenänderung aktualisiert der Host die native Liste, die Werkzeuge der alten Phase verschwinden sofort, und die Werkzeuge der neuen Phase können direkt geladen und aufgerufen werden.

Verfolgungsjagden werden innerhalb von Play über chase_start/query/action/end verwaltet und sind strikt exklusiv zu Combat. Beim Start einer Verfolgungsjagd liest der MCP die explizit angegebenen CON-, Drive-Auto- oder Pack-Fertigkeiten aus dem Charakterblatt, führt die Geschwindigkeitsprobe über den Kampagnen-Zufallsstrom aus und berechnet die Aktionspunkte pro Runde basierend auf dem langsamsten effektiven MOV. chase_action verwaltet maßgeblich DEX-Reihenfolge, Aktionspunktverbrauch, Streckenposition, Hindernisproben und Rundenrücksetzung; Positionsänderungen und Quellen bei Erfolg/Fehlschlag von Hindernissen müssen explizit von Pack oder Agent angegeben werden, der MCP spekuliert nicht über narrative Gelände. Spieler können nur autorisierte Charaktere steuern, Start/Ende der Verfolgungsjagd sind nur für Keeper zugänglich, und alle Zufälle und Zustandsänderungen besitzen Revisionen und präzise Idempotenzbelege.

Ermittlungskontinuität verwendet drei voneinander getrennte Ledger und kann eine Erzählung nicht automatisch als Tatsache behandeln, die allen Charakteren bekannt ist:

• campaign_event schreibt in die Timeline innerhalb des Zweigs und erfordert explizit eine Zielgruppe von dm, party, public oder actor; es kann Sprecher/Hörer/Zeuge/Ziel-Teilnehmer markieren.

• continuity_context gibt den durch ein einheitliches Zeichenbudget begrenzten Zweigkontext zurück. Nicht-Keeper-Aufrufe erzwingen immer eine Spielerprojektion und können nur das private Wissen der autorisierten eigenen Charaktere lesen.

• memory_change(action="commit") rechnet ein Ereignis, eine objektive Faktenrevision, eine Pro-Charakter-Wissensrevision und optionale Snapshots atomar ab; abgeleitete Fakten und Wissen verweisen standardmäßig auf dasselbe Quellenereignis. Exakte Wiederholungen geben die ursprüngliche Antwort zurück, und jeder Teilfehler führt zu einem vollständigen Rollback.

Objektives memory_query und alle Kontinuitätsschreibvorgänge sind nur für Keeper zugänglich; Spieler können das objektive Fakten-Ledger nicht nutzen, um Hinweise, Geheimnisse, falsche Überzeugungen oder Gruppengrenzen zu umgehen. Während Combat bleiben sichere Kontinuitätslesevorgänge erhalten, aber Timeline- und Speicherschreibvorgänge sind deaktiviert und werden nach der Rückkehr zu Play wiederhergestellt; echte Stdio-Regressionstests verifizieren, dass diese nativen Werkzeuge je nach Phasenschema korrekt erscheinen und verschwinden.

Quellenklare Ermittlungsproben verwenden investigation_check(open|spend_luck|push|settle|abort) und investigation_query. Der MCP liest die exakt benannten Fertigkeiten, Merkmale oder Luck aus dem Charakterblatt, würfelt mit dem Kampagnen-Zufallsstrom und persistiert noch nicht abgeschlossene menschliche Entscheidungen. Das Ausgeben von Luck muss in den Kampagneneinstellungen explizit aktiviert sein; die genaue Ausgabe und die Charakterrevision werden atomar abgerechnet. Bei einer Push-Probe müssen eine neue Vorgehensweise und die vom Keeper angedrohten Fehlschlagkosten angegeben werden; nach dem zweiten Wurf kann keine Luck mehr ausgegeben werden. Ausstehende Entscheidungen können über Neustarts hinweg wiederhergestellt werden und blockieren den Eintritt in Combat, Chase oder die Rückkehr zu Lobby, bis sie abgerechnet oder vom Keeper abgebrochen werden; erfolgreiche Fertigkeiten werden nur einmal markiert und für das Wachstum nach der Sitzung aufbewahrt.

Proben spekulieren nicht über die Bedeutung oder Zielgruppe von Hinweisen. settle gibt eine mechanische Quittung zurück; der Agent verbucht dann über memory_change(action="commit") die quellspezifische Erzählung, objektive Tatsachen, Pro-Charakter-Wissen und die Fehlschlagkosten der Push-Probe. Offensichtliche oder unverzichtbare Hinweise umgehen die Probe vollständig und werden direkt über Kontinuität abgerechnet; ein Modul darf nicht durch eine Reihe schlechter Würfe blockiert werden.

Kombinierte Proben verwenden denselben wiederherstellbaren Ablauf, aber ein einzelner d100 wird gleichzeitig gegen zwei bis acht Fertigkeiten oder Merkmale aus dem Charakterblatt verglichen. Der Keeper muss explizit requirement="any" oder "all" wählen; das Ausgeben von Luck kann nur diese aggregierte Anforderung präzise kaufen, und jede erfolgreiche Fertigkeitskomponente erhält einzeln eine Wachstumsmarkierung. CoC erfindet keine D&D-artige Gruppenregel für „Mehrheitserfolg“. Echte Gruppen-Luck wird über group_luck_query/check gelesen, das die aktuelle Luck aller anwesenden Teilnehmer erfasst; nur der Ermittler mit der niedrigsten Luck darf repräsentieren. Bei Gleichstand des niedrigsten Werts muss der Keeper explizit wählen.

Wachstum nach der Sitzung ist nur in Lobby verfügbar. development_query listet die markierten Fertigkeiten auf; development_settle führt in einer einzelnen Kampagnen-Zufallsstromtransaktion alle Wachstumswürfe, Fertigkeitsaktualisierungen, den ersten Mastery-SAN-Bonus, das Leeren der Markierungen und einen Prüfbeleg aus. Cthulhu Mythos wird explizit als nicht für normales Wachstum geeignet markiert, und falsche Markierungen werden entfernt. Die Schreibgrenze validiert gleichzeitig Charakterkontrolle, Kampagnen-/Charakterrevision, Zweig und idempotente Wiederholung.

Related MCP server: foundry-cli

Modul-Pack-Erstellungsworkflow

CoC-Module verwenden das einheitliche 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 akzeptiert eine source_path für PDF, Markdown oder Text aus der Import-Whitelist oder name plus content für generierte Inhalte. Mechanische Importe erzeugen nur inaktive Entwürfe; wenn der Prozess nach einem committeten Zwischenschritt unterbrochen wird, fährt advance mit diesem Schritt fort. evidence liefert begrenzte Textblöcke, verwaltete PDF-Seitenwiedergabe-Belege, Assets und Inhaltsprüfungen; edit unterstützt checksummengebundene PDF-Textrevisionen, CoC-Inhaltsprüfung, Validierung des aktuellen CoC-Statblock-Schemas, Whitelist-Assets, Akteur-Bindungen und Pack-Entscheidungen. Statblöcke können echte, aber unvollständige Nichtkampf-NPC-Daten aus der Quelle behalten; kampfnotwendige Felder werden nur erzwungen, wenn explizit combat_ready deklariert ist. Das Ändern des Quelltexts erzeugt eine neue inaktive mechanische Version und invalidiert nachgelagerte Entwurfsentscheidungen. Spielkonfiguration und Inhaltsverzeichnisentscheidungen müssen die unbearbeiteten Quellbelege aus evidence referenzieren. Der Abschluss erfordert eine explizite Agentenbestätigung und erzeugt ein .sagasmith-pack, das nicht stillschweigend geändert werden kann; nur ein aus dieser endgültigen Datei erneut importiertes Modul kann aktiviert werden.

Kommerzielle Regelwerke und Module bleiben immer lokal. Mit SAGASMITH_COC_MCP_MODULE_IMPORT_ROOTS konfigurieren Sie zulässige Quellwurzelverzeichnisse; mehrere Pfade verwenden das systemabhängige Pfadtrennzeichen. Das Repository verteilt weder Originalbücher, extrahierte Texte noch Original-Assets.

Pack-Import verwendet ein deterministisches Wiederherstellungsprotokoll: Die Pack-Checksumme gehört zur Kandidatenversionsidentität; jeder Schritt von Modul, Asset, Inhaltsprüfung, Akteur und Bindung konvergiert über Inhaltsidentität oder Unter-Idempotenzschlüssel. Wenn der Prozess vor der endgültigen Quittung unterbrochen wird, kann mit der ursprünglichen Anfrage und idempotency_key erneut versucht werden, ohne doppelte Laufzeitobjekte zu erzeugen. Aktivieren, Deaktivieren und Löschen committen jeweils präzise Belege; nach dem Löschen kann dieselbe Anfrage weiterhin die ursprüngliche Antwort wiedergeben.

Start

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

Der einheitliche lokale Stack verwendet einen streamable HTTP-Autoritätsdienst mit einem 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

Der Browser kann keinen Principal übermitteln. Das Gateway bindet die Identität serverseitig, unterhält eine unabhängige MCP-Sitzung pro Browser/Kampagne und aktualisiert nach tools/list_changed die echte native Werkzeugliste.

Der Status liegt standardmäßig unter .sagasmith-coc-mcp/. Die wichtigsten Konfigurationseinträge:

• SAGASMITH_COC_MCP_HOME

• SAGASMITH_COC_MCP_MODULE_IMPORT_ROOTS

• SAGASMITH_COC_SKILLS_DIR

• SAGASMITH_MODULEGEN_SKILLS_DIR

• SAGASMITH_COC_MCP_BOUND_PRINCIPAL_ID

Entwicklung

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

Der Originalcode ist unter Apache-2.0 lizenziert. Call of Cthulhu und zugehörige kommerzielle Inhalte gehören den jeweiligen Rechteinhabern.