FoundryVTT MCP Server

Полнофункциональный, готовый к продакшену сервер Model Context Protocol (MCP) для Foundry Virtual Tabletop (FoundryVTT).

Этот сервер позволяет ИИ-ассистентам (Claude Desktop, Claude Code, Oh My Pi, VS Code, Cursor и др.) выступать в роли полноценных, автономных со-ГМ и помощников ГМ внутри FoundryVTT. Он предоставляет полный доступ на чтение и запись к игровой механике, актёрам, предметам, токенам, боевым столкновениям, объектам канваса (стены, свет, звук, шаблоны, рисунки, заметки, тайлы), плейлистам, макросам, таблицам бросков, компендиумам, мировым настройкам и живому рендерингу канваса.

🌟 Ключевые возможности и функции (111 инструментов)

• 👁️ Поток событий в реальном времени и журнал активности (watch_events): Осведомлённость о событиях без опроса через Socket.IO modifyDocument и сопутствующие push-уведомления моста. ИИ-ГМ может выполнять длинный опрос потока с курсором (cursor, waitMs, excludeSelf, types, sceneId), чтобы мгновенно реагировать, когда игроки общаются в чате, перемещают токены, продвигают бой, переключают двери или выбирают цели.

• 🎲 Игровая механика и интерактивный чат: Бросайте кости с использованием стандартной или сложной нотации с отбрасыванием/сохранением (4d6kh3, 1d20r1). Бросайте и публикуйте интерактивные, кликабельные карточки в чат Foundry через мост-компаньон (roll_and_post).

• 🗺️ Полный контроль канваса и пространства: Создавайте, просматривайте, обновляйте и удаляйте все типы объектов канваса:

  • Регионы сцен (v12+): create_region, delete_region, list_regions с геометрическими формами (rectangle, circle, ellipse, polygon) и автоматизированным поведением триггеров.

  • Стены и двери: стандартные, двери (открыть/закрыть/запереть), секретные двери, окна, эфирные стены и пользовательские координаты (create_wall, list_walls, set_door_state).

  • Окружающий свет: размещение по координатам или ячейкам сетки, радиусы тусклого/яркого света, эффекты анимации, пороги цвета (create_light, update_light, delete_light, list_lights).

  • Окружающие звуки: аудиодорожки, радиусы, громкость, режимы повтора (create_sound, delete_sound, list_sounds).

  • Шаблоны областей: конус, круг, луч и прямоугольник для областей действия заклинаний с вращением и цветами (create_template, delete_template, list_templates).

  • Рисунки: произвольные и геометрические фигуры, стили обводки/заливки и текстовые аннотации (create_drawing, delete_drawing, list_drawings).

  • Заметки на карте и булавки: маркеры достопримечательностей, связанные с записями журнала или отдельные метки (create_note, delete_note, list_notes).

  • Тайлы и реквизит: размещение декоративных тайлов и фонов (create_tile, delete_tile, list_tiles).

  • Захват области просмотра канваса: снимок экрана области просмотра ГМ с наложенной сеткой координат ([col,row]) через capture_scene.

  • Целеуказание и анимированные пинги: привлечение внимания игроков с помощью анимированных пингов камеры (ping_canvas) и просмотр/установка прицелов наведения на токены (set_target, get_targets).

• 🧙 Управление токенами и актёрами:

  • Движение с поиском пути A*: токены обходят стены и автоматически открывают закрытые двери на своём пути (move_token_pathfind).

  • Зрение и освещение токенов: настройка дальности обзора, режимов зрения, излучаемого тусклого/яркого света и углов обнаружения (update_token_vision).

  • Обобщённые активные эффекты: создание, обновление, удаление и просмотр механических баффов/дебаффов с изменениями атрибутов (key, mode, value, priority) и длительностью (rounds, seconds, turns) на верхнеуровневых или синтетических актёрах без связи с токеном (create_actor_effect, update_actor_effect, delete_actor_effect, list_actor_effects).

  • Статусные эффекты: применение/снятие системно-независимых статусных эффектов (apply_status_effect).

  • Импорт актёров и предметов из компендиума: импорт целых NPC/монстров из пакетов компендиума с автоматическим восстановлением после ошибок по каждому предмету (import_compendium_actor) или импорт конкретных предметов в инвентарь актёра (create_actor_item).

  • Изменения системных атрибутов: изменение данных системы актёра (HP, временные HP, валюта, ресурсы, ячейки заклинаний) с помощью JSON merge-патчей (update_actor_attributes).

• ⚔️ Управление боевыми столкновениями: Создание столкновений, добавление участников из токенов, управление порядком инициативы, продвижение ходов/раундов, отслеживание активных участников, пауза/возобновление игрового времени (set_pause) и завершение столкновений.

