MCP RPG Worldstate

로컬, 시스템 중립적 MCP 서버로, AI 게임 마스터에게 롤플레잉 세계를 위한 영구 기억을 제공합니다. 서술적 콘텐츠는 대부분 자유 텍스트로 저장하며, 검색과 일관성에 중요한 것만 구조화합니다: 세계 소속, 엔티티 유형, 장소, 장면, 참가자, 활성 상태.

기본 원칙

일시적이거나 서술적으로 관련 없는 관찰이 아닌, 영구적이거나 서술적으로 중요한 사실만 저장합니다. 고장난 행성 기상 제어 장치는 중요할 수 있지만, 바람에 흐트러진 헤어스타일은 일반적으로 중요하지 않습니다.

일반적인 조회는 의도적으로 단계적으로 이루어집니다:

1. list_worlds는 기존 세이브를 표시합니다.

2. get_world_overview는 간결한 세이브 미리보기를 제공합니다.

3. get_current_context는 즉시 플레이 가능한 장면을 로드합니다.

4. search_entities는 필요할 때만 추가 세부 정보를 가져옵니다.

변경 사항은 apply_world_changes를 사용하여 단일 원자적 호출로 묶을 수 있습니다.

새로 생성된 엔티티는 동일한 호출 내에서 로컬 참조를 통해 서로를 참조할 수 있습니다. 간결한 이벤트 및 체크포인트 아카이브는 필요 시 현재 상태가 어떻게 형성되었는지 설명하지만, 권위 있는 세계 상태를 대체하지는 않습니다.

Related MCP server: Librarian

요구 사항 및 설치

• Node.js 24 이상 (통합 SQLite 모듈용)

• npm

npm install
npm run build
npm test

서버는 기본적으로 작업 디렉터리의 rpg-worldstate.sqlite를 사용합니다. 안정적이고 명시적인 저장 위치를 위해서는 RPG_WORLDSTATE_DB를 절대 경로로 설정해야 합니다.

MCP 구성

로컬 MCP 클라이언트는 stdio를 통해 서버를 시작할 수 있습니다. 일반적인 구성 패턴은 다음과 같습니다:

{
  "mcpServers": {
    "rpg-worldstate": {
      "command": "node",
      "args": [
        "/home/eurobertics/projects/mcp_rpg_worldstate/dist/index.js"
      ],
      "env": {
        "RPG_WORLDSTATE_DB": "/home/eurobertics/projects/mcp_rpg_worldstate/rpg-worldstate.sqlite"
      }
    }
  }
}

이 구성의 정확한 위치는 사용 중인 MCP 클라이언트에 따라 다릅니다. 서버는 MCP 프로토콜이 stdout에서 깨끗하게 유지되도록 프로토콜 메시지를 stderr에만 기록합니다.

Windows의 Claude Desktop, 서버는 WSL에 있는 경우

Claude Desktop이 Windows에서 실행되고 MCP 서버가 WSL 내부에 설치된 경우, Claude는 wsl.exe를 통해 서버를 시작할 수 있습니다. 구성은 일반적으로 다음 위치에 있습니다:

%APPDATA%\Claude\claude_desktop_config.json

예시:

{
  "mcpServers": {
    "rpg-worldstate": {
      "command": "wsl.exe",
      "args": [
        "-d",
        "Ubuntu",
        "--exec",
        "bash",
        "-lc",
        "cd /home/eurobertics/projects/mcp_rpg_worldstate && RPG_WORLDSTATE_DB=/home/eurobertics/projects/mcp_rpg_worldstate/rpg-worldstate.sqlite exec node dist/index.js"
      ]
    }
  }
}

Ubuntu는 사용 중인 WSL 배포판의 정확한 이름과 일치해야 합니다. 설치된 배포판은 PowerShell에서 다음 명령으로 확인할 수 있습니다:

wsl.exe --list --quiet

