SagaSmith CoC MCP

Chino · Inglés · Descripción general de la plataforma

El servicio MCP local autoritativo de Call of Cthulhu 7e de SagaSmithAI. Integra la persistencia de campaña, la memoria ramificada, el conocimiento de personajes, las instantáneas, la recuperación de módulos y el Content Pack unificados de sagasmith-core, con el d100, la cordura, el combate, las persecuciones y el flujo aleatorio reproducible de sagasmith-coc en una frontera MCP nativa.

Límites de ejecución

• El MCP es responsable del estado autoritativo de la campaña, los permisos, la revisión, la idempotencia, los recibos del flujo aleatorio y la confirmación atómica de las resoluciones aleatorias.

• Cada sesión MCP mantiene de forma independiente la exposición de herramientas nativas; las políticas Lobby, Play y Combat se vuelven a validar en cada invocación.

• El Host debe responder a tools/list_changed y refrescar el esquema nativo; no hay un conjunto fijo de herramientas, simulación de texto ni fallback con exposure_call.

• El Agent es responsable de interpretar las fuentes y de tomar las decisiones semánticas específicas del módulo; el Pack final conserva la evidencia de origen de estas decisiones.

Flujo de carga de capacidades nativas:

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

La interfaz de restauración del Keeper está formada por branch_query/change, snapshot_query/change y state_revision. Todas las operaciones de escritura exigen una revisión/rama explícita o una guarda de cursor histórico, además de idempotency_key; checkout, restore, undo y redo disparan tools/list_changed tras cambiar la fase autoritativa. Una vez que el Host refresca la lista, puede volver a cargar e invocar directamente las herramientas nativas legítimas de esa fase.

Snapshot sigue siendo, en el protocolo público, un documento de estado completo e independientemente restaurable; el esquema subyacente v8 solo comprime cada documento de forma independiente como un registro zlib-1 y verifica los bytes comprimidos, el checksum del documento y la identidad del nodo. snapshot_query/change, el checkout de rama, undo/redo y la recuperación tras reinicio no dependen de la reproducción de la cadena de ancestros.

Al arrancar, el servicio ejecuta las migraciones de Core Alembic y exige que la base de datos se ajuste al esquema v8 actual de Snapshot. Antes del despliegue hay que hacer una copia de seguridad de data/ttrpgbase.db con el servicio detenido y el WAL de SQLite ya convergido; las bases de datos externas usan su copia de seguridad coherente nativa. El formato actual no se puede degradar; para revertir, la base de datos, Core, CoC y MCP deben restaurarse como un conjunto de versiones coincidentes.

Las fases Play y Combat ofrecen dos resoluciones de estado de personaje con origen explícito:

• coc_sanity_check completa atómicamente la tirada de SAN, los dados de pérdida, la tirada de INT necesaria, la locura temporal/indefinida/permanente, el episodio de frenesí y su duración, y confirma el flujo aleatorio de la campaña y la hoja del investigador en el mismo grupo de revisión.

• coc_hp_change completa atómicamente el daño o la curación; una herida grave única usa el flujo aleatorio autoritativo para realizar la tirada de CON necesaria y persiste los estados de major wound, unconscious, dying, dead y curación. Un cambio de HP puro, sin extracción aleatoria, no fabrica una revisión de campaña.

Ambas herramientas exigen permiso de control del personaje, revisión de campaña/personaje y clave de idempotencia; una repetición exacta devuelve la respuesta original, sin extraer ni resolver de nuevo.

El combate autoritativo usa herramientas nativas orientadas a tareas, en lugar de permitir que el invocador reescriba directamente campaign.state:

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

combat_start valida la revisión de personaje de los participantes y entra en Combate con el orden por DEX, DEX+50 para armas de fuego preparadas y desempate estable para valores iguales. El ataque persiste primero la elección pendiente de respuesta; el controlador del objetivo elige entonces esquivar, contraatacar, cubrirse o no responder. resolve resuelve desde el flujo aleatorio de la campaña ataques, defensas, daño extremo/perforante, munición, CON, HP y heridas, y escribe la campaña y los personajes afectados en el mismo grupo de revisión. El modo Grid conserva las coordenadas y valida distancias de movimiento/cuerpo a cuerpo en el motor; el modo Agent no genera coordenadas, solo acepta los hechos espaciales que el Agent indique explícitamente. combat_end devuelve a Play y lista los personajes que aún requieren recuperación por estado de muerte inminente.

