@g33ks/foundryvtt-mcp 0.0.0-stage โ 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +22 -0
- package/README.md +468 -2
- package/dist/character/manager.js +208 -0
- package/dist/cli/checks.js +307 -0
- package/dist/cli/config-file.js +120 -0
- package/dist/cli/init.js +410 -0
- package/dist/cli/prompt.js +117 -0
- package/dist/cli/snippets.js +49 -0
- package/dist/combat/manager.js +371 -0
- package/dist/config/env-layers.js +49 -0
- package/dist/config/index.js +298 -0
- package/dist/config/sources.js +201 -0
- package/dist/core.js +415 -0
- package/dist/diagnostics/client.js +353 -0
- package/dist/diagnostics/types.js +94 -0
- package/dist/foundry/auth.js +220 -0
- package/dist/foundry/browser-detect.js +170 -0
- package/dist/foundry/client.js +5555 -0
- package/dist/foundry/dice-formula.js +154 -0
- package/dist/foundry/event-log.js +299 -0
- package/dist/foundry/headless-gm-session.js +740 -0
- package/dist/foundry/journal-history.js +90 -0
- package/dist/foundry/journal-integrity.js +306 -0
- package/dist/foundry/module-bridge.js +413 -0
- package/dist/foundry/types.js +52 -0
- package/dist/foundry/world-cache.js +386 -0
- package/dist/index.js +107 -0
- package/dist/mcp-server.js +63 -0
- package/dist/server.js +159 -0
- package/dist/shared/build-order.js +134 -0
- package/dist/shared/config-hash.js +62 -0
- package/dist/shared/config-notice.js +55 -0
- package/dist/shared/control.js +255 -0
- package/dist/shared/daemon-link.js +135 -0
- package/dist/shared/daemon.js +313 -0
- package/dist/shared/ipc-client.js +200 -0
- package/dist/shared/ipc-server.js +316 -0
- package/dist/shared/paths.js +79 -0
- package/dist/shared/protocol.js +230 -0
- package/dist/shared/relay-config.js +65 -0
- package/dist/shared/relay.js +120 -0
- package/dist/shared/rotating-log.js +57 -0
- package/dist/shared/spawn.js +39 -0
- package/dist/shared/state-file.js +33 -0
- package/dist/shared/token.js +62 -0
- package/dist/shared/version.js +57 -0
- package/dist/tools/base.js +74 -0
- package/dist/tools/definitions.js +3109 -0
- package/dist/tools/handlers/actor-mutations.js +128 -0
- package/dist/tools/handlers/actors.js +114 -0
- package/dist/tools/handlers/chat-mutations.js +49 -0
- package/dist/tools/handlers/chat.js +36 -0
- package/dist/tools/handlers/combat-mutations.js +215 -0
- package/dist/tools/handlers/combat-order.js +94 -0
- package/dist/tools/handlers/combat.js +51 -0
- package/dist/tools/handlers/compendium.js +83 -0
- package/dist/tools/handlers/diagnostics.js +438 -0
- package/dist/tools/handlers/dice.js +54 -0
- package/dist/tools/handlers/effects.js +103 -0
- package/dist/tools/handlers/events.js +50 -0
- package/dist/tools/handlers/generation.js +258 -0
- package/dist/tools/handlers/item-mutations.js +132 -0
- package/dist/tools/handlers/items.js +53 -0
- package/dist/tools/handlers/journal-mutations.js +230 -0
- package/dist/tools/handlers/journals.js +80 -0
- package/dist/tools/handlers/module-bridge.js +421 -0
- package/dist/tools/handlers/placeable-mutations.js +272 -0
- package/dist/tools/handlers/resources.js +203 -0
- package/dist/tools/handlers/roll-tables.js +97 -0
- package/dist/tools/handlers/scene-mutations.js +159 -0
- package/dist/tools/handlers/scenes.js +355 -0
- package/dist/tools/handlers/settings.js +53 -0
- package/dist/tools/handlers/tile-mutations.js +56 -0
- package/dist/tools/handlers/token-mutations.js +356 -0
- package/dist/tools/handlers/users.js +59 -0
- package/dist/tools/handlers/utils.js +47 -0
- package/dist/tools/handlers/wall-mutations.js +98 -0
- package/dist/tools/handlers/world-documents.js +222 -0
- package/dist/tools/handlers/world.js +92 -0
- package/dist/tools/index.js +25 -0
- package/dist/tools/new-router.js +97 -0
- package/dist/tools/registry.js +79 -0
- package/dist/tools/resources.js +63 -0
- package/dist/tools/router.js +688 -0
- package/dist/tools/write-tools.js +97 -0
- package/dist/utils/cache-instance.js +30 -0
- package/dist/utils/cache.js +205 -0
- package/dist/utils/diagnostics.js +332 -0
- package/dist/utils/guards.js +17 -0
- package/dist/utils/image-size.js +160 -0
- package/dist/utils/log-args.js +47 -0
- package/dist/utils/logger.js +203 -0
- package/dist/utils/refusal.js +30 -0
- package/dist/utils/sanitize.js +22 -0
- package/dist/utils/serial-queue.js +22 -0
- package/package.json +124 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Lauri Gates
|
|
4
|
+
Copyright (c) 2026 G33ks
|
|
5
|
+
|
|
6
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
7
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
8
|
+
in the Software without restriction, including without limitation the rights
|
|
9
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
10
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
11
|
+
furnished to do so, subject to the following conditions:
|
|
12
|
+
|
|
13
|
+
The above copyright notice and this permission notice shall be included in all
|
|
14
|
+
copies or substantial portions of the Software.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
17
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
18
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
19
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
20
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
21
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
22
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,469 @@
|
|
|
1
|
-
#
|
|
1
|
+
# FoundryVTT MCP Server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://github.com/G33ks/foundryvtt-mcp/actions/workflows/test.yml)
|
|
4
|
+
[](https://github.com/G33ks/foundryvtt-mcp/actions/workflows/security.yml)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[](https://nodejs.org/)
|
|
7
|
+
[](https://www.typescriptlang.org/)
|
|
8
|
+
[](https://modelcontextprotocol.io/)
|
|
9
|
+
|
|
10
|
+
A comprehensive, production-grade [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for **Foundry Virtual Tabletop (FoundryVTT)**.
|
|
11
|
+
|
|
12
|
+
This server empowers AI assistants (Claude Desktop, Claude Code, Oh My Pi, VS Code, Cursor, etc.) to act as fully capable, autonomous **Co-GMs and GM assistants** inside FoundryVTT. It provides complete read and write access across game mechanics, actors, items, tokens, combat encounters, canvas placeables (walls, lights, sounds, templates, drawings, notes, tiles), playlists, macros, roll tables, compendiums, world settings, and live canvas rendering.
|
|
13
|
+
|
|
14
|
+
**To install it, follow the [Quick Start](#-quick-start)** โ seven steps, from Foundry to a working connector in Claude.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## ๐งญ How it works
|
|
19
|
+
|
|
20
|
+
```mermaid
|
|
21
|
+
flowchart LR
|
|
22
|
+
subgraph PC["Your computer"]
|
|
23
|
+
C1["AI client<br/>(Claude Desktop, Claude Codeโฆ)"] -->|"MCP (stdio)"| R1["Relay"]
|
|
24
|
+
C2["Another AI client"] -->|"MCP (stdio)"| R2["Relay"]
|
|
25
|
+
R1 & R2 -->|"named pipe /<br/>Unix socket"| D["Shared process"]
|
|
26
|
+
D -->|"launches"| B["Invisible GM browser<br/>+ companion module"]
|
|
27
|
+
D <-->|"bridge WebSocket<br/>(loopback, authenticated)"| B
|
|
28
|
+
end
|
|
29
|
+
subgraph S["Foundry server (local or remote)"]
|
|
30
|
+
F["FoundryVTT world"]
|
|
31
|
+
end
|
|
32
|
+
D -->|"Socket.IO:<br/>read & write documents"| F
|
|
33
|
+
B -->|"loads the game page<br/>as a GM user"| F
|
|
34
|
+
D -.->|"HTTP (optional):<br/>REST API module"| F
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Your AI assistant starts a small relay program for this server. Every relay, from one assistant or several, hands its requests to the same background process, which keeps a single connection to Foundry open. That process reads and changes the world through Foundry's normal connection, the one any player's browser uses. Some things only a real Foundry page can do: capturing the canvas, rolling dice with Foundry's own engine, reading compendium documents, uploading files, pausing the game. For those, the background process runs an invisible browser, sharing its own Foundry session, where the companion module runs. The module talks only to that process, and only after each has proven its identity to the other.
|
|
38
|
+
|
|
39
|
+
**Technical details:**
|
|
40
|
+
|
|
41
|
+
- **Live world cache**: on connect, the server loads the world over Socket.IO and keeps it in memory; every `modifyDocument` broadcast โ from the AI's own writes or from any user in Foundry โ updates it, so reads are instant and stay current. `refresh_world_data` forces a full reload.
|
|
42
|
+
- **Socket.IO connection**: authenticates as `FOUNDRY_USERNAME` (Assistant GM role recommended) and performs every write over Foundry's core `modifyDocument` protocol โ only when `FOUNDRY_WRITE_ENABLED=true`. It is the only side that logs in: when Foundry forgets its session (server restart, world shut down) it logs in again by itself, retrying every 5 s at first and at most every 2 min, and tool calls made meanwhile wait up to 15 s before being refused with the reason.
|
|
43
|
+
- **Invisible GM session**: started when `FOUNDRY_MODULE_BRIDGE_ENABLED=true`. The shared process drives a background browser through `playwright-core`: the first one found among Chrome, Edge, Brave, Vivaldi, a system Chromium and Playwright's own Chromium (`npx playwright install chromium`), or the Chromium-based browser set in `FOUNDRY_HEADLESS_GM_EXECUTABLE_PATH`. The page shares the Socket.IO connection's session โ one account, one login โ and never fills the `/join` form: Foundry keeps several connections per session, so neither ejects the other. The page stays on `/game` (a navigation elsewhere, such as **Log Out**, is blocked and the page reloads `/game`, because leaving would log the shared session out). A watchdog reloads the page if the module stays disconnected for about a minute. Advanced: `FOUNDRY_HEADLESS_GM_USERNAME` / `FOUNDRY_HEADLESS_GM_PASSWORD` naming another account give the page its own login instead. A human can meanwhile play as a normal **Player** in their own browser.
|
|
44
|
+
- **Companion module** (`foundryvtt-mcp-bridge`, 0.5.0 or later): runs only in that GM session and serves the bridge tools โ `capture_scene` (canvas screenshot with a grid overlay), `roll_and_post` (native `Roll` chat cards), `get_document_schema`, `search_compendium_content` and compendium imports, `upload_asset` (FilePicker), `set_pause`, `ping_canvas`, `set_target` / `get_targets`. Without it these tools report unavailable; everything else keeps working. The bridge listens on loopback only and authenticates the module โ see [Module Bridge Security](#module-bridge-security).
|
|
45
|
+
- **Optional REST API module**: with `FOUNDRY_API_KEY` set, the server also connects to the Foundry Local REST API module over HTTP. It backs the diagnostics tools (`get_health_status`, `get_system_health`, `get_recent_logs`, `search_logs`, `diagnose_errors`) and `search_compendium`, and some reads use it instead of the cache (actor and item search, actor details, scene and world info, `roll_dice`). Socket.IO stays the main connection and carries every write.
|
|
46
|
+
- **Shared process** (default): MCP clients may start several server instances โ Claude Desktop starts several at launch โ so each instance is only a lightweight relay, and the FoundryVTT connection, the bridge and the GM session live once, in a background process every relay shares. See [Shared Process Mode](#shared-process-mode); `FOUNDRY_MCP_SHARED=false` runs everything in one process instead.
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## ๐ Key Highlights & Capabilities (114 Tools)
|
|
51
|
+
|
|
52
|
+
- ๐๏ธ **Real-Time Event Stream & Activity Log (`watch_events`)**: Zero-polling event awareness via Socket.IO `modifyDocument` and companion bridge pushes. An AI DM agent can long-poll on a cursor-addressed stream (`cursor`, `waitMs`, `excludeSelf`, `types`, `sceneId`) to react instantly when players chat, move tokens, advance combat, toggle doors, or select targets.
|
|
53
|
+
- ๐ฒ **Game Mechanics & Interactive Chat**: Roll dice with standard or complex drop/keep notation (`4d6kh3`, `1d20r1`). Roll and post interactive, clickable chat cards directly to the Foundry chat log via the companion bridge (`roll_and_post`).
|
|
54
|
+
- ๐บ๏ธ **Full Canvas & Spatial Control**: Create, inspect, update, and remove all canvas placeable types:
|
|
55
|
+
- **Scene Regions (v12+)**: `create_region`, `delete_region`, `list_regions` with geometric shapes (`rectangle`, `circle`, `ellipse`, `polygon`) and automated trigger behaviors.
|
|
56
|
+
- **Walls & Doors**: standard, doors (open/close/lock), secret doors, windows, ethereal walls, and custom coordinates (`create_wall`, `list_walls`, `set_door_state`).
|
|
57
|
+
- **Ambient Lights**: coordinate or grid-cell placement, dim/bright radii, animation effects, color thresholds (`create_light`, `update_light`, `delete_light`, `list_lights`).
|
|
58
|
+
- **Ambient Sounds**: audio tracks, radii, volume, repeat modes (`create_sound`, `delete_sound`, `list_sounds`).
|
|
59
|
+
- **Measured Templates**: cone, circle, ray, and rect spell area-of-effect markers with directional rotation and colors (`create_template`, `delete_template`, `list_templates`).
|
|
60
|
+
- **Drawings**: freehand and geometrical shapes, stroke/fill styling, and text annotations (`create_drawing`, `delete_drawing`, `list_drawings`).
|
|
61
|
+
- **Map Notes & Pins**: landmark markers linked to journal entries or standalone labels (`create_note`, `delete_note`, `list_notes`).
|
|
62
|
+
- **Tiles & Props**: place decorative tiles and backgrounds (`create_tile`, `delete_tile`, `list_tiles`).
|
|
63
|
+
- **Canvas Viewport Capture**: screenshot the GM canvas viewport with a burned-in coordinate grid overlay (`[col,row]`) via `capture_scene`.
|
|
64
|
+
- **Targeting & Animated Pings**: focus player attention with animated camera pings (`ping_canvas`) and view/set token targeting reticles (`set_target`, `get_targets`).
|
|
65
|
+
- ๐ง **Token & Actor Control**:
|
|
66
|
+
- **A\* Pathfinding Movement**: tokens navigate around walls and automatically open closed doors along their path (`move_token_pathfind`).
|
|
67
|
+
- **Token Vision & Lighting**: configure sight ranges, vision modes, dim/bright emitted light, and vision detection angles (`update_token_vision`).
|
|
68
|
+
- **Generalized ActiveEffects**: create, update, delete, and inspect mechanical buffs/debuffs with attribute changes (`key`, `mode`, `value`, `priority`) and durations (`rounds`, `seconds`, `turns`) on top-level or synthetic unlinked token actors (`create_actor_effect`, `update_actor_effect`, `delete_actor_effect`, `list_actor_effects`).
|
|
69
|
+
- **Status Conditions**: apply/remove system-agnostic status conditions (`apply_status_effect`).
|
|
70
|
+
- **Compendium Actor & Item Import**: import entire NPC/monster documents from compendium packs with automatic per-item error recovery (`import_compendium_actor`), or import specific items into actor inventories (`create_actor_item`).
|
|
71
|
+
- **System Attribute Mutations**: patch actor system data (HP, temporary HP, currency, resources, spell slots) using JSON merge patches (`update_actor_attributes`).
|
|
72
|
+
- โ๏ธ **Combat Encounter Management**: Create encounters, seed combatants from tokens, manage initiative orders, advance turns/rounds, track active combatants, pause/unpause the game clock (`set_pause`), and end encounters.
|
|
73
|
+
- ๐ **World Documents & Organization**:
|
|
74
|
+
- **Folders**: manage hierarchical folder structures for actors, items, journals, and scenes (`create_folder`, `list_folders`).
|
|
75
|
+
- **Macros**: inspect, create, and delete script/chat macros (`create_macro`, `list_macros`, `delete_macro`).
|
|
76
|
+
- **Playlists & Audio**: create multi-track playlists, control playback (play, pause, stop), and adjust track states (`create_playlist`, `set_playlist_state`, `list_playlists`).
|
|
77
|
+
- **Roll Tables**: create tables with automatic sequential range distribution (`1dN`), and draw live results (`create_roll_table`, `roll_table`, `list_roll_tables`).
|
|
78
|
+
- **Document Ownership & User Roles**: configure granular document permissions (`set_document_ownership`) and user roles with self-demotion lockout guards (`set_user_role`).
|
|
79
|
+
- **World Settings**: safely inspect and update module and system settings with built-in protection against core engine corruption (`get_world_setting`, `set_world_setting`).
|
|
80
|
+
- **Asset Uploads**: upload images, tokens, and audio directly into Foundry's `Data/` storage via native FilePicker or local filesystem (`upload_asset`).
|
|
81
|
+
- ๐ซ๏ธ **Scene, Weather & Exploration Management**: Switch active scenes, adjust darkness levels, toggle global illumination, set environmental weather effects (`set_scene_weather`), and reset Fog of War exploration (`reset_fog`).
|
|
82
|
+
- ๐ **Rules & Compendium Search**: Search world documents, compendium packs, and rule text with contextual snippets (`search_compendium_content`, `lookup_rule`).
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## ๐ Quick Start
|
|
86
|
+
|
|
87
|
+
Seven steps, in this order. [SETUP_GUIDE.md](SETUP_GUIDE.md) gives the details of each one; [TROUBLESHOOTING.md](TROUBLESHOOTING.md) helps when a step fails.
|
|
88
|
+
|
|
89
|
+
### 1. Check the prerequisites
|
|
90
|
+
|
|
91
|
+
- **Node.js 22 or newer** (current LTS recommended), with npm โ `node --version` shows yours. Download it from [nodejs.org](https://nodejs.org/).
|
|
92
|
+
- **FoundryVTT v13 or v14**, with a world you can open as its Gamemaster. Foundry may run on this computer or on a server.
|
|
93
|
+
- **A Chromium-based browser** on this computer: Google Chrome, Microsoft Edge, Brave, Vivaldi or Chromium. The server finds it by itself; you will never see it open.
|
|
94
|
+
- **Claude desktop** or **Claude Code**.
|
|
95
|
+
|
|
96
|
+
### 2. Install the companion module
|
|
97
|
+
|
|
98
|
+
On Foundry's **Setup** screen (the one listing your worlds; from a running world, **Game Settings** โ **Return to Setup**). Foundry may first ask for its administrator password, the one set when Foundry was installed, not a user's password:
|
|
99
|
+
|
|
100
|
+
1. Open **Add-on Modules** โ **Install Module**.
|
|
101
|
+
2. Paste this URL into the **Manifest URL** field at the bottom, then click **Install**:
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
https://raw.githubusercontent.com/G33ks/foundryvtt-mcp/main/foundry-module/module.json
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Updates and the manual copy: see [SETUP_GUIDE.md](SETUP_GUIDE.md#2-install-companion-module-foundryvtt-mcp-bridge).
|
|
108
|
+
|
|
109
|
+
### 3. In the world: create the user, then enable the module
|
|
110
|
+
|
|
111
|
+
Launch your world and log in as its Gamemaster.
|
|
112
|
+
|
|
113
|
+
1. **Create a dedicated user**: **Game Settings** โ **User Management** โ **Create Additional User**. Name it `mcp-api` (or any name), give it a **long password used nowhere else**, set its role to **Assistant GM**, then save.
|
|
114
|
+
2. **Enable the module**: **Game Settings** โ **Manage Modules**, check **FoundryVTT MCP Bridge**, then click **Save Module Settings**. The world reloads; log in again if Foundry asks.
|
|
115
|
+
|
|
116
|
+
This one account is all the server needs. Prefer **Assistant GM** to **Gamemaster**: as a Gamemaster, the server's invisible session could take the *active GM* role from you โ see [SETUP_GUIDE.md](SETUP_GUIDE.md#3-in-the-world-create-a-dedicated-user-and-enable-the-module).
|
|
117
|
+
|
|
118
|
+
### 4. Install the server
|
|
119
|
+
|
|
120
|
+
In a terminal (PowerShell, Terminal on macOS, any shell on Linux):
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
npm install -g @g33ks/foundryvtt-mcp
|
|
124
|
+
foundryvtt-mcp --version
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
In Windows PowerShell, if `npm` is refused with *running scripts is disabled on this system*, type `npm.cmd` instead of `npm`. `npm` may print warnings (a blocked install script, funding messages); they do not stop the install. `foundryvtt-mcp --version` prints the installed version.
|
|
128
|
+
|
|
129
|
+
- **The package is `@g33ks/foundryvtt-mcp`.** The unscoped `foundryvtt-mcp` package on npm is the original project's, no longer this one.
|
|
130
|
+
- **Install it globally** rather than running it through `npx`: npx keeps packages in a cache that npm replaces or deletes, so `init` prints no client entry from there.
|
|
131
|
+
- **To work on the code**, from a clone: see [CONTRIBUTING.md](CONTRIBUTING.md); in the commands of this guide, use `node dist/index.js` (from the clone) instead of `foundryvtt-mcp`.
|
|
132
|
+
|
|
133
|
+
### 5. Run `init`
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
foundryvtt-mcp init
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
It asks for Foundry's address (the URL you open Foundry with in your browser, such as `http://localhost:30000` or `https://foundry.example.com`), the account from step 3 and whether the assistant may change the game (no by default), checking each answer against your Foundry: world running, account role, module enabled, browser. Then it writes the [configuration file](#configuration-file), the only place your settings live, and prints what to give your AI client. Details: [SETUP_GUIDE.md](SETUP_GUIDE.md#5-run-init).
|
|
140
|
+
|
|
141
|
+
The client entries it prints name two absolute paths: the Node.js that ran `init` and the installed server. **After changing or updating Node.js** (nvm, a new installer), run `foundryvtt-mcp init` again and replace the entries.
|
|
142
|
+
|
|
143
|
+
### 6. Add the server to Claude
|
|
144
|
+
|
|
145
|
+
Use what `init` printed at the end:
|
|
146
|
+
|
|
147
|
+
- **Claude desktop**: **Settings** โ **Developer** โ **Edit Config** opens `claude_desktop_config.json`. Add the `foundryvtt` entry printed by `init` under `"mcpServers"` (keep any entries already there), save, then **quit Claude desktop completely** (also from the notification area or menu bar) and start it again.
|
|
148
|
+
- **Claude Code**: run the `claude mcp add foundryvtt โฆ` command printed by `init` in a terminal, then start a new Claude Code session.
|
|
149
|
+
|
|
150
|
+
No `env` block is needed: the settings are in the configuration file.
|
|
151
|
+
|
|
152
|
+
### 7. Check that it works
|
|
153
|
+
|
|
154
|
+
1. In the terminal: `foundryvtt-mcp init --check`. It should end with `All checks passed.`; a โ line says what to fix.
|
|
155
|
+
2. In Claude, ask: *"Show the FoundryVTT connector's health status."* Claude calls `get_health_status` (allow the tool when Claude asks), which should show the FoundryVTT connection โ
, the module bridge โ
connected with an authenticated module, the headless GM session logged in with its browser, and the configuration file the settings come from.
|
|
156
|
+
|
|
157
|
+
The first call can take a few seconds while the server connects. If something is โ, the message says why; see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
|
|
158
|
+
|
|
159
|
+
> **Playing as a human while the AI GMs?** No extra setup needed. Log into your own Foundry client as a **Player** โ or as your own **Gamemaster**: with `mcp-api` an Assistant GM, you stay the active GM. The server opens its own invisible background browser session with `mcp-api`'s session for GM-tier canvas access (screenshots, dice rolls, pausing, uploads); only `mcp-api` appears in the player list for it. The module bridge requires this session: a GM tab you open yourself never connects to it (see [Module Bridge Security](#module-bridge-security)).
|
|
160
|
+
|
|
161
|
+
### Updating
|
|
162
|
+
|
|
163
|
+
1. Close your AI clients (quit Claude desktop completely).
|
|
164
|
+
2. In a terminal:
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
npm install -g @g33ks/foundryvtt-mcp@latest
|
|
168
|
+
foundryvtt-mcp stop
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
`stop` ends the shared process still running the previous version; `foundryvtt-mcp --version` shows the new one.
|
|
172
|
+
3. Start your clients again. Their entries stay valid: the installed server keeps its path. The companion module updates separately, from Foundry's Setup screen ([SETUP_GUIDE.md](SETUP_GUIDE.md#2-install-companion-module-foundryvtt-mcp-bridge)).
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
## โ๏ธ Configuration & Client Setup
|
|
177
|
+
|
|
178
|
+
### Configuration File
|
|
179
|
+
|
|
180
|
+
Every MCP client on the machine shares **one configuration file**, so a client entry needs only the command and its arguments โ no `env` block:
|
|
181
|
+
|
|
182
|
+
| System | Location |
|
|
183
|
+
| :--- | :--- |
|
|
184
|
+
| Windows | `%LOCALAPPDATA%\foundryvtt-mcp\config.env` (next to the shared process's state) |
|
|
185
|
+
| macOS, Linux | `$XDG_CONFIG_HOME/foundryvtt-mcp/config.env`, or `~/.config/foundryvtt-mcp/config.env` |
|
|
186
|
+
|
|
187
|
+
`FOUNDRY_MCP_CONFIG` names another file and wins over everything; with `FOUNDRY_MCP_STATE_DIR` set, the file is `<that directory>/config.env` (a fully isolated setup, for tests).
|
|
188
|
+
|
|
189
|
+
**The easy way** is `foundryvtt-mcp init` ([Quick Start](#5-run-init), step 5): it writes the file after checking each answer against your FoundryVTT. `foundryvtt-mcp init --check` re-runs the checks on the existing file, without asking or writing anything.
|
|
190
|
+
|
|
191
|
+
By hand: one `KEY=value` per line, with exactly the names of the variables below; `#` starts a comment:
|
|
192
|
+
|
|
193
|
+
```env
|
|
194
|
+
FOUNDRY_URL=https://foundry.example.com
|
|
195
|
+
FOUNDRY_USERNAME=mcp-api
|
|
196
|
+
FOUNDRY_PASSWORD='your password'
|
|
197
|
+
FOUNDRY_WRITE_ENABLED=true
|
|
198
|
+
FOUNDRY_MODULE_BRIDGE_ENABLED=true
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
- **Quote values**: put each value between `'โฆ'`; if it contains an apostrophe, between `` `โฆ` ``. Unquoted, a `#` cuts the value (the rest is a comment) and surrounding spaces are dropped. Nothing is escaped inside quotes.
|
|
202
|
+
- **Passwords** are stored in clear: the file is for your user only. On macOS and Linux the server warns when others may read it (`chmod 600` it). They never appear in logs or in `status` (shown as `<set>`).
|
|
203
|
+
- **Priority, setting by setting**: an environment variable (the client's `env` block, or the system) wins, then a `.env` in the working directory (for development), then the file, then the default. `foundryvtt-mcp status` shows where each setting comes from.
|
|
204
|
+
- **After editing the file**, run `foundryvtt-mcp stop`: the next call starts the shared process with the new settings. A client whose relay was waiting for a configuration needs nothing: its next call reads the file.
|
|
205
|
+
- **The file is authoritative**: a client that still passes its own `env` block is served with the configuration the shared process runs, and its first tool result says which of its settings are ignored and where they come from (see [Shared Process Mode](#shared-process-mode)).
|
|
206
|
+
- **No configuration at all**: the server still starts and lists its tools; each call says where the file is expected and what it needs (`FOUNDRY_URL`, `FOUNDRY_USERNAME`, `FOUNDRY_PASSWORD`) โ see [SETUP_GUIDE.md](SETUP_GUIDE.md#the-configuration-file).
|
|
207
|
+
|
|
208
|
+
### Environment Variables
|
|
209
|
+
|
|
210
|
+
The same names work in the configuration file, in an `env` block, in the system environment or in a development `.env`.
|
|
211
|
+
|
|
212
|
+
| Variable | Required | Default | Description |
|
|
213
|
+
| :--- | :--- | :--- | :--- |
|
|
214
|
+
| `FOUNDRY_URL` | **Yes** | `http://localhost:30000` | FoundryVTT server URL |
|
|
215
|
+
| `FOUNDRY_USERNAME` | **Yes** | โ | FoundryVTT user account name |
|
|
216
|
+
| `FOUNDRY_PASSWORD` | **Yes** | โ | FoundryVTT user account password |
|
|
217
|
+
| `FOUNDRY_WRITE_ENABLED` | No | `false` | Enables game-state mutations (walls, actors, tokens, etc.) |
|
|
218
|
+
| `FOUNDRY_MODULE_BRIDGE_ENABLED` | No | `false` | Enables WebSocket bridge for canvas screenshots & chat rolls |
|
|
219
|
+
| `FOUNDRY_MODULE_BRIDGE_PORT` | No | `31415` | WebSocket port for the companion module bridge |
|
|
220
|
+
| `FOUNDRY_HEADLESS_GM_ENABLED` | No | `true` | Auto-launches an invisible GM-tier browser session to host the module bridge. Required for the bridge: with `false` the companion module never connects (manually opened GM tabs are not supported) and a warning is logged at startup |
|
|
221
|
+
| `FOUNDRY_HEADLESS_GM_USERNAME` | No | โ | Advanced two-account mode: another account the headless session logs in as through `/join`. Unset (or equal to `FOUNDRY_USERNAME`), the session shares the connector's own session |
|
|
222
|
+
| `FOUNDRY_HEADLESS_GM_PASSWORD` | No | `FOUNDRY_PASSWORD` | Password of that other account (two-account mode only) |
|
|
223
|
+
| `FOUNDRY_HEADLESS_GM_EXECUTABLE_PATH` | No | โ | Path to any Chromium-based browser binary (Chrome, Edge, Brave, Vivaldiโฆ), skipping auto-detection |
|
|
224
|
+
| `FOUNDRY_DATA_PATH` | No | โ | Local path to Foundry `Data/` for asset dimension discovery |
|
|
225
|
+
| `FOUNDRY_API_KEY` | No | โ | Optional REST API key for server diagnostics tools |
|
|
226
|
+
| `FOUNDRY_EVENT_BUFFER_SIZE` | No | `500` | In-memory event log ring buffer capacity |
|
|
227
|
+
| `FOUNDRY_EVENT_WAIT_MS` | No | `25000` | Default long-polling timeout for `watch_events` |
|
|
228
|
+
| `LOG_LEVEL` | No | `info` | Logging verbosity (`debug`, `info`, `warn`, `error`) |
|
|
229
|
+
| `FOUNDRY_MCP_SHARED` | No | `true` | Shared-process mode; `false` makes every instance own its own connection, bridge and browser (all-in-one) |
|
|
230
|
+
| `FOUNDRY_MCP_IDLE_TIMEOUT_MINUTES` | No | `5` | Minutes the shared process stays up with **no relay connected** before exiting (it disconnects from FoundryVTT then); `0` = never |
|
|
231
|
+
| `FOUNDRY_MCP_STATE_DIR` | No | see below | Directory for the shared process's token, state file and logs; a non-default directory also gets its own pipe (an isolated shared process) and its own `config.env`. Environment or `.env` only |
|
|
232
|
+
| `FOUNDRY_MCP_CONFIG` | No | see [Configuration File](#configuration-file) | Path of the configuration file. Environment or `.env` only |
|
|
233
|
+
|
|
234
|
+
#### Choosing the Headless GM Browser
|
|
235
|
+
|
|
236
|
+
Without `FOUNDRY_HEADLESS_GM_EXECUTABLE_PATH`, the server looks at the usual install locations for Google Chrome, then Microsoft Edge, Brave, Vivaldi, a system Chromium, and last Playwright's own Chromium (only present after `npx playwright install chromium`), and uses the first one that starts. `status` and `get_health_status` show which (`detected`). To choose the browser โ another Chromium-based one, or one installed elsewhere โ point the variable at its executable in the configuration file; it is then used with no fallback (`configured`):
|
|
237
|
+
|
|
238
|
+
```env
|
|
239
|
+
FOUNDRY_HEADLESS_GM_EXECUTABLE_PATH='C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe'
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
In a JSON `env` block instead, Windows backslashes must be doubled; forward slashes (`C:/Program Files/...`) work everywhere and need no escaping. The headless browser is launched with Chromium's local network access checks disabled so the module can reach `ws://localhost` from the Foundry page โ see [TROUBLESHOOTING.md](TROUBLESHOOTING.md#module-bridge-never-connects--websocket--failed).
|
|
243
|
+
|
|
244
|
+
### Shared Process Mode
|
|
245
|
+
|
|
246
|
+
By default `foundryvtt-mcp` is a **relay**: it answers `initialize` and `tools/list` immediately and forwards `tools/call` and `resources/read` to a **shared process** (`foundryvtt-mcp daemon`) that holds the FoundryVTT connection, the module bridge and the headless GM session.
|
|
247
|
+
|
|
248
|
+
- **Automatic start**: the first relay that finds no shared process starts one in the background (detached, so it survives the client closing or restarting the relay) and waits for it โ up to ~30 s. Relays started at the same time end up sharing a single process. Relays connect as soon as they start, so the FoundryVTT connection and the GM session are ready before the first tool call.
|
|
249
|
+
- **Lifetime**: the shared process stays up while at least one relay is connected, however long it goes without calls. It exits `FOUNDRY_MCP_IDLE_TIMEOUT_MINUTES` (5 by default) after the last client closes, on `stop`, when a relay of a newer version connects (or, for the same version, of a later install or rebuild), or when a relay whose settings match a changed configuration file connects โ it then lets running calls finish and the relay starts a fresh one. Closing and reopening a client within that delay keeps the same process and the same FoundryVTT connection. A call that was already running always completes, even if the client that asked for it went away.
|
|
250
|
+
- **FoundryVTT not reachable yet**: the shared process stays up, returns the connection error to the call, and retries on the next call โ start FoundryVTT before or after your AI client, in any order. With FoundryVTT up but no world launched, it retries by itself in the background (every 5 s at first, at most every 2 min) and connects as soon as the world is launched.
|
|
251
|
+
- **Writes**: tools that change game state run one at a time, in arrival order; reads run in parallel.
|
|
252
|
+
- **Commands**:
|
|
253
|
+
|
|
254
|
+
```bash
|
|
255
|
+
foundryvtt-mcp status # pid, version, uptime, FoundryVTT / bridge / GM session state, relays, log path
|
|
256
|
+
foundryvtt-mcp stop # finish running calls, then stop the shared process
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
They only read the state directory, so they work from any terminal โ no FoundryVTT configuration needed.
|
|
260
|
+
- **State directory**: `%LOCALAPPDATA%\foundryvtt-mcp\` on Windows, `$XDG_STATE_HOME/foundryvtt-mcp/` (or `~/.local/state/foundryvtt-mcp/`) elsewhere. It holds the access token relays must present (`token`), the state file (`daemon.json`) and the logs (`daemon.log`, `relay.log`, rotated at 5 MB ร 3). Relays reach the shared process through the named pipe `\\.\pipe\foundryvtt-mcp-<user>` (Windows) or a Unix socket in the state directory.
|
|
261
|
+
- **One configuration for every client**: put the settings in the [configuration file](#configuration-file) and leave the clients' `env` blocks out. The connection settings (URL, account, passwords, API key, socket path, writes, bridge, headless GM session, data path) decide which shared process serves a client:
|
|
262
|
+
- a relay with the file's settings as it is now, while the running process was started differently (the file changed, or another client's `env` block started it), restarts the process once with the file's settings;
|
|
263
|
+
- any other difference โ a client still passing its own `env` block โ is served with the running configuration, never restarted: the client's first tool result names its ignored settings, and `status` lists them;
|
|
264
|
+
- other settings (`LOG_LEVEL`, timeouts, idle delayโฆ) never matter: the shared process's own apply.
|
|
265
|
+
- **Configuration source**: Claude Desktop starts MCP servers with `C:\Windows\System32` as working directory, where no `.env` file is looked up, and passes only a few Windows variables besides the `env` block; Claude Code passes its whole environment. The shared process inherits the environment and working directory of the relay that starts it, and reads the configuration file itself.
|
|
266
|
+
- **Module bridge**: listens on loopback only (`127.0.0.1` and `::1`); the module reaches it at `ws://localhost:<port>` from the headless browser on the same machine, and authenticates โ see [Module Bridge Security](#module-bridge-security).
|
|
267
|
+
|
|
268
|
+
### Module Bridge Security
|
|
269
|
+
|
|
270
|
+
The bridge drives a GM session, and its loopback port is reachable by every local process and every page open in a local browser. So the server and the companion module (0.5.0 or later) authenticate each other, with nothing to configure:
|
|
271
|
+
|
|
272
|
+
- **Origin**: the WebSocket upgrade is refused (HTTP 403) unless its `Origin` header is the origin of `FOUNDRY_URL` โ a page from another site cannot open the socket.
|
|
273
|
+
- **Mutual handshake (protocol v1)**: the server sends a random challenge; the module answers with an HMAC-SHA256 proof, and the server answers with its own proof, which the module checks before obeying. Both are keyed by a random secret the shared process generates at startup and keeps in memory only โ never written to disk, logged or returned by a tool. The headless GM session exposes a `window.foundryMcpBridge` function to its page (a Playwright binding) that computes the proofs, so the secret never enters the page or the WebSocket. It disappears with the shared process.
|
|
274
|
+
- **Until authenticated**, a connection receives no command, nothing it sends is processed, and it cannot displace the connected module. It is closed with `4401` (wrong proof, unknown protocol, any other message), `4408` (no answer within 5 s โ typically a module older than 0.5.0, logged as such) or `1009` (a message over 4 KiB). Refusals are logged as warnings (rate-limited); `status` and `get_health_status` show whether an authenticated module is connected.
|
|
275
|
+
- **No manual GM tab**: a GM tab opened by hand has no `window.foundryMcpBridge`, so the module logs `no foundryvtt-mcp credentials in this browser, bridge disabled` to the browser console and stays silent. `FOUNDRY_HEADLESS_GM_ENABLED=false` therefore disables the bridge in practice.
|
|
276
|
+
- **Check it**: with the connector running and the module connected, `npm run check:bridge-security`, from a clone, tries four forged connections and confirms each is refused while the module stays connected.
|
|
277
|
+
|
|
278
|
+
### Client entries
|
|
279
|
+
|
|
280
|
+
A client entry starts Node.js on the installed server, both by their absolute path: MCP clients may start servers with a reduced `PATH` and an undefined working directory. `foundryvtt-mcp init` prints the entries with the right paths. By hand:
|
|
281
|
+
|
|
282
|
+
- `<NODE>`: what `node -p process.execPath` prints, such as `C:\Program Files\nodejs\node.exe` or `/usr/local/bin/node`;
|
|
283
|
+
- `<ENTRY>`: what `npm root -g` prints, followed by `/@g33ks/foundryvtt-mcp/dist/index.js` โ such as `C:\Users\you\AppData\Roaming\npm\node_modules\@g33ks\foundryvtt-mcp\dist\index.js`. From a clone, `<clone>/dist/index.js`.
|
|
284
|
+
|
|
285
|
+
In JSON, double each Windows backslash, or write forward slashes. After changing or updating Node.js, `<NODE>` changes: run `foundryvtt-mcp init` again.
|
|
286
|
+
|
|
287
|
+
### Claude Desktop Configuration
|
|
288
|
+
|
|
289
|
+
With the settings in the [configuration file](#configuration-file), add to `claude_desktop_config.json`:
|
|
290
|
+
|
|
291
|
+
```json
|
|
292
|
+
{
|
|
293
|
+
"mcpServers": {
|
|
294
|
+
"foundryvtt": {
|
|
295
|
+
"command": "<NODE>",
|
|
296
|
+
"args": ["<ENTRY>"]
|
|
297
|
+
}
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
### Claude Code Configuration
|
|
303
|
+
|
|
304
|
+
`claude mcp add foundryvtt --scope user -- "<NODE>" "<ENTRY>"` (all your projects; `--scope local` for the current project only), or in `~/.claude.json` (or a project's `.mcp.json`):
|
|
305
|
+
|
|
306
|
+
```json
|
|
307
|
+
{
|
|
308
|
+
"mcpServers": {
|
|
309
|
+
"foundryvtt": {
|
|
310
|
+
"type": "stdio",
|
|
311
|
+
"command": "<NODE>",
|
|
312
|
+
"args": ["<ENTRY>"]
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
}
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
**Alternative, not recommended:** an `env` block in a client entry still works (its values win over the file for that client), but the shared process serves every client with one configuration, so a client whose `env` block disagrees is told its settings are ignored โ see [Shared Process Mode](#shared-process-mode).
|
|
319
|
+
|
|
320
|
+
### Oh My Pi Configuration
|
|
321
|
+
|
|
322
|
+
Add to `~/.omp/agent/mcp.json` (or `~/.omp/mcp.json`):
|
|
323
|
+
|
|
324
|
+
```json
|
|
325
|
+
{
|
|
326
|
+
"mcpServers": {
|
|
327
|
+
"foundryvtt": {
|
|
328
|
+
"type": "stdio",
|
|
329
|
+
"command": "<NODE>",
|
|
330
|
+
"args": ["<ENTRY>"],
|
|
331
|
+
"timeout": 60000
|
|
332
|
+
}
|
|
333
|
+
}
|
|
334
|
+
}
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
---
|
|
338
|
+
|
|
339
|
+
## ๐ ๏ธ Tool Catalog (114 Tools)
|
|
340
|
+
|
|
341
|
+
### 1. Real-Time Event Awareness
|
|
342
|
+
- `watch_events` โ long-poll a cursor-addressed activity log (`cursor`, `waitMs`, `limit`, `kinds`, `types`, `actions`, `sceneId`, `excludeSelf`) capturing document broadcasts and canvas activity without polling.
|
|
343
|
+
|
|
344
|
+
### 2. Canvas & Spatial Placeables
|
|
345
|
+
- `create_region` / `delete_region` / `list_regions` โ manage Scene Regions (v12+) with geometric shapes (`rectangle`, `circle`, `ellipse`, `polygon`) and automated behaviors.
|
|
346
|
+
- `create_wall` / `delete_wall` / `list_walls` / `set_door_state` โ complete wall and door geometry management.
|
|
347
|
+
- `create_light` / `update_light` / `delete_light` / `list_lights` โ ambient lighting control (radii, colors, animations).
|
|
348
|
+
- `create_sound` / `delete_sound` / `list_sounds` โ ambient audio placement on canvas scenes.
|
|
349
|
+
- `create_template` / `delete_template` / `list_templates` โ spell and effect area-of-effect templates.
|
|
350
|
+
- `create_drawing` / `delete_drawing` / `list_drawings` โ map shapes, zones, and text annotations.
|
|
351
|
+
- `create_note` / `delete_note` / `list_notes` โ map pins and landmark markers.
|
|
352
|
+
- `create_tile` / `delete_tile` / `list_tiles` โ decorative tiles and map props.
|
|
353
|
+
- `capture_scene` โ screenshot the active scene canvas with a grid coordinate overlay burned in.
|
|
354
|
+
- `ping_canvas` โ emit an animated canvas ping at specific pixel coordinates.
|
|
355
|
+
- `find_open_cells` โ scan scenes for unblocked grid cells suitable for token/prop placement.
|
|
356
|
+
- `list_scene_assets` โ discover map backgrounds, token art, and audio files with parsed tags and dimensions.
|
|
357
|
+
- `upload_asset` โ upload image/audio files into Foundry's `Data/` directory via FilePicker or local filesystem.
|
|
358
|
+
|
|
359
|
+
### 3. Tokens & Movement
|
|
360
|
+
- `spawn_token` โ place actor tokens on scenes with custom size, elevation, and coordinates.
|
|
361
|
+
- `delete_token` โ remove tokens from scenes without deleting the underlying actor.
|
|
362
|
+
- `list_tokens` โ list placed tokens on active or specific scenes.
|
|
363
|
+
- `move_token` โ teleport a token to exact pixel coordinates.
|
|
364
|
+
- `move_token_pathfind` โ move tokens using A* obstacle avoidance around walls with automatic door opening.
|
|
365
|
+
- `move_tokens` โ batch move multiple tokens simultaneously.
|
|
366
|
+
- `set_target` / `get_targets` โ set and inspect token targeting reticles across connected users.
|
|
367
|
+
- `update_token_vision` โ configure vision ranges, vision modes, dim/bright emitted lights, and angles.
|
|
368
|
+
- `apply_status_effect` โ toggle simple status conditions (`prone`, `stunned`, `blinded`, `invisible`, etc.).
|
|
369
|
+
|
|
370
|
+
### 4. Actors & Inventory
|
|
371
|
+
- `create_world_actor` / `create_full_actor` / `delete_world_actor` โ create and delete actor documents.
|
|
372
|
+
- `import_compendium_actor` โ import entire NPCs/monsters from compendium packs with embedded items and automatic error recovery.
|
|
373
|
+
- `search_actors` โ query actors by name and type with cursor pagination support.
|
|
374
|
+
- `get_actor_details` โ retrieve actor system data, statistics, attributes, and health.
|
|
375
|
+
- `update_actor_attributes` โ patch nested system data using dot paths (`attributes.hp.value`, `currency.gp`).
|
|
376
|
+
- `get_actor_inventory` โ list owned items with full system properties.
|
|
377
|
+
- `search_items` โ search world item documents by name, optionally filtered by type (world items, not owned items).
|
|
378
|
+
- `create_actor_item` โ create inline items OR import directly from compendium packs (`source: { type: 'compendium', compendiumId, itemId }`).
|
|
379
|
+
- `update_actor_item` โ apply JSON merge patches to owned items.
|
|
380
|
+
- `delete_actor_item` โ delete specific items from actor inventories.
|
|
381
|
+
- `create_actor_effect` / `update_actor_effect` / `delete_actor_effect` / `list_actor_effects` โ general-purpose ActiveEffects with mechanical changes (`key`, `mode`, `value`, `priority`) and durations on top-level or synthetic unlinked token actors.
|
|
382
|
+
|
|
383
|
+
### 5. Combat Encounters
|
|
384
|
+
- `start_combat` โ create encounters and seed combatants from scene tokens.
|
|
385
|
+
- `get_combat_state` โ retrieve combatant turn order, HP, AC, and round number.
|
|
386
|
+
- `set_initiative` โ set combatant initiative values and re-order turns.
|
|
387
|
+
- `next_turn` โ advance the turn tracker (handles round increments and skips defeated combatants).
|
|
388
|
+
- `set_pause` โ pause or unpause the game clock.
|
|
389
|
+
- `end_combat` โ terminate active encounters.
|
|
390
|
+
|
|
391
|
+
### 6. World Documents & Organization
|
|
392
|
+
- `list_folders` / `create_folder` โ organize actors, items, journals, and scenes in nested folders.
|
|
393
|
+
- `list_macros` / `create_macro` / `delete_macro` โ manage script and chat macro documents.
|
|
394
|
+
- `list_playlists` / `create_playlist` / `set_playlist_state` / `delete_playlist` โ audio playlist and sound controls.
|
|
395
|
+
- `create_roll_table` / `delete_roll_table` / `roll_table` / `list_roll_tables` โ table creation and result rolling.
|
|
396
|
+
- `get_world_setting` / `set_world_setting` โ inspect and modify system/module settings with core protection.
|
|
397
|
+
- `set_document_ownership` โ configure granular document permissions (`none`, `limited`, `observer`, `owner`).
|
|
398
|
+
- `get_world_summary` โ world metadata (title, game system, core version) and per-collection document counts.
|
|
399
|
+
- `search_world` โ search actors, items, scenes, and journals by name at once, grouped by collection.
|
|
400
|
+
- `get_users` / `set_user_role` โ list connected users and change permission roles with self-demotion lockout guards.
|
|
401
|
+
- `create_journal_entry` / `get_journal` / `search_journals` / `delete_journal_entry` โ manage session notes and lore. `get_journal` lists each page's id; pass `raw: true` for the full, unmodified page HTML.
|
|
402
|
+
- `update_journal_page` / `add_journal_page` / `update_journal_entry` โ edit existing journals: replace or append to a page's content (or rename it), add a page after the last one, and rename, refile, or change the visibility of an entry. Page writes work on the page as stored on the server, never on the cache: an append is added to the current text, and a replace needs the `version` token printed by `get_journal` `raw: true` and is refused if the page changed since. Every write keeps a local copy of the previous text, returns the new version token, and the page is watched for a later overwrite (a stale save, or an open FoundryVTT editor's autosave) โ see [TROUBLESHOOTING.md](TROUBLESHOOTING.md#a-journal-edit-was-overwritten).
|
|
403
|
+
|
|
404
|
+
### 7. Scene, Weather & Exploration
|
|
405
|
+
- `create_scene` / `delete_scene` / `get_scene_info` / `switch_scene` โ scene creation and player activation.
|
|
406
|
+
- `set_scene_weather` โ set or clear weather effects (`rain`, `snow`, `fog`, `""`).
|
|
407
|
+
- `set_scene_lighting` โ ambient darkness levels and global illumination settings.
|
|
408
|
+
- `reset_fog` โ reset Fog of War exploration on active scenes.
|
|
409
|
+
|
|
410
|
+
### 8. Game Mechanics & Bridge Tools
|
|
411
|
+
- `roll_dice` โ local mathematical dice formula evaluation.
|
|
412
|
+
- `roll_and_post` โ evaluates formulas via Foundry's native engine and posts interactive chat cards.
|
|
413
|
+
- `lookup_rule` โ search world journals and system compendium packs for rules with snippet previews.
|
|
414
|
+
- `get_document_schema` โ introspect game system DataModel schemas for actor and item types.
|
|
415
|
+
- `search_compendium` โ search compendium packs by name and metadata, across all enabled packs or one pack (requires the REST API module; returns no results without it).
|
|
416
|
+
- `search_compendium_content` โ deep search inside compendium pack documents and journal pages.
|
|
417
|
+
- `send_chat_message` / `get_chat_messages` โ post and read messages from the Foundry chat log.
|
|
418
|
+
- `generate_npc` / `generate_loot` โ instant procedural generators.
|
|
419
|
+
|
|
420
|
+
### 9. Diagnostics & Logging
|
|
421
|
+
- `get_health_status` / `get_system_health` โ connection and server health metrics.
|
|
422
|
+
- `get_recent_logs` / `search_logs` โ inspect server logs and error stack traces.
|
|
423
|
+
- `diagnose_errors` โ analyze recent errors into prioritized resolution suggestions.
|
|
424
|
+
- `refresh_world_data` โ force a re-fetch of the cached world state snapshot.
|
|
425
|
+
|
|
426
|
+
## ๐งช Development & Testing
|
|
427
|
+
|
|
428
|
+
```bash
|
|
429
|
+
# Install dependencies (exactly the locked versions)
|
|
430
|
+
npm ci
|
|
431
|
+
|
|
432
|
+
# Compile TypeScript
|
|
433
|
+
npm run build
|
|
434
|
+
|
|
435
|
+
# Run the unit test suite
|
|
436
|
+
npm test
|
|
437
|
+
|
|
438
|
+
# Run linter and formatting checks
|
|
439
|
+
npm run lint
|
|
440
|
+
|
|
441
|
+
# Start server in development watch mode
|
|
442
|
+
npm run dev
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
`npm run lint && npx tsc --noEmit && npm test` runs the lint, type check and unit tests in one go.
|
|
446
|
+
|
|
447
|
+
---
|
|
448
|
+
|
|
449
|
+
## ๐ค Contributing & Community
|
|
450
|
+
|
|
451
|
+
- **Questions and help**: [GitHub Discussions](https://github.com/G33ks/foundryvtt-mcp/discussions) (Q&A).
|
|
452
|
+
- **Bugs and feature requests**: [issues](https://github.com/G33ks/foundryvtt-mcp/issues/new/choose).
|
|
453
|
+
- **Contributing**: [CONTRIBUTING.md](CONTRIBUTING.md) โ setup, checks, testing against a real world.
|
|
454
|
+
- **Security**: report vulnerabilities privately, as described in [SECURITY.md](SECURITY.md).
|
|
455
|
+
- **Code of Conduct**: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
|
|
456
|
+
|
|
457
|
+
---
|
|
458
|
+
|
|
459
|
+
## ๐ฑ Origins
|
|
460
|
+
|
|
461
|
+
This project was started by Lauri Gates as [laurigates/foundryvtt-mcp](https://github.com/laurigates/foundryvtt-mcp). It was continued in [RN0000/foundryvtt-mcp](https://github.com/RN0000/foundryvtt-mcp), then forked as [duckpuppy/foundryvtt-mcp](https://github.com/duckpuppy/foundryvtt-mcp), from which this repository, [G33ks/foundryvtt-mcp](https://github.com/G33ks/foundryvtt-mcp), was forked. It now continues independently.
|
|
462
|
+
|
|
463
|
+
Thanks to everyone who built the earlier versions. Their work is kept in this repository's history and in [CHANGELOG.md](CHANGELOG.md); issue numbers from before the fork refer to the laurigates tracker.
|
|
464
|
+
|
|
465
|
+
---
|
|
466
|
+
|
|
467
|
+
## ๐ License
|
|
468
|
+
|
|
469
|
+
This project is licensed under the [MIT License](LICENSE).
|