SagaSmith Narrative MCP
An authoritative, system-neutral MCP for long-form tabletop narrative play. Itdepends on sagasmith-core for durable campaigns, transactions, revisions,documents, continuity ledgers, snapshots, and branches.
The base runtime has two phases: lobby and play. A profile may opt into anauthoritative conflict phase. Native MCP tools are session-scoped and dynamic;hosts must process tools/list_changed notifications.
The server never guesses rules from prose. A campaign binds an immutable profileversion and checksum. Profiles may use Level 0 (explicit Agent/human rulings) orthe limited pure Level 1 mechanics in this package. More complex rules require aseparate system provider.
Lobby administrators can inspect campaign-scoped profile/Pack drafts throughnarrative_query. Access changes support grant and revoke operations withlast-owner protection; controlled actors can be updated through actor_change.Recovery queries and snapshot/branch mutations are administrator-only.
See Architecture and authority andProfile and Pack lifecycle for the durable productboundary. Three self-authored regression campaigns live in fixtures/ash-harbor,fixtures/moss-road-seasons, and fixtures/echo-manor-voices. The third is a15-session, five-NPC character-performance campaign with declared goals,private motives, red lines, false beliefs, relationship arcs, voice markers,isolated dialogue, and a recovered alternate ending.
Development
python -m pip install -e ".[dev]"
pytest
ruff check .
Run the original campaign fixtures concurrently through real stdio MCP sessions:
python scripts/regression_parallel_campaigns.py --output .runs/parallel
The runner opens real stdio MCP sessions, uses a separate session identity foreach principal, executes every declared route step, follows a focused alternatebranch, and emits machine-readable per-campaign timelines and a combinedsummary. A non-zero exit means the run is not accepted.
The Agent Host integration uses the MCP and Agent repositories' own environments: thetest process runs with ../SagaSmith-agent/.venv/Scripts/python.exe, while thespawned MCP server runs with this repository's .venv/Scripts/python.exe:
../SagaSmith-agent/.venv/Scripts/python.exe -m pytest -q tests/test_agent_host_integration.py
Run locally with sagasmith-narrative-mcp. Its independent default home is~/.sagasmith/narrative-mcp. Set SAGASMITH_NARRATIVE_MCP_HOME to relocate it,SAGASMITH_NARRATIVE_MCP_DATABASE_URL to use an explicit database, andSAGASMITH_NARRATIVE_MCP_BOUND_PRINCIPAL_ID when the transport authenticatesone principal.
Without SAGASMITH_NARRATIVE_MCP_BOUND_PRINCIPAL_ID, stdio is a trustedsingle-user local mode; model-supplied principal fields are not multiplayerauthentication. A multiplayer deployment must bind one authenticated principalper MCP process through a trusted transport. Shared-principal HTTP exposure isnot currently supported and the server must not be published directly to anetwork.