• 📜 Мировые документы и организация:

  • Папки: управление иерархическими структурами папок для актёров, предметов, журналов и сцен (create_folder, list_folders).

  • Макросы: просмотр, создание и удаление скриптовых/чатовых макросов (create_macro, list_macros, delete_macro).

  • Плейлисты и аудио: создание многодорожечных плейлистов, управление воспроизведением (play, pause, stop) и изменение состояний дорожек (create_playlist, set_playlist_state, list_playlists).

  • Таблицы бросков: создание таблиц с автоматическим распределением последовательных диапазонов (1dN) и получение живых результатов (create_roll_table, roll_table, list_roll_tables).

  • Права владения документами и роли пользователей: настройка детальных прав на документы (set_document_ownership) и ролей пользователей с защитой от само-понижения (set_user_role).

  • Мировые настройки: безопасный просмотр и обновление настроек модулей и систем со встроенной защитой от повреждения ядра движка (get_world_setting, set_world_setting).

  • Загрузка ресурсов: загрузка изображений, токенов и аудио непосредственно в хранилище Data/ Foundry через нативный FilePicker или локальную файловую систему (upload_asset).

• 🌫️ Управление сценами, погодой и исследованием: Переключение активных сцен, регулировка уровня темноты, включение глобального освещения, установка эффектов погоды (set_scene_weather) и сброс тумана войны (reset_fog).

• 🔍 Поиск правил и компендиума: Поиск по мировым документам, пакетам компендиума и тексту правил с контекстными фрагментами (search_compendium_content, lookup_rule).

Related MCP server: Foundry VTT MCP Bridge

🏗️ Архитектура

Сервер использует гибридную архитектуру для обеспечения отзывчивости в реальном времени и глубокой интеграции с игровым движком:

┌─────────────────────────────────────────────────────────────┐
│                    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. Основное соединение Socket.IO: Подключается к FoundryVTT как аутентифицированный пользователь (mcp-api). Автоматически синхронизирует и кэширует состояние мира, обеспечивая мгновенные запросы и высокочастотные мутации документов через протокол modifyDocument.

2. Мост-компаньон (foundryvtt-mcp-bridge): Лёгкий модуль Foundry, работающий в браузере, который выполняет операции, связанные с канвасом (снимок экрана PIXI с сеткой, нативный рендеринг карточек чата Roll, интроспекция схемы документов и извлечение предметов из компендиума).

3. Опциональный модуль REST API: Предоставляет диагностику сервера, получение журналов и отчёты о состоянии при установке локального REST-модуля.

🚀 Быстрый старт

1. Предварительные требования

• Node.js 18+ или Bun

• FoundryVTT v11+ / v12+ с запущенным активным миром

• Отдельная учётная запись Foundry с ролью Гейммастер или Помощник ГМ

2. Настройка выделенного пользователя Foundry

В FoundryVTT:

1. Откройте Configuration → User Management

2. Нажмите Create User

3. Установите имя пользователя: mcp-api, пароль: mcp (или на ваш выбор)

4. Роль: Гейммастер (или Помощник ГМ с включёнными правами на запись)

3. Установка модуля-компаньона (рекомендуется)

Скопируйте папку foundry-module из этого репозитория в каталог Data/modules/ вашего 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"

В FoundryVTT перейдите в Manage Modules и включите FoundryVTT MCP Bridge.

⚙️ Конфигурация и настройка клиента

Переменные окружения

Конфигурация Claude Desktop

Добавьте в 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"
      }
    }
  }
}

Конфигурация Oh My Pi

Добавьте в ~/.omp/agent/mcp.json (или ~/.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
    }
  }
}

🛠️ Каталог инструментов (111 инструментов)

1. Осведомлённость о событиях в реальном времени

• watch_events — длинный опрос журнала активности с курсором (cursor, waitMs, limit, kinds, types, actions, sceneId, excludeSelf) для захвата трансляций документов и активности канваса без опроса.

2. Канвас и пространственные объекты

• create_region / delete_region / list_regions — управление регионами сцен (v12+) с геометрическими формами (rectangle, circle, ellipse, polygon) и автоматизированным поведением.

• create_wall / delete_wall / list_walls / set_door_state — полное управление геометрией стен и дверей.

• create_light / update_light / delete_light / list_lights — управление окружающим освещением (радиусы, цвета, анимации).

• create_sound / delete_sound / list_sounds — размещение окружающего аудио на сценах канваса.

• create_template / delete_template / list_templates — шаблоны областей действия заклинаний и эффектов.

• create_drawing / delete_drawing / list_drawings — фигуры на карте, зоны и текстовые аннотации.

• create_note / delete_note / list_notes — булавки на карте и маркеры достопримечательностей.

• create_tile / delete_tile / list_tiles — декоративные тайлы и реквизит карты.

• capture_scene — снимок экрана активной сцены с наложенной сеткой координат.

• ping_canvas — отправка анимированного пинга на канвас по указанным пиксельным координатам.

• find_open_cells — сканирование сцен на предмет свободных ячеек сетки, подходящих для размещения токенов/реквизита.

• list_scene_assets — обнаружение фонов карт, изображений токенов и аудиофайлов с разобранными тегами и размерами.