bash -lc는 로그인 셸을 로드합니다. 이는 특히 Node.js가 fnm이나 nvm 같은 버전 관리자를 통해 설치된 경우 중요합니다. 프로젝트 및 데이터베이스 경로는 WSL 내부의 Linux 경로입니다. 전체 셸 명령문은 JSON 구성에서 args의 단일 요소로 유지되어야 합니다.

시작은 Claude 구성 전에 PowerShell에서 직접 확인할 수 있습니다:

wsl.exe -d Ubuntu --exec bash -lc "cd /home/eurobertics/projects/mcp_rpg_worldstate && RPG_WORLDSTATE_DB=/home/eurobertics/projects/mcp_rpg_worldstate/rpg-worldstate.sqlite exec node dist/index.js"

성공적으로 시작되면 stderr에 예를 들어 다음과 같이 표시됩니다:

mcp-rpg-worldstate is using /home/eurobertics/projects/mcp_rpg_worldstate/rpg-worldstate.sqlite

이후 프로세스는 활성 상태를 유지하며 stdin을 통해 MCP 메시지를 기다립니다. 이것이 예상된 동작입니다. 구성 파일을 변경한 후에는 Claude Desktop을 완전히 종료하고 다시 시작해야 합니다.

ChatGPT 참고: 이 구성은 Claude Desktop의 로컬 stdio 전송을 사용합니다. ChatGPT Desktop에는 그대로 적용할 수 없습니다. 그러려면 서버가 ChatGPT가 지원하는 HTTP 전송과 접근 가능한 URL을 통해 추가로 제공되어야 합니다.

도구

엔티티 유형은 character, location, plot, note, item입니다. 캐릭터나 아이템은 locationId를 통해 현재 위치를 가질 수 있습니다. 장소는 parentId로 중첩될 수 있습니다. 장면 참여는 이와 별개입니다: 짧은 공동 장면 전환이 모든 영구 위치를 자동으로 변경할 필요는 없습니다.

배치 내 로컬 참조

Create 작업은 호출 내에서 고유한 ref를 정의할 수 있습니다. 다른 변경 사항은 참조된 Create 작업이 배열에서 나중에 있더라도 locationRef 또는 parentRef로 이를 사용할 수 있습니다:

{
  "worldId": 1,
  "changes": [
    {
      "action": "create",
      "ref": "mara",
      "kind": "character",
      "name": "Mara",
      "locationRef": "tavern"
    },
    {
      "action": "create",
      "ref": "cellar",
      "kind": "location",
      "name": "Weinkeller",
      "parentRef": "tavern"
    },
    {
      "action": "create",
      "ref": "tavern",
      "kind": "location",
      "name": "Zum hinkenden Drachen"
    }
  ],
  "summary": "Mara und ihr Gasthaus wurden eingeführt."
}

응답에는 생성된 숫자 ID가 포함된 createdRefs가 포함됩니다. 알 수 없거나, 중복되거나, 순환적인 참조 및 예를 들어 locationId와 locationRef를 동시에 지정하는 경우 전체 트랜잭션이 중단됩니다.

이벤트, 비밀 및 체크포인트

apply_world_changes의 summary는 간결한 역사적 이벤트 항목을 생성합니다. 배치가 비밀 엔티티와 관련된 경우 요약은 eventSecret: true로 비밀로 표시되거나 생략되어야 합니다. 이렇게 하면 비밀 변경이 실수로 공개 이벤트 기록에 나타날 수 없습니다.

get_recent_events는 기본적으로 id DESC 순서로 이벤트를 제공하며, 역방향 페이지네이션을 위한 beforeId, 텍스트 검색 및 sinceCheckpointId를 지원합니다. 각 체크포인트는 내부적으로 당시의 이벤트 상태를 저장하므로 "이 체크포인트 이후로 무엇이 있었나?"라는 질문에 명확하게 답할 수 있습니다.

