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 加载登录 shell。当 Node.js 通过版本管理器（如 fnm 或 nvm）安装时，这一点尤其重要。项目和数据库路径是 WSL 内的 Linux 路径。完整的 shell 指令必须保持为 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 嵌套。场景参与与此分开：短暂的共同场景切换不必自动改变所有持久位置。

批量中的本地引用

创建操作可以定义在调用内唯一的 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，其中包含生成的数字 ID。未知、重复或循环引用，以及同时指定例如 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 协议测试