@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.
Files changed (96) hide show
  1. package/LICENSE +22 -0
  2. package/README.md +468 -2
  3. package/dist/character/manager.js +208 -0
  4. package/dist/cli/checks.js +307 -0
  5. package/dist/cli/config-file.js +120 -0
  6. package/dist/cli/init.js +410 -0
  7. package/dist/cli/prompt.js +117 -0
  8. package/dist/cli/snippets.js +49 -0
  9. package/dist/combat/manager.js +371 -0
  10. package/dist/config/env-layers.js +49 -0
  11. package/dist/config/index.js +298 -0
  12. package/dist/config/sources.js +201 -0
  13. package/dist/core.js +415 -0
  14. package/dist/diagnostics/client.js +353 -0
  15. package/dist/diagnostics/types.js +94 -0
  16. package/dist/foundry/auth.js +220 -0
  17. package/dist/foundry/browser-detect.js +170 -0
  18. package/dist/foundry/client.js +5555 -0
  19. package/dist/foundry/dice-formula.js +154 -0
  20. package/dist/foundry/event-log.js +299 -0
  21. package/dist/foundry/headless-gm-session.js +740 -0
  22. package/dist/foundry/journal-history.js +90 -0
  23. package/dist/foundry/journal-integrity.js +306 -0
  24. package/dist/foundry/module-bridge.js +413 -0
  25. package/dist/foundry/types.js +52 -0
  26. package/dist/foundry/world-cache.js +386 -0
  27. package/dist/index.js +107 -0
  28. package/dist/mcp-server.js +63 -0
  29. package/dist/server.js +159 -0
  30. package/dist/shared/build-order.js +134 -0
  31. package/dist/shared/config-hash.js +62 -0
  32. package/dist/shared/config-notice.js +55 -0
  33. package/dist/shared/control.js +255 -0
  34. package/dist/shared/daemon-link.js +135 -0
  35. package/dist/shared/daemon.js +313 -0
  36. package/dist/shared/ipc-client.js +200 -0
  37. package/dist/shared/ipc-server.js +316 -0
  38. package/dist/shared/paths.js +79 -0
  39. package/dist/shared/protocol.js +230 -0
  40. package/dist/shared/relay-config.js +65 -0
  41. package/dist/shared/relay.js +120 -0
  42. package/dist/shared/rotating-log.js +57 -0
  43. package/dist/shared/spawn.js +39 -0
  44. package/dist/shared/state-file.js +33 -0
  45. package/dist/shared/token.js +62 -0
  46. package/dist/shared/version.js +57 -0
  47. package/dist/tools/base.js +74 -0
  48. package/dist/tools/definitions.js +3109 -0
  49. package/dist/tools/handlers/actor-mutations.js +128 -0
  50. package/dist/tools/handlers/actors.js +114 -0
  51. package/dist/tools/handlers/chat-mutations.js +49 -0
  52. package/dist/tools/handlers/chat.js +36 -0
  53. package/dist/tools/handlers/combat-mutations.js +215 -0
  54. package/dist/tools/handlers/combat-order.js +94 -0
  55. package/dist/tools/handlers/combat.js +51 -0
  56. package/dist/tools/handlers/compendium.js +83 -0
  57. package/dist/tools/handlers/diagnostics.js +438 -0
  58. package/dist/tools/handlers/dice.js +54 -0
  59. package/dist/tools/handlers/effects.js +103 -0
  60. package/dist/tools/handlers/events.js +50 -0
  61. package/dist/tools/handlers/generation.js +258 -0
  62. package/dist/tools/handlers/item-mutations.js +132 -0
  63. package/dist/tools/handlers/items.js +53 -0
  64. package/dist/tools/handlers/journal-mutations.js +230 -0
  65. package/dist/tools/handlers/journals.js +80 -0
  66. package/dist/tools/handlers/module-bridge.js +421 -0
  67. package/dist/tools/handlers/placeable-mutations.js +272 -0
  68. package/dist/tools/handlers/resources.js +203 -0
  69. package/dist/tools/handlers/roll-tables.js +97 -0
  70. package/dist/tools/handlers/scene-mutations.js +159 -0
  71. package/dist/tools/handlers/scenes.js +355 -0
  72. package/dist/tools/handlers/settings.js +53 -0
  73. package/dist/tools/handlers/tile-mutations.js +56 -0
  74. package/dist/tools/handlers/token-mutations.js +356 -0
  75. package/dist/tools/handlers/users.js +59 -0
  76. package/dist/tools/handlers/utils.js +47 -0
  77. package/dist/tools/handlers/wall-mutations.js +98 -0
  78. package/dist/tools/handlers/world-documents.js +222 -0
  79. package/dist/tools/handlers/world.js +92 -0
  80. package/dist/tools/index.js +25 -0
  81. package/dist/tools/new-router.js +97 -0
  82. package/dist/tools/registry.js +79 -0
  83. package/dist/tools/resources.js +63 -0
  84. package/dist/tools/router.js +688 -0
  85. package/dist/tools/write-tools.js +97 -0
  86. package/dist/utils/cache-instance.js +30 -0
  87. package/dist/utils/cache.js +205 -0
  88. package/dist/utils/diagnostics.js +332 -0
  89. package/dist/utils/guards.js +17 -0
  90. package/dist/utils/image-size.js +160 -0
  91. package/dist/utils/log-args.js +47 -0
  92. package/dist/utils/logger.js +203 -0
  93. package/dist/utils/refusal.js +30 -0
  94. package/dist/utils/sanitize.js +22 -0
  95. package/dist/utils/serial-queue.js +22 -0
  96. package/package.json +124 -4
