@g33ks/foundryvtt-mcp 2.2.1 → 3.0.1

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.
@@ -32,7 +32,7 @@ const CONFIRM_FIRST = 'DESTRUCTIVE and not undoable from this server: confirm th
32
32
  * registry class is what *executes* the tool while `getAllTools()` is what is
33
33
  * *listed*, so a divergence would be invisible.
34
34
  */
35
- 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.';
35
+ 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, an attack, damage, or any random result.';
36
36
  /**
37
37
  * Dice rolling tool definitions
38
38
  */
@@ -62,7 +62,7 @@ export const diceTools = [
62
62
  export const actorTools = [
63
63
  {
64
64
  name: 'search_actors',
65
- 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).",
65
+ description: "Search actors (player characters, NPCs) by name, optionally filtered by type. Returns a summary line per match: name, type, and the level and current/max hit points when the actor stores them at details.level and attributes.hp. Use when: checking whether an actor exists, or getting a quick roster. Do not use when: you already have the actorId and want more of that actor's values - 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).",
66
66
  inputSchema: {
67
67
  type: 'object',
68
68
  properties: {
@@ -88,7 +88,7 @@ export const actorTools = [
88
88
  },
89
89
  {
90
90
  name: 'get_actor_details',
91
- 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. For one token on a map, give sceneId + tokenId instead of actorId: an unlinked token (a copy of a monster with its own HP) reports its own values, a linked token the values of its world actor. 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 - get_actor_inventory lists them.',
91
+ description: 'Get details for one actor by id: type, and the level, current/max hit points, armour class and ability values the actor stores at details.level, attributes.hp, attributes.ac and abilities (a game system that stores them elsewhere shows fewer fields; get_actor_stats returns all of its data); 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 values - notably as the read-before-write step for update_actor_attributes. For one token on a map, give sceneId + tokenId instead of actorId: an unlinked token (a copy of a creature with its own values) reports its own values, a linked token the values of its world actor. 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 - get_actor_inventory lists them.',
92
92
  inputSchema: {
93
93
  type: 'object',
94
94
  properties: {
@@ -110,7 +110,7 @@ export const actorTools = [
110
110
  },
111
111
  {
112
112
  name: 'get_actor_inventory',
113
- 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. For one token on a map, give sceneId + tokenId instead of actorId: an unlinked token lists its own items (those it inherits from its base actor and its own, without the ones removed from it), a linked token its world actor's. Do not use when: you only need the actor's HP/AC/abilities - use get_actor_details.",
113
+ description: "List an actor's owned items (equipment, features, abilities…) 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 action or a trade. For one token on a map, give sceneId + tokenId instead of actorId: an unlinked token lists its own items (those it inherits from its base actor and its own, without the ones removed from it), a linked token its world actor's. Do not use when: you only need the actor's own values - use get_actor_details.",
114
114
  inputSchema: {
115
115
  type: 'object',
116
116
  properties: {
@@ -140,7 +140,7 @@ export const actorTools = [
140
140
  export const actorMutationTools = [
141
141
  {
142
142
  name: 'update_actor_attributes',
143
- 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. For one token on a map - an unlinked copy of a monster, which has its own HP - give sceneId + tokenId instead of actorId: only that token changes, not the base actor or its other copies. Write only stored fields: a field the game system computes from others is accepted and saved by the server, but has no effect in play. Do not use when: changing an item the actor owns (use update_actor_item) or only reading current values (use get_actor_details). ' +
143
+ description: 'Update fields on an actor\'s system data. Patch keys are dot-paths into actor.system (e.g. "attributes.health.value", "resources.primary.value", "details.notes") and values are absolute target values, never relative deltas. If the actor stores a value at one of these paths, it is range-checked: attributes.hp.value against max + temp, spells.<key>.value against the max of that entry, and attributes.exhaustion against 0-10 (0-6 when the data of the actor marks older rules). Returns the post-update value for every patched path. Use when: applying damage or healing, spending a resource, or adjusting a stored value on a known actorId. For one token on a map - an unlinked copy of a creature, which has its own values - give sceneId + tokenId instead of actorId: only that token changes, not the base actor or its other copies. Write only stored fields: a field the game system computes from others is accepted and saved by the server, but has no effect in play. Do not use when: changing an item the actor owns (use update_actor_item) or only reading current values (use get_actor_details). ' +
144
144
  WRITE_GATE,
145
145
  inputSchema: {
146
146
  type: 'object',
@@ -160,7 +160,7 @@ export const actorMutationTools = [
160
160
  patch: {
161
161
  type: 'object',
162
162
  description: 'Map of dot-path → value, where each dot-path addresses a field under actor.system ' +
163
- '(e.g. {"attributes.hp.value": 30, "currency.gp": 12}). Values must be number, string, or boolean.',
163
+ '(e.g. {"attributes.health.value": 30, "resources.primary.value": 2}). Values must be number, string, or boolean.',
164
164
  additionalProperties: {
165
165
  type: ['number', 'string', 'boolean'],
166
166
  },
@@ -202,7 +202,7 @@ export const actorMutationTools = [
202
202
  },
203
203
  {
204
204
  name: 'create_full_actor',
205
- 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. " +
205
+ description: "Create a new top-level Actor document AND seed it with starting items (gear, weapons, features, …) 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 attributes plus starting equipment and features) 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. " +
206
206
  WRITE_GATE,
207
207
  inputSchema: {
208
208
  type: 'object',
@@ -225,7 +225,7 @@ export const actorMutationTools = [
225
225
  },
226
226
  items: {
227
227
  type: 'array',
228
- description: 'Optional starting items (skills, weapons, gear, cyberware, …) to create on the actor immediately after it exists',
228
+ description: 'Optional starting items (weapons, gear, features, …) to create on the actor immediately after it exists',
229
229
  items: {
230
230
  type: 'object',
231
231
  properties: {
@@ -235,7 +235,7 @@ export const actorMutationTools = [
235
235
  },
236
236
  type: {
237
237
  type: 'string',
238
- description: 'Game-system item type (e.g. "weapon", "skill") - use get_document_schema("Item", type) to learn the real field names first',
238
+ description: 'Game-system item type (e.g. "weapon", "feature") - use get_document_schema("Item", type) to learn the real field names first',
239
239
  },
240
240
  system: {
241
241
  type: 'object',
@@ -308,7 +308,7 @@ export const itemTools = [
308
308
  export const compendiumTools = [
309
309
  {
310
310
  name: 'search_compendium',
311
- 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.',
311
+ description: 'Search FoundryVTT compendium packs by name and metadata; searches all enabled packs unless compendiumId scopes it to one pack. Use when: looking up creatures, items or rules 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.',
312
312
  inputSchema: {
313
313
  type: 'object',
314
314
  properties: {
@@ -330,7 +330,7 @@ export const compendiumTools = [
330
330
  },
331
331
  itemType: {
332
332
  type: 'string',
333
- description: 'Item type filter (spell, weapon, feat, etc.)',
333
+ description: 'Item type filter (e.g. weapon, equipment, feature)',
334
334
  },
335
335
  spellLevel: {
336
336
  type: 'number',
@@ -366,7 +366,7 @@ export const compendiumTools = [
366
366
  export const itemMutationTools = [
367
367
  {
368
368
  name: 'create_actor_item',
369
- 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. For one token on a map, give sceneId + tokenId (an actorId given as well must be the actor of the token): an unlinked token gets the item on that token only, a linked token on its world actor. 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. ' +
369
+ 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, feature, or piece of equipment to a known actorId. For one token on a map, give sceneId + tokenId (an actorId given as well must be the actor of the token): an unlinked token gets the item on that token only, a linked token on its world actor. 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. ' +
370
370
  WRITE_GATE,
371
371
  inputSchema: {
372
372
  type: 'object',
@@ -510,7 +510,7 @@ export const sceneMutationTools = [
510
510
  },
511
511
  backgroundSrc: {
512
512
  type: 'string',
513
- description: 'Data-relative path to the background image (e.g. "assets/cyberpunk/maps/v1/x.jpg"), as returned by list_scene_assets',
513
+ description: 'Data-relative path to the background image (e.g. "assets/maps/v1/x.jpg"), as returned by list_scene_assets',
514
514
  },
515
515
  width: {
516
516
  type: 'number',
@@ -586,7 +586,7 @@ export const sceneMutationTools = [
586
586
  },
587
587
  {
588
588
  name: 'set_scene_lighting',
589
- 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. " +
589
+ description: "Set a scene's ambient darkness level (0-1) and/or global illumination (globalLight, globalLightThreshold). Written to the Scene document's environment fields (environment.darknessLevel, environment.globalLight) - 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. " +
590
590
  WRITE_GATE,
591
591
  inputSchema: {
592
592
  type: 'object',
@@ -846,7 +846,7 @@ export const tileTools = [
846
846
  export const tileMutationTools = [
847
847
  {
848
848
  name: 'create_tile',
849
- 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. " +
849
+ 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 its own statistics and act in combat - use create_world_actor + spawn_token instead. " +
850
850
  WRITE_GATE,
851
851
  inputSchema: {
852
852
  type: 'object',
@@ -982,7 +982,7 @@ export const placeableTools = [
982
982
  },
983
983
  {
984
984
  name: 'list_templates',
985
- 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.',
985
+ description: 'List the Measured Templates (area-of-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 areas of effect or finding a templateId for delete_template.',
986
986
  inputSchema: {
987
987
  type: 'object',
988
988
  properties: {
@@ -1308,7 +1308,7 @@ export const placeableMutationTools = [
1308
1308
  },
1309
1309
  {
1310
1310
  name: 'create_template',
1311
- 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). ' +
1311
+ description: 'Place a Measured Template (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). ' +
1312
1312
  WRITE_GATE,
1313
1313
  inputSchema: {
1314
1314
  type: 'object',
@@ -1376,7 +1376,7 @@ export const placeableMutationTools = [
1376
1376
  export const generationTools = [
1377
1377
  {
1378
1378
  name: 'generate_npc',
1379
- 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.',
1379
+ description: 'Generate a random fantasy-style NPC as text, from built-in lists that do not depend on the game system of the world (name, people, profession, hit points, ability values, background). 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.',
1380
1380
  inputSchema: {
1381
1381
  type: 'object',
1382
1382
  properties: {
@@ -1400,13 +1400,13 @@ export const generationTools = [
1400
1400
  },
1401
1401
  {
1402
1402
  name: 'generate_loot',
1403
- 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.",
1403
+ description: "Generate random fantasy-style treasure for an encounter as text, from built-in tables that do not depend on the game system of the world. Only the coin amounts vary: they scale with challengeRating, 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.",
1404
1404
  inputSchema: {
1405
1405
  type: 'object',
1406
1406
  properties: {
1407
1407
  challengeRating: {
1408
1408
  type: 'number',
1409
- description: 'Challenge rating for loot generation',
1409
+ description: 'Difficulty of the encounter; the coin amounts scale with it',
1410
1410
  minimum: 0,
1411
1411
  maximum: 30,
1412
1412
  },
@@ -1526,7 +1526,7 @@ export const diagnosticsTools = [
1526
1526
  export const combatTools = [
1527
1527
  {
1528
1528
  name: 'get_combat_state',
1529
- 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.",
1529
+ description: "Get the active combat encounter: initiative order with each combatant's name and initiative, its hit points and armour class when its actor stores them at attributes.hp and attributes.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.",
1530
1530
  inputSchema: {
1531
1531
  type: 'object',
1532
1532
  properties: {},
@@ -1665,7 +1665,7 @@ export const tokenMutationTools = [
1665
1665
  },
1666
1666
  {
1667
1667
  name: 'apply_status_effect',
1668
- 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. With the module bridge enabled, it first waits up to 10 s for the companion module if it is still connecting. With module 0.6.0 or later, the status goes through the game system\'s own status effects, so the system recognises the effect as its condition; effects carrying the status that were written earlier over the socket are reported when applying and removed with active=false. Some game systems ask for a value when a status is created; pass it in createOptions, under the option name the system documents. Without it, the call fails at once and nothing is created. createOptions need that path: they are refused when it is not available (no module 0.6.0, or writes disabled), and ignored when the status is already active. Otherwise, or if the module does not come, an effect carrying the status is written over the socket (its icon always shown), which a game system that defines its own statuses with fixed effect ids may not recognise. The answer names the path used. On an unlinked token only that token changes: a status it inherits from its base actor is found and can be removed from that token alone. Use when: a condition is gained or lost. Do not use when: changing numeric state such as HP - use update_actor_attributes. ' +
1668
+ 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. With the module bridge enabled, it first waits up to 10 s for the companion module if it is still connecting. With module 0.6.0 or later, the status goes through the game system\'s own status effects, so the system recognises the effect as its condition; effects carrying the status that were written earlier over the socket are reported when applying and removed with active=false. Some game systems ask for a value when a status is created; pass it in createOptions, under the option name the system documents. Without it, the call fails at once and nothing is created. createOptions need that path: they are refused when it is not available (no module 0.6.0, or writes disabled), and ignored when the status is already active. Otherwise, or if the module does not come, an effect carrying the status is written over the socket (its icon always shown), which a game system that defines its own statuses with fixed effect ids may not recognise. The answer names the path used. On an unlinked token only that token changes: a status it inherits from its base actor is found and can be removed from that token alone. Use when: a condition is gained or lost. Do not use when: changing numeric state such as hit points - use update_actor_attributes. ' +
1669
1669
  WRITE_GATE +
1670
1670
  ' 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.',
1671
1671
  inputSchema: {
@@ -1698,7 +1698,7 @@ export const tokenMutationTools = [
1698
1698
  },
1699
1699
  {
1700
1700
  name: 'spawn_token',
1701
- 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. " +
1701
+ 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 creature, 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. " +
1702
1702
  WRITE_GATE,
1703
1703
  inputSchema: {
1704
1704
  type: 'object',
@@ -1733,7 +1733,7 @@ export const tokenMutationTools = [
1733
1733
  },
1734
1734
  {
1735
1735
  name: 'delete_token',
1736
- 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. " +
1736
+ description: "Remove a token from a scene without deleting the underlying actor. Use when: a creature 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. " +
1737
1737
  WRITE_GATE,
1738
1738
  inputSchema: {
1739
1739
  type: 'object',
@@ -2531,7 +2531,7 @@ export const rollTableTools = [
2531
2531
  export const settingsTools = [
2532
2532
  {
2533
2533
  name: 'get_world_setting',
2534
- 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.',
2534
+ description: 'Read a world setting by its namespaced key (e.g. "my-module.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.',
2535
2535
  inputSchema: {
2536
2536
  type: 'object',
2537
2537
  properties: {
@@ -2545,7 +2545,7 @@ export const settingsTools = [
2545
2545
  },
2546
2546
  {
2547
2547
  name: 'set_world_setting',
2548
- 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). ' +
2548
+ description: 'Update or create a world setting value for a system or module namespace (e.g. "my-module.settingName"). Refuses writes to the "core.*" namespace (core settings control the Foundry client itself and can break the world; change those in the UI). ' +
2549
2549
  CONFIRM_FIRST +
2550
2550
  ' ' +
2551
2551
  WRITE_GATE,
@@ -2594,7 +2594,7 @@ export const moduleBridgeTools = [
2594
2594
  },
2595
2595
  type: {
2596
2596
  type: 'string',
2597
- 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',
2597
+ description: 'The Actor or Item type to introspect (e.g. "character", "npc", "weapon") - system-specific; list valid types by trying an obviously-wrong one, or check get_world_summary/the system documentation',
2598
2598
  },
2599
2599
  },
2600
2600
  required: ['documentType', 'type'],
@@ -2659,14 +2659,14 @@ export const moduleBridgeTools = [
2659
2659
  },
2660
2660
  {
2661
2661
  name: 'import_compendium_actor',
2662
- 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.' +
2662
+ 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 creature 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.' +
2663
2663
  WRITE_GATE,
2664
2664
  inputSchema: {
2665
2665
  type: 'object',
2666
2666
  properties: {
2667
2667
  compendiumId: {
2668
2668
  type: 'string',
2669
- description: 'Compendium pack id the actor lives in (e.g. "dnd5e.monsters")',
2669
+ description: 'Compendium pack id the actor lives in (e.g. "world.creatures")',
2670
2670
  },
2671
2671
  actorId: {
2672
2672
  type: 'string',
@@ -2686,7 +2686,7 @@ export const moduleBridgeTools = [
2686
2686
  },
2687
2687
  {
2688
2688
  name: 'set_target',
2689
- 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. " +
2689
+ 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 targets, or marking a shared target. " +
2690
2690
  MODULE_WRITE_GATE,
2691
2691
  inputSchema: {
2692
2692
  type: 'object',
@@ -2822,7 +2822,7 @@ export const moduleBridgeTools = [
2822
2822
  export const effectTools = [
2823
2823
  {
2824
2824
  name: 'create_actor_effect',
2825
- 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 actor, or actorId plus the sceneId+tokenId pair for one token: a linked token writes its world actor, an unlinked token only that token (its own copy of the actor), never the base actor or its other tokens. The token must carry actorId. 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. ' +
2825
+ 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 actor, or actorId plus the sceneId+tokenId pair for one token: a linked token writes its world actor, an unlinked token only that token (its own copy of the actor), never the base actor or its other tokens. The token must carry actorId. 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 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. ' +
2826
2826
  WRITE_GATE,
2827
2827
  inputSchema: {
2828
2828
  type: 'object',
@@ -2867,7 +2867,7 @@ export const effectTools = [
2867
2867
  properties: {
2868
2868
  key: {
2869
2869
  type: 'string',
2870
- description: 'Dot-path into the actor being modified (e.g. "system.attributes.hp.max")',
2870
+ description: 'Dot-path into the actor being modified (e.g. "system.attributes.health.max")',
2871
2871
  },
2872
2872
  mode: {
2873
2873
  type: 'string',
@@ -6,7 +6,7 @@
6
6
  * connection (mutations use the core `modifyDocument` protocol).
7
7
  */
8
8
  import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
9
- import { withToolError } from './utils.js';
9
+ import { deletionNote, withToolError } from './utils.js';
10
10
  /**
11
11
  * Handles actor attribute update requests.
12
12
  *
@@ -125,9 +125,11 @@ export async function handleDeleteWorldActor(args, foundryClient) {
125
125
  throw new McpError(ErrorCode.InvalidParams, 'actorId is required and must be a string');
126
126
  }
127
127
  return withToolError('delete actor', async () => {
128
- await foundryClient.deleteWorldActor(actorId);
128
+ const note = await foundryClient.deleteWorldActor(actorId);
129
129
  return {
130
- content: [{ type: 'text', text: `🗑️ **Actor Deleted**\n**ID:** ${actorId}` }],
130
+ content: [
131
+ { type: 'text', text: `🗑️ **Actor Deleted**\n**ID:** ${actorId}${deletionNote(note)}` },
132
+ ],
131
133
  };
132
134
  });
133
135
  }
@@ -10,7 +10,7 @@
10
10
  import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
11
11
  import { combatantName } from './combat.js';
12
12
  import { getCurrentCombatant, getTurnOrder, turnIndexAfterInitiativeChange, } from './combat-order.js';
13
- import { withToolError } from './utils.js';
13
+ import { deletionNote, withToolError } from './utils.js';
14
14
  /**
15
15
  * Computes the next `{ turn, round }` for an active combat.
16
16
  *
@@ -90,14 +90,14 @@ export async function handleEndCombat(_args, foundryClient) {
90
90
  throw new McpError(ErrorCode.InvalidRequest, 'No active combat to end.');
91
91
  }
92
92
  return withToolError('end combat', async () => {
93
- await foundryClient.endCombat(combat._id);
93
+ const note = await foundryClient.endCombat(combat._id);
94
94
  return {
95
95
  content: [
96
96
  {
97
97
  type: 'text',
98
98
  text: `⚔️ **Combat Ended**
99
99
  **Encounter:** ${combat._id}
100
- The active combat encounter has been removed.`,
100
+ The active combat encounter has been removed.${deletionNote(note)}`,
101
101
  },
102
102
  ],
103
103
  };
@@ -10,7 +10,7 @@ import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
10
10
  import { journalVersion } from '../../foundry/journal-integrity.js';
11
11
  import { VISIBILITY_LEVELS } from '../../foundry/types.js';
12
12
  import { refusalError } from '../../utils/refusal.js';
13
- import { withJournalWarnings, withToolError } from './utils.js';
13
+ import { deletionNote, withJournalWarnings, withToolError } from './utils.js';
14
14
  /** Version token of a page body as returned by the server. */
15
15
  function pageVersion(page) {
16
16
  return journalVersion(page?.text?.content ?? '');
@@ -219,10 +219,13 @@ export async function handleDeleteJournalEntry(args, foundryClient) {
219
219
  return withToolError('delete journal entry', async () => {
220
220
  const target = foundryClient.getJournal(journalId);
221
221
  const name = target?.name ?? journalId;
222
- await foundryClient.deleteJournalEntry(journalId);
222
+ const note = await foundryClient.deleteJournalEntry(journalId);
223
223
  return withJournalWarnings(foundryClient, {
224
224
  content: [
225
- { type: 'text', text: `🗑️ **Journal Entry Deleted**\n**Entry:** ${name} (${journalId})` },
225
+ {
226
+ type: 'text',
227
+ text: `🗑️ **Journal Entry Deleted**\n**Entry:** ${name} (${journalId})${deletionNote(note)}`,
228
+ },
226
229
  ],
227
230
  });
228
231
  });
@@ -6,7 +6,7 @@
6
6
  * FOUNDRY_WRITE_ENABLED.
7
7
  */
8
8
  import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
9
- import { withToolError } from './utils.js';
9
+ import { deletionNote, withToolError } from './utils.js';
10
10
  /**
11
11
  * Handles listing the world's roll tables.
12
12
  */
@@ -83,12 +83,12 @@ export async function handleDeleteRollTable(args, foundryClient) {
83
83
  throw new McpError(ErrorCode.InvalidParams, 'tableId is required and must be a string');
84
84
  }
85
85
  return withToolError('delete roll table', async () => {
86
- await foundryClient.deleteRollTable(tableId);
86
+ const note = await foundryClient.deleteRollTable(tableId);
87
87
  return {
88
88
  content: [
89
89
  {
90
90
  type: 'text',
91
- text: `🗑️ **Roll Table Deleted**\n**ID:** ${tableId}`,
91
+ text: `🗑️ **Roll Table Deleted**\n**ID:** ${tableId}${deletionNote(note)}`,
92
92
  },
93
93
  ],
94
94
  };
@@ -6,7 +6,7 @@
6
6
  */
7
7
  import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
8
8
  import { resolveSceneId } from './scenes.js';
9
- import { withToolError } from './utils.js';
9
+ import { deletionNote, withToolError } from './utils.js';
10
10
  /**
11
11
  * Handles creating a new Scene document from a background image on disk.
12
12
  */
@@ -66,9 +66,14 @@ export async function handleDeleteScene(args, foundryClient) {
66
66
  return withToolError('delete scene', async () => {
67
67
  const target = foundryClient.getScenes().find((s) => s._id === sceneId);
68
68
  const name = target?.name ?? sceneId;
69
- await foundryClient.deleteScene(sceneId);
69
+ const note = await foundryClient.deleteScene(sceneId);
70
70
  return {
71
- content: [{ type: 'text', text: `🗑️ **Scene Deleted**\n**Scene:** ${name} (${sceneId})` }],
71
+ content: [
72
+ {
73
+ type: 'text',
74
+ text: `🗑️ **Scene Deleted**\n**Scene:** ${name} (${sceneId})${deletionNote(note)}`,
75
+ },
76
+ ],
72
77
  };
73
78
  });
74
79
  }
@@ -4,6 +4,7 @@
4
4
  * Handles scene information retrieval and management.
5
5
  */
6
6
  import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
7
+ import { readSceneLighting } from '../../foundry/scene-lighting.js';
7
8
  import { withToolError } from './utils.js';
8
9
  /**
9
10
  * Handles scene information requests
@@ -12,6 +13,10 @@ export async function handleGetSceneInfo(args, foundryClient) {
12
13
  const { sceneId } = args;
13
14
  return withToolError('get scene info', async () => {
14
15
  const scene = await foundryClient.getCurrentScene(sceneId);
16
+ // The REST API module answers with the raw document, which keeps them under `environment`.
17
+ const { darkness, globalLight } = readSceneLighting(scene);
18
+ const lightLabel = globalLight === undefined ? 'Unknown' : globalLight ? 'Enabled' : 'Disabled';
19
+ const darknessLabel = darkness === undefined ? 'Unknown' : `${Math.round(darkness * 100)}%`;
15
20
  return {
16
21
  content: [
17
22
  {
@@ -24,8 +29,8 @@ export async function handleGetSceneInfo(args, foundryClient) {
24
29
  **Dimensions:** ${scene.width} x ${scene.height} pixels
25
30
  **Padding:** ${scene.padding * 100}%
26
31
  **Grid:** ${scene.grid ? `${scene.grid.size}px, distance ${scene.grid.distance}${scene.grid.units ? ` ${scene.grid.units}` : ''}` : 'Unknown'}
27
- **Global Light:** ${scene.globalLight ? 'Enabled' : 'Disabled'}
28
- **Darkness Level:** ${scene.darkness * 100}%
32
+ **Global Light:** ${lightLabel}
33
+ **Darkness Level:** ${darknessLabel}
29
34
 
30
35
  **Description:** ${scene.description || 'No description available.'}`,
31
36
  },
@@ -22,6 +22,13 @@ export function withJournalWarnings(foundryClient, response) {
22
22
  ],
23
23
  };
24
24
  }
25
+ /**
26
+ * Ends a deletion's response with the client's note when only a re-read
27
+ * confirmed the deletion (see `FoundryClient.deleteScene` and the like).
28
+ */
29
+ export function deletionNote(note) {
30
+ return note ? `\n\n⚠️ ${note}` : '';
31
+ }
25
32
  /**
26
33
  * Wraps an async handler function with standard error logging and McpError conversion.
27
34
  *
@@ -2,7 +2,7 @@
2
2
  * @fileoverview World document tool handlers (folders, macros, playlists).
3
3
  */
4
4
  import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
5
- import { withToolError } from './utils.js';
5
+ import { deletionNote, withToolError } from './utils.js';
6
6
  // ============================================================================
7
7
  // Folder handlers
8
8
  // ============================================================================
@@ -98,12 +98,12 @@ export async function handleDeleteMacro(args, foundryClient) {
98
98
  throw new McpError(ErrorCode.InvalidParams, 'macroId is required and must be a string');
99
99
  }
100
100
  return withToolError('delete macro', async () => {
101
- await foundryClient.deleteMacro(macroId);
101
+ const note = await foundryClient.deleteMacro(macroId);
102
102
  return {
103
103
  content: [
104
104
  {
105
105
  type: 'text',
106
- text: `🗑️ **Macro Deleted**\n**ID:** ${macroId}`,
106
+ text: `🗑️ **Macro Deleted**\n**ID:** ${macroId}${deletionNote(note)}`,
107
107
  },
108
108
  ],
109
109
  };
@@ -181,12 +181,12 @@ export async function handleDeletePlaylist(args, foundryClient) {
181
181
  throw new McpError(ErrorCode.InvalidParams, 'playlistId is required and must be a string');
182
182
  }
183
183
  return withToolError('delete playlist', async () => {
184
- await foundryClient.deletePlaylist(playlistId);
184
+ const note = await foundryClient.deletePlaylist(playlistId);
185
185
  return {
186
186
  content: [
187
187
  {
188
188
  type: 'text',
189
- text: `🗑️ **Playlist Deleted**\n**ID:** ${playlistId}`,
189
+ text: `🗑️ **Playlist Deleted**\n**ID:** ${playlistId}${deletionNote(note)}`,
190
190
  },
191
191
  ],
192
192
  };
@@ -6,8 +6,14 @@
6
6
  * client's SDK then builds its own `McpError`, which adds the prefix a second
7
7
  * time (G33ks/foundryvtt-mcp#15). The message
8
8
  * on the wire must therefore be the bare text.
9
+ *
10
+ * A failed tool call is not a JSON-RPC error but a result with
11
+ * `isError: true`, so the model reads why it failed (MCP specification,
12
+ * "Error Handling" of tools). No client adds a prefix to a result: the text
13
+ * carries the one prefix itself. An unknown tool and a failed resource read
14
+ * (`resources/read` has no `isError`) stay JSON-RPC errors.
9
15
  */
10
- import { McpError } from '@modelcontextprotocol/sdk/types.js';
16
+ import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
11
17
  /** McpError prefixes its message with "MCP error <code>: "; this is the text without it. */
12
18
  export function bareMessage(error) {
13
19
  return error.message.replace(/^MCP error -?\d+: /, '');
@@ -28,6 +34,24 @@ export class WireError extends Error {
28
34
  this.data = data;
29
35
  }
30
36
  }
37
+ /**
38
+ * A failed tool call as the client gets it: an `isError` result whose text
39
+ * is "MCP error <code>: <message>", with the McpError's code, or
40
+ * InternalError for any other error. An unknown tool is thrown again as a
41
+ * {@link WireError}, to stay a JSON-RPC error.
42
+ */
43
+ export function toolErrorResult(error) {
44
+ if (error instanceof McpError && error.code === ErrorCode.MethodNotFound) {
45
+ throw new WireError(error.code, bareMessage(error), error.data);
46
+ }
47
+ const code = error instanceof McpError ? error.code : ErrorCode.InternalError;
48
+ const message = error instanceof McpError
49
+ ? bareMessage(error)
50
+ : error instanceof Error
51
+ ? error.message
52
+ : String(error);
53
+ return { isError: true, content: [{ type: 'text', text: `MCP error ${code}: ${message}` }] };
54
+ }
31
55
  /**
32
56
  * Runs a request handler; an `McpError` it throws leaves with its bare
33
57
  * message, its code and its data, so the client shows one prefix. Any other
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@g33ks/foundryvtt-mcp",
3
- "version": "2.2.1",
3
+ "version": "3.0.1",
4
4
  "description": "Model Context Protocol server for FoundryVTT integration",
5
5
  "bin": {
6
6
  "foundryvtt-mcp": "dist/index.js"
@@ -13,6 +13,7 @@
13
13
  "smoke": "node scripts/smoke-test.js",
14
14
  "smoke:dotenv": "node scripts/smoke-dotenv.js",
15
15
  "smoke:pack": "node scripts/smoke-pack.js",
16
+ "docs:tools": "node scripts/generate-tools-doc.js",
16
17
  "stress:shared": "node scripts/stress-shared.js",
17
18
  "check:bridge-security": "node scripts/check-bridge-security.js",
18
19
  "bridge:package": "node scripts/package-bridge.js",