La regresión con host stdio real cubre Lobby → Play → Combat → Play: tras cada cambio de fase, el Host refresca la lista nativa, las herramientas de la fase anterior desaparecen de inmediato y las de la nueva fase pueden cargarse e invocarse directamente.

Las persecuciones se gestionan dentro de Play mediante chase_start/query/action/end y son estrictamente exclusivas con el Combate. Al comenzar una persecución, el MCP lee de la hoja de personaje los valores explícitos de CON, Drive Auto o habilidades del Pack, resuelve la tirada de velocidad con el flujo aleatorio de la campaña y calcula los puntos de acción de cada ronda según el MOV efectivo más lento. chase_action mantiene de forma autoritativa el orden de DEX, el gasto de puntos de acción, la posición en la ruta, las tiradas de obstáculos y el reinicio de ronda; el cambio de posición asociado al éxito/fracaso de un obstáculo y su origen deben ser proporcionados explícitamente por el Pack o el Agent; el MCP no adivina el terreno narrativo. Los jugadores solo pueden operar personajes autorizados; iniciar/finalizar una persecución está reservado al Keeper, y todos los cambios aleatorios y de estado tienen revisión y recibos de idempotencia exactos.

La continuidad de la investigación usa tres libros de contabilidad separados entre sí; la narración no puede tratarse automáticamente como un hecho conocido por todos los personajes:

• campaign_event escribe en la línea temporal de la rama; debe indicar explícitamente la audiencia dm, party, public o actor, y puede marcar participantes como speaker/listener/witness/target.

• continuity_context devuelve el contexto de la rama sujeto a un presupuesto de caracteres unificado. Las invocaciones que no son de Keeper aplican siempre una proyección de jugador, por lo que solo se puede leer el conocimiento privado de los personajes para los que se está autorizado.

• memory_change(action="commit") resuelve atómicamente un evento, una revisión de hechos objetivos, revisiones de conocimiento por personaje y una instantánea opcional; los hechos y conocimientos derivados referencian por defecto el mismo evento de origen. Una repetición exacta devuelve la respuesta original; cualquier fallo de un subelemento revierte todo el conjunto.

El memory_query objetivo y todas las escrituras de continuidad están reservados al Keeper; los jugadores no pueden usar el libro de hechos objetivos para eludir pistas, secretos, creencias erróneas o la separación entre grupos. Durante el Combate se mantienen las lecturas de continuidad seguras, pero se desactivan las escrituras de línea temporal y memoria, que se restablecen al volver a Play; la regresión con stdio real verifica que estas herramientas nativas aparecen y desaparecen correctamente con el esquema de cada fase.

Las tiradas de investigación con origen explícito usan investigation_check(open|spend_luck|push|settle|abort) e investigation_query. El MCP lee de la hoja de personaje habilidades, rasgos o Luck con nombres exactos, tira los dados con el flujo aleatorio de la campaña y persiste las elecciones humanas aún no completadas. El gasto de Luck debe estar habilitado explícitamente por la configuración de la campaña; el gasto exacto se resuelve atómicamente con la revisión del personaje. La apuesta desesperada (push) debe aportar un nuevo enfoque y el coste del fracaso anunciado por el Keeper; no se puede gastar más Luck después de la segunda tirada. Las elecciones pendientes se recuperan entre reinicios y bloquean la entrada a Combat o Chase o el regreso a Lobby hasta que se resuelvan o el Keeper las aborte; una habilidad superada solo se marca una vez, a la espera del crecimiento posterior a la sesión.

Las tiradas no adivinan el significado de las pistas ni su audiencia. settle devuelve un recibo mecánico; después, el Agent registra mediante memory_change(action="commit") la narrativa específica de la fuente, los hechos objetivos, el conocimiento por personaje y el coste del fracaso de la tirada empujada. Las pistas evidentes o indispensables omiten por completo la tirada y se resuelven directamente con la continuidad; no se puede bloquear un módulo por una racha de malas tiradas.

