MCP RPG Worldstate

Локальный, системно-нейтральный MCP-сервер, который даёт ИИ-мастеру игры постоянную память для миров ролевых игр. Он хранит повествовательный контент преимущественно в виде свободного текста и структурирует только то, что важно для поиска и согласованности: принадлежность к миру, типы сущностей, места, сцены, участников и активные состояния.

Основная идея

Сохраняются постоянные или повествовательно значимые факты — а не каждое мимолётное наблюдение. Сломанное планетарное управление погодой может быть важным; причёска, изменившаяся на ветру, обычно нет.

Типичный запрос намеренно ступенчатый:

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.

Claude Desktop в Windows с сервером в 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 загружает login-оболочку. Это особенно важно, если Node.js установлен через менеджер версий, такой как fnm или nvm. Пути к проекту и базе данных — это пути Linux внутри WSL. Полная команда оболочки должна оставаться одним элементом args в JSON-конфигурации.

Запуск можно проверить прямо из PowerShell перед настройкой Claude:

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

После этого процесс остаётся активным и ожидает MCP-сообщения через stdin. Это ожидаемое поведение. После изменения файла конфигурации необходимо полностью завершить и перезапустить Claude Desktop.

Примечание для ChatGPT: Эта конфигурация использует локальный транспорт stdio от Claude Desktop. Её нельзя без изменений перенести на ChatGPT Desktop. Для этого сервер должен быть дополнительно предоставлен через поддерживаемый ChatGPT HTTP-транспорт и доступный URL.

Инструменты

Типы сущностей: character, location, plot, note и item. Персонаж или предмет может получить текущее местоположение через locationId. Места можно вкладывать с помощью parentId. Участие в сцене отделено от этого: короткая общая смена сцены не должна автоматически менять все постоянные места нахождения.

Локальные ссылки в пакете

Операции создания могут определять уникальный в рамках вызова ref. Другие изменения могут использовать его через 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."
}

Ответ содержит createdRefs с созданными числовыми идентификаторами. Неизвестные, дублирующиеся или циклические ссылки, а также одновременное указание, например, locationId и locationRef, прерывают всю транзакцию.

События, секреты и контрольные точки

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

Сервер не классифицирует, не очищает и не переформулирует содержимое автоматически. Вызывающий ИИ отвечает за правильную классификацию. Сущности и события остаются авторитетным источником; контрольные точки — это компактные повествовательные предпросмотры сохранений.

get_world_overview и list_checkpoints по умолчанию возвращают только playerRecap. gmNotes выводится только при includeSecrets: true как отдельное поле. Эта опция может использоваться только в авторизованном контексте мастера игры. Оба текста никогда не объединяются сервером.

Ранее принимавшаяся входная summary для create_checkpoint больше не поддерживается. Это заставляет каждого нового клиента явно создавать безопасный для игроков обзор.

Миграции базы данных

Схема версионируется через 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