@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.
- package/README.md +70 -411
- package/dist/foundry/auth.js +40 -1
- package/dist/foundry/client.js +151 -24
- package/dist/foundry/scene-lighting.js +41 -0
- package/dist/mcp-server.js +12 -5
- package/dist/tools/definitions.js +32 -32
- package/dist/tools/handlers/actor-mutations.js +5 -3
- package/dist/tools/handlers/combat-mutations.js +3 -3
- package/dist/tools/handlers/journal-mutations.js +6 -3
- package/dist/tools/handlers/roll-tables.js +3 -3
- package/dist/tools/handlers/scene-mutations.js +8 -3
- package/dist/tools/handlers/scenes.js +7 -2
- package/dist/tools/handlers/utils.js +7 -0
- package/dist/tools/handlers/world-documents.js +5 -5
- package/dist/utils/mcp-errors.js +25 -1
- package/package.json +2 -1
|
@@ -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,
|
|
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
|
|
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
|
|
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,
|
|
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.
|
|
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.
|
|
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 (
|
|
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 (
|
|
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", "
|
|
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
|
|
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 (
|
|
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,
|
|
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/
|
|
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
|
|
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
|
|
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 (
|
|
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 (
|
|
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,
|
|
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
|
|
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: '
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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. "
|
|
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. "
|
|
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"
|
|
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
|
|
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. "
|
|
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
|
|
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
|
|
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.
|
|
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: [
|
|
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
|
-
{
|
|
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: [
|
|
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:** ${
|
|
28
|
-
**Darkness Level:** ${
|
|
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
|
};
|
package/dist/utils/mcp-errors.js
CHANGED
|
@@ -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": "
|
|
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",
|