MCP RPG Worldstate

Un servidor MCP local y neutral respecto al sistema que proporciona a una dirección de juego de IA una memoria permanente para mundos de juegos de rol. Almacena contenido narrativo principalmente como texto libre y estructura solo lo que es importante para la búsqueda y la coherencia: pertenencia al mundo, tipos de entidad, lugares, escenas, participantes y estados activos.

Idea rectora

Se almacenan hechos permanentes o narrativamente relevantes, no cualquier observación transitoria. Un control meteorológico planetario averiado puede ser importante; un peinado alterado por el viento, normalmente no.

La recuperación típica está deliberadamente escalonada:

1. list_worlds muestra las partidas existentes.

2. get_world_overview proporciona una vista previa compacta de la partida.

3. get_current_context carga la escena inmediatamente jugable.

4. search_entities obtiene más detalles solo cuando es necesario.

Los cambios se pueden agrupar con apply_world_changes en una única llamada atómica.

Las entidades recién creadas pueden referirse entre sí dentro de la misma llamada mediante referencias locales. Un archivo compacto de eventos y checkpoints explica, si es necesario, cómo se ha llegado al estado actual, sin sustituir el estado del mundo autoritativo.

Related MCP server: Librarian

Requisitos e instalación

• Node.js 24 o superior (para el módulo SQLite integrado)

• npm

npm install
npm run build
npm test

El servidor utiliza por defecto rpg-worldstate.sqlite en el directorio de trabajo. Para una ubicación de almacenamiento estable y explícita, se debe establecer RPG_WORLDSTATE_DB como ruta absoluta.

Configuración de MCP

Un cliente MCP local puede iniciar el servidor a través de stdio. El patrón general de configuración es:

{
  "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"
      }
    }
  }
}

La ubicación exacta de esta configuración depende del cliente MCP utilizado. El servidor escribe mensajes de registro exclusivamente en stderr, para que el protocolo MCP permanezca limpio en stdout.

Claude Desktop en Windows con servidor en WSL

Si Claude Desktop se ejecuta en Windows, pero el servidor MCP está instalado dentro de WSL, Claude puede iniciarlo mediante wsl.exe. La configuración se encuentra normalmente en:

%APPDATA%\Claude\claude_desktop_config.json

Ejemplo:

{
  "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 debe corresponder al nombre exacto de la distribución WSL utilizada. PowerShell muestra las distribuciones instaladas con el siguiente comando:

wsl.exe --list --quiet

bash -lc carga una shell de inicio de sesión. Esto es especialmente importante si Node.js se instaló mediante un gestor de versiones como fnm o nvm. La ruta del proyecto y de la base de datos son rutas de Linux dentro de WSL. La instrucción completa de shell debe seguir siendo un único elemento de args en la configuración JSON.

El inicio se puede comprobar directamente desde PowerShell antes de la configuración de 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"

Si el inicio es correcto, aparece en stderr, por ejemplo:

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

El proceso permanece activo y espera mensajes MCP a través de stdin. Ese es el comportamiento esperado. Después de modificar el archivo de configuración, Claude Desktop debe cerrarse por completo y reiniciarse.

Nota de ChatGPT: Esta configuración utiliza el transporte local stdio de Claude Desktop. No se puede adoptar sin cambios para ChatGPT Desktop. Para ello, el servidor tendría que ofrecerse además a través de un transporte HTTP compatible con ChatGPT y una URL accesible.

Herramientas

Los tipos de entidad son character, location, plot, note e item. Un personaje u objeto puede recibir una ubicación actual mediante locationId. Los lugares se pueden anidar con parentId. La participación en la escena es independiente de ello: un breve cambio de escena compartido no tiene que modificar automáticamente todas las ubicaciones permanentes.

Referencias locales en un lote

Las operaciones de creación pueden definir una ref única dentro de la llamada. Otros cambios pueden usarla con locationRef o parentRef, incluso si la operación de creación referenciada aparece más tarde en el array:

{
  "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."
}

La respuesta contiene createdRefs con los IDs numéricos generados. Las referencias desconocidas, duplicadas o circulares, así como la indicación simultánea de, por ejemplo, locationId y locationRef, abortan toda la transacción.

Eventos, secretos y checkpoints

Un summary en apply_world_changes genera una entrada de evento histórica compacta. En cuanto el lote afecta a una entidad secreta, el resumen debe marcarse como secreto con eventSecret: true u omitirse. Así, ningún cambio secreto puede aparecer accidentalmente en el historial público de eventos.

get_recent_events devuelve eventos por defecto en el orden id DESC, admite beforeId para la paginación hacia atrás, búsqueda de texto y sinceCheckpointId. Cada checkpoint almacena internamente el estado de eventos de ese momento, de modo que «¿Qué ocurrió desde este checkpoint?» se puede responder sin ambigüedad.

list_checkpoints devuelve también los checkpoints más antiguos, primero los más recientes, y pagina mediante beforeId.

Checkpoints seguros para jugadores

Cada nuevo checkpoint separa dos canales de información:

{
  "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 es obligatorio y está destinado exclusivamente a hechos ya observados, revelados o razonablemente conocidos.

• gmNotes es opcional y siempre está destinado exclusivamente al director de juego.

• Las identidades ocultas, motivos, causas, planes, lugares y desarrollos futuros nunca pertenecen a playerRecap.

• En caso de duda, una información pertenece a gmNotes, a una entidad secreta o a un evento secreto, no al resumen público.

El servidor no clasifica, depura ni reformula contenidos automáticamente. La IA que realiza la llamada es responsable de la clasificación correcta. Las entidades y los eventos siguen siendo la fuente autoritativa; los checkpoints son vistas previas narrativas compactas de la partida.

get_world_overview y list_checkpoints devuelven por defecto exclusivamente playerRecap. gmNotes solo se emite como campo separado con includeSecrets: true. Esta opción solo puede utilizarse en un contexto legítimo de director de juego. El servidor nunca fusiona ambos textos.

La entrada anterior summary para create_checkpoint ya no se acepta. Por lo tanto, cada nuevo cliente debe crear explícitamente un resumen seguro para los jugadores.

Migraciones de base de datos

El esquema se versiona mediante PRAGMA user_version de SQLite. Al iniciar el servidor, las bases de datos antiguas se migran automáticamente al estado actual dentro de transacciones. Los contenidos antiguos de summary de checkpoints se consideran potencialmente secretos por precaución: se trasladan a gmNotes y en público se sustituyen solo por un aviso neutral. Un resumen antiguo nunca se publica automáticamente como conocimiento de los jugadores. No obstante, antes de un cambio de versión se recomienda hacer una copia de seguridad del archivo SQLite.

Skill opcional de Codex

En skills/rpg-worldstate-gm se encuentra una pequeña skill complementaria con reglas para la carga moderada, cambios de estado relevantes, secretos y checkpoints. No es necesaria para el servidor MCP ni para otros clientes.

Para la instalación local, la carpeta se puede copiar al directorio personal de skills de Codex:

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

Eliminación y consistencia

delete_world exige por seguridad la confirmación exacta DELETE: <Weltname>. Después, SQLite elimina mediante cascadas de claves foráneas todos los personajes, lugares, tramas, escenas, checkpoints y eventos de ese mundo.

Las vinculaciones entre mundos diferentes se rechazan. Los cambios agrupados se ejecutan en una transacción: si un cambio no es válido, no se guarda ninguno de ellos.

Desarrollo

npm run dev
npm run check
npm test

Los archivos más importantes son:

• src/store.ts: esquema SQLite, validación y consultas

• src/server.ts: herramientas MCP públicas y esquemas de entrada

• src/index.ts: punto de entrada local stdio

• src/*.test.ts: pruebas de base de datos y de protocolo MCP