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クライアントによって異なります。サーバーはプロトコルメッセージをstderrにのみ書き込み、MCPプロトコルがstdoutでクリーンに保たれるようにします。

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 でページングします。

プレイヤーセーフなチェックポイント

新しい各チェックポイントは、2つの情報チャネルを分離します：

{
  "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は外部キーカスケードを介して、その世界のすべてのキャラクター、場所、プロット、シーン、チェックポイント、イベントを削除します。

異なる世界間のリンクは拒否されます。バンドルされた変更はトランザクションで実行されます：1つの変更が無効な場合、どれも保存されません。

開発

npm run dev
npm run check
npm test

最も重要なファイルは次のとおりです：

• src/store.ts：SQLiteスキーマ、検証、クエリ

• src/server.ts：公開MCPツールと入力スキーマ

• src/index.ts：ローカルstdioエントリポイント

• src/*.test.ts：データベースおよびMCPプロトコルテスト