SagaSmith CoC MCP

중국어 · English · 플랫폼 개요

SagaSmithAI의 Call of Cthulhu 7e 로컬 권위 MCP 서비스입니다. sagasmith-core의 캠페인 영속성, 분기 메모리, 캐릭터 지식, 스냅샷, 모듈 검색 및 통합 Content Pack을 sagasmith-coc의 d100, 이성, 전투, 추격 및 재생 가능한 난수 스트림과 하나의 네이티브 MCP 경계로 통합합니다.

런타임 경계

• MCP는 권위 있는 캠페인 상태, 권한, revision, 멱등성, 난수 스트림 영수증 및 무작위 판정의 원자적 커밋을 담당합니다.

• 각 MCP 세션은 네이티브 도구 노출을 독립적으로 유지합니다. Lobby, Play, Combat 전략은 호출 시 다시 검증합니다.

• 호스트는 tools/list_changed에 응답하고 네이티브 스키마를 새로 고쳐야 합니다. 고정된 도구 집합, 텍스트 시뮬레이션 또는 exposure_call 폴백은 없습니다.

• 에이전트는 출처를 해석하고 모듈 특유의 의미론적 결정을 내립니다. 최종 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가 트리거됩니다. 호스트는 목록을 새로 고친 후 해당 단계의 적법한 네이티브 도구를 다시 로드하고 직접 호출할 수 있습니다.

Snapshot은 공개 프로토콜에서 여전히 독립적으로 복구 가능한 완전한 상태 문서입니다. 기본 schema v8은 각 문서를 개별적으로 zlib-1 레코드로 압축하고 압축 바이트, 문서 checksum 및 노드 신원을 검증합니다. snapshot_query/change, 브랜치 checkout, undo/redo 및 재시작 복구는 조상 체인 재생에 의존하지 않습니다.

서비스 시작 시 Core Alembic 마이그레이션을 실행하고 데이터베이스가 현재 Snapshot schema v8을 충족해야 합니다. 배포 전에 서비스가 중지되고 SQLite WAL이 수렴된 후 data/ttrpgbase.db를 백업해야 합니다. 외부 데이터베이스는 자체 네이티브 일관성 백업을 사용합니다. 현재 형식은 다운그레이드할 수 없습니다. 롤백하려면 데이터베이스, 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을 검증하고 DEX, 준비된 총기의 DEX+50, 안정적인 동점 순서로 Combat에 진입합니다. 공격은 먼저 응답 대기 선택을 영속화합니다. 대상 제어자는 회피, 반격, 엄폐를 위해 몸을 숙이기 또는 무응답 중에서 선택합니다. resolve는 캠페인 난수 스트림에서 공격, 방어, 극도로 어려운/관통 피해, 탄약, CON, HP 및 부상을 정산하고 캠페인과 영향을 받은 캐릭터를 동일한 revision group에 기록합니다. Grid 모드는 엔진이 좌표를 저장하고 이동/근접 거리를 검증합니다. Agent 모드는 좌표를 생성하지 않으며 Agent가 명시적으로 제공한 공간 사실만 수용합니다. combat_end는 Play로 돌아가고 여전히 죽어가는 상태 회복 처리가 필요한 캐릭터를 나열합니다.

실제 stdio 호스트 회귀 테스트는 Lobby → Play → Combat → Play를 포함합니다. 단계가 변경될 때마다 호스트는 네이티브 목록을 새로 고치고 이전 단계 도구는 즉시 사라지며 새 단계 도구는 직접 로드하고 호출할 수 있습니다.

추격은 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 회귀 테스트는 이러한 네이티브 도구가 단계 스키마에 따라 올바르게 나타나고 사라지는지 검증합니다.

