Servidor MCP para FoundryVTT

Un servidor Model Context Protocol (MCP) completo y de nivel de producción para Foundry Virtual Tabletop (FoundryVTT).

Este servidor permite a los asistentes de IA (Claude Desktop, Claude Code, Oh My Pi, VS Code, Cursor, etc.) actuar como Co-GMs y asistentes de GM totalmente capaces y autónomos dentro de FoundryVTT. Proporciona acceso completo de lectura y escritura a mecánicas de juego, actores, objetos, tokens, encuentros de combate, placeables del lienzo (paredes, luces, sonidos, plantillas, dibujos, notas, baldosas), listas de reproducción, macros, tablas de rollo, compendios, ajustes del mundo y renderizado en vivo del lienzo.

🌟 Características y Capacidades Destacadas (111 Herramientas)

• 👁️ Flujo de Eventos en Tiempo Real y Registro de Actividad (watch_events): Conciencia de eventos sin sondeo mediante Socket.IO modifyDocument y empujes del puente complementario. Un agente DM de IA puede hacer una encuesta larga en un flujo direccionado por cursor (cursor, waitMs, excludeSelf, types, sceneId) para reaccionar al instante cuando los jugadores chatean, mueven tokens, avanzan el combate, alternan puertas o seleccionan objetivos.

• 🎲 Mecánicas de Juego y Chat Interactivo: Lanza dados con notación estándar o compleja de mantener/descartar (4d6kh3, 1d20r1). Lanza y publica tarjetas de chat interactivas y clicables directamente en el registro de chat de Foundry mediante el puente complementario (roll_and_post).

• 🗺️ Control Total del Lienzo y Espacial: Crea, inspecciona, actualiza y elimina todos los tipos de placeables del lienzo:

  • Regiones de Escena (v12+): create_region, delete_region, list_regions con formas geométricas (rectangle, circle, ellipse, polygon) y comportamientos de activación automatizados.

  • Paredes y Puertas: estándar, puertas (abrir/cerrar/bloquear), puertas secretas, ventanas, paredes etéreas y coordenadas personalizadas (create_wall, list_walls, set_door_state).

  • Luces Ambientales: colocación por coordenadas o celda de cuadrícula, radios tenue/brillante, efectos de animación, umbrales de color (create_light, update_light, delete_light, list_lights).

  • Sonidos Ambientales: pistas de audio, radios, volumen, modos de repetición (create_sound, delete_sound, list_sounds).

  • Plantillas Medidas: marcadores de área de efecto de cono, círculo, rayo y rectángulo con rotación direccional y colores (create_template, delete_template, list_templates).

  • Dibujos: formas a mano alzada y geométricas, estilo de trazo/relleno y anotaciones de texto (create_drawing, delete_drawing, list_drawings).

  • Notas y Marcadores del Mapa: marcadores de lugares vinculados a entradas de diario o etiquetas independientes (create_note, delete_note, list_notes).

  • Baldosas y Accesorios: coloca baldosas decorativas y fondos (create_tile, delete_tile, list_tiles).

  • Captura del Viewport del Lienzo: captura de pantalla del viewport del lienzo del GM con una superposición de cuadrícula de coordenadas grabada ([col,row]) mediante capture_scene.

  • Objetivos y Pings Animados: enfoca la atención de los jugadores con pings de cámara animados (ping_canvas) y ve/establece retículas de objetivos de tokens (set_target, get_targets).

• 🧙 Control de Tokens y Actores:

  • Movimiento con Búsqueda de Ruta A*: los tokens navegan alrededor de las paredes y abren automáticamente puertas cerradas en su camino (move_token_pathfind).

  • Visión e Iluminación de Tokens: configura rangos de visión, modos de visión, luz emitida tenue/brillante y ángulos de detección de visión (update_token_vision).

  • ActiveEffects Generalizados: crea, actualiza, elimina e inspecciona mejoras/penalizaciones mecánicas con cambios de atributos (key, mode, value, priority) y duraciones (rounds, seconds, turns) en actores de nivel superior o actores de token sintéticos no vinculados (create_actor_effect, update_actor_effect, delete_actor_effect, list_actor_effects).

  • Condiciones de Estado: aplica/elimina condiciones de estado independientes del sistema (apply_status_effect).

  • Importación de Actores y Objetos de Compendio: importa documentos completos de PNJ/monstruos desde paquetes de compendio con recuperación automática de errores por objeto (import_compendium_actor), o importa objetos específicos en inventarios de actores (create_actor_item).

  • Mutaciones de Atributos del Sistema: parcha los datos del sistema de actores (PG, PG temporales, moneda, recursos, espacios de conjuros) usando parches de fusión JSON (update_actor_attributes).

