@g33ks/foundryvtt-mcp 2.2.0 β 3.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/README.md +68 -410
- package/dist/config/index.js +6 -0
- package/dist/config/sources.js +1 -0
- package/dist/core.js +3 -0
- package/dist/foundry/auth.js +40 -1
- package/dist/foundry/client.js +62 -18
- package/dist/foundry/scene-lighting.js +41 -0
- package/dist/mcp-server.js +12 -5
- package/dist/shared/config-hash.js +1 -0
- package/dist/tools/definitions.js +50 -42
- package/dist/tools/handlers/module-bridge.js +109 -21
- package/dist/tools/handlers/scenes.js +7 -2
- package/dist/tools/router.js +5 -5
- package/dist/utils/mcp-errors.js +25 -1
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -2,460 +2,118 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://github.com/G33ks/foundryvtt-mcp/actions/workflows/test.yml)
|
|
4
4
|
[](https://github.com/G33ks/foundryvtt-mcp/actions/workflows/security.yml)
|
|
5
|
-
[](https://www.typescriptlang.org/)
|
|
8
|
-
[](https://modelcontextprotocol.io/)
|
|
5
|
+
[](https://www.npmjs.com/package/@g33ks/foundryvtt-mcp)
|
|
6
|
+
[](https://github.com/G33ks/foundryvtt-mcp/blob/main/LICENSE)
|
|
9
7
|
|
|
10
|
-
A
|
|
8
|
+
A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that lets an AI assistant such as Claude read and run a **Foundry Virtual Tabletop** world with you: look things up, keep notes, place tokens and scenery, run combat, roll dice. It is not tied to a game system: it works through FoundryVTT's own documents and each system's data as it is (see [Compatibility](https://github.com/G33ks/foundryvtt-mcp/blob/main/docs/compatibility.md)).
|
|
11
9
|
|
|
12
|
-
|
|
10
|
+
## How it works
|
|
13
11
|
|
|
14
|
-
|
|
12
|
+

|
|
15
13
|
|
|
16
|
-
|
|
14
|
+
Your AI client starts a small relay program. Every relay hands its requests to one background process, which logs in to FoundryVTT with an account of its own, the way a player's browser does, and keeps the world in memory. For what only a real FoundryVTT page can do (capturing the canvas, native dice rolls, compendium documents, uploads), that process runs an invisible browser where the companion module **FoundryVTT MCP Bridge** connects to it. Details: [Architecture](https://github.com/G33ks/foundryvtt-mcp/blob/main/docs/architecture.md).
|
|
17
15
|
|
|
18
|
-
##
|
|
16
|
+
## What it does
|
|
19
17
|
|
|
20
|
-
|
|
18
|
+
More than a hundred tools, in these groups ([full list](https://github.com/G33ks/foundryvtt-mcp/blob/main/docs/tools.md)):
|
|
21
19
|
|
|
22
|
-
|
|
20
|
+
- **Actors and items**: search, details, inventory, attribute changes, owned items, active effects, on a world actor or on one token.
|
|
21
|
+
- **Tokens**: place, move (with pathfinding around walls), remove, vision, status conditions.
|
|
22
|
+
- **Scenes**: create, activate, lighting, weather, fog of war.
|
|
23
|
+
- **Canvas**: walls and doors, lights, sounds, map notes, drawings, templates, regions, tiles, free grid cells, the images and sounds available.
|
|
24
|
+
- **Combat**: start, initiative, turns, end, current state.
|
|
25
|
+
- **Journals**: search, read, create, and edit pages safely (version check, local copies, overwrite detection).
|
|
26
|
+
- **Chat and dice**: read and send messages; roll dice, with FoundryVTT's own engine when the REST API module's key is set and locally otherwise.
|
|
27
|
+
- **World**: summary and search, folders, macros, playlists, roll tables, users and roles, ownership, settings.
|
|
28
|
+
- **Compendiums, rules and generators**: compendium search, rule lookup in journals and compendiums, quick NPC and loot generators.
|
|
29
|
+
- **Companion module**: canvas capture, rolls posted to chat by FoundryVTT, document schemas, compendium content and imports, an actor's prepared data, targets, pings, pause, file uploads.
|
|
30
|
+
- **Events and diagnostics**: a live activity log to follow the game, the connector's health, server logs.
|
|
23
31
|
|
|
24
|
-
|
|
32
|
+
Writes are off until you allow them; while they are off, every tool that changes the world is refused. See [Security](https://github.com/G33ks/foundryvtt-mcp/blob/main/docs/security.md).
|
|
25
33
|
|
|
26
|
-
|
|
34
|
+
## Requirements
|
|
27
35
|
|
|
28
|
-
- **
|
|
29
|
-
- **
|
|
30
|
-
- **
|
|
31
|
-
- **
|
|
32
|
-
- **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.
|
|
33
|
-
- **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.
|
|
36
|
+
- **Node.js 22 or newer**, with npm.
|
|
37
|
+
- **FoundryVTT v13 or v14** with a world you can open as its Gamemaster, on this computer or on a server. Tried with v14 builds 369 and 370; v13 is accepted by the companion module and handled by the code, but not tried (see [Compatibility](https://github.com/G33ks/foundryvtt-mcp/blob/main/docs/compatibility.md)).
|
|
38
|
+
- **A Chromium-based browser** on this computer: Google Chrome, Microsoft Edge, Brave, Vivaldi or Chromium. You never see it open.
|
|
39
|
+
- **An MCP client**: Claude desktop or Claude Code (others that start servers over stdio should work).
|
|
34
40
|
|
|
35
|
-
|
|
41
|
+
## Quick start
|
|
36
42
|
|
|
37
|
-
|
|
43
|
+
### 1. Install the companion module, create the connector's account
|
|
38
44
|
|
|
39
|
-
|
|
40
|
-
- π² **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`).
|
|
41
|
-
- πΊοΈ **Full Canvas & Spatial Control**: Create, inspect, update, and remove all canvas placeable types:
|
|
42
|
-
- **Scene Regions (v12+)**: `create_region`, `delete_region`, `list_regions` with geometric shapes (`rectangle`, `circle`, `ellipse`, `polygon`) and automated trigger behaviors.
|
|
43
|
-
- **Walls & Doors**: standard, doors (open/close/lock), secret doors, windows, ethereal walls, and custom coordinates (`create_wall`, `list_walls`, `set_door_state`).
|
|
44
|
-
- **Ambient Lights**: coordinate or grid-cell placement, dim/bright radii, animation effects, color thresholds (`create_light`, `update_light`, `delete_light`, `list_lights`).
|
|
45
|
-
- **Ambient Sounds**: audio tracks, radii, volume, repeat modes (`create_sound`, `delete_sound`, `list_sounds`).
|
|
46
|
-
- **Measured Templates**: cone, circle, ray, and rect spell area-of-effect markers with directional rotation and colors (`create_template`, `delete_template`, `list_templates`).
|
|
47
|
-
- **Drawings**: freehand and geometrical shapes, stroke/fill styling, and text annotations (`create_drawing`, `delete_drawing`, `list_drawings`).
|
|
48
|
-
- **Map Notes & Pins**: landmark markers linked to journal entries or standalone labels (`create_note`, `delete_note`, `list_notes`).
|
|
49
|
-
- **Tiles & Props**: place decorative tiles and backgrounds (`create_tile`, `delete_tile`, `list_tiles`).
|
|
50
|
-
- **Canvas Viewport Capture**: screenshot the GM canvas viewport with a burned-in coordinate grid overlay (`[col,row]`) via `capture_scene`.
|
|
51
|
-
- **Targeting & Animated Pings**: focus player attention with animated camera pings (`ping_canvas`) and view/set token targeting reticles (`set_target`, `get_targets`).
|
|
52
|
-
- π§ **Token & Actor Control**:
|
|
53
|
-
- **A\* Pathfinding Movement**: tokens navigate around walls and automatically open closed doors along their path (`move_token_pathfind`).
|
|
54
|
-
- **Token Vision & Lighting**: configure sight ranges, vision modes, dim/bright emitted light, and vision detection angles (`update_token_vision`).
|
|
55
|
-
- **Generalized ActiveEffects**: create, update, delete, and inspect mechanical buffs/debuffs with attribute changes (`key`, `mode`, `value`, `priority`) and durations (`rounds`, `seconds`, `turns`) on world actors or on one token (an unlinked token changes alone, not its base actor) (`create_actor_effect`, `update_actor_effect`, `delete_actor_effect`, `list_actor_effects`).
|
|
56
|
-
- **Status Conditions**: apply/remove system-agnostic status conditions (`apply_status_effect`).
|
|
57
|
-
- **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`).
|
|
58
|
-
- **System Attribute Mutations**: patch actor system data (HP, temporary HP, currency, resources, spell slots) using JSON merge patches (`update_actor_attributes`).
|
|
59
|
-
- βοΈ **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.
|
|
60
|
-
- π **World Documents & Organization**:
|
|
61
|
-
- **Folders**: manage hierarchical folder structures for actors, items, journals, and scenes (`create_folder`, `list_folders`).
|
|
62
|
-
- **Macros**: inspect, create, and delete script/chat macros (`create_macro`, `list_macros`, `delete_macro`).
|
|
63
|
-
- **Playlists & Audio**: create multi-track playlists, control playback (play, pause, stop), and adjust track states (`create_playlist`, `set_playlist_state`, `list_playlists`).
|
|
64
|
-
- **Roll Tables**: create tables with automatic sequential range distribution (`1dN`), and draw live results (`create_roll_table`, `roll_table`, `list_roll_tables`).
|
|
65
|
-
- **Document Ownership & User Roles**: configure granular document permissions (`set_document_ownership`) and user roles with self-demotion lockout guards (`set_user_role`).
|
|
66
|
-
- **World Settings**: safely inspect and update module and system settings with built-in protection against core engine corruption (`get_world_setting`, `set_world_setting`).
|
|
67
|
-
- **Asset Uploads**: upload images, tokens, and audio directly into Foundry's `Data/` storage via native FilePicker or local filesystem (`upload_asset`).
|
|
68
|
-
- π«οΈ **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`).
|
|
69
|
-
- π **Rules & Compendium Search**: Search world documents, compendium packs, and rule text with contextual snippets (`search_compendium_content`, `lookup_rule`).
|
|
70
|
-
---
|
|
71
|
-
|
|
72
|
-
## π Quick Start
|
|
73
|
-
|
|
74
|
-
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.
|
|
75
|
-
|
|
76
|
-
### 1. Check the prerequisites
|
|
77
|
-
|
|
78
|
-
- **Node.js 22 or newer** (current LTS recommended), with npm β `node --version` shows yours. Download it from [nodejs.org](https://nodejs.org/).
|
|
79
|
-
- **FoundryVTT v13 or v14**, with a world you can open as its Gamemaster. Foundry may run on this computer or on a server.
|
|
80
|
-
- **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.
|
|
81
|
-
- **Claude desktop** or **Claude Code**.
|
|
82
|
-
|
|
83
|
-
### 2. Install the companion module
|
|
84
|
-
|
|
85
|
-
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:
|
|
86
|
-
|
|
87
|
-
1. Open **Add-on Modules** β **Install Module**.
|
|
88
|
-
2. Paste this URL into the **Manifest URL** field at the bottom, then click **Install**:
|
|
45
|
+
1. On FoundryVTT's **Setup** screen: **Add-on Modules** β **Install Module**, paste this **Manifest URL**, then **Install**:
|
|
89
46
|
|
|
90
47
|
```
|
|
91
48
|
https://raw.githubusercontent.com/G33ks/foundryvtt-mcp/main/foundry-module/module.json
|
|
92
49
|
```
|
|
93
50
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
### 3. In the world: create the user, then enable the module
|
|
97
|
-
|
|
98
|
-
Launch your world and log in as its Gamemaster.
|
|
51
|
+
2. Launch your world as its Gamemaster. **Game Settings** β **User Management** β **Create Additional User**: name it, for example, `mcp-api`, give it a long password used nowhere else and the **Assistant GM** role.
|
|
52
|
+
3. **Game Settings** β **Manage Modules**: check **FoundryVTT MCP Bridge**, then **Save Module Settings**.
|
|
99
53
|
|
|
100
|
-
|
|
101
|
-
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.
|
|
102
|
-
|
|
103
|
-
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).
|
|
104
|
-
|
|
105
|
-
### 4. Install the server
|
|
106
|
-
|
|
107
|
-
In a terminal (PowerShell, Terminal on macOS, any shell on Linux):
|
|
54
|
+
### 2. Install the connector
|
|
108
55
|
|
|
109
56
|
```bash
|
|
110
57
|
npm install -g @g33ks/foundryvtt-mcp
|
|
111
58
|
foundryvtt-mcp --version
|
|
112
59
|
```
|
|
113
60
|
|
|
114
|
-
In Windows PowerShell, if `npm` is refused
|
|
61
|
+
In Windows PowerShell, if `npm` or `foundryvtt-mcp` is refused (*running scripts is disabled*), type `npm.cmd` and `foundryvtt-mcp.cmd` instead. The package is `@g33ks/foundryvtt-mcp`, not the unscoped `foundryvtt-mcp`.
|
|
115
62
|
|
|
116
|
-
|
|
117
|
-
- **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.
|
|
118
|
-
- **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`.
|
|
119
|
-
|
|
120
|
-
### 5. Run `init`
|
|
63
|
+
### 3. Run `init`
|
|
121
64
|
|
|
122
65
|
```bash
|
|
123
66
|
foundryvtt-mcp init
|
|
124
67
|
```
|
|
125
68
|
|
|
126
|
-
It asks for
|
|
127
|
-
|
|
128
|
-
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.
|
|
129
|
-
|
|
130
|
-
### 6. Add the server to Claude
|
|
131
|
-
|
|
132
|
-
Use what `init` printed at the end:
|
|
133
|
-
|
|
134
|
-
- **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.
|
|
135
|
-
- **Claude Code**: run the `claude mcp add foundryvtt β¦` command printed by `init` in a terminal, then start a new Claude Code session.
|
|
136
|
-
|
|
137
|
-
No `env` block is needed: the settings are in the configuration file.
|
|
69
|
+
It asks for FoundryVTT's address (the one you open in your browser), the account from step 1 and whether the AI may change the world (no by default). It checks each answer against your FoundryVTT, writes the configuration file, and prints what to give your MCP client. It needs an interactive terminal: on Windows, PowerShell or Command Prompt (in Git Bash, prefix it with `winpty`). You can allow writes later: see [Configuration](https://github.com/G33ks/foundryvtt-mcp/blob/main/docs/configuration.md).
|
|
138
70
|
|
|
139
|
-
###
|
|
71
|
+
### 4. Add the connector to your MCP client
|
|
140
72
|
|
|
141
|
-
|
|
142
|
-
|
|
73
|
+
- **Claude desktop**: **Settings** β **Developer** β **Edit Config**, add the `foundryvtt` entry `init` printed under `"mcpServers"`, save, then quit Claude desktop completely (also from the notification area or menu bar) and start it again.
|
|
74
|
+
- **Claude Code**: run the `claude mcp add foundryvtt β¦` command `init` printed, then start a new session.
|
|
143
75
|
|
|
144
|
-
|
|
76
|
+
### 5. First try
|
|
145
77
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
### Updating
|
|
149
|
-
|
|
150
|
-
1. Close your AI clients (quit Claude desktop completely).
|
|
151
|
-
2. In a terminal:
|
|
152
|
-
|
|
153
|
-
```bash
|
|
154
|
-
npm install -g @g33ks/foundryvtt-mcp@latest
|
|
155
|
-
foundryvtt-mcp stop
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
`stop` ends the shared process still running the previous version; `foundryvtt-mcp --version` shows the new one.
|
|
159
|
-
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)).
|
|
160
|
-
|
|
161
|
-
---
|
|
162
|
-
|
|
163
|
-
## βοΈ Configuration & Client Setup
|
|
164
|
-
|
|
165
|
-
### Configuration File
|
|
166
|
-
|
|
167
|
-
Every MCP client on the machine shares **one configuration file**, so a client entry needs only the command and its arguments β no `env` block:
|
|
168
|
-
|
|
169
|
-
| System | Location |
|
|
170
|
-
| :--- | :--- |
|
|
171
|
-
| Windows | `%LOCALAPPDATA%\foundryvtt-mcp\config.env` (next to the shared process's state) |
|
|
172
|
-
| macOS, Linux | `$XDG_CONFIG_HOME/foundryvtt-mcp/config.env`, or `~/.config/foundryvtt-mcp/config.env` |
|
|
173
|
-
|
|
174
|
-
`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).
|
|
175
|
-
|
|
176
|
-
**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.
|
|
177
|
-
|
|
178
|
-
By hand: one `KEY=value` per line, with exactly the names of the variables below; `#` starts a comment:
|
|
179
|
-
|
|
180
|
-
```env
|
|
181
|
-
FOUNDRY_URL=https://foundry.example.com
|
|
182
|
-
FOUNDRY_USERNAME=mcp-api
|
|
183
|
-
FOUNDRY_PASSWORD='your password'
|
|
184
|
-
FOUNDRY_WRITE_ENABLED=true
|
|
185
|
-
FOUNDRY_MODULE_BRIDGE_ENABLED=true
|
|
186
|
-
```
|
|
187
|
-
|
|
188
|
-
- **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.
|
|
189
|
-
- **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>`).
|
|
190
|
-
- **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.
|
|
191
|
-
- **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.
|
|
192
|
-
- **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)).
|
|
193
|
-
- **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).
|
|
194
|
-
|
|
195
|
-
### Environment Variables
|
|
196
|
-
|
|
197
|
-
The same names work in the configuration file, in an `env` block, in the system environment or in a development `.env`.
|
|
198
|
-
|
|
199
|
-
| Variable | Required | Default | Description |
|
|
200
|
-
| :--- | :--- | :--- | :--- |
|
|
201
|
-
| `FOUNDRY_URL` | **Yes** | `http://localhost:30000` | FoundryVTT server URL |
|
|
202
|
-
| `FOUNDRY_USERNAME` | **Yes** | β | FoundryVTT user account name |
|
|
203
|
-
| `FOUNDRY_PASSWORD` | **Yes** | β | FoundryVTT user account password |
|
|
204
|
-
| `FOUNDRY_WRITE_ENABLED` | No | `false` | Enables game-state mutations (walls, actors, tokens, etc.) |
|
|
205
|
-
| `FOUNDRY_MODULE_BRIDGE_ENABLED` | No | `false` | Enables WebSocket bridge for canvas screenshots & chat rolls |
|
|
206
|
-
| `FOUNDRY_MODULE_BRIDGE_PORT` | No | `31415` | WebSocket port for the companion module bridge |
|
|
207
|
-
| `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 |
|
|
208
|
-
| `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 |
|
|
209
|
-
| `FOUNDRY_HEADLESS_GM_PASSWORD` | No | `FOUNDRY_PASSWORD` | Password of that other account (two-account mode only) |
|
|
210
|
-
| `FOUNDRY_HEADLESS_GM_EXECUTABLE_PATH` | No | β | Path to any Chromium-based browser binary (Chrome, Edge, Brave, Vivaldiβ¦), skipping auto-detection |
|
|
211
|
-
| `FOUNDRY_DATA_PATH` | No | β | Local path to Foundry `Data/` for asset dimension discovery |
|
|
212
|
-
| `FOUNDRY_API_KEY` | No | β | Optional REST API key for server diagnostics tools |
|
|
213
|
-
| `FOUNDRY_EVENT_BUFFER_SIZE` | No | `500` | In-memory event log ring buffer capacity |
|
|
214
|
-
| `FOUNDRY_EVENT_WAIT_MS` | No | `25000` | Default long-polling timeout for `watch_events` |
|
|
215
|
-
| `LOG_LEVEL` | No | `info` | Logging verbosity (`debug`, `info`, `warn`, `error`) |
|
|
216
|
-
| `FOUNDRY_MCP_SHARED` | No | `true` | Shared-process mode; `false` makes every instance own its own connection, bridge and browser (all-in-one) |
|
|
217
|
-
| `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 |
|
|
218
|
-
| `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 |
|
|
219
|
-
| `FOUNDRY_MCP_CONFIG` | No | see [Configuration File](#configuration-file) | Path of the configuration file. Environment or `.env` only |
|
|
220
|
-
|
|
221
|
-
#### Choosing the Headless GM Browser
|
|
222
|
-
|
|
223
|
-
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`):
|
|
224
|
-
|
|
225
|
-
```env
|
|
226
|
-
FOUNDRY_HEADLESS_GM_EXECUTABLE_PATH='C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe'
|
|
227
|
-
```
|
|
78
|
+
With your world launched in FoundryVTT:
|
|
228
79
|
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
### Shared Process Mode
|
|
232
|
-
|
|
233
|
-
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.
|
|
234
|
-
|
|
235
|
-
- **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.
|
|
236
|
-
- **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.
|
|
237
|
-
- **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.
|
|
238
|
-
- **Writes**: tools that change game state run one at a time, in arrival order; reads run in parallel.
|
|
239
|
-
- **Commands**:
|
|
240
|
-
|
|
241
|
-
```bash
|
|
242
|
-
foundryvtt-mcp status # pid, version, uptime, FoundryVTT / bridge / GM session state, relays, log path
|
|
243
|
-
foundryvtt-mcp stop # finish running calls, then stop the shared process
|
|
244
|
-
```
|
|
245
|
-
|
|
246
|
-
They only read the state directory, so they work from any terminal β no FoundryVTT configuration needed.
|
|
247
|
-
- **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.
|
|
248
|
-
- **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:
|
|
249
|
-
- 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;
|
|
250
|
-
- 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;
|
|
251
|
-
- other settings (`LOG_LEVEL`, timeouts, idle delayβ¦) never matter: the shared process's own apply.
|
|
252
|
-
- **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.
|
|
253
|
-
- **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).
|
|
254
|
-
|
|
255
|
-
### Module Bridge Security
|
|
256
|
-
|
|
257
|
-
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:
|
|
258
|
-
|
|
259
|
-
- **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.
|
|
260
|
-
- **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.
|
|
261
|
-
- **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, and its version: the one it announced (0.6.0 or later), otherwise the version installed in the world followed by `(not announced)`.
|
|
262
|
-
- **Module announcement (0.6.0 or later)**: the module's answer to the challenge also lists its version and the commands it serves. The proofs do not cover this list: it only decides which commands the server tries to send, and an absent or malformed one never fails the authentication.
|
|
263
|
-
- **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.
|
|
264
|
-
- **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.
|
|
265
|
-
|
|
266
|
-
### Client entries
|
|
267
|
-
|
|
268
|
-
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:
|
|
269
|
-
|
|
270
|
-
- `<NODE>`: what `node -p process.execPath` prints, such as `C:\Program Files\nodejs\node.exe` or `/usr/local/bin/node`;
|
|
271
|
-
- `<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`.
|
|
272
|
-
|
|
273
|
-
In JSON, double each Windows backslash, or write forward slashes. After changing or updating Node.js, `<NODE>` changes: run `foundryvtt-mcp init` again.
|
|
274
|
-
|
|
275
|
-
### Claude Desktop Configuration
|
|
276
|
-
|
|
277
|
-
With the settings in the [configuration file](#configuration-file), add to `claude_desktop_config.json`:
|
|
278
|
-
|
|
279
|
-
```json
|
|
280
|
-
{
|
|
281
|
-
"mcpServers": {
|
|
282
|
-
"foundryvtt": {
|
|
283
|
-
"command": "<NODE>",
|
|
284
|
-
"args": ["<ENTRY>"]
|
|
285
|
-
}
|
|
286
|
-
}
|
|
287
|
-
}
|
|
288
|
-
```
|
|
289
|
-
|
|
290
|
-
### Claude Code Configuration
|
|
291
|
-
|
|
292
|
-
`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`):
|
|
293
|
-
|
|
294
|
-
> **Windows PowerShell:** the command works as printed when `claude` is the installer's `claude.exe` (or a `.cmd`). If `Get-Command claude` shows a `claude.ps1` (installed with npm), PowerShell swallows the `--`: write `'--'` instead.
|
|
295
|
-
|
|
296
|
-
```json
|
|
297
|
-
{
|
|
298
|
-
"mcpServers": {
|
|
299
|
-
"foundryvtt": {
|
|
300
|
-
"type": "stdio",
|
|
301
|
-
"command": "<NODE>",
|
|
302
|
-
"args": ["<ENTRY>"]
|
|
303
|
-
}
|
|
304
|
-
}
|
|
305
|
-
}
|
|
306
|
-
```
|
|
307
|
-
|
|
308
|
-
**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).
|
|
309
|
-
|
|
310
|
-
### Oh My Pi Configuration
|
|
311
|
-
|
|
312
|
-
Add to `~/.omp/agent/mcp.json` (or `~/.omp/mcp.json`):
|
|
313
|
-
|
|
314
|
-
```json
|
|
315
|
-
{
|
|
316
|
-
"mcpServers": {
|
|
317
|
-
"foundryvtt": {
|
|
318
|
-
"type": "stdio",
|
|
319
|
-
"command": "<NODE>",
|
|
320
|
-
"args": ["<ENTRY>"],
|
|
321
|
-
"timeout": 60000
|
|
322
|
-
}
|
|
323
|
-
}
|
|
324
|
-
}
|
|
325
|
-
```
|
|
326
|
-
|
|
327
|
-
---
|
|
328
|
-
|
|
329
|
-
## π οΈ Tool Catalog (115 Tools)
|
|
330
|
-
|
|
331
|
-
### 1. Real-Time Event Awareness
|
|
332
|
-
- `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.
|
|
333
|
-
|
|
334
|
-
### 2. Canvas & Spatial Placeables
|
|
335
|
-
- `create_region` / `delete_region` / `list_regions` β manage Scene Regions (v12+) with geometric shapes (`rectangle`, `circle`, `ellipse`, `polygon`) and automated behaviors.
|
|
336
|
-
- `create_wall` / `delete_wall` / `list_walls` / `set_door_state` β complete wall and door geometry management.
|
|
337
|
-
- `create_light` / `update_light` / `delete_light` / `list_lights` β ambient lighting control (radii, colors, animations).
|
|
338
|
-
- `create_sound` / `delete_sound` / `list_sounds` β ambient audio placement on canvas scenes.
|
|
339
|
-
- `create_template` / `delete_template` / `list_templates` β spell and effect area-of-effect templates.
|
|
340
|
-
- `create_drawing` / `delete_drawing` / `list_drawings` β map shapes, zones, and text annotations.
|
|
341
|
-
- `create_note` / `delete_note` / `list_notes` β map pins and landmark markers.
|
|
342
|
-
- `create_tile` / `delete_tile` / `list_tiles` β decorative tiles and map props.
|
|
343
|
-
- `capture_scene` β screenshot the active scene canvas with a grid coordinate overlay burned in.
|
|
344
|
-
- `ping_canvas` β emit an animated canvas ping at specific pixel coordinates.
|
|
345
|
-
- `find_open_cells` β scan scenes for unblocked grid cells suitable for token/prop placement.
|
|
346
|
-
- `list_scene_assets` β discover map backgrounds, token art, and audio files with parsed tags and dimensions.
|
|
347
|
-
- `upload_asset` β upload image/audio files into Foundry's `Data/` directory via FilePicker or local filesystem.
|
|
348
|
-
|
|
349
|
-
### 3. Tokens & Movement
|
|
350
|
-
- `spawn_token` β place actor tokens on scenes with custom size, elevation, and coordinates.
|
|
351
|
-
- `delete_token` β remove tokens from scenes without deleting the underlying actor.
|
|
352
|
-
- `list_tokens` β list placed tokens on active or specific scenes.
|
|
353
|
-
- `move_token` β teleport a token to exact pixel coordinates.
|
|
354
|
-
- `move_token_pathfind` β move tokens using A* obstacle avoidance around walls with automatic door opening.
|
|
355
|
-
- `move_tokens` β batch move multiple tokens simultaneously.
|
|
356
|
-
- `set_target` / `get_targets` β set and inspect token targeting reticles across connected users.
|
|
357
|
-
- `update_token_vision` β configure vision ranges, vision modes, dim/bright emitted lights, and angles.
|
|
358
|
-
- `apply_status_effect` β toggle status conditions (`prone`, `stunned`, `blinded`, `invisible`, etc.). With the companion module 0.6.0 or later connected (it waits up to 10 s for one still connecting), it goes through the game system's own status effects, so the system recognises the condition, and effects an earlier version wrote for the status are reported, then removed with `active=false`. A game system that asks for a value when a status is created gets it from `createOptions`, under the option name the system documents; without it the call fails at once and nothing is created. `createOptions` are refused when that path is not available. Otherwise it writes an effect carrying the status over the socket (token icon always shown), which a game system that defines its own statuses with fixed effect ids may not recognise. The answer names the path used.
|
|
359
|
-
|
|
360
|
-
### 4. Actors & Inventory
|
|
361
|
-
- `create_world_actor` / `create_full_actor` / `delete_world_actor` β create and delete actor documents.
|
|
362
|
-
- `import_compendium_actor` β import entire NPCs/monsters from compendium packs with embedded items and automatic error recovery.
|
|
363
|
-
- `search_actors` β query actors by name and type with cursor pagination support.
|
|
364
|
-
- `get_actor_details` β retrieve actor system data, statistics, attributes, and health; with `sceneId` + `tokenId`, those of one token (an unlinked token has its own).
|
|
365
|
-
- `update_actor_attributes` β patch nested system data using dot paths (`attributes.hp.value`, `currency.gp`), on a world actor or one token. Write stored fields only: a field the game system computes is saved but has no effect in play.
|
|
366
|
-
- `get_actor_inventory` β list owned items with full system properties, of a world actor or one token.
|
|
367
|
-
- `get_actor_stats` β an actor's prepared system data as JSON, including the values the game system computes and does not store, of a world actor or one token; `paths` narrows it, `maxBytes` bounds it (companion module 0.6.0 or later).
|
|
368
|
-
- `search_items` β search world item documents by name, optionally filtered by type (world items, not owned items).
|
|
369
|
-
- `create_actor_item` β create inline items OR import directly from compendium packs (`source: { type: 'compendium', compendiumId, itemId }`).
|
|
370
|
-
- `update_actor_item` β apply JSON merge patches to owned items.
|
|
371
|
-
- `delete_actor_item` β delete specific items from actor inventories.
|
|
372
|
-
- The three item tools also take `sceneId` + `tokenId`: on an unlinked token, only that token changes.
|
|
373
|
-
- `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 a world actor or one token (on an unlinked token, only that token changes).
|
|
374
|
-
|
|
375
|
-
### 5. Combat Encounters
|
|
376
|
-
- `start_combat` β create encounters and seed combatants from scene tokens; the encounter begins at round 1.
|
|
377
|
-
- `get_combat_state` β retrieve combatant turn order, HP, AC, and round number.
|
|
378
|
-
- `set_initiative` β set combatant initiative values and re-order turns.
|
|
379
|
-
- `next_turn` β advance the turn tracker (handles round increments and skips defeated combatants).
|
|
380
|
-
- `set_pause` β pause or unpause the game clock.
|
|
381
|
-
- `end_combat` β terminate active encounters.
|
|
382
|
-
|
|
383
|
-
### 6. World Documents & Organization
|
|
384
|
-
- `list_folders` / `create_folder` β organize actors, items, journals, and scenes in nested folders.
|
|
385
|
-
- `list_macros` / `create_macro` / `delete_macro` β manage script and chat macro documents.
|
|
386
|
-
- `list_playlists` / `create_playlist` / `set_playlist_state` / `delete_playlist` β audio playlist and sound controls.
|
|
387
|
-
- `create_roll_table` / `delete_roll_table` / `roll_table` / `list_roll_tables` β table creation and result rolling.
|
|
388
|
-
- `get_world_setting` / `set_world_setting` β inspect and modify system/module settings with core protection.
|
|
389
|
-
- `set_document_ownership` β configure granular document permissions (`none`, `limited`, `observer`, `owner`).
|
|
390
|
-
- `get_world_summary` β world metadata (title, game system, core version) and per-collection document counts.
|
|
391
|
-
- `search_world` β search actors, items, scenes, and journals by name at once, grouped by collection.
|
|
392
|
-
- `get_users` / `set_user_role` β list connected users and change permission roles with self-demotion lockout guards.
|
|
393
|
-
- `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.
|
|
394
|
-
- `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).
|
|
395
|
-
|
|
396
|
-
### 7. Scene, Weather & Exploration
|
|
397
|
-
- `create_scene` / `delete_scene` / `get_scene_info` / `switch_scene` β scene creation and player activation.
|
|
398
|
-
- `set_scene_weather` β set or clear weather effects (`rain`, `snow`, `fog`, `""`).
|
|
399
|
-
- `set_scene_lighting` β ambient darkness levels and global illumination settings.
|
|
400
|
-
- `reset_fog` β reset Fog of War exploration on active scenes.
|
|
401
|
-
|
|
402
|
-
### 8. Game Mechanics & Bridge Tools
|
|
403
|
-
- `roll_dice` β local mathematical dice formula evaluation.
|
|
404
|
-
- `roll_and_post` β evaluates formulas via Foundry's native engine and posts interactive chat cards.
|
|
405
|
-
- `lookup_rule` β search world journals and system compendium packs for rules with snippet previews.
|
|
406
|
-
- `get_document_schema` β introspect game system DataModel schemas for actor and item types, with computed (`persisted: false`) fields and number bounds; for a type declared only by template.json, its default values with inferred types (module 0.6.0 or later).
|
|
407
|
-
- `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).
|
|
408
|
-
- `search_compendium_content` β deep search inside compendium pack documents and journal pages.
|
|
409
|
-
- `send_chat_message` / `get_chat_messages` β post and read messages from the Foundry chat log.
|
|
410
|
-
- `generate_npc` / `generate_loot` β instant procedural generators.
|
|
411
|
-
|
|
412
|
-
### 9. Diagnostics & Logging
|
|
413
|
-
- `get_health_status` / `get_system_health` β connection and server health metrics.
|
|
414
|
-
- `get_recent_logs` / `search_logs` β inspect server logs and error stack traces.
|
|
415
|
-
- `diagnose_errors` β analyze recent errors into prioritized resolution suggestions.
|
|
416
|
-
- `refresh_world_data` β force a re-fetch of the cached world state snapshot.
|
|
417
|
-
|
|
418
|
-
## π§ͺ Development & Testing
|
|
419
|
-
|
|
420
|
-
```bash
|
|
421
|
-
# Install dependencies (exactly the locked versions)
|
|
422
|
-
npm ci
|
|
423
|
-
|
|
424
|
-
# Compile TypeScript
|
|
425
|
-
npm run build
|
|
426
|
-
|
|
427
|
-
# Run the unit test suite
|
|
428
|
-
npm test
|
|
429
|
-
|
|
430
|
-
# Run linter and formatting checks
|
|
431
|
-
npm run lint
|
|
432
|
-
|
|
433
|
-
# Start server in development watch mode
|
|
434
|
-
npm run dev
|
|
435
|
-
```
|
|
80
|
+
1. `foundryvtt-mcp init --check` should end with `All checks passed.`
|
|
81
|
+
2. Ask your AI client: *"Show the FoundryVTT connector's health status."* It should show the FoundryVTT connection, the module bridge and the GM session connected. The first call can take a few seconds.
|
|
436
82
|
|
|
437
|
-
|
|
83
|
+
When something fails, the message says why; [TROUBLESHOOTING.md](https://github.com/G33ks/foundryvtt-mcp/blob/main/TROUBLESHOOTING.md) explains each one. Every step in detail, updates and uninstalling: [Installation](https://github.com/G33ks/foundryvtt-mcp/blob/main/docs/installation.md).
|
|
438
84
|
|
|
439
|
-
|
|
85
|
+
## Known limitations
|
|
440
86
|
|
|
441
|
-
|
|
87
|
+
- **Close a journal page in FoundryVTT before the AI writes to it.** An open editor's autosave can overwrite the AI's change; the connector detects it and keeps a copy, but cannot prevent it.
|
|
88
|
+
- **Write stored fields only.** A value the game system computes is accepted and saved, but has no effect in play; `get_document_schema` tells them apart.
|
|
89
|
+
- **`search_compendium` needs the separate REST API module.** Without it, use `search_compendium_content`, which goes through the companion module.
|
|
90
|
+
- **`watch_events` does not see the connector's own changes**, only those of other users.
|
|
91
|
+
- **One connector per computer**: two would compete for the companion module's port.
|
|
92
|
+
- **Some changes stay yours**: the connector does not promote anyone to Gamemaster nor change the world's permission settings.
|
|
93
|
+
- **After FoundryVTT restarts, launch the world again.** The connector waits for it and reconnects by itself.
|
|
94
|
+
- **After an update, restart your MCP client**: a client started earlier keeps the previous list of tools.
|
|
442
95
|
|
|
443
|
-
|
|
444
|
-
- **Bugs and feature requests**: [issues](https://github.com/G33ks/foundryvtt-mcp/issues/new/choose).
|
|
445
|
-
- **Contributing**: [CONTRIBUTING.md](CONTRIBUTING.md) β setup, checks, testing against a real world.
|
|
446
|
-
- **Security**: report vulnerabilities privately, as described in [SECURITY.md](SECURITY.md).
|
|
447
|
-
- **Code of Conduct**: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
|
|
96
|
+
## Documentation
|
|
448
97
|
|
|
449
|
-
|
|
98
|
+
- [Installation](https://github.com/G33ks/foundryvtt-mcp/blob/main/docs/installation.md): every step, other clients, updating, uninstalling.
|
|
99
|
+
- [Configuration](https://github.com/G33ks/foundryvtt-mcp/blob/main/docs/configuration.md): the configuration file and every setting.
|
|
100
|
+
- [Tools](https://github.com/G33ks/foundryvtt-mcp/blob/main/docs/tools.md): every tool, what it needs, whether it writes.
|
|
101
|
+
- [Architecture](https://github.com/G33ks/foundryvtt-mcp/blob/main/docs/architecture.md): relays, the shared process, the invisible session, the bridge.
|
|
102
|
+
- [Security](https://github.com/G33ks/foundryvtt-mcp/blob/main/docs/security.md): what the connector can do and keeps, and how to limit it.
|
|
103
|
+
- [Compatibility](https://github.com/G33ks/foundryvtt-mcp/blob/main/docs/compatibility.md): FoundryVTT versions, hosting, clients, game systems.
|
|
104
|
+
- [Troubleshooting](https://github.com/G33ks/foundryvtt-mcp/blob/main/TROUBLESHOOTING.md) and the [changelog](https://github.com/G33ks/foundryvtt-mcp/blob/main/CHANGELOG.md).
|
|
450
105
|
|
|
451
|
-
##
|
|
106
|
+
## Contributing and support
|
|
452
107
|
|
|
453
|
-
|
|
108
|
+
- Questions: [GitHub Discussions](https://github.com/G33ks/foundryvtt-mcp/discussions). Bugs and requests: [issues](https://github.com/G33ks/foundryvtt-mcp/issues/new/choose).
|
|
109
|
+
- Working on the code: [CONTRIBUTING.md](https://github.com/G33ks/foundryvtt-mcp/blob/main/CONTRIBUTING.md).
|
|
110
|
+
- Vulnerabilities: privately, as [SECURITY.md](https://github.com/G33ks/foundryvtt-mcp/blob/main/SECURITY.md) describes.
|
|
111
|
+
- [Code of Conduct](https://github.com/G33ks/foundryvtt-mcp/blob/main/CODE_OF_CONDUCT.md).
|
|
454
112
|
|
|
455
|
-
|
|
113
|
+
## Origins
|
|
456
114
|
|
|
457
|
-
|
|
115
|
+
Started by Lauri Gates as [laurigates/foundryvtt-mcp](https://github.com/laurigates/foundryvtt-mcp), 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 was forked; it now continues independently. Thanks to everyone who built the earlier versions; their work is kept in the history and in the changelog.
|
|
458
116
|
|
|
459
|
-
##
|
|
117
|
+
## License
|
|
460
118
|
|
|
461
|
-
|
|
119
|
+
[MIT](https://github.com/G33ks/foundryvtt-mcp/blob/main/LICENSE).
|
package/dist/config/index.js
CHANGED
|
@@ -100,6 +100,11 @@ const ConfigSchema = z.object({
|
|
|
100
100
|
*/
|
|
101
101
|
assets: z.object({
|
|
102
102
|
dataPath: z.string().optional(),
|
|
103
|
+
/**
|
|
104
|
+
* The one folder `upload_asset` may read a `sourcePath` from. Unset, the
|
|
105
|
+
* tool takes `contentBase64` only: the server reads no local file for it.
|
|
106
|
+
*/
|
|
107
|
+
uploadSourceDir: z.string().optional(),
|
|
103
108
|
}),
|
|
104
109
|
/**
|
|
105
110
|
* In-memory world-event ring backing `watch_events` β the cursor-addressed
|
|
@@ -172,6 +177,7 @@ function rawConfig(v) {
|
|
|
172
177
|
},
|
|
173
178
|
assets: {
|
|
174
179
|
dataPath: v.FOUNDRY_DATA_PATH,
|
|
180
|
+
uploadSourceDir: v.FOUNDRY_UPLOAD_SOURCE_DIR,
|
|
175
181
|
},
|
|
176
182
|
events: {
|
|
177
183
|
bufferSize: int(v.FOUNDRY_EVENT_BUFFER_SIZE),
|
package/dist/config/sources.js
CHANGED
package/dist/core.js
CHANGED
|
@@ -115,6 +115,9 @@ export class FoundryCore {
|
|
|
115
115
|
if (config.assets.dataPath) {
|
|
116
116
|
clientConfig.dataPath = config.assets.dataPath;
|
|
117
117
|
}
|
|
118
|
+
if (config.assets.uploadSourceDir) {
|
|
119
|
+
clientConfig.uploadSourceDir = config.assets.uploadSourceDir;
|
|
120
|
+
}
|
|
118
121
|
// Same state directory as the shared process's daemon.json, in both modes.
|
|
119
122
|
clientConfig.journalHistoryDir = path.join(defaultStateDir(), 'journal-history');
|
|
120
123
|
clientConfig.journalConflictsFile = path.join(defaultStateDir(), 'journal-conflicts.json');
|