• upload_asset — загрузка файлов изображений/аудио в каталог Data/ Foundry через FilePicker или локальную файловую систему.

3. Токены и движение

• spawn_token — размещает токены актёров на сценах с заданным размером, высотой и координатами.

• delete_token — удаляет токены со сцен без удаления базового актёра.

• list_tokens — выводит список размещённых токенов на активной или конкретных сценах.

• move_token — телепортирует токен в точные пиксельные координаты.

• move_token_pathfind — перемещает токены с обходом препятствий A* вокруг стен и автоматическим открытием дверей.

• move_tokens — пакетное перемещение нескольких токенов одновременно.

• set_target / get_targets — установка и просмотр прицельных ретикул токенов у подключённых пользователей.

• update_token_vision — настройка радиусов обзора, режимов зрения, тусклого/яркого излучаемого света и углов.

• apply_status_effect — переключение простых состояний (prone, stunned, blinded, invisible и т.д.).

4. Актёры и инвентарь

• create_world_actor / create_full_actor / delete_world_actor — создание и удаление документов актёров.

• import_compendium_actor — импорт целых NPC/монстров из компендиум-паков со встроенными предметами и автоматическим восстановлением после ошибок.

• search_actors — поиск актёров по имени и типу с поддержкой курсорной пагинации.

• get_actor_details — получение системных данных актёра, характеристик, атрибутов и здоровья.

• update_actor_attributes — изменение вложенных системных данных через точечные пути (attributes.hp.value, currency.gp).

• get_actor_inventory — список принадлежащих предметов с полными системными свойствами.

• create_actor_item — создание встроенных предметов ИЛИ импорт напрямую из компендиум-паков (source: { type: 'compendium', compendiumId, itemId }).

• update_actor_item — применение JSON merge-патчей к принадлежащим предметам.

• delete_actor_item — удаление конкретных предметов из инвентарей актёров.

• create_actor_effect / update_actor_effect / delete_actor_effect / list_actor_effects — универсальные ActiveEffects с механическими изменениями (key, mode, value, priority) и длительностями для актёров верхнего уровня или синтетических актёров несвязанных токенов.

5. Боевые столкновения

• start_combat — создание столкновений и наполнение участниками из токенов сцены.

• get_combat_state — получение порядка ходов участников, HP, AC и номера раунда.

• set_initiative — установка значений инициативы участников и переупорядочивание ходов.

• next_turn — продвижение трекера ходов (обрабатывает увеличение номера раунда и пропуск побеждённых участников).

• set_pause — пауза или возобновление игрового времени.

• end_combat — завершение активных столкновений.

6. Документы мира и организация

• list_folders / create_folder — организация актёров, предметов, журналов и сцен во вложенных папках.

• list_macros / create_macro / delete_macro — управление документами скриптовых и чат-макросов.

• list_playlists / create_playlist / set_playlist_state / delete_playlist — аудиоплейлисты и управление звуком.

• create_roll_table / delete_roll_table / roll_table / list_roll_tables — создание таблиц и бросок результатов.

• get_world_setting / set_world_setting — просмотр и изменение настроек систем/модулей с защитой ядра.

• set_document_ownership — настройка детальных прав доступа к документам (none, limited, observer, owner).

• get_users / set_user_role — список подключённых пользователей и изменение ролей с защитой от само-понижения.

• create_journal_entry / get_journal / search_journals / delete_journal_entry — управление заметками сессий и лором.

7. Сцены, погода и исследование

• create_scene / delete_scene / get_scene_info / switch_scene — создание сцен и активация для игроков.

• set_scene_weather — установка или сброс погодных эффектов (rain, snow, fog, "").

• set_scene_lighting — уровень окружающей темноты и глобальные настройки освещения.

• reset_fog — сброс исследования Туман войны на активных сценах.

8. Игровая механика и инструменты моста

• roll_dice — локальное математическое вычисление формулы броска.

• roll_and_post — вычисление формул через нативный движок Foundry и публикация интерактивных карточек в чат.

• lookup_rule — поиск правил в журналах мира и системных компендиум-паках с предпросмотром фрагментов.

• get_document_schema — интроспекция схем DataModel игровой системы для типов актёров и предметов.

• search_compendium_content — глубокий поиск внутри документов компендиум-паков и страниц журналов.

• send_chat_message / get_chat_messages — публикация и чтение сообщений из журнала чата Foundry.

• generate_npc / generate_loot — мгновенные процедурные генераторы.

9. Диагностика и журналирование

• get_health_status / get_system_health — метрики подключения и здоровья сервера.

• get_recent_logs / search_logs — просмотр журналов сервера и стеков ошибок.

• diagnose_errors — анализ недавних ошибок с приоритизированными предложениями по устранению.

• refresh_world_data — принудительное повторное получение кэшированного снимка состояния мира.

🧪 Разработка и тестирование

# 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

📄 Лицензия

Этот проект распространяется под лицензией MIT License.