출처가 명확한 조사 판정은 investigation_check(open|spend_luck|push|settle|abort) 및 investigation_query를 사용합니다. MCP는 캐릭터 시트에서 정확한 이름의 스킬, 특징 또는 Luck을 읽고, 캠페인 난수 스트림으로 주사위를 굴리며, 아직 완료되지 않은 인간 선택을 영속화합니다. Spending Luck은 캠페인 설정에서 명시적으로 활성화되어야 하며, 정확한 지출과 캐릭터 revision이 원자적으로 정산됩니다. 밀어붙이기는 새로운 행동 방식과 Keeper가 예고한 실패 비용을 제시해야 하며, 두 번째 주사위를 굴린 후에는 더 이상 Luck을 쓸 수 없습니다. 대기 중인 선택은 재시작을 넘어 복구될 수 있으며, 정산되거나 Keeper가 중단할 때까지 Combat, Chase 진입 또는 Lobby 복귀를 차단합니다. 성공한 스킬은 한 번만 표시되며, 이후 성장을 위해 남겨집니다.

판정은 단서의 의미나 대상을 추측하지 않습니다. settle은 기계적 영수증을 반환하며, 이후 Agent는 memory_change(action="commit")를 통해 출처별 서술, 객관적 사실, 캐릭터별 지식, 그리고 밀어붙이기 실패 비용을 원장에 기록합니다. 명백하거나 없어서는 안 될 단서는 판정을 완전히 우회하여 연속성으로 직접 정산하므로, 연속된 나쁜 주사위로 모듈이 차단될 수 없습니다.

조합 판정은 동일한 복구 가능한 프로세스를 재사용하지만, 한 번의 d100이 캐릭터 시트에서 읽은 두 개에서 여덟 개의 스킬 또는 특징을 동시에 비교합니다. Keeper는 requirement="any" 또는 "all"을 명시적으로 선택해야 합니다. Luck 지출은 이 집계 요구사항을 정확히 구매할 수 있을 뿐이며, 성공한 각 스킬 구성요소는 개별적으로 성장 표시를 얻습니다. CoC는 D&D식 “다수 성공” 그룹 규칙을 만들어내지 않습니다. 실제 그룹 Luck은 group_luck_query/check가 현장의 모든 참가자의 현재 Luck을 읽어 최저 Luck의 탐사자만 대표할 수 있게 합니다. 최저 값이 동률일 때는 Keeper가 명시적으로 선택해야 합니다.

회의 후 성장은 Lobby에서만 열립니다. development_query는 체크된 스킬을 나열하고, development_settle은 한 번의 캠페인 난수 스트림 트랜잭션에서 모든 성장 주사위, 스킬 업데이트, 첫 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 스키마 검증, 허용 목록 에셋, 액터 바인딩 및 Pack 결정을 지원합니다. statblock은 출처에 실제 있지만 불완전한 비전투 NPC 데이터를 유지할 수 있습니다. combat_ready를 명시적으로 선언한 경우에만 전투 필수 필드가 강제됩니다. 원본 텍스트를 수정하면 새로운 미활성 기계 버전이 생성되고 하위 초안 결정이 무효화됩니다. 플레이 구성 및 카탈로그 결정은 evidence가 반환한 원본 그대로의 출처 영수증을 참조해야 합니다. 마무리에는 Agent의 명시적 확인이 필요하며, 조용히 수정할 수 없는 .sagasmith-pack이 생성됩니다. 이 최종 아카이브에서 다시 가져온 모듈만 활성화할 수 있습니다.

상업용 룰북과 모듈은 항상 로컬에 유지됩니다. SAGASMITH_COC_MCP_MODULE_IMPORT_ROOTS로 읽을 수 있는 소스 루트 디렉터리를 구성하며, 여러 경로는 시스템 경로 구분 기호를 사용합니다. 저장소는 원본 서적, 추출된 텍스트 또는 원본 서적 에셋을 배포하지 않습니다.

Pack 가져오기는 결정적 복구 프로토콜을 사용합니다. Pack checksum은 후보 버전의 정체성에 속하며, 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 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는 서버 측에서 정체성을 바인딩하고, 각 브라우저/캠페인에 대해 독립적인 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 및 관련 상업 콘텐츠의 권리는 각 권리 보유자에게 있습니다.