SagaSmith CoC MCP

中文 · English · Обзор платформы

SagaSmithAI — локальный авторитетный MCP-сервис для Call of Cthulhu 7e. Он объединяет персистентность кампаний, ветвящуюся память, знания персонажей, снимки, поиск модулей и единый Content Pack из sagasmith-core с d100, рассудком, боем, погоней и воспроизводимым потоком случайностей из sagasmith-coc в единую нативную MCP-границу.

Границы среды выполнения

• MCP отвечает за авторитетное состояние кампании, права доступа, revision, идемпотентность, квитанции потока случайности и атомарную фиксацию случайных определений.

• Каждый MCP-сеанс независимо поддерживает предоставление нативных инструментов; стратегии Lobby, Play, Combat дополнительно проверяются при вызове.

• Host должен реагировать на tools/list_changed и обновлять нативную схему; нет фиксированного набора инструментов, текстовой симуляции или fallback через 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 документа и идентичность узла. snapshot_query/change, branch checkout, undo/redo и восстановление после перезапуска не зависят от воспроизведения цепочки предков.

При запуске сервис выполняет миграции Core Alembic и требует, чтобы база данных соответствовала текущей Snapshot schema v8. Перед развёртыванием необходимо создать резервную копию data/ttrpgbase.db после остановки сервиса и схождения SQLite WAL; для внешних баз данных используйте их собственные согласованные резервные копии. Текущий формат нельзя понизить (downgrade); откат должен восстановить базу данных, Core, CoC и MCP как согласованный набор версий.

Фазы Play и Combat предоставляют два вида расчёта состояния персонажа с явным указанием источника:

• 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 персонажей участников и входит в Combat в порядке DEX, DEX+50 для подготовленного огнестрельного оружия и стабильном порядке при равных значениях. Атака сначала сохраняет выбор, ожидающий ответа; затем контролёр цели выбирает уклонение, контратаку, нырок за укрытие или отсутствие реакции. 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 и точную идемпотентную квитанцию.

Непрерывность расследования использует три отдельных типа реестров; нельзя автоматически считать повествование фактом, известным всем персонажам:

• campaign_event записывает события в временную шкалу ветки и требует явно указать аудиторию dm, party, public или actor, а также может помечать участников speaker/listener/witness/target.

• continuity_context возвращает контекст ветки, ограниченный единым бюджетом символов. Вызовы не от Keeper всегда принудительно используют проекцию игрока и могут читать только приватные знания своих авторизованных персонажей.

• memory_change(action="commit") атомарно фиксирует событие, ревизию объективных фактов, ревизию знаний для каждого персонажа и опциональный снимок; производные факты и знания по умолчанию ссылаются на то же исходное событие. Точный повтор возвращает исходный ответ, при сбое любого подэлемента всё откатывается целиком.

Объективный memory_query и все операции записи непрерывности доступны только Keeper; игроки не могут использовать реестр объективных фактов, чтобы обойти улики, тайны, ложные убеждения или границы групп. Во время Combat безопасное чтение непрерывности сохраняется, но запись временной шкалы и памяти отключается и восстанавливается после возврата в Play; реальный stdio-регресс проверяет, что эти нативные инструменты правильно появляются и исчезают вместе с schema фазы.

Проверки расследования с явным источником используют investigation_check(open|spend_luck|push|settle|abort) и investigation_query. MCP считывает с листа персонажа точно названный навык, черту или Luck, бросает кубы, используя поток случайности кампании, и сохраняет ожидающие решения человека. Трата Luck (Spending Luck) должна быть явно включена настройками кампании; точная трата и revision персонажа фиксируются атомарно. При отчаянной попытке (push) необходимо указать новый способ действий и объявленную Keeper цену провала; после второго броска Luck больше тратить нельзя. Ожидающие выбора могут быть восстановлены после перезапуска и блокируют вход в Combat, Chase или возврат в Lobby, пока не будут урегулированы или прерваны Keeper; успешный навык отмечается только один раз и остаётся для последующего развития.

Проверки не угадывают смысл улик или их аудиторию. settle возвращает механическую квитанцию, после чего Agent через memory_change(action="commit") фиксирует специфичное для источника повествование, объективные факты, знания по каждому персонажу и цену провала отчаянной попытки. Очевидные или обязательные улики полностью минуют проверку и разрешаются напрямую через непрерывность; из-за серии плохих бросков модуль не может быть заблокирован.

Комбинированные проверки используют тот же восстанавливаемый процесс, но одно d100 одновременно сравнивается с двумя-восемью навыками или чертами, считанными с листа персонажа. Keeper должен явно выбрать requirement="any" или "all"; потратить Luck можно только точно на это агрегированное требование, и каждая успешная составляющая навыка отдельно получает отметку роста. CoC не выдумывает D&D-подобное групповое правило «большинство успехов». Настоящая групповая Luck считывается через group_luck_query/check у всех присутствующих участников, и представлять может только сыщик с наименьшей Luck; при равенстве минимальных значений Keeper должен явно сделать выбор.

Последующий рост доступен только в Lobby. development_query перечисляет отмеченные навыки, development_settle в одной транзакции потока случайности кампании выполняет все кубы роста, обновление навыков, первый бонус SAN за мастерство, очистку отметок и аудитную квитанцию; Cthulhu Mythos явно помечается как неприменимый к обычному росту, и ошибочные отметки удаляются. Граница записи также проверяет право управления персонажем, campaign/character 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 принимает source_path для PDF, Markdown, текстовых файлов из белого списка импорта или 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 использует детерминированный протокол восстановления: checksum Pack принадлежит идентичности кандидатной версии, каждый шаг module, asset, content review, actor и binding сходится по идентичности содержимого или субидемпотентному ключу. Если процесс прерывается до финальной квитанции, повторный запрос с исходным запросом и idempotency_key продолжает работу и не создаёт дублирующихся объектов времени выполнения. Активация, деактивация и удаление фиксируют точные квитанции; повторный запрос после удаления по-прежнему может воспроизвести исходный ответ.

Запуск

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

Единый локальный стек использует авторитетный сервис streamable HTTP и шлюз Workbench с липкими сеансами:

$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 привязывает идентичность на стороне сервера, сохраняет отдельный 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 и связанный коммерческий контент принадлежат их соответствующим правообладателям.