Las tiradas combinadas reutilizan el mismo flujo recuperable, pero un solo d100 compara simultáneamente entre dos y ocho habilidades o rasgos leídos de la hoja de personaje. El Keeper debe elegir explícitamente requirement=\"any\" o \"all\"; gastar Luck solo puede comprar exactamente este requisito agregado, y cada componente de habilidad superado recibe su propia marca de crecimiento. CoC no inventa reglas de grupo de “mayoría de éxitos” al estilo D&D. El Luck de grupo real se obtiene con group_luck_query/check, que lee el Luck actual de todos los participantes en la escena y solo permite que represente al grupo el investigador con el Luck más bajo; en caso de empate en el valor mínimo, el Keeper debe elegir explícitamente.

El crecimiento posterior a la sesión solo está disponible en Lobby. development_query enumera las habilidades marcadas; development_settle realiza todas las tiradas de crecimiento, la actualización de habilidades, la recompensa de SAN por la primera maestría, el borrado de marcas y el recibo de auditoría en una única transacción del flujo aleatorio de la campaña; Cthulhu Mythos se marca explícitamente como no apto para crecimiento normal y se eliminan las marcas erróneas. El límite de escritura valida además el control del personaje, la revisión de campaña/personaje, la rama y la reproducción idempotente.

Related MCP server: foundry-cli

Flujo de creación de Module Pack

Los módulos de CoC usan el schema v2 unificado sagasmith.content-package:

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 acepta rutas source_path de PDF, Markdown o texto en la lista blanca de importación, o un name más content para contenido generado. La importación mecánica solo produce borradores no activados; si el proceso se interrumpe tras un paso intermedio confirmado, advance continúa desde ese paso. evidence proporciona bloques de texto acotados, recibos de renderizado de páginas PDF gestionadas, activos y revisión de contenido; edit admite revisiones de texto PDF vinculadas a checksum, revisión de contenido CoC, validación con el schema actual de statblocks CoC, activos en lista blanca, vinculación de actores y decisiones del Pack. Un statblock puede conservar datos de NPC no combativo que sean reales pero incompletos en la fuente; los campos obligatorios de combate solo se exigen cuando se declara explícitamente combat_ready. Modificar el texto fuente crea una nueva versión mecánica no activada e invalida las decisiones de borrador posteriores. La configuración de juego y las decisiones de catálogo deben citar los recibos de origen tal como los devuelve evidence. La finalización requiere confirmación explícita del Agent y genera un .sagasmith-pack que no puede modificarse en silencio; solo los módulos reimportados desde ese archivo final pueden activarse.

Los libros de reglas comerciales y los módulos permanecen siempre en local. Con SAGASMITH_COC_MCP_MODULE_IMPORT_ROOTS se configuran los directorios raíz de origen permitidos para lectura; para varias rutas se usa el separador de rutas del sistema. El repositorio no distribuye los libros originales, el texto extraído ni los activos de los libros originales.

La importación de Packs usa un protocolo de recuperación determinista: el checksum del Pack pertenece a la identidad de la versión candidata; cada paso de module, asset, content review, actor y binding converge por identidad de contenido o claves subidempotentes. Si el proceso se interrumpe antes del recibo final, basta reintentar con la solicitud original e idempotency_key para continuar, sin generar objetos de runtime duplicados. La activación, desactivación y eliminación confirman cada una un recibo exacto; después de eliminar, la misma solicitud puede seguir reproduciendo la respuesta original.

Arranque

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

La pila local unificada usa el servicio autoritativo HTTP streamable y el gateway de Workbench con sesiones adhesivas:

$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

El navegador no puede enviar un principal. El Gateway vincula la identidad en el lado del servidor, mantiene una sesión MCP independiente para cada navegador/campaña y refresca la lista real de herramientas nativas después de tools/list_changed.

El estado se encuentra por defecto en .sagasmith-coc-mcp/. Principales opciones de configuración:

• SAGASMITH_COC_MCP_HOME

• SAGASMITH_COC_MCP_MODULE_IMPORT_ROOTS

• SAGASMITH_COC_SKILLS_DIR

• SAGASMITH_MODULEGEN_SKILLS_DIR

• SAGASMITH_COC_MCP_BOUND_PRINCIPAL_ID

Desarrollo

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

El código original está bajo licencia Apache-2.0. Los derechos de Call of Cthulhu y del contenido comercial relacionado pertenecen a sus respectivos titulares.