• ⚔️ Gestión de Encuentros de Combate: Crea encuentros, siembra combatientes desde tokens, gestiona órdenes de iniciativa, avanza turnos/rounds, rastrea combatientes activos, pausa/reanuda el reloj del juego (set_pause) y termina encuentros.

• 📜 Documentos del Mundo y Organización:

  • Carpetas: gestiona estructuras jerárquicas de carpetas para actores, objetos, diarios y escenas (create_folder, list_folders).

  • Macros: inspecciona, crea y elimina macros de script/chat (create_macro, list_macros, delete_macro).

  • Listas de Reproducción y Audio: crea listas de reproducción multipista, controla la reproducción (reproducir, pausar, detener) y ajusta los estados de las pistas (create_playlist, set_playlist_state, list_playlists).

  • Tablas de Rollo: crea tablas con distribución automática de rangos secuenciales (1dN) y saca resultados en vivo (create_roll_table, roll_table, list_roll_tables).

  • Propiedad de Documentos y Roles de Usuario: configura permisos granulares de documentos (set_document_ownership) y roles de usuario con salvaguardas de bloqueo de autodegradación (set_user_role).

  • Ajustes del Mundo: inspecciona y actualiza de forma segura ajustes de módulos y sistemas con protección integrada contra la corrupción del motor central (get_world_setting, set_world_setting).

  • Cargas de Activos: sube imágenes, tokens y audio directamente al almacenamiento Data/ de Foundry mediante FilePicker nativo o sistema de archivos local (upload_asset).

• 🌫️ Gestión de Escena, Clima y Exploración: Cambia escenas activas, ajusta niveles de oscuridad, alterna la iluminación global, establece efectos climáticos ambientales (set_scene_weather) y restablece la exploración de la Niebla de Guerra (reset_fog).

• 🔍 Búsqueda de Reglas y Compendio: Busca documentos del mundo, paquetes de compendio y texto de reglas con fragmentos contextuales (search_compendium_content, lookup_rule).

Related MCP server: Foundry VTT MCP Bridge

🏗️ Arquitectura

El servidor emplea una arquitectura híbrida para ofrecer capacidad de respuesta en tiempo real y una integración profunda con el motor del juego:

┌─────────────────────────────────────────────────────────────┐
│                    AI Assistant / MCP Client                │
│             (Claude Desktop, Oh My Pi, VS Code)             │
└──────────────────────────────┬──────────────────────────────┘
                               │ MCP (stdio)
┌──────────────────────────────▼──────────────────────────────┐
│                    FoundryVTT MCP Server                    │
├──────────────────────────────┬──────────────────────────────┤
│  In-Memory World Cache       │  A* Pathfinding Router       │
│  (Live Socket.IO Sync)       │  Dice Notation Engine        │
└──────────────┬───────────────┴──────────────┬───────────────┘
               │ Socket.IO (Port 30000)       │ WebSocket (Port 31415)
               │ (modifyDocument / Events)    │ (Bridge Protocol)
┌──────────────▼──────────────────────────────▼───────────────┐
│                    FoundryVTT Game Engine                   │
│  ┌────────────────────────┐    ┌─────────────────────────┐  │
│  │   Active World & Data  │    │  Companion Module       │  │
│  │   (Actors, Scenes, …)  │    │  (foundryvtt-mcp-bridge)│  │
│  └────────────────────────┘    └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

1. Conexión Principal Socket.IO: Se conecta a FoundryVTT como un usuario autenticado (mcp-api). Sincroniza y cachea automáticamente el estado del mundo, lo que permite búsquedas instantáneas y mutaciones de documentos de alta frecuencia mediante el protocolo modifyDocument.

2. Puente de Módulo Complementario (foundryvtt-mcp-bridge): Un módulo ligero de Foundry que se ejecuta en el navegador y ejecuta operaciones vinculadas al lienzo (captura de pantalla del lienzo PIXI con superposición de cuadrícula, renderizado nativo de tarjetas de chat Roll, introspección de esquemas de documentos y extracción de objetos de compendio).

3. Módulo REST API Opcional: Proporciona diagnósticos del servidor, recuperación de registros e informes de salud cuando el módulo REST local está instalado.

🚀 Inicio Rápido

1. Requisitos Previos

• Node.js 18+ o Bun

• FoundryVTT v11+ / v12+ ejecutando un mundo activo

• Una cuenta de usuario dedicada de Foundry con rol de Gamemaster o Assistant GM

2. Configurar Usuario Dedicado de Foundry

En FoundryVTT:

1. Abre Configuración → Gestión de Usuarios

2. Haz clic en Crear Usuario