@@ -0,0 +1,3109 @@
1
+ /**
2
+ * @fileoverview Tool definitions for FoundryVTT MCP Server
3
+ *
4
+ * This module contains all tool schema definitions organized by category.
5
+ * Tools are separated into logical groups for better maintainability.
6
+ */
7
+ /**
8
+ * Shared write-safety clause appended to every mutation tool description.
9
+ *
10
+ * Both halves are enforced in code by `assertWriteable()`
11
+ * (`src/foundry/client.ts`): the `FOUNDRY_WRITE_ENABLED` opt-in (default
12
+ * `false`, see `src/config/index.ts`) and a live authenticated Socket.IO
13
+ * session. Foundry itself enforces the GM/owner permission (ADR-010).
14
+ */
15
+ const WRITE_GATE = 'WRITE: mutates the live world. Requires FOUNDRY_WRITE_ENABLED=true (default false) and an active Socket.IO connection, and is refused otherwise; Foundry additionally enforces GM/owner permission on the document.';
16
+ /**
17
+ * Extra clause for destructive tools (data removal that this server cannot undo).
18
+ */
19
+ const CONFIRM_FIRST = 'DESTRUCTIVE and not undoable from this server: confirm the exact target with the user before calling.';
20
+ /**
21
+ * Canonical `roll_dice` description.
22
+ *
23
+ * Exported so `RollDiceTool` (`src/tools/handlers/dice.ts`) can reuse the exact
24
+ * same string instead of keeping a second copy that silently drifts: the
25
+ * registry class is what *executes* the tool while `getAllTools()` is what is
26
+ * *listed*, so a divergence would be invisible.
27
+ */
28
+ export const ROLL_DICE_DESCRIPTION = 'Roll dice and return the total with a per-term breakdown. Dice terms and whole numbers joined by + or -, with whitespace allowed anywhere ("1d20+5", "1d20 + 5", "1d20+5+3", "2d6 + 1d4", "3d6"; a count-less "d20" means one die), always work and every term counts towards the total - that is the portable grammar, safe on either transport. Multiplication and Foundry modifier syntax such as "4d6kh3" or "1d20r1" are rejected on both transports, with an error naming the offending character and its position, never dropped from the total in silence. Parentheses are the one difference: with FOUNDRY_API_KEY set the formula goes to FoundryVTT\'s own Roll engine, which evaluates them, while the default Socket.IO transport rolls locally and rejects them by name - and a REST roll that cannot reach the server falls back to that same local roller, so a parenthesised formula can still fail there. Prefer the expanded form when it matters. Use when: the user asks for a check, save, attack, damage, or any random result.';
29
+ /**
30
+ * Dice rolling tool definitions
31
+ */
32
+ export const diceTools = [
33
+ {
34
+ name: 'roll_dice',
35
+ description: ROLL_DICE_DESCRIPTION,
36
+ inputSchema: {
37
+ type: 'object',
38
+ properties: {
39
+ formula: {
40
+ type: 'string',
41
+ description: 'Dice formula (e.g., "1d20+5", "3d6")',
42
+ },
43
+ reason: {
44
+ type: 'string',
45
+ description: 'Optional reason for the roll',
46
+ },
47
+ },
48
+ required: ['formula'],
49
+ },
50
+ },
51
+ ];
52
+ /**
53
+ * Actor management tool definitions
54
+ */
55
+ export const actorTools = [
56
+ {
57
+ name: 'search_actors',
58
+ description: "Search actors (player characters, NPCs) by name, optionally filtered by type. Returns a summary line per match: name, type, level and current/max HP. Use when: checking whether an actor exists, or getting a quick roster with HP. Do not use when: you already have the actorId and want that actor's ability scores - use get_actor_details; or you need the actorId itself, which this tool does not print - read the foundry://actors resource, whose JSON lists up to the first 100 actors with their _id (not exhaustive in larger worlds).",
59
+ inputSchema: {
60
+ type: 'object',
61
+ properties: {
62
+ query: {
63
+ type: 'string',
64
+ description: 'Search query for actor names',
65
+ },
66
+ type: {
67
+ type: 'string',
68
+ description: 'Actor type filter (character, npc, etc.)',
69
+ },
70
+ limit: {
71
+ type: 'number',
72
+ description: 'Maximum number of results to return',
73
+ default: 10,
74
+ },
75
+ cursor: {
76
+ type: 'string',
77
+ description: 'Opaque pagination cursor from a previous response to fetch the next page',
78
+ },
79
+ },
80
+ },
81
+ },
82
+ {
83
+ name: 'get_actor_details',
84
+ description: 'Get details for one actor by id: type, level, current/max HP, AC and ability scores; no biography or description text is returned (the description line always reads "No description available."). Use when: you have an actorId and need its current HP or ability scores - notably as the read-before-write step for update_actor_attributes. Do not use when: you only have a name - run search_actors first; or you need the ids of items the actor owns, which this tool does not return (no tool in this server lists owned-item ids - ask the user for the itemId).',
85
+ inputSchema: {
86
+ type: 'object',
87
+ properties: {
88
+ actorId: {
89
+ type: 'string',
90
+ description: 'The ID of the actor to retrieve',
91
+ },
92
+ },
93
+ required: ['actorId'],
94
+ },
95
+ },
96
+ {
97
+ name: 'get_actor_inventory',
98
+ description: "List an actor's owned items (equipment, spells, features) with full system data per item, unlike get_actor_details which only reports the actor's own top-level stats. Use when: checking what a character or NPC carries or knows before an attack, spell, or trade. Do not use when: you only need the actor's HP/AC/abilities - use get_actor_details.",
99
+ inputSchema: {
100
+ type: 'object',
101
+ properties: {
102
+ actorId: {
103
+ type: 'string',
104
+ description: 'The ID of the actor whose inventory to list',
105
+ },
106
+ },
107
+ required: ['actorId'],
108
+ },
109
+ },
110
+ ];
111
+ /**
112
+ * Actor attribute mutation tool definitions (laurigates/foundryvtt-mcp#143)
113
+ *
114
+ * WRITE operations — require FOUNDRY_WRITE_ENABLED=true and an active
115
+ * Socket.IO connection (mutations use the core `modifyDocument` protocol).
116
+ */
117
+ export const actorMutationTools = [
118
+ {
119
+ name: 'update_actor_attributes',
120
+ description: 'Update fields on an actor\'s system data. Patch keys are dot-paths into actor.system (e.g. "attributes.hp.value", "attributes.hp.temp", "currency.gp", "resources.primary.value", "spells.spell1.value", "attributes.exhaustion") and values are absolute target values, never relative deltas. Validates HP <= max + temp, spell slots <= max, and exhaustion within 0-10 (2024) or 0-6 (2014), and returns the post-update value for every patched path. Use when: applying damage or healing, spending a spell slot or resource, or adjusting currency on a known actorId. Do not use when: changing an item the actor owns (use update_actor_item) or only reading current values (use get_actor_details). ' +
121
+ WRITE_GATE,
122
+ inputSchema: {
123
+ type: 'object',
124
+ properties: {
125
+ actorId: {
126
+ type: 'string',
127
+ description: 'The ID of the actor to update',
128
+ },
129
+ patch: {
130
+ type: 'object',
131
+ description: 'Map of dot-path → value, where each dot-path addresses a field under actor.system ' +
132
+ '(e.g. {"attributes.hp.value": 30, "currency.gp": 12}). Values must be number, string, or boolean.',
133
+ additionalProperties: {
134
+ type: ['number', 'string', 'boolean'],
135
+ },
136
+ },
137
+ },
138
+ required: ['actorId', 'patch'],
139
+ },
140
+ },
141
+ {
142
+ name: 'create_world_actor',
143
+ description: 'Create a new top-level Actor document (a permanent NPC or character sheet in the sidebar), optionally seeded with system data and filed under a folder. Use when: a new NPC or creature needs to exist as a persistent document, not just described in text. Do not use when: a quick throwaway description is enough - use generate_npc; or when adding an item to an actor that already exists - use create_actor_item. ' +
144
+ WRITE_GATE,
145
+ inputSchema: {
146
+ type: 'object',
147
+ properties: {
148
+ name: {
149
+ type: 'string',
150
+ description: 'Actor display name',
151
+ },
152
+ type: {
153
+ type: 'string',
154
+ description: 'Game-system actor type (e.g. "character", "npc")',
155
+ },
156
+ system: {
157
+ type: 'object',
158
+ description: 'Optional system-specific data merged into actor.system',
159
+ },
160
+ folder: {
161
+ type: 'string',
162
+ description: 'Optional Folder document id to file the actor under',
163
+ },
164
+ },
165
+ required: ['name', 'type'],
166
+ },
167
+ },
168
+ {
169
+ name: 'create_full_actor',
170
+ description: "Create a new top-level Actor document AND seed it with starting items (skills, gear, weapons, cyberware, …) in one call, instead of create_world_actor followed by one create_actor_item per item. Pairs with get_document_schema: call that once per Actor/Item type to learn the real field names for `system`, then build the whole character here in a single call. The actor is always created first - a failure there aborts the whole call. Item creation is best-effort per item, not atomic: a bad item (e.g. a typo'd type) is reported in the response's item-failures list rather than losing the actor or the items that did succeed. Use when: standing up a fully-statted PC or NPC (correct ability scores/attributes plus starting equipment/skills) in one round trip. Do not use when: the actor already exists - use create_actor_item to add items to it; or a bare/generic actor is enough - use create_world_actor. " +
171
+ WRITE_GATE,
172
+ inputSchema: {
173
+ type: 'object',
174
+ properties: {
175
+ name: {
176
+ type: 'string',
177
+ description: 'Actor display name',
178
+ },
179
+ type: {
180
+ type: 'string',
181
+ description: 'Game-system actor type (e.g. "character", "npc")',
182
+ },
183
+ system: {
184
+ type: 'object',
185
+ description: 'Optional system-specific data merged into actor.system - use get_document_schema("Actor", type) to learn the real field names first',
186
+ },
187
+ folder: {
188
+ type: 'string',
189
+ description: 'Optional Folder document id to file the actor under',
190
+ },
191
+ items: {
192
+ type: 'array',
193
+ description: 'Optional starting items (skills, weapons, gear, cyberware, …) to create on the actor immediately after it exists',
194
+ items: {
195
+ type: 'object',
196
+ properties: {
197
+ name: {
198
+ type: 'string',
199
+ description: 'Item display name',
200
+ },
201
+ type: {
202
+ type: 'string',
203
+ description: 'Game-system item type (e.g. "weapon", "skill") - use get_document_schema("Item", type) to learn the real field names first',
204
+ },
205
+ system: {
206
+ type: 'object',
207
+ description: 'Optional system-specific data merged into item.system',
208
+ },
209
+ },
210
+ required: ['name', 'type'],
211
+ },
212
+ },
213
+ },
214
+ required: ['name', 'type'],
215
+ },
216
+ },
217
+ {
218
+ name: 'delete_world_actor',
219
+ description: 'Permanently delete a top-level Actor document. Use when: the user explicitly asks to remove an NPC or character sheet, and has given you the actorId. Do not use when: only removing a token placed on a scene - use delete_token; the actor document is untouched by that. ' +
220
+ CONFIRM_FIRST +
221
+ ' ' +
222
+ WRITE_GATE,
223
+ inputSchema: {
224
+ type: 'object',
225
+ properties: {
226
+ actorId: {
227
+ type: 'string',
228
+ description: 'The ID of the actor to delete',
229
+ },
230
+ },
231
+ required: ['actorId'],
232
+ },
233
+ },
234
+ ];
235
+ /**
236
+ * Item management tool definitions
237
+ */
238
+ export const itemTools = [
239
+ {
240
+ name: 'search_items',
241
+ description: 'Search item documents in the world by name, optionally filtered by type. Returns name, type and rarity per match (rarity shows "Common" when the system records none); price is not available and always prints "Unknown price", and the rarity filter is ignored unless the REST API module is configured (FOUNDRY_API_KEY). Item ids are not printed - read the foundry://items resource, whose JSON lists up to the first 100 items with their _id (not exhaustive in larger worlds). Use when: checking whether an item exists in the world. Do not use when: searching compendium packs (use search_compendium) or listing what one actor carries (this searches world items, not owned items).',
242
+ inputSchema: {
243
+ type: 'object',
244
+ properties: {
245
+ query: {
246
+ type: 'string',
247
+ description: 'Search query for item names',
248
+ },
249
+ type: {
250
+ type: 'string',
251
+ description: 'Item type filter (weapon, armor, consumable, etc.)',
252
+ },
253
+ rarity: {
254
+ type: 'string',
255
+ description: 'Item rarity filter (common, uncommon, rare, etc.). Applied only in REST API mode (FOUNDRY_API_KEY); ignored on the default Socket.IO path.',
256
+ },
257
+ limit: {
258
+ type: 'number',
259
+ description: 'Maximum number of results to return',
260
+ default: 10,
261
+ },
262
+ cursor: {
263
+ type: 'string',
264
+ description: 'Opaque pagination cursor from a previous response to fetch the next page',
265
+ },
266
+ },
267
+ },
268
+ },
269
+ ];
270
+ /**
271
+ * Compendium search tool definitions (laurigates/foundryvtt-mcp#144)
272
+ */
273
+ export const compendiumTools = [
274
+ {
275
+ name: 'search_compendium',
276
+ description: 'Search FoundryVTT compendium packs by name and metadata; searches all enabled packs unless compendiumId scopes it to one pack. Use when: looking up spells, monsters, or equipment that are not yet present in the world. Do not use when: the document already exists in the world - use search_items or search_world. Requires the REST API module (FOUNDRY_API_KEY); without it the search returns no results instead of failing.',
277
+ inputSchema: {
278
+ type: 'object',
279
+ properties: {
280
+ query: {
281
+ type: 'string',
282
+ description: 'Search query for compendium entry names',
283
+ },
284
+ filters: {
285
+ type: 'object',
286
+ description: 'Optional metadata filters to narrow the search',
287
+ properties: {
288
+ compendiumId: {
289
+ type: 'string',
290
+ description: 'Scope the search to a single compendium pack',
291
+ },
292
+ packType: {
293
+ type: 'string',
294
+ description: 'Pack document type (Item, Actor, JournalEntry, Macro)',
295
+ },
296
+ itemType: {
297
+ type: 'string',
298
+ description: 'Item type filter (spell, weapon, feat, etc.)',
299
+ },
300
+ spellLevel: {
301
+ type: 'number',
302
+ description: 'Spell level filter',
303
+ },
304
+ source: {
305
+ type: 'string',
306
+ description: 'Source/rules filter (e.g. a sourcebook abbreviation)',
307
+ },
308
+ },
309
+ },
310
+ limit: {
311
+ type: 'number',
312
+ description: 'Maximum number of results per page',
313
+ default: 20,
314
+ },
315
+ cursor: {
316
+ type: 'string',
317
+ description: 'Opaque pagination cursor from a prior result\'s "Next page" cursor; omit for the first page',
318
+ },
319
+ },
320
+ required: ['query'],
321
+ },
322
+ },
323
+ ];
324
+ /**
325
+ * Actor item mutation tool definitions (WRITE — require FOUNDRY_WRITE_ENABLED
326
+ * and an active Socket.IO connection; mutations use `modifyDocument`)
327
+ *
328
+ * The canonical mutation target is the D&D 5e v4+ activity schema. Item
329
+ * `system` patches honour JSON-merge-patch semantics on nested paths.
330
+ */
331
+ export const itemMutationTools = [
332
+ {
333
+ name: 'create_actor_item',
334
+ description: 'Create an item on an actor from an inline item document (type, name, system) or by referencing a compendium pack entry (compendium sources require the companion Foundry module). Use when: adding a new weapon, spell, feature, or piece of equipment to a known actorId. Do not use when: editing an item the actor already owns - use update_actor_item. Replacing an item is not atomic: create the replacement first and delete the old one second. Canonical target: D&D 5e v4+ activity schema. ' +
335
+ WRITE_GATE,
336
+ inputSchema: {
337
+ type: 'object',
338
+ properties: {
339
+ actorId: {
340
+ type: 'string',
341
+ description: 'The ID of the actor to add the item to',
342
+ },
343
+ source: {
344
+ type: 'object',
345
+ description: 'Item source. Either { type: "inline", item: { type, name, system } } or { type: "compendium", compendiumId, itemId } (requires companion module).',
346
+ properties: {
347
+ type: {
348
+ type: 'string',
349
+ enum: ['compendium', 'inline'],
350
+ description: 'Source kind: "inline" (provides inline item data) or "compendium" (fetches from pack via companion module).',
351
+ },
352
+ compendiumId: {
353
+ type: 'string',
354
+ description: 'Compendium pack id (compendium source)',
355
+ },
356
+ itemId: {
357
+ type: 'string',
358
+ description: 'Item id within the compendium pack (compendium source)',
359
+ },
360
+ item: {
361
+ type: 'object',
362
+ description: 'Inline item document with type, name, and system (inline source)',
363
+ },
364
+ },
365
+ required: ['type'],
366
+ },
367
+ },
368
+ required: ['actorId', 'source'],
369
+ },
370
+ },
371
+ {
372
+ name: 'update_actor_item',
373
+ description: "Apply a JSON merge patch to an item's system data on an actor: nested paths such as activities.{id}.consumption.targets are supported, values are absolute (arrays replace, null deletes). Use when: changing fields on an item the actor already owns, given actorId + itemId. Do not use when: adding a new item (create_actor_item) or removing one (delete_actor_item). Canonical target: D&D 5e v4+ activity schema. " +
374
+ WRITE_GATE,
375
+ inputSchema: {
376
+ type: 'object',
377
+ properties: {
378
+ actorId: {
379
+ type: 'string',
380
+ description: 'The ID of the actor that owns the item',
381
+ },
382
+ itemId: {
383
+ type: 'string',
384
+ description: 'The ID of the item to update',
385
+ },
386
+ patch: {
387
+ type: 'object',
388
+ description: 'JSON merge patch applied to item.system; nested paths supported (e.g. activities.{id}.consumption.targets)',
389
+ },
390
+ },
391
+ required: ['actorId', 'itemId', 'patch'],
392
+ },
393
+ },
394
+ {
395
+ name: 'delete_actor_item',
396
+ description: "Permanently remove an item owned by an actor. Use when: the user explicitly asks to delete or discard a specific owned item, and has given you the itemId - no tool in this server lists owned-item ids, so never guess one. Do not use when: only the item's data needs to change - use update_actor_item. In a replacement or migration flow, run create_actor_item first and this second: the two calls are not atomic, and failing after the delete loses the item. Echo the actorId and itemId back to the user and get their confirmation before calling. " +
397
+ CONFIRM_FIRST +
398
+ ' ' +
399
+ WRITE_GATE,
400
+ inputSchema: {
401
+ type: 'object',
402
+ properties: {
403
+ actorId: {
404
+ type: 'string',
405
+ description: 'The ID of the actor that owns the item',
406
+ },
407
+ itemId: {
408
+ type: 'string',
409
+ description: 'The ID of the item to delete',
410
+ },
411
+ },
412
+ required: ['actorId', 'itemId'],
413
+ },
414
+ },
415
+ ];
416
+ /**
417
+ * Scene management tool definitions
418
+ */
419
+ export const sceneTools = [
420
+ {
421
+ name: 'get_scene_info',
422
+ description: "Get details of the active scene, or of a specific scene by id: name, scene id, active/navigation flags, pixel dimensions, padding, grid (type, size in pixels, distance, units), and lighting (global light, darkness); no description text is returned unless a module has set a description flag on the scene (the description line otherwise reads 'No description available.'). Use when: you need the sceneId, grid size, or the scene's pixel extents. Do not use when: looking a scene up by name (use search_world), or you need token/tile coordinates - this tool returns neither; use list_tiles or the foundry://scenes resource.",
423
+ inputSchema: {
424
+ type: 'object',
425
+ properties: {
426
+ sceneId: {
427
+ type: 'string',
428
+ description: 'Optional scene ID. If not provided, returns current scene',
429
+ },
430
+ },
431
+ },
432
+ },
433
+ ];
434
+ /**
435
+ * Scene mutation tool definitions
436
+ *
437
+ * WRITE operations — require FOUNDRY_WRITE_ENABLED=true and an active
438
+ * Socket.IO connection (mutations use the core `modifyDocument` protocol).
439
+ */
440
+ export const sceneMutationTools = [
441
+ {
442
+ name: 'create_scene',
443
+ description: "Create a new Scene document from a background image already present under FoundryVTT's Data directory (see list_scene_assets to browse available map art). Width/height default to the image's real pixel dimensions read from disk (requires FOUNDRY_DATA_PATH) — the single biggest source of a misaligned grid when set by hand; pass width/height explicitly to override. Use when: a new location needs a scene before the party arrives there, or a fresh battlemap needs to exist as a document. Do not use when: the scene already exists - use switch_scene to activate it, or set_scene_lighting to change its lighting. " +
444
+ WRITE_GATE,
445
+ inputSchema: {
446
+ type: 'object',
447
+ properties: {
448
+ name: {
449
+ type: 'string',
450
+ description: 'Scene display name',
451
+ },
452
+ backgroundSrc: {
453
+ type: 'string',
454
+ description: 'Data-relative path to the background image (e.g. "assets/cyberpunk/maps/v1/x.jpg"), as returned by list_scene_assets',
455
+ },
456
+ width: {
457
+ type: 'number',
458
+ description: "Optional explicit pixel width; defaults to the image's real width",
459
+ },
460
+ height: {
461
+ type: 'number',
462
+ description: "Optional explicit pixel height; defaults to the image's real height",
463
+ },
464
+ gridSize: {
465
+ type: 'number',
466
+ description: 'Grid cell size in pixels (default 100)',
467
+ },
468
+ gridType: {
469
+ type: 'number',
470
+ description: 'Foundry grid type constant (default 1 = square)',
471
+ },
472
+ gridDistance: {
473
+ type: 'number',
474
+ description: 'Real-world distance one grid cell represents (default 1)',
475
+ },
476
+ gridUnits: {
477
+ type: 'string',
478
+ description: 'Unit label for gridDistance (e.g. "ft", "m") (default "ft")',
479
+ },
480
+ padding: {
481
+ type: 'number',
482
+ description: 'Fractional canvas padding around the background image (default 0.25)',
483
+ },
484
+ backgroundColor: {
485
+ type: 'string',
486
+ description: 'Hex color shown outside the background image (default "#999999")',
487
+ },
488
+ activate: {
489
+ type: 'boolean',
490
+ description: 'Optional; true to immediately activate the new scene for all players',
491
+ },
492
+ },
493
+ required: ['name', 'backgroundSrc'],
494
+ },
495
+ },
496
+ {
497
+ name: 'switch_scene',
498
+ description: "Activate a scene, switching every connected player's canvas to it. FoundryVTT enforces a single active scene server-side, so activating one automatically deactivates whichever scene was active before - no separate deactivation call is needed. Use when: the party moves to a new map (new area, travel, a battle starting on a prepared map). Do not use when: you only need to read scene info - use get_scene_info. " +
499
+ WRITE_GATE,
500
+ inputSchema: {
501
+ type: 'object',
502
+ properties: {
503
+ sceneId: {
504
+ type: 'string',
505
+ description: 'The ID of the scene to activate',
506
+ },
507
+ },
508
+ required: ['sceneId'],
509
+ },
510
+ },
511
+ {
512
+ name: 'delete_scene',
513
+ description: 'Permanently delete a Scene document. Use when: the user explicitly asks to remove a map that is no longer needed. Do not use when: you only want to stop showing it to players - use switch_scene to activate a different one instead; deleting the active scene leaves no scene active. ' +
514
+ CONFIRM_FIRST +
515
+ ' ' +
516
+ WRITE_GATE,
517
+ inputSchema: {
518
+ type: 'object',
519
+ properties: {
520
+ sceneId: {
521
+ type: 'string',
522
+ description: 'The ID of the scene to delete',
523
+ },
524
+ },
525
+ required: ['sceneId'],
526
+ },
527
+ },
528
+ {
529
+ name: 'set_scene_lighting',
530
+ description: "Set a scene's ambient darkness level (0-1) and/or global illumination fields (globalLight, globalLightThreshold). Plain Scene document fields - no canvas access required. Use when: transitioning to night, dimming a room, or lighting a torch-lit area. Do not use when: you only need to read current lighting - use get_scene_info. " +
531
+ WRITE_GATE,
532
+ inputSchema: {
533
+ type: 'object',
534
+ properties: {
535
+ sceneId: {
536
+ type: 'string',
537
+ description: 'The ID of the scene to update',
538
+ },
539
+ darkness: {
540
+ type: 'number',
541
+ minimum: 0,
542
+ maximum: 1,
543
+ description: 'Ambient darkness level, 0 (fully lit) to 1 (pitch black)',
544
+ },
545
+ globalLight: {
546
+ type: 'boolean',
547
+ description: 'Whether the whole scene is globally illuminated',
548
+ },
549
+ globalLightThreshold: {
550
+ type: 'number',
551
+ description: 'Darkness level above which global light is suppressed',
552
+ },
553
+ },
554
+ required: ['sceneId'],
555
+ },
556
+ },
557
+ {
558
+ name: 'reset_fog',
559
+ description: 'Reset fog of war exploration progress for a scene, defaulting to the active scene when sceneId is omitted. ' +
560
+ CONFIRM_FIRST +
561
+ ' ' +
562
+ WRITE_GATE,
563
+ inputSchema: {
564
+ type: 'object',
565
+ properties: {
566
+ sceneId: {
567
+ type: 'string',
568
+ description: 'Optional Scene ID; defaults to the active scene',
569
+ },
570
+ },
571
+ },
572
+ },
573
+ {
574
+ name: 'set_scene_weather',
575
+ description: 'Set or clear weather effects on a scene (e.g. "rain", "snow", "leaves", "rainStorm", "fog", or empty string "" to clear). Default values come from Foundry core; additional effects may be available if weather modules are installed. ' +
576
+ WRITE_GATE,
577
+ inputSchema: {
578
+ type: 'object',
579
+ properties: {
580
+ weather: {
581
+ type: 'string',
582
+ description: 'Weather effect key (e.g. "rain", "snow", "leaves", "rainStorm", "fog"), or "" to clear',
583
+ },
584
+ sceneId: {
585
+ type: 'string',
586
+ description: 'Optional Scene ID; defaults to the active scene',
587
+ },
588
+ },
589
+ required: ['weather'],
590
+ },
591
+ },
592
+ ];
593
+ /**
594
+ * Wall (structural) tool definitions
595
+ *
596
+ * `list_walls` is a pure read over cached worldData. `create_wall`,
597
+ * `delete_wall`, and `set_door_state` are WRITE operations — require
598
+ * FOUNDRY_WRITE_ENABLED=true and an active Socket.IO connection (mutations
599
+ * use the core `modifyDocument` protocol). `ds` (door state) is a plain
600
+ * field on the `Wall` embedded document, so none of this needs canvas access.
601
+ */
602
+ export const wallMutationTools = [
603
+ {
604
+ name: 'list_walls',
605
+ description: "List the Walls on a scene (id, endpoints, and the move/sight/door/ds fields), defaulting to the active scene when sceneId is omitted. Read from cached worldData - no canvas access needed. Use when: finding a wallId for delete_wall/set_door_state, or checking a scene's current wall layout before adding more. Do not use when: you need tile or token positions instead - this only lists Wall documents.",
606
+ inputSchema: {
607
+ type: 'object',
608
+ properties: {
609
+ sceneId: {
610
+ type: 'string',
611
+ description: 'Optional Scene ID; defaults to the active scene',
612
+ },
613
+ },
614
+ },
615
+ },
616
+ {
617
+ name: 'create_wall',
618
+ description: 'Create a new Wall segment on a scene - the structural building block for rooms, corridors, and doors. Unlike create_tile (which centres in a cell), a wall connects two grid *vertices* (intersections): fromCol/fromRow -> toCol/toRow, e.g. fromCol:3,fromRow:5 -> toCol:4,toRow:5 is the one-cell-long top edge of cell (3,5); a longer run spans multiple cells in one call. Alternatively pass explicit pixel x1/y1/x2/y2. type selects one of FoundryVTT\'s own named wall presets (the ones its wall-tool palette offers): "wall" (default, solid - blocks movement and sight), "door" (openable via set_door_state, starts closed), "secretDoor" (looks like a wall until discovered, starts closed), "terrain" (blocks movement; sight/light only block on the second crossing - hedges, foliage: you can see the hedge but not what is directly behind it), "invisible" (blocks movement but not sight - furniture, low obstacles, hidden traps), "ethereal" (the inverse of invisible: blocks sight but not movement - magical curtains, spectral barriers). Use when: building out a scene\'s room layout, or adding a door/terrain/invisible/ethereal wall to an existing wall line. Do not use when: you want to toggle an existing door open/closed/locked - use set_door_state; or decorate with a prop - use create_tile. ' +
619
+ WRITE_GATE,
620
+ inputSchema: {
621
+ type: 'object',
622
+ properties: {
623
+ sceneId: {
624
+ type: 'string',
625
+ description: 'The ID of the scene to place the wall on',
626
+ },
627
+ x1: {
628
+ type: 'number',
629
+ description: 'Start pixel x coordinate. Alternative to fromCol/fromRow.',
630
+ },
631
+ y1: {
632
+ type: 'number',
633
+ description: 'Start pixel y coordinate. Alternative to fromCol/fromRow.',
634
+ },
635
+ x2: {
636
+ type: 'number',
637
+ description: 'End pixel x coordinate. Alternative to toCol/toRow.',
638
+ },
639
+ y2: {
640
+ type: 'number',
641
+ description: 'End pixel y coordinate. Alternative to toCol/toRow.',
642
+ },
643
+ fromCol: {
644
+ type: 'number',
645
+ description: 'Start grid vertex column. Alternative to x1/y1.',
646
+ },
647
+ fromRow: {
648
+ type: 'number',
649
+ description: 'Start grid vertex row. Alternative to x1/y1.',
650
+ },
651
+ toCol: {
652
+ type: 'number',
653
+ description: 'End grid vertex column. Alternative to x2/y2.',
654
+ },
655
+ toRow: {
656
+ type: 'number',
657
+ description: 'End grid vertex row. Alternative to x2/y2.',
658
+ },
659
+ type: {
660
+ type: 'string',
661
+ enum: ['wall', 'door', 'secretDoor', 'terrain', 'invisible', 'ethereal'],
662
+ description: 'Wall nature (default "wall"): wall = solid; door = openable, starts closed; secretDoor = hidden until discovered, starts closed; terrain = blocks movement, sight blocks only on the second crossing; invisible = blocks movement, not sight; ethereal = blocks sight, not movement',
663
+ },
664
+ },
665
+ required: ['sceneId'],
666
+ },
667
+ },
668
+ {
669
+ name: 'delete_wall',
670
+ description: 'Remove a Wall from a scene. Use when: undoing a placement mistake, or opening up a room by removing a wall segment entirely (as opposed to opening a door - use set_door_state to keep the wall and just toggle it). Do not use when: you want to remove a tile or token instead - this only affects Wall documents. ' +
671
+ WRITE_GATE,
672
+ inputSchema: {
673
+ type: 'object',
674
+ properties: {
675
+ sceneId: {
676
+ type: 'string',
677
+ description: 'The ID of the scene the wall is on',
678
+ },
679
+ wallId: {
680
+ type: 'string',
681
+ description: 'The ID of the wall to remove',
682
+ },
683
+ },
684
+ required: ['sceneId', 'wallId'],
685
+ },
686
+ },
687
+ {
688
+ name: 'set_door_state',
689
+ description: "Open, close, or lock a door (a Wall document with door !== 0). Use when: a party opens or shuts a door, or a door should be locked/unlocked. Do not use when: you don't have the wallId - use list_walls, or ask the user, or read the foundry://scenes resource. " +
690
+ WRITE_GATE,
691
+ inputSchema: {
692
+ type: 'object',
693
+ properties: {
694
+ wallId: {
695
+ type: 'string',
696
+ description: 'The ID of the door (Wall document) to change',
697
+ },
698
+ state: {
699
+ type: 'number',
700
+ enum: [0, 1, 2],
701
+ description: '0 = closed, 1 = open, 2 = locked',
702
+ },
703
+ sceneId: {
704
+ type: 'string',
705
+ description: 'Optional Scene ID to scope the wall lookup',
706
+ },
707
+ },
708
+ required: ['wallId', 'state'],
709
+ },
710
+ },
711
+ ];
712
+ /**
713
+ * Tile read tool definitions
714
+ *
715
+ * All three are pure reads over cached worldData or the local filesystem
716
+ * (list_scene_assets, requires FOUNDRY_DATA_PATH) — no FOUNDRY_WRITE_ENABLED
717
+ * needed. Together they let a scene be decorated without a `capture_scene`
718
+ * screenshot: browse available art, find where it's safe to place, check
719
+ * what's already down.
720
+ */
721
+ export const tileTools = [
722
+ {
723
+ name: 'list_scene_assets',
724
+ description: 'List image assets (map backgrounds, prop/token art) under a folder of the FoundryVTT Data directory, with real pixel dimensions and any `[Tag, Tag]`-bracketed keyword tags parsed out of the filename (the naming convention several battlemap packs use). Requires FOUNDRY_DATA_PATH — this server must run on the same host as FoundryVTT. Use when: choosing a background for create_scene, or browsing available decoration art for create_tile before placing anything. Do not use when: FOUNDRY_DATA_PATH is not set - this always returns empty in that case.',
725
+ inputSchema: {
726
+ type: 'object',
727
+ properties: {
728
+ subdir: {
729
+ type: 'string',
730
+ description: 'Data-relative folder to scan (default "assets")',
731
+ },
732
+ query: {
733
+ type: 'string',
734
+ description: 'Optional case-insensitive substring filter on filename or parsed tags',
735
+ },
736
+ limit: {
737
+ type: 'number',
738
+ description: 'Maximum results to return (default 200)',
739
+ },
740
+ kind: {
741
+ type: 'string',
742
+ enum: ['image', 'audio'],
743
+ description: 'Asset category to scan for: "image" (default) or "audio"',
744
+ default: 'image',
745
+ },
746
+ },
747
+ },
748
+ },
749
+ {
750
+ name: 'list_tiles',
751
+ description: 'List the Tiles placed on a scene (id, image src, position, size, rotation, hidden), defaulting to the active scene when sceneId is omitted. Read from cached worldData - no capture_scene screenshot needed to see current decoration state. Use when: checking what is already placed before adding more, or getting a tileId for delete_tile. Do not use when: you need token positions instead of tile positions - tiles and tokens are separate document types; this only lists tiles.',
752
+ inputSchema: {
753
+ type: 'object',
754
+ properties: {
755
+ sceneId: {
756
+ type: 'string',
757
+ description: 'Optional Scene ID; defaults to the active scene',
758
+ },
759
+ },
760
+ },
761
+ },
762
+ {
763
+ name: 'find_open_cells',
764
+ description: "Scan a scene's grid for cells with no wall crossing them and no existing tile/token already centred there - a placement candidate list for create_tile/spawn_token that needs no screenshot to compute. Restricted to the background image's own extent; the scene's padding margin is never returned as floor. Use when: deciding where to place a new tile or token without visual inspection. Do not use when: you already have a specific target position in mind - this is for open-ended 'somewhere sensible' placement, not for verifying one exact spot.",
765
+ inputSchema: {
766
+ type: 'object',
767
+ properties: {
768
+ sceneId: {
769
+ type: 'string',
770
+ description: 'The ID of the scene to scan',
771
+ },
772
+ limit: {
773
+ type: 'number',
774
+ description: 'Maximum open cells to return (default 50)',
775
+ },
776
+ },
777
+ required: ['sceneId'],
778
+ },
779
+ },
780
+ ];
781
+ /**
782
+ * Tile mutation tool definitions
783
+ *
784
+ * WRITE operations — require FOUNDRY_WRITE_ENABLED=true and an active
785
+ * Socket.IO connection (mutations use the core `modifyDocument` protocol).
786
+ */
787
+ export const tileMutationTools = [
788
+ {
789
+ name: 'create_tile',
790
+ description: "Place a decorative Tile on a scene from an image already present under FoundryVTT's Data directory (see list_scene_assets). Width/height default to the image's real pixel dimensions when not given. Position is either explicit pixel x/y (top-left corner) or a gridCol/gridRow cell (the tile is centred in that cell - see find_open_cells for candidates). By default refuses to place a tile whose bounding box crosses a scene wall; pass allowWallOverlap: true to place anyway (e.g. a wall-mounted prop). Use when: decorating a scene with scenery (crates, dumpsters, vehicles, graffiti) that is not a creature or NPC. Do not use when: the object is a creature/NPC that should have HP and act in combat - use create_world_actor + spawn_token instead. " +
791
+ WRITE_GATE,
792
+ inputSchema: {
793
+ type: 'object',
794
+ properties: {
795
+ sceneId: {
796
+ type: 'string',
797
+ description: 'The ID of the scene to place the tile on',
798
+ },
799
+ src: {
800
+ type: 'string',
801
+ description: 'Data-relative path to the tile image, as returned by list_scene_assets',
802
+ },
803
+ x: {
804
+ type: 'number',
805
+ description: 'Target top-left x pixel coordinate. Alternative to gridCol/gridRow.',
806
+ },
807
+ y: {
808
+ type: 'number',
809
+ description: 'Target top-left y pixel coordinate. Alternative to gridCol/gridRow.',
810
+ },
811
+ gridCol: {
812
+ type: 'number',
813
+ description: 'Grid column to centre the tile in. Alternative to x/y.',
814
+ },
815
+ gridRow: {
816
+ type: 'number',
817
+ description: 'Grid row to centre the tile in. Alternative to x/y.',
818
+ },
819
+ width: {
820
+ type: 'number',
821
+ description: "Optional explicit pixel width; defaults to the image's real width",
822
+ },
823
+ height: {
824
+ type: 'number',
825
+ description: "Optional explicit pixel height; defaults to the image's real height",
826
+ },
827
+ rotation: {
828
+ type: 'number',
829
+ description: 'Optional rotation in degrees (default 0)',
830
+ },
831
+ elevation: {
832
+ type: 'number',
833
+ description: 'Optional elevation (default 0)',
834
+ },
835
+ hidden: {
836
+ type: 'boolean',
837
+ description: 'Optional; true to place the tile hidden from players',
838
+ },
839
+ allowWallOverlap: {
840
+ type: 'boolean',
841
+ description: 'Optional; true to allow placement even if the bounding box crosses a wall (default false - refuses)',
842
+ },
843
+ },
844
+ required: ['sceneId', 'src'],
845
+ },
846
+ },
847
+ {
848
+ name: 'delete_tile',
849
+ description: 'Remove a Tile from a scene. Use when: undoing a placement mistake, or clearing decoration that no longer fits the scene. Do not use when: you want to remove a token or actor instead - this only affects Tile documents; use delete_token or delete_world_actor. ' +
850
+ WRITE_GATE,
851
+ inputSchema: {
852
+ type: 'object',
853
+ properties: {
854
+ sceneId: {
855
+ type: 'string',
856
+ description: 'The ID of the scene the tile is on',
857
+ },
858
+ tileId: {
859
+ type: 'string',
860
+ description: 'The ID of the tile to remove',
861
+ },
862
+ },
863
+ required: ['sceneId', 'tileId'],
864
+ },
865
+ },
866
+ ];
867
+ /**
868
+ * Placeable read tools (lights, sounds, notes, drawings, templates).
869
+ * Pure reads over cached worldData — no write gate.
870
+ */
871
+ export const placeableTools = [
872
+ {
873
+ name: 'list_lights',
874
+ description: 'List the AmbientLight sources placed on a scene (id, position, dim/bright radius, color, rotation, animation, hidden), defaulting to the active scene when sceneId is omitted. Read from cached worldData - no canvas access needed. Use when: inspecting scene lighting or finding a lightId for update_light/delete_light.',
875
+ inputSchema: {
876
+ type: 'object',
877
+ properties: {
878
+ sceneId: {
879
+ type: 'string',
880
+ description: 'Optional Scene ID; defaults to the active scene',
881
+ },
882
+ },
883
+ },
884
+ },
885
+ {
886
+ name: 'list_sounds',
887
+ description: 'List the AmbientSound sources placed on a scene (id, position, radius, audio path, volume, repeat, hidden), defaulting to the active scene when sceneId is omitted. Read from cached worldData - no canvas access needed. Use when: inspecting ambient audio or finding a soundId for delete_sound.',
888
+ inputSchema: {
889
+ type: 'object',
890
+ properties: {
891
+ sceneId: {
892
+ type: 'string',
893
+ description: 'Optional Scene ID; defaults to the active scene',
894
+ },
895
+ },
896
+ },
897
+ },
898
+ {
899
+ name: 'list_notes',
900
+ description: 'List the Map Notes (journal pins) placed on a scene (id, position, label text, linked journal entry and page, global visibility), defaulting to the active scene when sceneId is omitted. Read from cached worldData - no canvas access needed. Use when: finding pins on the map or getting a noteId for delete_note.',
901
+ inputSchema: {
902
+ type: 'object',
903
+ properties: {
904
+ sceneId: {
905
+ type: 'string',
906
+ description: 'Optional Scene ID; defaults to the active scene',
907
+ },
908
+ },
909
+ },
910
+ },
911
+ {
912
+ name: 'list_drawings',
913
+ description: 'List the Drawings placed on a scene (id, shape type, position, dimensions/radius, text label, colors, hidden, locked), defaulting to the active scene when sceneId is omitted. Read from cached worldData - no canvas access needed. Use when: inspecting canvas shapes or finding a drawingId for delete_drawing.',
914
+ inputSchema: {
915
+ type: 'object',
916
+ properties: {
917
+ sceneId: {
918
+ type: 'string',
919
+ description: 'Optional Scene ID; defaults to the active scene',
920
+ },
921
+ },
922
+ },
923
+ },
924
+ {
925
+ name: 'list_templates',
926
+ description: 'List the Measured Templates (AOE spell/effect shapes) placed on a scene (id, template type, position, distance, direction, angle, width, colors, hidden), defaulting to the active scene when sceneId is omitted. Read from cached worldData - no canvas access needed. Use when: inspecting active spell areas or finding a templateId for delete_template.',
927
+ inputSchema: {
928
+ type: 'object',
929
+ properties: {
930
+ sceneId: {
931
+ type: 'string',
932
+ description: 'Optional Scene ID; defaults to the active scene',
933
+ },
934
+ },
935
+ },
936
+ },
937
+ ];
938
+ /**
939
+ * Placeable mutation tools (lights, sounds, notes, drawings, templates).
940
+ * WRITE operations — require FOUNDRY_WRITE_ENABLED=true and an active Socket.IO connection.
941
+ */
942
+ export const placeableMutationTools = [
943
+ {
944
+ name: 'create_light',
945
+ description: 'Create a new AmbientLight source on a scene at either pixel x/y or a gridCol/gridRow cell (the light is centered in that cell). Supports dim/bright radii, color hex tint (#rrggbb), angle, rotation, and animation presets (e.g. torch, pulse, chroma). ' +
946
+ WRITE_GATE,
947
+ inputSchema: {
948
+ type: 'object',
949
+ properties: {
950
+ sceneId: {
951
+ type: 'string',
952
+ description: 'Optional Scene ID; defaults to the active scene',
953
+ },
954
+ x: { type: 'number', description: 'Pixel x coordinate (center)' },
955
+ y: { type: 'number', description: 'Pixel y coordinate (center)' },
956
+ gridCol: { type: 'number', description: 'Grid column (centers in cell)' },
957
+ gridRow: { type: 'number', description: 'Grid row (centers in cell)' },
958
+ dim: {
959
+ type: 'number',
960
+ description: 'Dim light radius in grid units (default 0)',
961
+ default: 0,
962
+ },
963
+ bright: {
964
+ type: 'number',
965
+ description: 'Bright light radius in grid units (default 0)',
966
+ default: 0,
967
+ },
968
+ color: {
969
+ type: 'string',
970
+ description: 'Light color as a 6-digit hex string (e.g. "#ff8800")',
971
+ },
972
+ angle: {
973
+ type: 'number',
974
+ description: 'Light emission angle in degrees (default 360)',
975
+ default: 360,
976
+ },
977
+ rotation: {
978
+ type: 'number',
979
+ description: 'Light rotation in degrees (default 0)',
980
+ default: 0,
981
+ },
982
+ animationType: {
983
+ type: 'string',
984
+ description: 'Optional animation type (e.g. "torch", "pulse", "chroma", "wave")',
985
+ },
986
+ animationSpeed: {
987
+ type: 'number',
988
+ description: 'Animation speed 0-10 (default 5)',
989
+ default: 5,
990
+ },
991
+ animationIntensity: {
992
+ type: 'number',
993
+ description: 'Animation intensity 1-10 (default 5)',
994
+ default: 5,
995
+ },
996
+ walls: {
997
+ type: 'boolean',
998
+ description: 'Whether light is constrained by walls (default true)',
999
+ default: true,
1000
+ },
1001
+ vision: {
1002
+ type: 'boolean',
1003
+ description: 'Whether this light provides vision to tokens (default false)',
1004
+ default: false,
1005
+ },
1006
+ hidden: {
1007
+ type: 'boolean',
1008
+ description: 'Whether the light source is hidden (default false)',
1009
+ default: false,
1010
+ },
1011
+ },
1012
+ },
1013
+ },
1014
+ {
1015
+ name: 'update_light',
1016
+ description: 'Update an existing AmbientLight source on a scene (radii, color, position, angle, animation, walls/vision/hidden). ' +
1017
+ WRITE_GATE,
1018
+ inputSchema: {
1019
+ type: 'object',
1020
+ properties: {
1021
+ lightId: { type: 'string', description: 'The ID of the ambient light to update' },
1022
+ sceneId: { type: 'string', description: 'Optional Scene ID; defaults to the active scene' },
1023
+ x: { type: 'number', description: 'New pixel x coordinate' },
1024
+ y: { type: 'number', description: 'New pixel y coordinate' },
1025
+ dim: { type: 'number', description: 'Dim light radius in grid units' },
1026
+ bright: { type: 'number', description: 'Bright light radius in grid units' },
1027
+ color: {
1028
+ type: 'string',
1029
+ description: 'Light color as a 6-digit hex string (e.g. "#ff8800")',
1030
+ },
1031
+ angle: { type: 'number', description: 'Light emission angle in degrees' },
1032
+ rotation: { type: 'number', description: 'Light rotation in degrees' },
1033
+ walls: { type: 'boolean', description: 'Whether light is constrained by walls' },
1034
+ vision: { type: 'boolean', description: 'Whether this light provides vision' },
1035
+ hidden: { type: 'boolean', description: 'Whether the light source is hidden' },
1036
+ },
1037
+ required: ['lightId'],
1038
+ },
1039
+ },
1040
+ {
1041
+ name: 'delete_light',
1042
+ description: `Permanently remove an AmbientLight from a scene. ${CONFIRM_FIRST} ${WRITE_GATE}`,
1043
+ inputSchema: {
1044
+ type: 'object',
1045
+ properties: {
1046
+ lightId: { type: 'string', description: 'The ID of the ambient light to delete' },
1047
+ sceneId: { type: 'string', description: 'Optional Scene ID; defaults to the active scene' },
1048
+ },
1049
+ required: ['lightId'],
1050
+ },
1051
+ },
1052
+ {
1053
+ name: 'create_sound',
1054
+ description: 'Create an AmbientSound source on a scene from an audio file path (browse available audio via list_scene_assets with kind="audio"). Placement is either pixel x/y or a gridCol/gridRow cell. ' +
1055
+ WRITE_GATE,
1056
+ inputSchema: {
1057
+ type: 'object',
1058
+ properties: {
1059
+ path: { type: 'string', description: 'Audio file path (e.g. "assets/audio/rain.mp3")' },
1060
+ sceneId: { type: 'string', description: 'Optional Scene ID; defaults to the active scene' },
1061
+ x: { type: 'number', description: 'Pixel x coordinate (center)' },
1062
+ y: { type: 'number', description: 'Pixel y coordinate (center)' },
1063
+ gridCol: { type: 'number', description: 'Grid column (centers in cell)' },
1064
+ gridRow: { type: 'number', description: 'Grid row (centers in cell)' },
1065
+ radius: {
1066
+ type: 'number',
1067
+ description: 'Audible radius in grid units (default 0)',
1068
+ default: 0,
1069
+ },
1070
+ volume: {
1071
+ type: 'number',
1072
+ description: 'Playback volume 0.0 to 1.0 (default 0.5)',
1073
+ default: 0.5,
1074
+ },
1075
+ repeat: {
1076
+ type: 'boolean',
1077
+ description: 'Whether the audio loops continuously (default false)',
1078
+ default: false,
1079
+ },
1080
+ walls: {
1081
+ type: 'boolean',
1082
+ description: 'Whether sound is blocked by walls (default true)',
1083
+ default: true,
1084
+ },
1085
+ easing: {
1086
+ type: 'boolean',
1087
+ description: 'Whether volume fades towards the boundary (default true)',
1088
+ default: true,
1089
+ },
1090
+ hidden: {
1091
+ type: 'boolean',
1092
+ description: 'Whether the sound is hidden/disabled (default false)',
1093
+ default: false,
1094
+ },
1095
+ },
1096
+ required: ['path'],
1097
+ },
1098
+ },
1099
+ {
1100
+ name: 'delete_sound',
1101
+ description: `Permanently remove an AmbientSound from a scene. ${CONFIRM_FIRST} ${WRITE_GATE}`,
1102
+ inputSchema: {
1103
+ type: 'object',
1104
+ properties: {
1105
+ soundId: { type: 'string', description: 'The ID of the ambient sound to delete' },
1106
+ sceneId: { type: 'string', description: 'Optional Scene ID; defaults to the active scene' },
1107
+ },
1108
+ required: ['soundId'],
1109
+ },
1110
+ },
1111
+ {
1112
+ name: 'create_note',
1113
+ description: 'Place a Map Note (journal pin) on a scene at pixel x/y or a gridCol/gridRow cell. Must link to an entryId (journal entry), provide text (standalone label), or both. ' +
1114
+ WRITE_GATE,
1115
+ inputSchema: {
1116
+ type: 'object',
1117
+ properties: {
1118
+ sceneId: { type: 'string', description: 'Optional Scene ID; defaults to the active scene' },
1119
+ entryId: {
1120
+ type: 'string',
1121
+ description: 'Optional JournalEntry document ID to link to this pin',
1122
+ },
1123
+ pageId: {
1124
+ type: 'string',
1125
+ description: 'Optional JournalEntryPage ID within the linked entry',
1126
+ },
1127
+ text: { type: 'string', description: 'Optional label text displayed below or on the pin' },
1128
+ x: { type: 'number', description: 'Pixel x coordinate (center)' },
1129
+ y: { type: 'number', description: 'Pixel y coordinate (center)' },
1130
+ gridCol: { type: 'number', description: 'Grid column (centers in cell)' },
1131
+ gridRow: { type: 'number', description: 'Grid row (centers in cell)' },
1132
+ iconSize: {
1133
+ type: 'number',
1134
+ description: 'Pin icon size in pixels (minimum 32, default 40)',
1135
+ default: 40,
1136
+ },
1137
+ fontSize: {
1138
+ type: 'number',
1139
+ description: 'Label font size in pixels (8-128, default 32)',
1140
+ default: 32,
1141
+ },
1142
+ textAnchor: {
1143
+ type: 'number',
1144
+ description: 'Text anchor point: 0 (center), 1 (bottom/default), 2 (top), 3 (left), 4 (right)',
1145
+ default: 1,
1146
+ },
1147
+ global: {
1148
+ type: 'boolean',
1149
+ description: 'Whether the note is visible regardless of fog/vision (default false)',
1150
+ default: false,
1151
+ },
1152
+ },
1153
+ },
1154
+ },
1155
+ {
1156
+ name: 'delete_note',
1157
+ description: 'Permanently remove a Map Note pin from a scene (does not delete the linked journal entry). ' +
1158
+ CONFIRM_FIRST +
1159
+ ' ' +
1160
+ WRITE_GATE,
1161
+ inputSchema: {
1162
+ type: 'object',
1163
+ properties: {
1164
+ noteId: { type: 'string', description: 'The ID of the map note to delete' },
1165
+ sceneId: { type: 'string', description: 'Optional Scene ID; defaults to the active scene' },
1166
+ },
1167
+ required: ['noteId'],
1168
+ },
1169
+ },
1170
+ {
1171
+ name: 'create_drawing',
1172
+ description: 'Create a Drawing shape on a scene (rectangle "r", circle "c", ellipse "e", or polygon "p") with optional text, fill, and stroke styling. Position x, y is the top-left corner of the shape. ' +
1173
+ WRITE_GATE,
1174
+ inputSchema: {
1175
+ type: 'object',
1176
+ properties: {
1177
+ x: { type: 'number', description: 'Pixel x coordinate (top-left)' },
1178
+ y: { type: 'number', description: 'Pixel y coordinate (top-left)' },
1179
+ shape: {
1180
+ type: 'string',
1181
+ enum: ['r', 'c', 'e', 'p'],
1182
+ description: 'Shape type: "r" (rectangle, default), "c" (circle), "e" (ellipse), "p" (polygon)',
1183
+ default: 'r',
1184
+ },
1185
+ sceneId: { type: 'string', description: 'Optional Scene ID; defaults to the active scene' },
1186
+ width: { type: 'number', description: 'Width in pixels (required for "r" and "e")' },
1187
+ height: { type: 'number', description: 'Height in pixels (required for "r" and "e")' },
1188
+ radius: { type: 'number', description: 'Radius in pixels (required for "c")' },
1189
+ points: {
1190
+ type: 'array',
1191
+ items: { type: 'number' },
1192
+ description: 'Array of coordinates [x1, y1, x2, y2, ...] with at least 3 points (required for "p")',
1193
+ },
1194
+ rotation: { type: 'number', description: 'Rotation in degrees (default 0)', default: 0 },
1195
+ strokeColor: {
1196
+ type: 'string',
1197
+ description: 'Stroke color as a 6-digit hex string (e.g. "#ffffff")',
1198
+ },
1199
+ strokeWidth: {
1200
+ type: 'number',
1201
+ description: 'Stroke line width in pixels (default 8)',
1202
+ default: 8,
1203
+ },
1204
+ fillType: {
1205
+ type: 'number',
1206
+ enum: [0, 1, 2],
1207
+ description: 'Fill type: 0 (none), 1 (solid), 2 (pattern)',
1208
+ },
1209
+ fillColor: {
1210
+ type: 'string',
1211
+ description: 'Fill color as a 6-digit hex string (e.g. "#336699")',
1212
+ },
1213
+ fillAlpha: {
1214
+ type: 'number',
1215
+ description: 'Fill opacity 0.0 to 1.0 (default 0.5)',
1216
+ default: 0.5,
1217
+ },
1218
+ text: { type: 'string', description: 'Optional text label displayed inside the drawing' },
1219
+ fontSize: {
1220
+ type: 'number',
1221
+ description: 'Font size in pixels (8-256, default 48)',
1222
+ default: 48,
1223
+ },
1224
+ hidden: {
1225
+ type: 'boolean',
1226
+ description: 'Whether the drawing is hidden from players (default false)',
1227
+ default: false,
1228
+ },
1229
+ locked: {
1230
+ type: 'boolean',
1231
+ description: 'Whether the drawing is locked from interaction (default false)',
1232
+ default: false,
1233
+ },
1234
+ },
1235
+ required: ['x', 'y'],
1236
+ },
1237
+ },
1238
+ {
1239
+ name: 'delete_drawing',
1240
+ description: `Permanently remove a Drawing from a scene. ${CONFIRM_FIRST} ${WRITE_GATE}`,
1241
+ inputSchema: {
1242
+ type: 'object',
1243
+ properties: {
1244
+ drawingId: { type: 'string', description: 'The ID of the drawing to delete' },
1245
+ sceneId: { type: 'string', description: 'Optional Scene ID; defaults to the active scene' },
1246
+ },
1247
+ required: ['drawingId'],
1248
+ },
1249
+ },
1250
+ {
1251
+ name: 'create_template',
1252
+ description: 'Place a Measured Template (spell/area-of-effect shape: "circle", "cone", "rect", "ray") on a scene at pixel x/y or a gridCol/gridRow cell. Distance is specified in scene grid units (e.g. metres or feet). ' +
1253
+ WRITE_GATE,
1254
+ inputSchema: {
1255
+ type: 'object',
1256
+ properties: {
1257
+ distance: {
1258
+ type: 'number',
1259
+ description: 'Effect distance/radius in grid units (e.g. 6m or 30ft)',
1260
+ },
1261
+ t: {
1262
+ type: 'string',
1263
+ enum: ['circle', 'cone', 'rect', 'ray'],
1264
+ description: 'Template type (default "circle")',
1265
+ default: 'circle',
1266
+ },
1267
+ sceneId: { type: 'string', description: 'Optional Scene ID; defaults to the active scene' },
1268
+ x: { type: 'number', description: 'Pixel x coordinate (origin point)' },
1269
+ y: { type: 'number', description: 'Pixel y coordinate (origin point)' },
1270
+ gridCol: { type: 'number', description: 'Grid column (centers origin in cell)' },
1271
+ gridRow: { type: 'number', description: 'Grid row (centers origin in cell)' },
1272
+ direction: {
1273
+ type: 'number',
1274
+ description: 'Direction angle in degrees (0 = right, 90 = down; required for cone/ray/rect)',
1275
+ default: 0,
1276
+ },
1277
+ angle: {
1278
+ type: 'number',
1279
+ description: 'Cone spread angle in degrees (required for cone, e.g. 45 or 53.13)',
1280
+ default: 0,
1281
+ },
1282
+ width: {
1283
+ type: 'number',
1284
+ description: 'Ray line width in grid units (required for ray)',
1285
+ default: 0,
1286
+ },
1287
+ borderColor: { type: 'string', description: 'Border color as a 6-digit hex string' },
1288
+ fillColor: { type: 'string', description: 'Fill color as a 6-digit hex string' },
1289
+ hidden: {
1290
+ type: 'boolean',
1291
+ description: 'Whether the template is hidden from players (default false)',
1292
+ default: false,
1293
+ },
1294
+ },
1295
+ required: ['distance'],
1296
+ },
1297
+ },
1298
+ {
1299
+ name: 'delete_template',
1300
+ description: 'Permanently remove a Measured Template area-of-effect shape from a scene. ' +
1301
+ CONFIRM_FIRST +
1302
+ ' ' +
1303
+ WRITE_GATE,
1304
+ inputSchema: {
1305
+ type: 'object',
1306
+ properties: {
1307
+ templateId: { type: 'string', description: 'The ID of the measured template to delete' },
1308
+ sceneId: { type: 'string', description: 'Optional Scene ID; defaults to the active scene' },
1309
+ },
1310
+ required: ['templateId'],
1311
+ },
1312
+ },
1313
+ ];
1314
+ /**
1315
+ * Content generation tool definitions
1316
+ */
1317
+ export const generationTools = [
1318
+ {
1319
+ name: 'generate_npc',
1320
+ description: 'Generate a random NPC (name, race, class, HP, ability scores, background) as text. Use when: the user needs a throwaway NPC on the spot. Do not use when: the NPC must exist in FoundryVTT - this creates no documents, and the result still has to be entered into the world by hand.',
1321
+ inputSchema: {
1322
+ type: 'object',
1323
+ properties: {
1324
+ level: {
1325
+ type: 'number',
1326
+ description: 'Character level (1-20)',
1327
+ minimum: 1,
1328
+ maximum: 20,
1329
+ default: 1,
1330
+ },
1331
+ race: {
1332
+ type: 'string',
1333
+ description: 'Character race (optional)',
1334
+ },
1335
+ class: {
1336
+ type: 'string',
1337
+ description: 'Character class (optional)',
1338
+ },
1339
+ },
1340
+ },
1341
+ },
1342
+ {
1343
+ name: 'generate_loot',
1344
+ description: "Generate random treasure for an encounter as text. Only the currency amounts vary: they scale with the challenge rating, while the item list is fixed (a Healing Potion and a Silver Ring) and the treasureType argument is accepted but not used. Use when: the user wants a quick coin total for an encounter. Do not use when: the loot should end up in an actor's inventory - this creates no documents; use create_actor_item for that.",
1345
+ inputSchema: {
1346
+ type: 'object',
1347
+ properties: {
1348
+ challengeRating: {
1349
+ type: 'number',
1350
+ description: 'Challenge rating for loot generation',
1351
+ minimum: 0,
1352
+ maximum: 30,
1353
+ },
1354
+ treasureType: {
1355
+ type: 'string',
1356
+ description: 'Type of treasure (hoard, individual, etc.). Accepted but not used - the generated result is the same whichever value is passed.',
1357
+ },
1358
+ },
1359
+ },
1360
+ },
1361
+ {
1362
+ name: 'lookup_rule',
1363
+ description: 'Search rules and mechanics across world journals and compendium journal packs. Compendium search requires the companion Foundry module.',
1364
+ inputSchema: {
1365
+ type: 'object',
1366
+ properties: {
1367
+ query: {
1368
+ type: 'string',
1369
+ description: 'Rule, keyword, or mechanic to look up',
1370
+ },
1371
+ },
1372
+ required: ['query'],
1373
+ },
1374
+ },
1375
+ ];
1376
+ /**
1377
+ * Diagnostics and logging tool definitions
1378
+ */
1379
+ export const diagnosticsTools = [
1380
+ {
1381
+ name: 'get_recent_logs',
1382
+ description: 'Get recent FoundryVTT server log entries, optionally filtered by level or since a timestamp. Use when: investigating an error or recent server behaviour. Do not use when: you have a specific term to look for - use search_logs. Requires the REST API module (FOUNDRY_API_KEY); fails without it.',
1383
+ inputSchema: {
1384
+ type: 'object',
1385
+ properties: {
1386
+ limit: {
1387
+ type: 'number',
1388
+ description: 'Number of log entries to retrieve',
1389
+ default: 20,
1390
+ minimum: 1,
1391
+ maximum: 100,
1392
+ },
1393
+ level: {
1394
+ type: 'string',
1395
+ description: 'Log level filter (debug, info, warn, error)',
1396
+ enum: ['debug', 'info', 'warn', 'error'],
1397
+ },
1398
+ since: {
1399
+ type: 'string',
1400
+ description: 'Get logs since this timestamp (ISO format)',
1401
+ },
1402
+ },
1403
+ },
1404
+ },
1405
+ {
1406
+ name: 'search_logs',
1407
+ description: 'Search the FoundryVTT server logs for a query string and list the matching entries. Use when: hunting a specific error message, stack trace, or module name. Do not use when: you just want the latest entries - use get_recent_logs. The reported match count is the server\'s total for the query, while limit caps how many of those entries are rendered (default 50, hard cap 1000). Level filtering accepts info, warn and error; "debug" is not a level this log store records, so it is reported back as unsupported and no level filter is applied. Requires the REST API module (FOUNDRY_API_KEY); fails without it.',
1408
+ inputSchema: {
1409
+ type: 'object',
1410
+ properties: {
1411
+ query: {
1412
+ type: 'string',
1413
+ description: 'Search query for log contents',
1414
+ },
1415
+ level: {
1416
+ type: 'string',
1417
+ description: 'Log level filter; "debug" is not recorded by this log store and is not applied',
1418
+ enum: ['debug', 'info', 'warn', 'error'],
1419
+ },
1420
+ limit: {
1421
+ type: 'number',
1422
+ description: 'Maximum number of matched entries to render (capped at 1000)',
1423
+ default: 50,
1424
+ },
1425
+ },
1426
+ required: ['query'],
1427
+ },
1428
+ },
1429
+ {
1430
+ name: 'get_system_health',
1431
+ description: "Get the FoundryVTT server's health report: the overall status (healthy, warning, or critical), FoundryVTT and game-system versions, world id and uptime, active/total user counts with the number of GMs, active/installed module counts, connected clients, heap and RSS memory, and the log buffer size with recent error/warning counts and error rate. CPU and disk are not reported - the diagnostics response models no such fields - and the uptime and memory lines are omitted when the server does not supply them. Use when: you want the server's own view of its health. Do not use when: you also want connection and world status - use get_health_status. Requires the REST API module (FOUNDRY_API_KEY); fails without it.",
1432
+ inputSchema: {
1433
+ type: 'object',
1434
+ properties: {},
1435
+ },
1436
+ },
1437
+ {
1438
+ name: 'diagnose_errors',
1439
+ description: 'Retrieve error diagnosis and health analysis from the FoundryVTT server logs via the REST API module (FOUNDRY_API_KEY). Reports error categories, health score, actionable suggestions, and recent errors.',
1440
+ inputSchema: {
1441
+ type: 'object',
1442
+ properties: {
1443
+ category: {
1444
+ type: 'string',
1445
+ description: 'Optional error category to filter summary and logs (e.g. "socket", "database")',
1446
+ },
1447
+ timeframe: {
1448
+ type: 'number',
1449
+ description: 'Timeframe in seconds to analyze (default 3600)',
1450
+ default: 3600,
1451
+ },
1452
+ },
1453
+ },
1454
+ },
1455
+ {
1456
+ name: 'get_health_status',
1457
+ description: "Get a combined health report: MCP-to-FoundryVTT connection state, world title/system/core version, and the server's health status with its active/total user counts, uptime, heap memory and recent error/warning counts. The world section is prefixed with a stale marker when the cached snapshot stopped following live document changes - typically a dropped connection, whose missed updates are never replayed - and refresh_world_data resyncs it. The connection line is a live read of the socket on the default Socket.IO transport, so it follows a link that drops or comes back in both directions; with FOUNDRY_API_KEY set there is no socket and it reports the outcome of the last REST request instead, not a live probe, so a server that went away between requests still reads as connected until the next request fails. Uptime and memory are omitted when the server does not report them; CPU, disk and playtime are not reported at all. Also lists the journal page overwrites detected in the last 24 hours (a connector write lost to a stale save or an open editor's autosave), with the path of each local copy. Degrades gracefully - sections that need the REST API module (FOUNDRY_API_KEY) report as unavailable rather than failing. Use when: first checking which world is loaded and whether the server reports itself healthy.",
1458
+ inputSchema: {
1459
+ type: 'object',
1460
+ properties: {},
1461
+ },
1462
+ },
1463
+ ];
1464
+ /**
1465
+ * Combat tool definitions
1466
+ */
1467
+ export const combatTools = [
1468
+ {
1469
+ name: 'get_combat_state',
1470
+ description: "Get the active combat encounter: initiative order with each combatant's name, initiative, HP and AC, plus the current round and which combatant is up. Use when: reporting whose turn it is, or checking whether a combat is already running before start_combat. Do not use when: you need a combatantId for set_initiative - this prints names and ordinals, not ids; read the foundry://combat resource, whose JSON includes each combatant's _id and lists combatants in this same initiative order, so the Nth entry printed here is that resource's combatants[N-1] and combat.turn indexes it directly.",
1471
+ inputSchema: {
1472
+ type: 'object',
1473
+ properties: {},
1474
+ },
1475
+ },
1476
+ ];
1477
+ /**
1478
+ * Combat control mutation tool definitions (FR-018)
1479
+ *
1480
+ * WRITE operations — require FOUNDRY_WRITE_ENABLED=true and an active Socket.IO
1481
+ * connection (mutations use the core `modifyDocument` protocol). All operate on
1482
+ * the *active* combat; the connected user needs GM/owner permission.
1483
+ */
1484
+ export const combatMutationTools = [
1485
+ {
1486
+ name: 'next_turn',
1487
+ description: 'Advance the active combat to the next turn, wrapping to the next round after the last combatant. When skipDefeated is true, defeated combatants are skipped. Use when: the current combatant has finished their turn. Do not use when: only reporting the turn order - use get_combat_state. ' +
1488
+ WRITE_GATE,
1489
+ inputSchema: {
1490
+ type: 'object',
1491
+ properties: {
1492
+ skipDefeated: {
1493
+ type: 'boolean',
1494
+ description: "Skip combatants flagged as defeated when advancing. Defaults to the combat's skipDefeated setting, or false.",
1495
+ },
1496
+ },
1497
+ },
1498
+ },
1499
+ {
1500
+ name: 'end_combat',
1501
+ description: 'End the active combat encounter by deleting its Combat document, discarding the initiative order and round count. Use when: the fight is over and the user asks to end the encounter. ' +
1502
+ CONFIRM_FIRST +
1503
+ ' ' +
1504
+ WRITE_GATE,
1505
+ inputSchema: {
1506
+ type: 'object',
1507
+ properties: {},
1508
+ },
1509
+ },
1510
+ {
1511
+ name: 'set_initiative',
1512
+ description: "Set a combatant's initiative in the active combat (or in combatId when given), reordering the turn order. When that reorder moves the combatant who is currently acting to a different position, the encounter's turn index is rewritten to follow them - whoever was up stays up, and the result says so - rather than leaving the marker on whoever slid into the old slot. That follow-up applies only to the active combat: a combatId naming some other encounter still records the initiative, but its turn order is not readable here and is left alone. Use when: an initiative roll needs to be recorded or corrected for a known combatantId. Do not use when: simply moving on to the next combatant - use next_turn. " +
1513
+ WRITE_GATE,
1514
+ inputSchema: {
1515
+ type: 'object',
1516
+ properties: {
1517
+ combatantId: {
1518
+ type: 'string',
1519
+ description: 'The ID of the combatant whose initiative to set',
1520
+ },
1521
+ initiative: {
1522
+ type: 'number',
1523
+ description: 'The initiative value to assign',
1524
+ },
1525
+ combatId: {
1526
+ type: 'string',
1527
+ description: 'Optional Combat document ID; defaults to the active combat',
1528
+ },
1529
+ },
1530
+ required: ['combatantId', 'initiative'],
1531
+ },
1532
+ },
1533
+ {
1534
+ name: 'start_combat',
1535
+ description: 'Start a new combat encounter, seeding combatants from tokens: pass explicit tokenIds, or omit them to seed every token on the scene. Defaults to the active scene when sceneId is omitted. Use when: a fight begins and no combat is running. Do not use when: a combat is already active - check get_combat_state first, since this always creates an additional encounter. ' +
1536
+ WRITE_GATE,
1537
+ inputSchema: {
1538
+ type: 'object',
1539
+ properties: {
1540
+ tokenIds: {
1541
+ type: 'array',
1542
+ items: { type: 'string' },
1543
+ description: 'Optional list of Token document IDs to add as combatants. Defaults to all tokens on the scene.',
1544
+ },
1545
+ sceneId: {
1546
+ type: 'string',
1547
+ description: 'Optional Scene document ID; defaults to the active scene.',
1548
+ },
1549
+ },
1550
+ },
1551
+ },
1552
+ ];
1553
+ /**
1554
+ * Token read tools (query-only; mirrors list_walls/list_tiles). No
1555
+ * FOUNDRY_WRITE_ENABLED gate - these only read the cached worldData.
1556
+ */
1557
+ export const tokenTools = [
1558
+ {
1559
+ name: 'list_tokens',
1560
+ description: "List the Tokens placed on a scene (id, display name, linked actorId, x/y pixel position, width/height in grid cells, elevation, rotation, hidden, disposition), defaulting to the active scene when sceneId is omitted. Read from cached worldData - no canvas access needed. Use when: you need to know what's on the map and where before moving, targeting, or applying an effect to a token, or to resolve a token's id from its name instead of asking the user. Do not use when: you need wall or tile layout instead - use list_walls/list_tiles.",
1561
+ inputSchema: {
1562
+ type: 'object',
1563
+ properties: {
1564
+ sceneId: {
1565
+ type: 'string',
1566
+ description: 'Optional Scene ID; defaults to the active scene',
1567
+ },
1568
+ },
1569
+ },
1570
+ },
1571
+ ];
1572
+ /**
1573
+ * Token manipulation mutation tool definitions (FR-019)
1574
+ *
1575
+ * WRITE operations — require FOUNDRY_WRITE_ENABLED=true and an active Socket.IO
1576
+ * connection (mutations use the core `modifyDocument` protocol). The connected
1577
+ * user needs GM/owner permission.
1578
+ */
1579
+ export const tokenMutationTools = [
1580
+ {
1581
+ name: 'move_token',
1582
+ description: 'Move a token to new x/y pixel coordinates on its scene; the token is located across scenes by id, optionally scoped with sceneId. Coordinates are absolute pixels, not grid squares and not offsets. Use when: repositioning a token to a position the user has given you, or one computed from list_tokens (current positions) and get_scene_info (grid size). Do not use when: repositioning several tokens at once - use move_tokens; or the destination may be blocked by a wall/door - use move_token_pathfind, which routes around them instead of teleporting through. ' +
1583
+ WRITE_GATE,
1584
+ inputSchema: {
1585
+ type: 'object',
1586
+ properties: {
1587
+ tokenId: {
1588
+ type: 'string',
1589
+ description: 'The ID of the token to move',
1590
+ },
1591
+ x: {
1592
+ type: 'number',
1593
+ description: 'Target x pixel coordinate on the scene',
1594
+ },
1595
+ y: {
1596
+ type: 'number',
1597
+ description: 'Target y pixel coordinate on the scene',
1598
+ },
1599
+ sceneId: {
1600
+ type: 'string',
1601
+ description: 'Optional Scene ID to scope the token lookup',
1602
+ },
1603
+ },
1604
+ required: ['tokenId', 'x', 'y'],
1605
+ },
1606
+ },
1607
+ {
1608
+ name: 'apply_status_effect',
1609
+ description: 'Apply or remove a status condition (e.g. "prone", "stunned") on a token\'s actor. Set active=false to remove. Matches by status id, so re-applying or clearing-when-absent is a no-op. Use when: a condition is gained or lost. Do not use when: changing numeric state such as HP or exhaustion - use update_actor_attributes. ' +
1610
+ WRITE_GATE +
1611
+ ' Exception: the no-op cases (applying an already-present status, or clearing an absent one) report success without attempting a write, so they also return normally while writes are disabled.',
1612
+ inputSchema: {
1613
+ type: 'object',
1614
+ properties: {
1615
+ tokenId: {
1616
+ type: 'string',
1617
+ description: 'The ID of the token whose actor to affect',
1618
+ },
1619
+ statusId: {
1620
+ type: 'string',
1621
+ description: "The status condition id (e.g. 'prone', 'stunned', 'blinded')",
1622
+ },
1623
+ active: {
1624
+ type: 'boolean',
1625
+ description: 'true to apply the effect (default), false to remove it',
1626
+ default: true,
1627
+ },
1628
+ sceneId: {
1629
+ type: 'string',
1630
+ description: 'Optional Scene ID to scope the token lookup',
1631
+ },
1632
+ },
1633
+ required: ['tokenId', 'statusId'],
1634
+ },
1635
+ },
1636
+ {
1637
+ name: 'spawn_token',
1638
+ description: "Place a new token for an existing actor onto a scene at given x/y pixel coordinates, defaulting to the active scene when sceneId is omitted. Base display fields (texture, size, vision) are seeded from the actor's prototypeToken. Use when: a monster, NPC, or reinforcement needs to appear on the map. Do not use when: repositioning a token that is already on the scene - use move_token. " +
1639
+ WRITE_GATE,
1640
+ inputSchema: {
1641
+ type: 'object',
1642
+ properties: {
1643
+ actorId: {
1644
+ type: 'string',
1645
+ description: 'The ID of the actor the new token represents',
1646
+ },
1647
+ x: {
1648
+ type: 'number',
1649
+ description: 'Target x pixel coordinate on the scene',
1650
+ },
1651
+ y: {
1652
+ type: 'number',
1653
+ description: 'Target y pixel coordinate on the scene',
1654
+ },
1655
+ sceneId: {
1656
+ type: 'string',
1657
+ description: 'Optional Scene ID; defaults to the active scene',
1658
+ },
1659
+ name: {
1660
+ type: 'string',
1661
+ description: "Optional display name override; defaults to the actor's name",
1662
+ },
1663
+ hidden: {
1664
+ type: 'boolean',
1665
+ description: 'Optional; true to place the token hidden from players',
1666
+ },
1667
+ },
1668
+ required: ['actorId', 'x', 'y'],
1669
+ },
1670
+ },
1671
+ {
1672
+ name: 'delete_token',
1673
+ description: "Remove a token from a scene without deleting the underlying actor. Use when: a monster is defeated and removed from the battle, or a token was placed by mistake. Do not use when: the actor document itself should be deleted - use delete_world_actor; this only removes the token's placement on the map. " +
1674
+ WRITE_GATE,
1675
+ inputSchema: {
1676
+ type: 'object',
1677
+ properties: {
1678
+ tokenId: {
1679
+ type: 'string',
1680
+ description: 'The ID of the token to remove',
1681
+ },
1682
+ sceneId: {
1683
+ type: 'string',
1684
+ description: 'Optional Scene ID to scope the token lookup',
1685
+ },
1686
+ },
1687
+ required: ['tokenId'],
1688
+ },
1689
+ },
1690
+ {
1691
+ name: 'move_token_pathfind',
1692
+ description: "Move a token to x/y coordinates, routing around impassable walls when the direct line is blocked (A* pathfinding over the scene's Wall geometry), and — unless openDoors is false — opening any closed doors the route needs to cross. Slower and more expensive than move_token (issues one document update per waypoint, with a short pause per door opened), and its wall detection covers ordinary geometric walls only, not anything canvas-only would also enforce (terrain height, drawing-based obstacles). Use when: a token should walk realistically around obstacles instead of teleporting through them, especially when doors are involved. Do not use when: the destination is in the open with nothing between - use move_token, which is one write instead of many. " +
1693
+ WRITE_GATE,
1694
+ inputSchema: {
1695
+ type: 'object',
1696
+ properties: {
1697
+ tokenId: {
1698
+ type: 'string',
1699
+ description: 'The ID of the token to move',
1700
+ },
1701
+ x: {
1702
+ type: 'number',
1703
+ description: 'Target x pixel coordinate on the scene',
1704
+ },
1705
+ y: {
1706
+ type: 'number',
1707
+ description: 'Target y pixel coordinate on the scene',
1708
+ },
1709
+ sceneId: {
1710
+ type: 'string',
1711
+ description: 'Optional Scene ID to scope the token lookup',
1712
+ },
1713
+ openDoors: {
1714
+ type: 'boolean',
1715
+ description: 'Whether to open closed doors blocking the route (default true)',
1716
+ default: true,
1717
+ },
1718
+ },
1719
+ required: ['tokenId', 'x', 'y'],
1720
+ },
1721
+ },
1722
+ {
1723
+ name: 'move_tokens',
1724
+ description: "Move several tokens in a single call - direct by default (like move_token), or wall-aware pathfinding per move when pathfind=true (like move_token_pathfind). Best-effort: one bad move (unknown tokenId, no route found, a rejected write) is reported in a failure list rather than losing moves that already succeeded. Use when: repositioning a whole party or group of NPCs at once - e.g. moving everyone into a room, or resetting an encounter's starting positions - instead of one move_token/move_token_pathfind call per token. Do not use when: moving a single token - move_token/move_token_pathfind is simpler. " +
1725
+ WRITE_GATE,
1726
+ inputSchema: {
1727
+ type: 'object',
1728
+ properties: {
1729
+ moves: {
1730
+ type: 'array',
1731
+ description: 'One or more token moves to perform in this call',
1732
+ items: {
1733
+ type: 'object',
1734
+ properties: {
1735
+ tokenId: {
1736
+ type: 'string',
1737
+ description: 'The ID of the token to move',
1738
+ },
1739
+ x: {
1740
+ type: 'number',
1741
+ description: 'Target x pixel coordinate on the scene',
1742
+ },
1743
+ y: {
1744
+ type: 'number',
1745
+ description: 'Target y pixel coordinate on the scene',
1746
+ },
1747
+ sceneId: {
1748
+ type: 'string',
1749
+ description: 'Optional Scene ID to scope the token lookup',
1750
+ },
1751
+ pathfind: {
1752
+ type: 'boolean',
1753
+ description: 'Route around walls/doors instead of a straight line, like move_token_pathfind (default false)',
1754
+ default: false,
1755
+ },
1756
+ openDoors: {
1757
+ type: 'boolean',
1758
+ description: 'When pathfind is true, whether to open closed doors blocking the route (default true)',
1759
+ default: true,
1760
+ },
1761
+ },
1762
+ required: ['tokenId', 'x', 'y'],
1763
+ },
1764
+ minItems: 1,
1765
+ },
1766
+ },
1767
+ required: ['moves'],
1768
+ },
1769
+ },
1770
+ {
1771
+ name: 'update_token_vision',
1772
+ description: "Update an existing placed token's vision and/or light emission properties (sight range, angle, vision mode, light dim/bright radii, color tint, angle, animation). " +
1773
+ WRITE_GATE,
1774
+ inputSchema: {
1775
+ type: 'object',
1776
+ properties: {
1777
+ tokenId: {
1778
+ type: 'string',
1779
+ description: 'The ID of the token to update',
1780
+ },
1781
+ sceneId: {
1782
+ type: 'string',
1783
+ description: 'Optional Scene ID to scope the token lookup',
1784
+ },
1785
+ sightEnabled: {
1786
+ type: 'boolean',
1787
+ description: 'Whether vision is enabled for this token (automatically set true if sightRange > 0)',
1788
+ },
1789
+ sightRange: {
1790
+ type: 'number',
1791
+ description: 'Token vision range in grid units',
1792
+ },
1793
+ sightAngle: {
1794
+ type: 'number',
1795
+ description: 'Vision cone angle in degrees (default 360)',
1796
+ },
1797
+ visionMode: {
1798
+ type: 'string',
1799
+ description: 'Vision mode id (e.g. "basic", "darkvision")',
1800
+ },
1801
+ lightDim: {
1802
+ type: 'number',
1803
+ description: 'Dim light emission radius in grid units',
1804
+ },
1805
+ lightBright: {
1806
+ type: 'number',
1807
+ description: 'Bright light emission radius in grid units',
1808
+ },
1809
+ lightColor: {
1810
+ type: 'string',
1811
+ description: 'Light emission color as a 6-digit hex string (e.g. "#ff8800")',
1812
+ },
1813
+ lightAngle: {
1814
+ type: 'number',
1815
+ description: 'Light emission angle in degrees (default 360)',
1816
+ },
1817
+ lightAnimationType: {
1818
+ type: 'string',
1819
+ description: 'Light animation type (e.g. "torch", "pulse", "chroma")',
1820
+ },
1821
+ },
1822
+ required: ['tokenId'],
1823
+ },
1824
+ },
1825
+ ];
1826
+ /**
1827
+ * Chat message tool definitions
1828
+ */
1829
+ export const chatTools = [
1830
+ {
1831
+ name: 'get_chat_messages',
1832
+ description: 'Get the most recent chat messages from the game log. Use when: you need recent in-game context - what players said, or roll results that already happened.',
1833
+ inputSchema: {
1834
+ type: 'object',
1835
+ properties: {
1836
+ limit: {
1837
+ type: 'number',
1838
+ description: 'Number of messages to retrieve (default 20)',
1839
+ default: 20,
1840
+ minimum: 1,
1841
+ maximum: 100,
1842
+ },
1843
+ },
1844
+ },
1845
+ },
1846
+ ];
1847
+ /**
1848
+ * Chat message mutation tool definitions
1849
+ *
1850
+ * WRITE operations — require FOUNDRY_WRITE_ENABLED=true and an active
1851
+ * Socket.IO connection (mutations use the core `modifyDocument` protocol).
1852
+ */
1853
+ export const chatMutationTools = [
1854
+ {
1855
+ name: 'send_chat_message',
1856
+ description: 'Post a message to the FoundryVTT chat log, optionally under a custom speaker name, whispered to specific users, and/or styled as out-of-character, in-character, or an emote (default: a plain system-style message). Use when: narrating a scene, speaking as an NPC, or sending a player a private clue. Do not use when: you only need to read recent chat - use get_chat_messages. ' +
1857
+ WRITE_GATE,
1858
+ inputSchema: {
1859
+ type: 'object',
1860
+ properties: {
1861
+ content: {
1862
+ type: 'string',
1863
+ description: 'Message body (HTML or plain text)',
1864
+ },
1865
+ speaker: {
1866
+ type: 'string',
1867
+ description: 'Optional display name shown as the speaker (e.g. an NPC name)',
1868
+ },
1869
+ whisperTo: {
1870
+ type: 'array',
1871
+ items: { type: 'string' },
1872
+ description: 'Optional list of User document ids to whisper the message to privately',
1873
+ },
1874
+ style: {
1875
+ type: 'string',
1876
+ enum: ['ooc', 'ic', 'emote'],
1877
+ description: "Message style. Omit for a plain message; 'ooc' out-of-character, 'ic' in-character, 'emote' an emote/action line.",
1878
+ },
1879
+ },
1880
+ required: ['content'],
1881
+ },
1882
+ },
1883
+ ];
1884
+ /**
1885
+ * User tool definitions
1886
+ */
1887
+ export const userTools = [
1888
+ {
1889
+ name: 'get_users',
1890
+ description: "List the world's users with their roles and online status. Online status is live while the Socket.IO connection is up: FoundryVTT's userActivity broadcasts are applied to the cached presence list as users connect and disconnect. It stops tracking if that connection drops and the missed changes are not replayed - get_health_status shows the snapshot as stale, and refresh_world_data resyncs it. Use when: you need to know which user holds the GM role, or who is connected right now.",
1891
+ inputSchema: {
1892
+ type: 'object',
1893
+ properties: {},
1894
+ },
1895
+ },
1896
+ {
1897
+ name: 'set_user_role',
1898
+ description: 'Change a user\'s permission role ("none", "player", "trusted", "assistant", "gamemaster"). Refuses self-demotion of the connected MCP user below assistant (3) to prevent accidental GM lockout. ' +
1899
+ CONFIRM_FIRST +
1900
+ ' ' +
1901
+ WRITE_GATE,
1902
+ inputSchema: {
1903
+ type: 'object',
1904
+ properties: {
1905
+ userId: { type: 'string', description: '16-char alphanumeric User document id' },
1906
+ role: {
1907
+ type: 'string',
1908
+ enum: ['none', 'player', 'trusted', 'assistant', 'gamemaster'],
1909
+ description: 'New role level for the user',
1910
+ },
1911
+ },
1912
+ required: ['userId', 'role'],
1913
+ },
1914
+ },
1915
+ ];
1916
+ /**
1917
+ * Journal tool definitions
1918
+ */
1919
+ export const journalTools = [
1920
+ {
1921
+ name: 'search_journals',
1922
+ description: 'Search journal entries by name and page content. Use when: looking for notes, lore, or handouts by keyword. Do not use when: you already have the journalId - use get_journal.',
1923
+ inputSchema: {
1924
+ type: 'object',
1925
+ properties: {
1926
+ query: {
1927
+ type: 'string',
1928
+ description: 'Search query for journal names and content',
1929
+ },
1930
+ limit: {
1931
+ type: 'number',
1932
+ description: 'Maximum number of results',
1933
+ default: 10,
1934
+ },
1935
+ },
1936
+ required: ['query'],
1937
+ },
1938
+ },
1939
+ {
1940
+ name: 'get_journal',
1941
+ description: 'Get one journal entry by id with the id and text of each page. By default page bodies are HTML-stripped and each is truncated to its first 500 characters, marked with a trailing "...", so long pages come back partial, and they come from the cached snapshot (flagged when it is stale). Pass raw: true to read the entry from the server instead, with the full, unmodified HTML and the version token of each page (version: <token>) - the expectedVersion update_journal_page requires to replace the content of that page. Use when: you have a journalId and need the text of its pages, or a pageId and the exact current HTML before editing a page with update_journal_page. Do not use when: you only have a title or keyword - run search_journals first.',
1942
+ inputSchema: {
1943
+ type: 'object',
1944
+ properties: {
1945
+ journalId: {
1946
+ type: 'string',
1947
+ description: 'The ID of the journal entry to retrieve',
1948
+ },
1949
+ raw: {
1950
+ type: 'boolean',
1951
+ description: "Read the entry from the server and return each page's full, unmodified HTML (text.content) and version token instead of the stripped 500-character preview. Use before rewriting a page so no markup or text is lost, and pass the page's version to update_journal_page as expectedVersion.",
1952
+ default: false,
1953
+ },
1954
+ },
1955
+ required: ['journalId'],
1956
+ },
1957
+ },
1958
+ ];
1959
+ /**
1960
+ * Journal mutation tool definitions (WRITE)
1961
+ */
1962
+ export const journalMutationTools = [
1963
+ {
1964
+ name: 'create_journal_entry',
1965
+ description: 'Create a new journal entry with one or more text pages, optionally filed under a folder. Defaults to GM-only visibility - pass visibility to let players read it. Use when: recording session notes, lore, or a handout in the world. Returns the id and version token of each created page. Do not use when: adding text to an existing entry - this always creates a new one. ' +
1966
+ WRITE_GATE,
1967
+ inputSchema: {
1968
+ type: 'object',
1969
+ properties: {
1970
+ name: {
1971
+ type: 'string',
1972
+ description: 'Title of the journal entry',
1973
+ },
1974
+ pages: {
1975
+ type: 'array',
1976
+ description: 'One or more pages to create on the entry',
1977
+ items: {
1978
+ type: 'object',
1979
+ properties: {
1980
+ name: {
1981
+ type: 'string',
1982
+ description: 'Page title',
1983
+ },
1984
+ content: {
1985
+ type: 'string',
1986
+ description: 'Page body as HTML or plain text',
1987
+ },
1988
+ },
1989
+ required: ['name', 'content'],
1990
+ },
1991
+ minItems: 1,
1992
+ },
1993
+ folder: {
1994
+ type: 'string',
1995
+ description: 'Optional Folder document id to file the entry under',
1996
+ },
1997
+ visibility: {
1998
+ type: 'string',
1999
+ enum: ['gm-only', 'observer', 'owner'],
2000
+ description: "Who can see the entry. 'gm-only' (default) hides it from players; 'observer' lets every player read it; 'owner' lets every player read and edit it.",
2001
+ },
2002
+ },
2003
+ required: ['name', 'pages'],
2004
+ },
2005
+ },
2006
+ {
2007
+ name: 'update_journal_page',
2008
+ description: 'Edit one page of an existing journal entry. mode "replace" (default) sets a new name and/or replaces the whole page content; mode "append" adds HTML to the end of the page as currently stored on the server. Replacing content requires expectedVersion: read the page with get_journal raw: true, rewrite from that HTML, and pass the version printed for the page - the write is refused, with nothing written, if the page changed since. Every write saves the previous content to a local copy first, and returns the new version token so another edit can follow without re-reading. The response warns when the page looks open in a FoundryVTT editor, whose autosave can overwrite the write (FoundryVTT does not report an editor closing, so the warning can outlast it by a few minutes). Use when: correcting, rewriting, or extending session notes, lore, or a handout page. Do not use when: adding a separate new page - use add_journal_page; renaming or moving the entry itself - use update_journal_entry. ' +
2009
+ WRITE_GATE,
2010
+ inputSchema: {
2011
+ type: 'object',
2012
+ properties: {
2013
+ journalId: {
2014
+ type: 'string',
2015
+ description: 'The ID of the journal entry that holds the page',
2016
+ },
2017
+ pageId: {
2018
+ type: 'string',
2019
+ description: 'The ID of the page to edit (shown by get_journal)',
2020
+ },
2021
+ mode: {
2022
+ type: 'string',
2023
+ enum: ['replace', 'append'],
2024
+ description: "'replace' (default) overwrites the page content with content (expectedVersion required) and/or renames it; 'append' adds content after the existing content as read from the server (name not allowed).",
2025
+ default: 'replace',
2026
+ },
2027
+ name: {
2028
+ type: 'string',
2029
+ description: 'New page title (replace mode only)',
2030
+ },
2031
+ content: {
2032
+ type: 'string',
2033
+ description: 'Page body as HTML or plain text. In replace mode it replaces the entire page content; in append mode it is added at the end.',
2034
+ },
2035
+ expectedVersion: {
2036
+ type: 'string',
2037
+ description: 'Version token of the page as last read (get_journal raw: true, or the version returned by the previous write). Required to replace content; optional in append mode. The write is refused if the page has changed since.',
2038
+ },
2039
+ },
2040
+ required: ['journalId', 'pageId'],
2041
+ },
2042
+ },
2043
+ {
2044
+ name: 'add_journal_page',
2045
+ description: 'Add a new text page to an existing journal entry, placed after its last page as read from the server. Returns the new page id and version token. Use when: a journal needs another section (a new session, an NPC, a location). Do not use when: the entry does not exist yet - use create_journal_entry; changing an existing page - use update_journal_page. ' +
2046
+ WRITE_GATE,
2047
+ inputSchema: {
2048
+ type: 'object',
2049
+ properties: {
2050
+ journalId: {
2051
+ type: 'string',
2052
+ description: 'The ID of the journal entry to add the page to',
2053
+ },
2054
+ name: {
2055
+ type: 'string',
2056
+ description: 'Page title',
2057
+ },
2058
+ content: {
2059
+ type: 'string',
2060
+ description: 'Page body as HTML or plain text',
2061
+ },
2062
+ },
2063
+ required: ['journalId', 'name', 'content'],
2064
+ },
2065
+ },
2066
+ {
2067
+ name: 'update_journal_entry',
2068
+ description: 'Rename a journal entry, move it into another folder, or change who can see it. Only the fields supplied change. Use when: retitling notes, filing them under a folder, or revealing a handout to players. Do not use when: changing page text - use update_journal_page; granting a specific user access - use set_document_ownership. ' +
2069
+ WRITE_GATE,
2070
+ inputSchema: {
2071
+ type: 'object',
2072
+ properties: {
2073
+ journalId: {
2074
+ type: 'string',
2075
+ description: 'The ID of the journal entry to update',
2076
+ },
2077
+ name: {
2078
+ type: 'string',
2079
+ description: 'New title of the journal entry',
2080
+ },
2081
+ folder: {
2082
+ type: 'string',
2083
+ description: 'Folder document id to move the entry into',
2084
+ },
2085
+ visibility: {
2086
+ type: 'string',
2087
+ enum: ['gm-only', 'observer', 'owner'],
2088
+ description: "Who can see the entry. 'gm-only' hides it from players; 'observer' lets every player read it; 'owner' lets every player read and edit it. Per-user ownership is kept.",
2089
+ },
2090
+ },
2091
+ required: ['journalId'],
2092
+ },
2093
+ },
2094
+ {
2095
+ name: 'delete_journal_entry',
2096
+ description: 'Permanently delete a journal entry. Use when: the user explicitly asks to remove outdated notes or a handout. Do not use when: only the content, title, folder or visibility needs to change - use update_journal_page, add_journal_page or update_journal_entry instead. ' +
2097
+ CONFIRM_FIRST +
2098
+ ' ' +
2099
+ WRITE_GATE,
2100
+ inputSchema: {
2101
+ type: 'object',
2102
+ properties: {
2103
+ journalId: {
2104
+ type: 'string',
2105
+ description: 'The ID of the journal entry to delete',
2106
+ },
2107
+ },
2108
+ required: ['journalId'],
2109
+ },
2110
+ },
2111
+ ];
2112
+ /**
2113
+ * World-level tool definitions
2114
+ */
2115
+ export const worldTools = [
2116
+ {
2117
+ name: 'search_world',
2118
+ description: 'Search across all collections (actors, items, scenes, journals) by name, grouped by collection. Use when: you do not know which collection holds what you are looking for. Do not use when: you already know the collection - use search_actors, search_items, or search_journals. Of those, only search_journals prints document ids; for actor and item ids read the foundry://actors and foundry://items resources, each of which lists up to the first 100 documents (not exhaustive in larger worlds).',
2119
+ inputSchema: {
2120
+ type: 'object',
2121
+ properties: {
2122
+ query: {
2123
+ type: 'string',
2124
+ description: 'Search query to match against entity names',
2125
+ },
2126
+ limit: {
2127
+ type: 'number',
2128
+ description: 'Maximum results per collection (default 5)',
2129
+ default: 5,
2130
+ },
2131
+ },
2132
+ required: ['query'],
2133
+ },
2134
+ },
2135
+ {
2136
+ name: 'get_world_summary',
2137
+ description: 'Get world metadata (title, game system, core version) and per-collection document counts. Use when: orienting yourself in an unfamiliar world, or confirming the game system before system-specific edits.',
2138
+ inputSchema: {
2139
+ type: 'object',
2140
+ properties: {},
2141
+ },
2142
+ },
2143
+ {
2144
+ name: 'refresh_world_data',
2145
+ description: 'Force a re-fetch of the cached world data from the FoundryVTT server. Reads are normally served from a cache that follows live document changes for as long as the connection holds, so this is rarely needed. Use when: the connection dropped and came back - the cache stopped following changes while it was down and nothing replays them, so it stays a point-in-time copy until this runs, and get_health_status flags it as stale until then; or a read still looks stale after an out-of-band change - notably edits to unlinked (synthetic) token actors, which the live update feed does not cover. Refreshes the cache only; it does not modify the world.',
2146
+ inputSchema: {
2147
+ type: 'object',
2148
+ properties: {},
2149
+ },
2150
+ },
2151
+ ];
2152
+ /**
2153
+ * World document read tools (folders, macros, playlists).
2154
+ */
2155
+ export const worldDocumentTools = [
2156
+ {
2157
+ name: 'list_folders',
2158
+ description: 'List sidebar folders in the world (id, name, document type, parent folder id, color), optionally filtered by document type (Actor, Item, Scene, JournalEntry, Playlist, RollTable, Cards, Macro, Compendium).',
2159
+ inputSchema: {
2160
+ type: 'object',
2161
+ properties: {
2162
+ type: {
2163
+ type: 'string',
2164
+ description: 'Optional document type filter (e.g. "Actor", "JournalEntry", "Item")',
2165
+ },
2166
+ },
2167
+ },
2168
+ },
2169
+ {
2170
+ name: 'list_macros',
2171
+ description: 'List Macro documents in the world (id, name, type script/chat, scope, folder, command preview). Use when: discovering available macros or finding a macroId for delete_macro.',
2172
+ inputSchema: {
2173
+ type: 'object',
2174
+ properties: {},
2175
+ },
2176
+ },
2177
+ {
2178
+ name: 'list_playlists',
2179
+ description: 'List Audio Playlists in the world (id, name, playing state, mode sequential/shuffle/simultaneous, channel, sound track list). Use when: checking background music/ambience state or getting ids for set_playlist_state.',
2180
+ inputSchema: {
2181
+ type: 'object',
2182
+ properties: {},
2183
+ },
2184
+ },
2185
+ ];
2186
+ /**
2187
+ * World document mutation tools (folders, macros, playlists).
2188
+ * WRITE operations — require FOUNDRY_WRITE_ENABLED=true and an active Socket.IO connection.
2189
+ */
2190
+ export const worldDocumentMutationTools = [
2191
+ {
2192
+ name: 'create_folder',
2193
+ description: 'Create a new sidebar Folder document to organize actors, items, scenes, journals, playlists, tables, or macros. ' +
2194
+ WRITE_GATE,
2195
+ inputSchema: {
2196
+ type: 'object',
2197
+ properties: {
2198
+ name: { type: 'string', description: 'Folder display name' },
2199
+ type: {
2200
+ type: 'string',
2201
+ description: 'Document type this folder contains: "Actor", "Item", "Scene", "JournalEntry", "Playlist", "RollTable", "Cards", "Macro", or "Compendium"',
2202
+ },
2203
+ parent: {
2204
+ type: 'string',
2205
+ description: 'Optional parent Folder ID for nested folder hierarchies',
2206
+ },
2207
+ color: {
2208
+ type: 'string',
2209
+ description: 'Optional folder color as a 6-digit hex string (e.g. "#ff0000")',
2210
+ },
2211
+ sorting: {
2212
+ type: 'string',
2213
+ enum: ['a', 'm'],
2214
+ description: 'Sorting mode: "a" (alphabetical, default) or "m" (manual)',
2215
+ default: 'a',
2216
+ },
2217
+ },
2218
+ required: ['name', 'type'],
2219
+ },
2220
+ },
2221
+ {
2222
+ name: 'create_macro',
2223
+ description: 'Create a new Macro document (script or chat). Authors and manages the document only — this server has no tool that executes a macro (deliberate security boundary: no arbitrary JS execution in GM browser). ' +
2224
+ WRITE_GATE,
2225
+ inputSchema: {
2226
+ type: 'object',
2227
+ properties: {
2228
+ name: { type: 'string', description: 'Macro display name' },
2229
+ type: {
2230
+ type: 'string',
2231
+ enum: ['script', 'chat'],
2232
+ description: 'Macro type: "script" (JavaScript) or "chat" (chat command)',
2233
+ },
2234
+ command: { type: 'string', description: 'Macro command content/script body' },
2235
+ folder: { type: 'string', description: 'Optional Folder ID to file the macro under' },
2236
+ img: { type: 'string', description: 'Optional icon image path' },
2237
+ scope: {
2238
+ type: 'string',
2239
+ enum: ['global', 'actors', 'actor'],
2240
+ description: 'Macro execution scope (default "global")',
2241
+ default: 'global',
2242
+ },
2243
+ },
2244
+ required: ['name', 'type', 'command'],
2245
+ },
2246
+ },
2247
+ {
2248
+ name: 'delete_macro',
2249
+ description: `Permanently delete a Macro document from the world. ${CONFIRM_FIRST} ${WRITE_GATE}`,
2250
+ inputSchema: {
2251
+ type: 'object',
2252
+ properties: {
2253
+ macroId: { type: 'string', description: 'The ID of the macro to delete' },
2254
+ },
2255
+ required: ['macroId'],
2256
+ },
2257
+ },
2258
+ {
2259
+ name: 'create_playlist',
2260
+ description: `Create a new audio Playlist document with optional starting sound tracks. ${WRITE_GATE}`,
2261
+ inputSchema: {
2262
+ type: 'object',
2263
+ properties: {
2264
+ name: { type: 'string', description: 'Playlist display name' },
2265
+ description: { type: 'string', description: 'Optional playlist description' },
2266
+ mode: {
2267
+ type: 'number',
2268
+ enum: [-1, 0, 1, 2],
2269
+ description: 'Playback mode: -1 (soundboard/disabled), 0 (sequential/default), 1 (shuffle), 2 (simultaneous)',
2270
+ default: 0,
2271
+ },
2272
+ channel: {
2273
+ type: 'string',
2274
+ enum: ['music', 'environment', 'interface'],
2275
+ description: 'Audio channel (default "music")',
2276
+ default: 'music',
2277
+ },
2278
+ fade: { type: 'number', description: 'Fade duration in milliseconds' },
2279
+ folder: { type: 'string', description: 'Optional Folder ID to file the playlist under' },
2280
+ sounds: {
2281
+ type: 'array',
2282
+ description: 'Optional sound tracks to create on this playlist',
2283
+ items: {
2284
+ type: 'object',
2285
+ properties: {
2286
+ name: { type: 'string', description: 'Track display name' },
2287
+ path: {
2288
+ type: 'string',
2289
+ description: 'Audio file path (e.g. "assets/audio/bgm.mp3")',
2290
+ },
2291
+ volume: {
2292
+ type: 'number',
2293
+ description: 'Track volume 0.0 to 1.0 (default 0.5)',
2294
+ default: 0.5,
2295
+ },
2296
+ repeat: {
2297
+ type: 'boolean',
2298
+ description: 'Whether the track loops (default false)',
2299
+ default: false,
2300
+ },
2301
+ },
2302
+ required: ['name', 'path'],
2303
+ },
2304
+ },
2305
+ },
2306
+ required: ['name'],
2307
+ },
2308
+ },
2309
+ {
2310
+ name: 'set_playlist_state',
2311
+ description: 'Start or stop playback of an entire playlist or a specific sound track within it. Drives Foundry playback state; client autoplay policies may affect audio output. ' +
2312
+ WRITE_GATE,
2313
+ inputSchema: {
2314
+ type: 'object',
2315
+ properties: {
2316
+ playlistId: { type: 'string', description: 'The ID of the playlist to control' },
2317
+ playing: { type: 'boolean', description: 'true to start playback, false to stop' },
2318
+ soundId: {
2319
+ type: 'string',
2320
+ description: 'Optional PlaylistSound ID to control a specific track instead of the entire playlist',
2321
+ },
2322
+ },
2323
+ required: ['playlistId', 'playing'],
2324
+ },
2325
+ },
2326
+ {
2327
+ name: 'delete_playlist',
2328
+ description: 'Permanently delete an audio Playlist document and its contained sounds. ' +
2329
+ CONFIRM_FIRST +
2330
+ ' ' +
2331
+ WRITE_GATE,
2332
+ inputSchema: {
2333
+ type: 'object',
2334
+ properties: {
2335
+ playlistId: { type: 'string', description: 'The ID of the playlist to delete' },
2336
+ },
2337
+ required: ['playlistId'],
2338
+ },
2339
+ },
2340
+ {
2341
+ name: 'set_document_ownership',
2342
+ description: 'Configure granular ownership permissions for a document. entries maps user IDs (or "default" for all players) to permission levels: "none" (0), "limited" (1), "observer" (2), "owner" (3). Document types supported: Actor, Item, Scene, JournalEntry, RollTable, Macro. ' +
2343
+ WRITE_GATE,
2344
+ inputSchema: {
2345
+ type: 'object',
2346
+ properties: {
2347
+ documentType: {
2348
+ type: 'string',
2349
+ enum: ['Actor', 'Item', 'Scene', 'JournalEntry', 'RollTable', 'Macro'],
2350
+ description: 'Document collection the target lives in',
2351
+ },
2352
+ documentId: { type: 'string', description: '16-char alphanumeric document id' },
2353
+ entries: {
2354
+ type: 'array',
2355
+ description: 'List of target and ownership level mappings',
2356
+ items: {
2357
+ type: 'object',
2358
+ properties: {
2359
+ target: {
2360
+ type: 'string',
2361
+ description: '16-char User ID, or "default" for all players',
2362
+ },
2363
+ level: {
2364
+ type: 'string',
2365
+ enum: ['none', 'limited', 'observer', 'owner'],
2366
+ description: 'Permission level to grant',
2367
+ },
2368
+ },
2369
+ required: ['target', 'level'],
2370
+ },
2371
+ minItems: 1,
2372
+ },
2373
+ },
2374
+ required: ['documentType', 'documentId', 'entries'],
2375
+ },
2376
+ },
2377
+ ];
2378
+ /**
2379
+ * Roll table tool definitions
2380
+ *
2381
+ * Neither tool mutates the world; `roll_table` draws locally against cached
2382
+ * table data and does not require FOUNDRY_WRITE_ENABLED.
2383
+ */
2384
+ export const rollTableTools = [
2385
+ {
2386
+ name: 'list_roll_tables',
2387
+ description: "List the world's roll tables by name, result count, and id. Use when: you need a tableId for roll_table, or want to see what random tables are available. Do not use when: you already have the tableId - go straight to roll_table.",
2388
+ inputSchema: {
2389
+ type: 'object',
2390
+ properties: {},
2391
+ },
2392
+ },
2393
+ {
2394
+ name: 'roll_table',
2395
+ description: "Draw a result from a roll table by id, rolling the table's own formula (or a uniform range when it has none) and returning the matched entry. This is a local, read-only draw: unlike FoundryVTT's own table draw, it does not mark the result as drawn or honor a no-duplicates setting, so repeat draws can repeat a result. Use when: rolling on a random encounter, loot, or event table. Do not use when: you don't have a tableId - run list_roll_tables first.",
2396
+ inputSchema: {
2397
+ type: 'object',
2398
+ properties: {
2399
+ tableId: {
2400
+ type: 'string',
2401
+ description: 'The ID of the roll table to draw from',
2402
+ },
2403
+ },
2404
+ required: ['tableId'],
2405
+ },
2406
+ },
2407
+ {
2408
+ name: 'create_roll_table',
2409
+ description: 'Create a new RollTable document with text results. Automatically assigns sequential ranges and a matching 1dN formula when ranges are omitted. ' +
2410
+ WRITE_GATE,
2411
+ inputSchema: {
2412
+ type: 'object',
2413
+ properties: {
2414
+ name: { type: 'string', description: 'Roll table display name' },
2415
+ results: {
2416
+ type: 'array',
2417
+ description: 'List of text result entries for this table',
2418
+ items: {
2419
+ type: 'object',
2420
+ properties: {
2421
+ text: { type: 'string', description: 'Result text description' },
2422
+ weight: { type: 'number', description: 'Relative weight (default 1)', default: 1 },
2423
+ range: {
2424
+ type: 'array',
2425
+ items: { type: 'number' },
2426
+ description: 'Optional roll range [low, high] (e.g. [1, 2]). Auto-assigned if omitted on all results.',
2427
+ },
2428
+ },
2429
+ required: ['text'],
2430
+ },
2431
+ minItems: 1,
2432
+ },
2433
+ description: { type: 'string', description: 'Optional table description' },
2434
+ formula: {
2435
+ type: 'string',
2436
+ description: 'Optional custom dice formula (e.g. "1d100" or "2d6")',
2437
+ },
2438
+ replacement: {
2439
+ type: 'boolean',
2440
+ description: 'Whether drawn results are replaced (default true)',
2441
+ default: true,
2442
+ },
2443
+ displayRoll: {
2444
+ type: 'boolean',
2445
+ description: 'Whether the roll total is displayed in chat (default true)',
2446
+ default: true,
2447
+ },
2448
+ folder: { type: 'string', description: 'Optional Folder ID to file the table under' },
2449
+ },
2450
+ required: ['name', 'results'],
2451
+ },
2452
+ },
2453
+ {
2454
+ name: 'delete_roll_table',
2455
+ description: `Permanently delete a RollTable document from the world. ${CONFIRM_FIRST} ${WRITE_GATE}`,
2456
+ inputSchema: {
2457
+ type: 'object',
2458
+ properties: {
2459
+ tableId: { type: 'string', description: 'The ID of the roll table to delete' },
2460
+ },
2461
+ required: ['tableId'],
2462
+ },
2463
+ },
2464
+ ];
2465
+ /**
2466
+ * World settings tool definitions
2467
+ */
2468
+ export const settingsTools = [
2469
+ {
2470
+ name: 'get_world_setting',
2471
+ description: 'Read a world setting by its namespaced key (e.g. "cyberpunk-red-core.customSetting" or "simple-calendar.year"). If the setting has never been modified from its system/module default, exists will be false. Use when: inspecting world configuration.',
2472
+ inputSchema: {
2473
+ type: 'object',
2474
+ properties: {
2475
+ key: {
2476
+ type: 'string',
2477
+ description: 'The namespaced setting key in the format {scope}.{field}',
2478
+ },
2479
+ },
2480
+ required: ['key'],
2481
+ },
2482
+ },
2483
+ {
2484
+ name: 'set_world_setting',
2485
+ description: 'Update or create a world setting value for a system or module namespace (e.g. "cyberpunk-red-core.settingName"). Refuses writes to the "core.*" namespace (core settings control the Foundry client itself and can break the world; change those in the UI). ' +
2486
+ CONFIRM_FIRST +
2487
+ ' ' +
2488
+ WRITE_GATE,
2489
+ inputSchema: {
2490
+ type: 'object',
2491
+ properties: {
2492
+ key: {
2493
+ type: 'string',
2494
+ description: 'The namespaced setting key in the format {scope}.{field} (non-core only)',
2495
+ },
2496
+ value: {
2497
+ description: 'The value to store (JSON-serializable: string, number, boolean, object, or array)',
2498
+ },
2499
+ },
2500
+ required: ['key', 'value'],
2501
+ },
2502
+ },
2503
+ ];
2504
+ /**
2505
+ * Module-bridge tool definitions
2506
+ *
2507
+ * Relayed through the companion Foundry module (a real, rendered browser
2508
+ * tab) rather than FoundryVTT's own Socket.IO document API - the only path
2509
+ * to canvas/PIXI-only capabilities. Requires FOUNDRY_MODULE_BRIDGE_ENABLED=true
2510
+ * and the module installed, enabled, and connected; fails clearly otherwise.
2511
+ */
2512
+ export const moduleBridgeTools = [
2513
+ {
2514
+ name: 'capture_scene',
2515
+ description: "Screenshot the active scene as seen on the GM's canvas, with a grid coordinate overlay (column,row per cell) burned in for spatial reasoning. Requires the companion Foundry module to be installed, enabled, and connected - fails with a clear error otherwise. Use when: you need to see the current map layout, token positions, or lighting to reason about it. Do not use when: you just need scene metadata (dimensions, darkness) - use get_scene_info, which needs no module.",
2516
+ inputSchema: {
2517
+ type: 'object',
2518
+ properties: {},
2519
+ },
2520
+ },
2521
+ {
2522
+ name: 'get_document_schema',
2523
+ description: "Introspect the connected game system's real DataModel schema for an Actor or Item type - the exact field names, types, string-enum choices, and default values that type accepts, read live from the running system (works for any installed system - Cyberpunk RED, D&D 5e, PF2e, etc - not a hardcoded list). Returns a nested JSON tree: each field has `type` (Number/String/Boolean/Schema/Array/…), `required`, `choices` for constrained strings, and `initial` for its default value; `fields` holds nested sub-fields, `element` describes an array's entries. Requires the companion Foundry module to be installed, enabled, and connected - fails with a clear error otherwise. Use when: building a `system` payload for create_world_actor/create_actor_item/create_full_actor and you do not already know that type's exact field names - call this once per type, then reuse the answer. Do not use when: you already know the schema from a prior call in this session - re-querying wastes a round trip; the schema does not change during a session.",
2524
+ inputSchema: {
2525
+ type: 'object',
2526
+ properties: {
2527
+ documentType: {
2528
+ type: 'string',
2529
+ enum: ['Actor', 'Item'],
2530
+ description: 'Which document collection the type belongs to',
2531
+ },
2532
+ type: {
2533
+ type: 'string',
2534
+ description: 'The Actor or Item type to introspect (e.g. "character", "npc", "weapon", "spell") - system-specific; list valid types by trying an obviously-wrong one, or check get_world_summary/the system documentation',
2535
+ },
2536
+ },
2537
+ required: ['documentType', 'type'],
2538
+ },
2539
+ },
2540
+ {
2541
+ name: 'search_compendium_content',
2542
+ description: 'Search compendium packs by name and journal entry text content using the browser-rendered Foundry session. Returns pack IDs, document IDs, names, and text snippet matches. Requires the companion Foundry module to be installed, enabled, and connected. Use when: looking up rules or items in compendiums.',
2543
+ inputSchema: {
2544
+ type: 'object',
2545
+ properties: {
2546
+ query: {
2547
+ type: 'string',
2548
+ description: 'Text query to search for across pack names and journal contents',
2549
+ },
2550
+ packType: {
2551
+ type: 'string',
2552
+ description: 'Optional document type to restrict search to (default "JournalEntry", e.g. "Item", "Actor")',
2553
+ default: 'JournalEntry',
2554
+ },
2555
+ limit: {
2556
+ type: 'number',
2557
+ description: 'Maximum number of results to return (default 20)',
2558
+ default: 20,
2559
+ },
2560
+ },
2561
+ },
2562
+ },
2563
+ {
2564
+ name: 'roll_and_post',
2565
+ description: 'Evaluate a dice formula using Foundry\'s native Roll engine and post it directly to chat as a rendered, clickable roll card. Supports full Foundry dice syntax (e.g. "4d6kh3", "1d20r1", exploding dice) that the local parser rejects. Requires the companion Foundry module.',
2566
+ inputSchema: {
2567
+ type: 'object',
2568
+ properties: {
2569
+ formula: {
2570
+ type: 'string',
2571
+ description: 'Dice formula to evaluate and post (e.g. "4d6kh3" or "2d6 + 5")',
2572
+ },
2573
+ flavor: {
2574
+ type: 'string',
2575
+ description: 'Optional flavor/context text displayed above the roll card',
2576
+ },
2577
+ speakerAlias: {
2578
+ type: 'string',
2579
+ description: 'Optional custom speaker alias displayed on the chat message',
2580
+ },
2581
+ whisperTo: {
2582
+ type: 'array',
2583
+ items: { type: 'string' },
2584
+ description: 'Optional list of User IDs to whisper the roll to privately',
2585
+ },
2586
+ rollMode: {
2587
+ type: 'string',
2588
+ enum: ['publicroll', 'gmroll', 'blindroll', 'selfroll'],
2589
+ description: 'Roll visibility mode (default "publicroll")',
2590
+ default: 'publicroll',
2591
+ },
2592
+ },
2593
+ required: ['formula'],
2594
+ },
2595
+ },
2596
+ {
2597
+ name: 'import_compendium_actor',
2598
+ description: 'Import a compendium Actor (with its embedded items and effects) as a new top-level world Actor - the gap spawn_token cannot close alone, since it requires an actor that already exists in the world. Best-effort on embedded items: if the game system rejects embedded documents on create, the actor is recreated without them and each item is seeded individually, reporting per-item failures rather than losing the whole import. Requires the companion Foundry module. Use when: adding a monster or NPC from a compendium to the world before spawning its token. Do not use when: the actor already exists in the world - use spawn_token directly.' +
2599
+ WRITE_GATE,
2600
+ inputSchema: {
2601
+ type: 'object',
2602
+ properties: {
2603
+ compendiumId: {
2604
+ type: 'string',
2605
+ description: 'Compendium pack id the actor lives in (e.g. "dnd5e.monsters")',
2606
+ },
2607
+ actorId: {
2608
+ type: 'string',
2609
+ description: "The compendium document's own id, as returned by search_compendium_content",
2610
+ },
2611
+ folderId: {
2612
+ type: 'string',
2613
+ description: 'Optional 16-char Folder document id to file the new world actor under',
2614
+ },
2615
+ name: {
2616
+ type: 'string',
2617
+ description: 'Optional rename for the world actor (default: the compendium name)',
2618
+ },
2619
+ },
2620
+ required: ['compendiumId', 'actorId'],
2621
+ },
2622
+ },
2623
+ {
2624
+ name: 'set_target',
2625
+ description: "Set or clear this GM user's target selection on the active canvas (renders the targeting reticle in connected player browsers). tokenIds are token document IDs on the currently viewed scene. Requires the companion Foundry module. Use when: directing player attention, declaring spell targets, or marking focus fire. " +
2626
+ WRITE_GATE,
2627
+ inputSchema: {
2628
+ type: 'object',
2629
+ properties: {
2630
+ tokenIds: {
2631
+ type: 'array',
2632
+ items: { type: 'string' },
2633
+ description: 'List of Token IDs on the active canvas to target (or un-target)',
2634
+ },
2635
+ targeted: {
2636
+ type: 'boolean',
2637
+ description: 'True to target, false to clear target on the given tokens (default: true)',
2638
+ default: true,
2639
+ },
2640
+ replace: {
2641
+ type: 'boolean',
2642
+ description: 'True to release all existing targets before setting new ones (default: false)',
2643
+ default: false,
2644
+ },
2645
+ },
2646
+ required: ['tokenIds'],
2647
+ },
2648
+ },
2649
+ {
2650
+ name: 'get_targets',
2651
+ description: 'List the current target selections of all connected users on the active canvas. Returns each user with the tokens they currently have targeted. Requires the companion Foundry module. Use when: checking who players are aiming at or focusing on.',
2652
+ inputSchema: {
2653
+ type: 'object',
2654
+ properties: {},
2655
+ },
2656
+ },
2657
+ {
2658
+ name: 'ping_canvas',
2659
+ description: "Emit an animated canvas ping at specific pixel coordinates on the active scene's view, drawing every connected player's camera and attention to that exact location. Requires the companion Foundry module. Use when: pointing out a trap, landmark, or hidden detail on the map. " +
2660
+ WRITE_GATE,
2661
+ inputSchema: {
2662
+ type: 'object',
2663
+ properties: {
2664
+ x: { type: 'number', description: 'Pixel x coordinate to ping' },
2665
+ y: { type: 'number', description: 'Pixel y coordinate to ping' },
2666
+ sceneId: {
2667
+ type: 'string',
2668
+ description: 'Optional scene id (fails if the GM canvas is viewing a different scene)',
2669
+ },
2670
+ },
2671
+ required: ['x', 'y'],
2672
+ },
2673
+ },
2674
+ {
2675
+ name: 'set_pause',
2676
+ description: 'Pause or unpause the game clock. When paused, token movement and real-time combat timers freeze for players. Requires the companion Foundry module. Use when: stepping away, narrating a long cutscene, or resolving a complex rules question. ' +
2677
+ WRITE_GATE,
2678
+ inputSchema: {
2679
+ type: 'object',
2680
+ properties: {
2681
+ paused: {
2682
+ type: 'boolean',
2683
+ description: 'True to pause, false to unpause (omit to toggle)',
2684
+ },
2685
+ },
2686
+ },
2687
+ },
2688
+ {
2689
+ name: 'upload_asset',
2690
+ description: "Upload a file (image, audio, etc.) into FoundryVTT's Data storage via the GM browser's FilePicker, returning the Foundry-relative path to feed directly into create_scene (backgroundSrc), create_tile (src), or create_sound (path). Provide exactly one of contentBase64 (base64-encoded file content) or sourcePath (an absolute path readable by this MCP server, which base64-encodes it server-side). Rejects payloads over 8 MiB. Requires the companion Foundry module. Use when: adding new map art, tokens, or audio the world does not already have. " +
2691
+ WRITE_GATE,
2692
+ inputSchema: {
2693
+ type: 'object',
2694
+ properties: {
2695
+ targetDir: {
2696
+ type: 'string',
2697
+ description: 'Data-relative destination folder (e.g. "assets/uploads")',
2698
+ },
2699
+ filename: {
2700
+ type: 'string',
2701
+ description: 'Destination filename, including extension',
2702
+ },
2703
+ contentBase64: {
2704
+ type: 'string',
2705
+ description: 'Base64-encoded file content. Mutually exclusive with sourcePath.',
2706
+ },
2707
+ sourcePath: {
2708
+ type: 'string',
2709
+ description: 'Absolute filesystem path readable by this MCP server. Mutually exclusive with contentBase64.',
2710
+ },
2711
+ mimeType: {
2712
+ type: 'string',
2713
+ description: 'Optional MIME type override; inferred from the filename extension if omitted',
2714
+ },
2715
+ },
2716
+ required: ['targetDir', 'filename'],
2717
+ oneOf: [{ required: ['contentBase64'] }, { required: ['sourcePath'] }],
2718
+ },
2719
+ },
2720
+ ];
2721
+ /**
2722
+ * General-purpose ActiveEffect tool definitions
2723
+ *
2724
+ * `apply_status_effect` (tokenMutationTools) stays the simpler, idempotent
2725
+ * status-toggle contract; these exist for mechanical buffs/debuffs with real
2726
+ * `changes`/`duration`.
2727
+ */
2728
+ export const effectTools = [
2729
+ {
2730
+ name: 'create_actor_effect',
2731
+ description: "Create a general-purpose ActiveEffect on an actor with mechanical changes (attribute modifiers) and/or a duration - not just a status toggle (use apply_status_effect for that). Give actorId alone for a world-linked actor, or actorId plus the sceneId+tokenId pair together for an unlinked token's synthetic actor. changes[].mode is a named FoundryVTT ACTIVE_EFFECT_MODES combine rule (add/multiply/override/upgrade/downgrade/custom), not a raw number. Use when: applying a spell buff, a debuff, or an equipment bonus with a real mechanical effect. Do not use when: toggling a simple named condition (prone, stunned) - use apply_status_effect. " +
2732
+ WRITE_GATE,
2733
+ inputSchema: {
2734
+ type: 'object',
2735
+ properties: {
2736
+ actorId: { type: 'string', description: "The actor's own document id" },
2737
+ sceneId: {
2738
+ type: 'string',
2739
+ description: 'Scene id, required together with tokenId for an unlinked token actor',
2740
+ },
2741
+ tokenId: {
2742
+ type: 'string',
2743
+ description: 'Token id, required together with sceneId for an unlinked token actor',
2744
+ },
2745
+ name: { type: 'string', description: 'Effect display name' },
2746
+ img: { type: 'string', description: 'Optional icon image path' },
2747
+ description: { type: 'string', description: 'Optional effect description text' },
2748
+ disabled: {
2749
+ type: 'boolean',
2750
+ description: 'Create the effect already disabled (default false)',
2751
+ },
2752
+ statuses: {
2753
+ type: 'array',
2754
+ items: { type: 'string' },
2755
+ description: 'Optional status condition ids this effect also represents',
2756
+ },
2757
+ duration: {
2758
+ type: 'object',
2759
+ description: 'Optional effect duration',
2760
+ properties: {
2761
+ rounds: { type: 'number' },
2762
+ turns: { type: 'number' },
2763
+ seconds: { type: 'number' },
2764
+ startRound: { type: 'number' },
2765
+ startTurn: { type: 'number' },
2766
+ },
2767
+ },
2768
+ changes: {
2769
+ type: 'array',
2770
+ description: 'Mechanical changes this effect applies',
2771
+ items: {
2772
+ type: 'object',
2773
+ properties: {
2774
+ key: {
2775
+ type: 'string',
2776
+ description: 'Dot-path into the actor being modified (e.g. "system.attributes.hp.max")',
2777
+ },
2778
+ mode: {
2779
+ type: 'string',
2780
+ enum: ['custom', 'multiply', 'add', 'downgrade', 'upgrade', 'override'],
2781
+ description: 'How this change combines with the base value',
2782
+ },
2783
+ value: { type: 'string', description: 'Change value (always a string on the wire)' },
2784
+ priority: {
2785
+ type: 'number',
2786
+ description: 'Optional application order (default: mode order)',
2787
+ },
2788
+ },
2789
+ required: ['key', 'mode', 'value'],
2790
+ },
2791
+ },
2792
+ },
2793
+ required: ['actorId', 'name'],
2794
+ },
2795
+ },
2796
+ {
2797
+ name: 'update_actor_effect',
2798
+ description: "Update fields on an existing ActiveEffect - every field replaces the corresponding one on the existing document, omitted fields are left as they are. Same actorId/sceneId+tokenId resolution as create_actor_effect. Use when: a buff's remaining duration changes, or its magnitude scales. Do not use when: the effect should end - use delete_actor_effect. " +
2799
+ WRITE_GATE,
2800
+ inputSchema: {
2801
+ type: 'object',
2802
+ properties: {
2803
+ actorId: { type: 'string', description: "The actor's own document id" },
2804
+ sceneId: {
2805
+ type: 'string',
2806
+ description: 'Scene id, required together with tokenId for an unlinked token actor',
2807
+ },
2808
+ tokenId: {
2809
+ type: 'string',
2810
+ description: 'Token id, required together with sceneId for an unlinked token actor',
2811
+ },
2812
+ effectId: { type: 'string', description: 'The ActiveEffect document id to update' },
2813
+ name: { type: 'string', description: 'New effect display name' },
2814
+ img: { type: 'string', description: 'New icon image path' },
2815
+ description: { type: 'string', description: 'New effect description text' },
2816
+ disabled: { type: 'boolean', description: 'Enable/disable the effect' },
2817
+ statuses: {
2818
+ type: 'array',
2819
+ items: { type: 'string' },
2820
+ description: 'Replacement status condition ids',
2821
+ },
2822
+ duration: {
2823
+ type: 'object',
2824
+ description: 'Replacement effect duration',
2825
+ properties: {
2826
+ rounds: { type: 'number' },
2827
+ turns: { type: 'number' },
2828
+ seconds: { type: 'number' },
2829
+ startRound: { type: 'number' },
2830
+ startTurn: { type: 'number' },
2831
+ },
2832
+ },
2833
+ changes: {
2834
+ type: 'array',
2835
+ description: 'Replacement mechanical changes',
2836
+ items: {
2837
+ type: 'object',
2838
+ properties: {
2839
+ key: { type: 'string' },
2840
+ mode: {
2841
+ type: 'string',
2842
+ enum: ['custom', 'multiply', 'add', 'downgrade', 'upgrade', 'override'],
2843
+ },
2844
+ value: { type: 'string' },
2845
+ priority: { type: 'number' },
2846
+ },
2847
+ required: ['key', 'mode', 'value'],
2848
+ },
2849
+ },
2850
+ },
2851
+ required: ['actorId', 'effectId'],
2852
+ },
2853
+ },
2854
+ {
2855
+ name: 'delete_actor_effect',
2856
+ description: 'Delete an ActiveEffect from an actor. Same actorId/sceneId+tokenId resolution as create_actor_effect. ' +
2857
+ CONFIRM_FIRST +
2858
+ ' ' +
2859
+ WRITE_GATE,
2860
+ inputSchema: {
2861
+ type: 'object',
2862
+ properties: {
2863
+ actorId: { type: 'string', description: "The actor's own document id" },
2864
+ sceneId: {
2865
+ type: 'string',
2866
+ description: 'Scene id, required together with tokenId for an unlinked token actor',
2867
+ },
2868
+ tokenId: {
2869
+ type: 'string',
2870
+ description: 'Token id, required together with sceneId for an unlinked token actor',
2871
+ },
2872
+ effectId: { type: 'string', description: 'The ActiveEffect document id to delete' },
2873
+ },
2874
+ required: ['actorId', 'effectId'],
2875
+ },
2876
+ },
2877
+ {
2878
+ name: 'list_actor_effects',
2879
+ description: "List the ActiveEffects on a world-linked actor, read from the cached world snapshot (no socket round trip). Only reaches a top-level Actor document - an unlinked token's synthetic per-token actor is not independently listable this way. Use when: checking what buffs/debuffs are currently active on an actor before applying another.",
2880
+ inputSchema: {
2881
+ type: 'object',
2882
+ properties: {
2883
+ actorId: { type: 'string', description: "The actor's own document id" },
2884
+ },
2885
+ required: ['actorId'],
2886
+ },
2887
+ },
2888
+ ];
2889
+ /**
2890
+ * Scene Region tool definitions (FoundryVTT v12+)
2891
+ */
2892
+ export const regionTools = [
2893
+ {
2894
+ name: 'list_regions',
2895
+ description: 'List the Scene Regions placed on a scene (FoundryVTT v12+). Regions are polygon/circle/rectangle areas that trigger behaviors when tokens enter, move through, or leave them. Use when: inspecting traps, teleport pads, atmospheric zones, or scripted triggers on a map.',
2896
+ inputSchema: {
2897
+ type: 'object',
2898
+ properties: {
2899
+ sceneId: {
2900
+ type: 'string',
2901
+ description: 'Optional scene id; defaults to the currently active scene',
2902
+ },
2903
+ },
2904
+ },
2905
+ },
2906
+ {
2907
+ name: 'create_region',
2908
+ description: 'Create a new Scene Region with shapes and/or automated behaviors (FoundryVTT v12+). Shapes use pixel coordinates (use get_scene_info/find_open_cells to convert from grid cells). Documented behaviors include teleportToken ({ destination: <region UUID> }), displayScrollingText ({ text, color, visibility }), adjustDarknessLevel ({ mode, modifier }), and pauseGame ({ once }); custom system/module behavior types pass through untouched. ' +
2909
+ WRITE_GATE,
2910
+ inputSchema: {
2911
+ type: 'object',
2912
+ properties: {
2913
+ name: { type: 'string', description: 'Region display name' },
2914
+ sceneId: {
2915
+ type: 'string',
2916
+ description: 'Optional scene id; defaults to the currently active scene',
2917
+ },
2918
+ color: {
2919
+ type: 'string',
2920
+ description: 'Optional 6-digit hex color for canvas rendering (e.g. "#ff8800")',
2921
+ },
2922
+ visibility: {
2923
+ type: 'number',
2924
+ description: '0 = hidden from players, 1 = visible to players (default: 0)',
2925
+ },
2926
+ elevation: {
2927
+ type: 'object',
2928
+ description: 'Optional 3D vertical bounds (null for unbounded)',
2929
+ properties: {
2930
+ bottom: { type: 'number' },
2931
+ top: { type: 'number' },
2932
+ },
2933
+ },
2934
+ shapes: {
2935
+ type: 'array',
2936
+ description: 'Pixel-coordinate geometric shapes defining the region boundary',
2937
+ items: {
2938
+ type: 'object',
2939
+ properties: {
2940
+ type: { type: 'string', enum: ['rectangle', 'circle', 'polygon'] },
2941
+ x: { type: 'number' },
2942
+ y: { type: 'number' },
2943
+ width: { type: 'number' },
2944
+ height: { type: 'number' },
2945
+ radius: { type: 'number' },
2946
+ points: {
2947
+ type: 'array',
2948
+ items: { type: 'number' },
2949
+ description: 'For polygon: array of alternating x,y coordinates (at least 6)',
2950
+ },
2951
+ },
2952
+ required: ['type'],
2953
+ },
2954
+ },
2955
+ behaviors: {
2956
+ type: 'array',
2957
+ description: 'Automated behaviors triggered when tokens interact with the region',
2958
+ items: {
2959
+ type: 'object',
2960
+ properties: {
2961
+ type: {
2962
+ type: 'string',
2963
+ description: 'Behavior type string, e.g. "teleportToken", "displayScrollingText", "adjustDarknessLevel", "pauseGame"',
2964
+ },
2965
+ system: { type: 'object', description: 'Behavior configuration data' },
2966
+ disabled: { type: 'boolean', description: 'Create the behavior disabled' },
2967
+ },
2968
+ required: ['type'],
2969
+ },
2970
+ },
2971
+ },
2972
+ required: ['name'],
2973
+ },
2974
+ },
2975
+ {
2976
+ name: 'delete_region',
2977
+ description: `Delete a Scene Region from a scene (FoundryVTT v12+). ${CONFIRM_FIRST} ${WRITE_GATE}`,
2978
+ inputSchema: {
2979
+ type: 'object',
2980
+ properties: {
2981
+ regionId: { type: 'string', description: 'The Region document id to delete' },
2982
+ sceneId: {
2983
+ type: 'string',
2984
+ description: 'Optional scene id; defaults to the currently active scene',
2985
+ },
2986
+ },
2987
+ required: ['regionId'],
2988
+ },
2989
+ },
2990
+ ];
2991
+ /**
2992
+ * World-event tool definitions
2993
+ *
2994
+ * Backed by an in-memory, cursor-addressed log of every `modifyDocument` /
2995
+ * `userActivity` broadcast this server has observed (plus canvas events
2996
+ * pushed by the companion module). Read-only.
2997
+ */
2998
+ export const eventTools = [
2999
+ {
3000
+ name: 'watch_events',
3001
+ description: "Wait for and return world activity since a cursor - chat messages, token/actor/combat updates, door state changes, user connect/disconnect, and canvas targeting - instead of re-polling get_chat_messages/get_combat_state in a loop. Blocks for up to waitMs (default 25000, max 120000) if nothing has happened yet, returning as soon as something does; pass 0 to check without waiting. Your MCP client's own request timeout must exceed waitMs or the call will appear to fail while still running server-side. Always pass the returned nextCursor back as `cursor` on your next call - it is required to avoid missing or re-reading events, and a nonzero `dropped` count means events were evicted from the buffer before your cursor (increase FOUNDRY_EVENT_BUFFER_SIZE, or catch up with refresh_world_data/get_scene_info). Changing kinds/types/actions/sceneId mid-stream cannot recover events a previous filter already skipped past. Use when: waiting for a player to act, or checking what happened while you were doing something else. Do not use when: you need the full current state of something - use the matching get_*/search_* tool instead.",
3002
+ inputSchema: {
3003
+ type: 'object',
3004
+ properties: {
3005
+ cursor: {
3006
+ type: 'string',
3007
+ description: '"now" (default) to start from this moment, "oldest" for the full retained buffer, or a nextCursor value from a previous call',
3008
+ default: 'now',
3009
+ },
3010
+ waitMs: {
3011
+ type: 'number',
3012
+ description: 'Milliseconds to block waiting for a new event before returning empty (default 25000, max 120000, 0 = return immediately)',
3013
+ default: 25000,
3014
+ minimum: 0,
3015
+ maximum: 120000,
3016
+ },
3017
+ limit: {
3018
+ type: 'number',
3019
+ description: 'Maximum events to return in one call (default 50, max 200)',
3020
+ default: 50,
3021
+ minimum: 1,
3022
+ maximum: 200,
3023
+ },
3024
+ kinds: {
3025
+ type: 'array',
3026
+ items: { type: 'string', enum: ['document', 'presence', 'target'] },
3027
+ description: 'Restrict to these event kinds (default: all)',
3028
+ },
3029
+ types: {
3030
+ type: 'array',
3031
+ items: { type: 'string' },
3032
+ description: 'Restrict to these document names, e.g. ["ChatMessage","Token","Combat"] (default: all)',
3033
+ },
3034
+ actions: {
3035
+ type: 'array',
3036
+ items: { type: 'string' },
3037
+ description: 'Restrict to these actions, e.g. ["create","update"] (default: all)',
3038
+ },
3039
+ sceneId: {
3040
+ type: 'string',
3041
+ description: 'Restrict to events on this scene (default: all scenes)',
3042
+ },
3043
+ excludeSelf: {
3044
+ type: 'boolean',
3045
+ description: "Drop events this server's own writes caused, when FoundryVTT echoes them back (default true)",
3046
+ default: true,
3047
+ },
3048
+ },
3049
+ },
3050
+ },
3051
+ ];
3052
+ /**
3053
+ * Get all tool definitions combined
3054
+ */
3055
+ export function getAllTools() {
3056
+ return [
3057
+ ...diceTools,
3058
+ ...actorTools,
3059
+ ...actorMutationTools,
3060
+ ...itemTools,
3061
+ ...compendiumTools,
3062
+ ...itemMutationTools,
3063
+ ...sceneTools,
3064
+ ...sceneMutationTools,
3065
+ ...wallMutationTools,
3066
+ ...tileTools,
3067
+ ...tileMutationTools,
3068
+ ...combatTools,
3069
+ ...placeableTools,
3070
+ ...placeableMutationTools,
3071
+ ...combatMutationTools,
3072
+ ...tokenTools,
3073
+ ...tokenMutationTools,
3074
+ ...chatTools,
3075
+ ...chatMutationTools,
3076
+ ...userTools,
3077
+ ...journalTools,
3078
+ ...journalMutationTools,
3079
+ ...worldTools,
3080
+ ...worldDocumentTools,
3081
+ ...worldDocumentMutationTools,
3082
+ ...rollTableTools,
3083
+ ...moduleBridgeTools,
3084
+ ...eventTools,
3085
+ ...effectTools,
3086
+ ...regionTools,
3087
+ ...generationTools,
3088
+ ...settingsTools,
3089
+ ...diagnosticsTools,
3090
+ ];
3091
+ }
3092
+ /**
3093
+ * Get modernized tool definitions from registry (when available)
3094
+ */
3095
+ export async function getModernizedTools() {
3096
+ try {
3097
+ const { toolRegistry } = await import('./registry.js');
3098
+ const modernTools = toolRegistry.getToolDefinitions();
3099
+ // Filter out tools that have been modernized to avoid duplicates
3100
+ const modernToolNames = new Set(modernTools.map((tool) => tool.name));
3101
+ const legacyTools = getAllTools().filter((tool) => !modernToolNames.has(tool.name));
3102
+ return [...modernTools, ...legacyTools];
3103
+ }
3104
+ catch (_error) {
3105
+ // Fallback to legacy definitions if registry is not available
3106
+ return getAllTools();
3107
+ }
3108
+ }
3109
+ //# sourceMappingURL=definitions.js.map