list_checkpoints는 이전 체크포인트도 최신순으로 제공하며 beforeId로 페이지네이션합니다.

플레이어 안전 체크포인트

각 새 체크포인트는 두 가지 정보 채널을 분리합니다:

{
  "worldId": 1,
  "title": "Die Nacht im hinkenden Drachen",
  "playerRecap": "Bernd fand im Keller eine königliche Münze. Mara behauptete, sie noch nie gesehen zu haben.",
  "gmNotes": "Mara ist die verschwundene Königin."
}

• playerRecap은 필수이며 이미 관찰되었거나, 공개되었거나, 합리적으로 알려진 사실만을 위한 것입니다.

• gmNotes는 선택 사항이며 항상 게임 마스터 전용입니다.

• 숨겨진 정체성, 동기, 원인, 계획, 장소 및 미래 전개는 절대 playerRecap에 속하지 않습니다.

• 의심스러운 경우 정보는 gmNotes, 비밀 엔티티 또는 비밀 이벤트에 속하며 공개 회고에 속하지 않습니다.

서버는 콘텐츠를 자동으로 분류하거나, 정리하거나, 재구성하지 않습니다. 호출하는 AI가 올바른 분류를 담당합니다. 엔티티와 이벤트는 권위 있는 소스로 남아 있으며, 체크포인트는 간결한 내러티브 세이브 미리보기입니다.

get_world_overview와 list_checkpoints는 기본적으로 playerRecap만 반환합니다. gmNotes는 includeSecrets: true일 때만 별도 필드로 출력됩니다. 이 옵션은 권한이 있는 게임 마스터 컨텍스트에서만 사용해야 합니다. 두 텍스트는 서버에서 절대 병합되지 않습니다.

create_checkpoint에 대한 이전 입력 summary는 더 이상 허용되지 않습니다. 따라서 모든 새 클라이언트는 명시적으로 플레이어 안전 회고를 만들어야 합니다.

데이터베이스 마이그레이션

스키마는 SQLite PRAGMA user_version을 통해 버전이 관리됩니다. 서버 시작 시 이전 데이터베이스는 트랜잭션 내에서 자동으로 최신 상태로 마이그레이션됩니다. 이전 체크포인트 summary 내용은 안전을 위해 잠재적으로 비밀로 간주됩니다: gmNotes로 이동되며 공개적으로는 중립적인 알림으로만 대체됩니다. 이전 요약은 자동으로 플레이어 지식으로 공개되지 않습니다. 버전 전환 전에는 SQLite 파일의 백업을 권장합니다.

선택적 Codex 스킬

skills/rpg-worldstate-gm 아래에 절약형 로딩, 관련 상태 변경, 비밀 및 체크포인트에 대한 규칙이 포함된 작은 보조 스킬이 있습니다. MCP 서버나 다른 클라이언트에는 필요하지 않습니다.

로컬 설치를 위해 폴더를 개인 Codex 스킬 디렉터리에 복사할 수 있습니다:

cp -R skills/rpg-worldstate-gm ~/.codex/skills/

삭제 및 일관성

delete_world는 안전을 위해 정확한 확인 DELETE: <세계 이름>을 요구합니다. 그 후 SQLite는 외래 키 캐스케이드를 통해 해당 세계의 모든 캐릭터, 장소, 플롯, 장면, 체크포인트 및 이벤트를 제거합니다.

서로 다른 세계 간의 연결은 거부됩니다. 묶인 변경 사항은 트랜잭션으로 실행됩니다: 하나의 변경이 유효하지 않으면 그 중 어떤 것도 저장되지 않습니다.

개발

npm run dev
npm run check
npm test

주요 파일은 다음과 같습니다:

• src/store.ts: SQLite 스키마, 검증 및 쿼리

• src/server.ts: 공개 MCP 도구 및 입력 스키마

• src/index.ts: 로컬 stdio 진입점

• src/*.test.ts: 데이터베이스 및 MCP 프로토콜 테스트