3. Establece Nombre de usuario: mcp-api, Contraseña: mcp (o tu elección)

4. Rol: Gamemaster (o Assistant GM con permisos de escritura habilitados)

3. Instalar el Módulo Complementario (Recomendado)

Copia la carpeta foundry-module de este repositorio a tu directorio Data/modules/ de FoundryVTT:

# Windows
cp -r foundry-module "%LOCALAPPDATA%/FoundryVTT/Data/modules/foundryvtt-mcp-bridge"

# macOS
cp -r foundry-module "~/Library/Application Support/FoundryVTT/Data/modules/foundryvtt-mcp-bridge"

# Linux
cp -r foundry-module "~/.local/share/FoundryVTT/Data/modules/foundryvtt-mcp-bridge"

En FoundryVTT, ve a Gestionar Módulos y habilita FoundryVTT MCP Bridge.

⚙️ Configuración y Configuración del Cliente

Variables de Entorno

Configuración de Claude Desktop

Agrega a claude_desktop_config.json:

{
  "mcpServers": {
    "foundryvtt": {
      "command": "node",
      "args": ["<PATH_TO_REPO>/dist/index.js"],
      "env": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_USERNAME": "mcp-api",
        "FOUNDRY_PASSWORD": "mcp",
        "FOUNDRY_WRITE_ENABLED": "true",
        "FOUNDRY_MODULE_BRIDGE_ENABLED": "true",
        "FOUNDRY_MODULE_BRIDGE_PORT": "31415"
      }
    }
  }
}

Configuración de Oh My Pi

Agrega a ~/.omp/agent/mcp.json (o ~/.omp/mcp.json):

{
  "mcpServers": {
    "foundryvtt": {
      "type": "stdio",
      "command": "node",
      "args": ["<PATH_TO_REPO>/dist/index.js"],
      "env": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_USERNAME": "mcp-api",
        "FOUNDRY_PASSWORD": "mcp",
        "FOUNDRY_WRITE_ENABLED": "true",
        "FOUNDRY_MODULE_BRIDGE_ENABLED": "true",
        "FOUNDRY_MODULE_BRIDGE_PORT": "31415"
      },
      "timeout": 60000
    }
  }
}

🛠️ Catálogo de Herramientas (111 Herramientas)

1. Conciencia de Eventos en Tiempo Real

• watch_events — sondeo largo de un registro de actividad direccionado por cursor (cursor, waitMs, limit, kinds, types, actions, sceneId, excludeSelf) que captura transmisiones de documentos y actividad del lienzo sin sondeo.

2. Lienzo y Placeables Espaciales

• create_region / delete_region / list_regions — gestiona Regiones de Escena (v12+) con formas geométricas (rectangle, circle, ellipse, polygon) y comportamientos automatizados.

• create_wall / delete_wall / list_walls / set_door_state — gestión completa de geometría de paredes y puertas.

• create_light / update_light / delete_light / list_lights — control de iluminación ambiental (radios, colores, animaciones).

• create_sound / delete_sound / list_sounds — colocación de audio ambiental en escenas del lienzo.

• create_template / delete_template / list_templates — plantillas de área de efecto para hechizos y efectos.

• create_drawing / delete_drawing / list_drawings — formas del mapa, zonas y anotaciones de texto.

• create_note / delete_note / list_notes — marcadores y pines del mapa.

• create_tile / delete_tile / list_tiles — baldosas decorativas y accesorios del mapa.

• capture_scene — captura de pantalla del lienzo de la escena activa con una superposición de coordenadas de cuadrícula grabada.

• ping_canvas — emite un ping animado en el lienzo en coordenadas de píxel específicas.

• find_open_cells — escanea escenas en busca de celdas de cuadrícula desbloqueadas adecuadas para colocación de tokens/accesorios.

• list_scene_assets — descubre fondos de mapas, arte de tokens y archivos de audio con etiquetas y dimensiones analizadas.

• upload_asset — sube archivos de imagen/audio al directorio Data/ de Foundry mediante FilePicker o sistema de archivos local.

• spawn_token — colocar fichas de actor en escenas con tamaño, elevación y coordenadas personalizados.

• delete_token — eliminar fichas de las escenas sin borrar el actor subyacente.

• list_tokens — listar las fichas colocadas en escenas activas o específicas.

• move_token — teletransportar una ficha a coordenadas de píxel exactas.

• move_token_pathfind — mover fichas mediante evitación de obstáculos A* alrededor de muros con apertura automática de puertas.

• move_tokens — mover varias fichas a la vez en lote.

• set_target / get_targets — establecer e inspeccionar las retículas de apuntado de fichas entre los usuarios conectados.

• update_token_vision — configurar rangos de visión, modos de visión, luces emitidas tenues/brillantes y ángulos.

• apply_status_effect — alternar condiciones de estado simples (prone, stunned, blinded, invisible, etc.).

4. Actores e Inventario

• create_world_actor / create_full_actor / delete_world_actor — crear y eliminar documentos de actor.

• import_compendium_actor — importar PNJ/monstruos completos desde paquetes de compendio con objetos integrados y recuperación automática de errores.

• search_actors — consultar actores por nombre y tipo con soporte de paginación por cursor.

• get_actor_details — recuperar los datos del sistema del actor, estadísticas, atributos y salud.

• update_actor_attributes — aplicar parches a datos anidados del sistema mediante rutas de puntos (attributes.hp.value, currency.gp).

• get_actor_inventory — listar los objetos en propiedad con todas sus propiedades del sistema.

• create_actor_item — crear objetos en línea O importarlos directamente desde paquetes de compendio (source: { type: 'compendium', compendiumId, itemId }).

• update_actor_item — aplicar parches de fusión JSON a los objetos en propiedad del actor.

• delete_actor_item — eliminar objetos específicos de los inventarios de los actores.

• create_actor_effect / update_actor_effect / delete_actor_effect / list_actor_effects — efectos activos de propósito general con cambios mecánicos (key, mode, value, priority) y duraciones en actores de nivel superior o actores sintéticos de fichas no vinculadas.

5. Encuentros de Combate

• start_combat — crear encuentros y generar combatientes a partir de las fichas de la escena.

• get_combat_state — recuperar el orden de turno de los combatientes, los PV, la CA y el número de ronda.

• set_initiative — establecer los valores de iniciativa de los combatientes y reordenar los turnos.

• next_turn — avanzar el marcador de turno (gestiona los incrementos de ronda y omite combatientes derrotados).

• set_pause — pausar o reanudar el reloj del juego.

• end_combat — finalizar encuentros activos.

6. Documentos del Mundo y Organización

• list_folders / create_folder — organizar actores, objetos, diarios y escenas en carpetas anidadas.

• list_macros / create_macro / delete_macro — gestionar documentos de macros de script y de chat.

• list_playlists / create_playlist / set_playlist_state / delete_playlist — listas de reproducción de audio y controles de sonido.

• create_roll_table / delete_roll_table / roll_table / list_roll_tables — creación de tablas y tiradas de resultados.

• get_world_setting / set_world_setting — inspeccionar y modificar ajustes de sistema/módulo con protección del núcleo.

• set_document_ownership — configurar permisos granulares de documentos (none, limited, observer, owner).

• get_users / set_user_role — listar usuarios conectados y cambiar roles de permiso con salvaguardas de bloqueo por autodegradación.

• create_journal_entry / get_journal / search_journals / delete_journal_entry — gestionar notas de sesión y trasfondo.

7. Escena, Clima y Exploración

• create_scene / delete_scene / get_scene_info / switch_scene — creación de escenas y activación para jugadores.

• set_scene_weather — establecer o eliminar efectos meteorológicos (rain, snow, fog, "").

• set_scene_lighting — niveles de oscuridad ambiental y ajustes de iluminación global.

• reset_fog — restablecer la exploración de la niebla de guerra en escenas activas.

8. Mecánicas del Juego y Herramientas de Puente

• roll_dice — evaluación local de fórmulas matemáticas de dados.

• roll_and_post — evaluar fórmulas mediante el motor nativo de Foundry y publicar tarjetas de chat interactivas.

• lookup_rule — buscar reglas en los diarios del mundo y en los paquetes de compendio del sistema con vistas previas de fragmentos.

• get_document_schema — inspeccionar los esquemas del DataModel del sistema para tipos de actor y objeto.

• search_compendium_content — buscar en profundidad dentro de los documentos de los paquetes de compendio y las páginas de diario.

• send_chat_message / get_chat_messages — publicar y leer mensajes del registro de chat de Foundry.

• generate_npc / generate_loot — generadores procedimentales instantáneos.

9. Diagnósticos y Registro

• get_health_status / get_system_health — métricas de salud de la conexión y del servidor.

• get_recent_logs / search_logs — inspeccionar registros del servidor y trazas de pila de errores.

• diagnose_errors — analizar errores recientes y convertirlos en sugerencias de resolución priorizadas.

• refresh_world_data — forzar la reobtención de la instantánea en caché del estado del mundo.

🧪 Desarrollo y Pruebas

# Install dependencies
npm install

# Compile TypeScript
npm run build

# Run complete unit test suite (713 tests)
npm test

# Run linter and formatting checks
npm run lint

# Start server in development watch mode
npm run dev

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT.