@g33ks/foundryvtt-mcp 2.1.0 → 2.2.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.
@@ -13,6 +13,13 @@
13
13
  * session. Foundry itself enforces the GM/owner permission (ADR-010).
14
14
  */
15
15
  const WRITE_GATE = 'WRITE: mutates the live world. Requires FOUNDRY_WRITE_ENABLED=true (default false) and an active Socket.IO connection, and is refused otherwise; Foundry additionally enforces GM/owner permission on the document.';
16
+ /**
17
+ * Write-safety clause for the tools the companion module carries out. They
18
+ * never use the Socket.IO connection, so it is not a condition; the module
19
+ * runs in a GM client. Enforced by `assertWritesEnabled()`
20
+ * (`src/tools/handlers/module-bridge.ts`).
21
+ */
22
+ const MODULE_WRITE_GATE = 'WRITE: changes the live world. Requires FOUNDRY_WRITE_ENABLED=true (default false) and the companion module, and is refused otherwise; FoundryVTT additionally enforces the GM permission.';
16
23
  /**
17
24
  * Extra clause for destructive tools (data removal that this server cannot undo).
18
25
  */
@@ -81,30 +88,46 @@ export const actorTools = [
81
88
  },
82
89
  {
83
90
  name: 'get_actor_details',
84
- description: 'Get details for one actor by id: type, level, current/max HP, AC and ability scores; no biography or description text is returned (the description line always reads "No description available."). Use when: you have an actorId and need its current HP or ability scores - notably as the read-before-write step for update_actor_attributes. Do not use when: you only have a name - run search_actors first; or you need the ids of items the actor owns, which this tool does not return (no tool in this server lists owned-item ids - ask the user for the itemId).',
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.',
85
92
  inputSchema: {
86
93
  type: 'object',
87
94
  properties: {
88
95
  actorId: {
89
96
  type: 'string',
90
- description: 'The ID of the actor to retrieve',
97
+ description: 'The ID of the actor to retrieve (omit when giving sceneId + tokenId)',
98
+ },
99
+ sceneId: {
100
+ type: 'string',
101
+ description: 'Scene id of the token, required together with tokenId',
102
+ },
103
+ tokenId: {
104
+ type: 'string',
105
+ description: "Token id: reads that token's own actor (base actor and the token's changes merged, for an unlinked token) instead of actorId",
91
106
  },
92
107
  },
93
- required: ['actorId'],
108
+ required: [],
94
109
  },
95
110
  },
96
111
  {
97
112
  name: 'get_actor_inventory',
98
- description: "List an actor's owned items (equipment, spells, features) with full system data per item, unlike get_actor_details which only reports the actor's own top-level stats. Use when: checking what a character or NPC carries or knows before an attack, spell, or trade. Do not use when: you only need the actor's HP/AC/abilities - use get_actor_details.",
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.",
99
114
  inputSchema: {
100
115
  type: 'object',
101
116
  properties: {
102
117
  actorId: {
103
118
  type: 'string',
104
- description: 'The ID of the actor whose inventory to list',
119
+ description: 'The ID of the actor whose inventory to list (omit when giving sceneId + tokenId)',
120
+ },
121
+ sceneId: {
122
+ type: 'string',
123
+ description: 'Scene id of the token, required together with tokenId',
124
+ },
125
+ tokenId: {
126
+ type: 'string',
127
+ description: "Token id: lists the items of that token's own actor (base actor and the token's changes merged, for an unlinked token) instead of actorId",
105
128
  },
106
129
  },
107
- required: ['actorId'],
130
+ required: [],
108
131
  },
109
132
  },
110
133
  ];
@@ -117,14 +140,22 @@ export const actorTools = [
117
140
  export const actorMutationTools = [
118
141
  {
119
142
  name: 'update_actor_attributes',
120
- description: 'Update fields on an actor\'s system data. Patch keys are dot-paths into actor.system (e.g. "attributes.hp.value", "attributes.hp.temp", "currency.gp", "resources.primary.value", "spells.spell1.value", "attributes.exhaustion") and values are absolute target values, never relative deltas. Validates HP <= max + temp, spell slots <= max, and exhaustion within 0-10 (2024) or 0-6 (2014), and returns the post-update value for every patched path. Use when: applying damage or healing, spending a spell slot or resource, or adjusting currency on a known actorId. Do not use when: changing an item the actor owns (use update_actor_item) or only reading current values (use get_actor_details). ' +
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). ' +
121
144
  WRITE_GATE,
122
145
  inputSchema: {
123
146
  type: 'object',
124
147
  properties: {
125
148
  actorId: {
126
149
  type: 'string',
127
- description: 'The ID of the actor to update',
150
+ description: 'The ID of the actor to update (omit when giving sceneId + tokenId)',
151
+ },
152
+ sceneId: {
153
+ type: 'string',
154
+ description: 'Scene id of the token to update, required together with tokenId',
155
+ },
156
+ tokenId: {
157
+ type: 'string',
158
+ description: "Token id: updates that token's own actor (its delta, for an unlinked token) instead of actorId",
128
159
  },
129
160
  patch: {
130
161
  type: 'object',
@@ -135,7 +166,7 @@ export const actorMutationTools = [
135
166
  },
136
167
  },
137
168
  },
138
- required: ['actorId', 'patch'],
169
+ required: ['patch'],
139
170
  },
140
171
  },
141
172
  {
@@ -161,6 +192,10 @@ export const actorMutationTools = [
161
192
  type: 'string',
162
193
  description: 'Optional Folder document id to file the actor under',
163
194
  },
195
+ flags: {
196
+ type: 'object',
197
+ description: 'Optional module flags for actor.flags, keyed by module id, e.g. {"my-module": {"key": "value"}} for data a module reads from the new actor',
198
+ },
164
199
  },
165
200
  required: ['name', 'type'],
166
201
  },
@@ -331,14 +366,22 @@ export const compendiumTools = [
331
366
  export const itemMutationTools = [
332
367
  {
333
368
  name: 'create_actor_item',
334
- description: 'Create an item on an actor from an inline item document (type, name, system) or by referencing a compendium pack entry (compendium sources require the companion Foundry module). Use when: adding a new weapon, spell, feature, or piece of equipment to a known actorId. Do not use when: editing an item the actor already owns - use update_actor_item. Replacing an item is not atomic: create the replacement first and delete the old one second. Canonical target: D&D 5e v4+ activity schema. ' +
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. ' +
335
370
  WRITE_GATE,
336
371
  inputSchema: {
337
372
  type: 'object',
338
373
  properties: {
339
374
  actorId: {
340
375
  type: 'string',
341
- description: 'The ID of the actor to add the item to',
376
+ description: 'The ID of the actor to add the item to (omit when giving sceneId + tokenId)',
377
+ },
378
+ sceneId: {
379
+ type: 'string',
380
+ description: 'Scene id of the token, required together with tokenId',
381
+ },
382
+ tokenId: {
383
+ type: 'string',
384
+ description: "Token id: adds the item to that token's own actor instead of actorId (only that token, for an unlinked token)",
342
385
  },
343
386
  source: {
344
387
  type: 'object',
@@ -365,19 +408,27 @@ export const itemMutationTools = [
365
408
  required: ['type'],
366
409
  },
367
410
  },
368
- required: ['actorId', 'source'],
411
+ required: ['source'],
369
412
  },
370
413
  },
371
414
  {
372
415
  name: 'update_actor_item',
373
- description: "Apply a JSON merge patch to an item's system data on an actor: nested paths such as activities.{id}.consumption.targets are supported, values are absolute (arrays replace, null deletes). Use when: changing fields on an item the actor already owns, given actorId + itemId. Do not use when: adding a new item (create_actor_item) or removing one (delete_actor_item). Canonical target: D&D 5e v4+ activity schema. " +
416
+ description: "Apply a JSON merge patch to an item's system data on an actor: nested paths such as activities.{id}.consumption.targets are supported, values are absolute (arrays replace, null deletes). Use when: changing fields on an item the actor already owns, given actorId + itemId. For one token on a map, give sceneId + tokenId: on an unlinked token only that token changes, even for an item it inherits from its base actor. Do not use when: adding a new item (create_actor_item) or removing one (delete_actor_item). Canonical target: D&D 5e v4+ activity schema. " +
374
417
  WRITE_GATE,
375
418
  inputSchema: {
376
419
  type: 'object',
377
420
  properties: {
378
421
  actorId: {
379
422
  type: 'string',
380
- description: 'The ID of the actor that owns the item',
423
+ description: 'The ID of the actor that owns the item (omit when giving sceneId + tokenId)',
424
+ },
425
+ sceneId: {
426
+ type: 'string',
427
+ description: 'Scene id of the token, required together with tokenId',
428
+ },
429
+ tokenId: {
430
+ type: 'string',
431
+ description: "Token id: changes the item on that token's own actor instead of actorId (only that token, for an unlinked token)",
381
432
  },
382
433
  itemId: {
383
434
  type: 'string',
@@ -388,12 +439,12 @@ export const itemMutationTools = [
388
439
  description: 'JSON merge patch applied to item.system; nested paths supported (e.g. activities.{id}.consumption.targets)',
389
440
  },
390
441
  },
391
- required: ['actorId', 'itemId', 'patch'],
442
+ required: ['itemId', 'patch'],
392
443
  },
393
444
  },
394
445
  {
395
446
  name: 'delete_actor_item',
396
- description: "Permanently remove an item owned by an actor. Use when: the user explicitly asks to delete or discard a specific owned item, and has given you the itemId - no tool in this server lists owned-item ids, so never guess one. Do not use when: only the item's data needs to change - use update_actor_item. In a replacement or migration flow, run create_actor_item first and this second: the two calls are not atomic, and failing after the delete loses the item. Echo the actorId and itemId back to the user and get their confirmation before calling. " +
447
+ description: "Permanently remove an item owned by an actor. Use when: the user explicitly asks to delete or discard a specific owned item, and you have its itemId from the user or from get_actor_inventory (which lists the ids of the items an actor owns) - never guess one. For one token on a map, give sceneId + tokenId: an unlinked token loses the item on that token only, even one it inherits from its base actor. Do not use when: only the item's data needs to change - use update_actor_item. In a replacement or migration flow, run create_actor_item first and this second: the two calls are not atomic, and failing after the delete loses the item. Echo the actorId and itemId back to the user and get their confirmation before calling. " +
397
448
  CONFIRM_FIRST +
398
449
  ' ' +
399
450
  WRITE_GATE,
@@ -402,14 +453,22 @@ export const itemMutationTools = [
402
453
  properties: {
403
454
  actorId: {
404
455
  type: 'string',
405
- description: 'The ID of the actor that owns the item',
456
+ description: 'The ID of the actor that owns the item (omit when giving sceneId + tokenId)',
457
+ },
458
+ sceneId: {
459
+ type: 'string',
460
+ description: 'Scene id of the token, required together with tokenId',
461
+ },
462
+ tokenId: {
463
+ type: 'string',
464
+ description: "Token id: deletes the item from that token's own actor instead of actorId (only that token, for an unlinked token)",
406
465
  },
407
466
  itemId: {
408
467
  type: 'string',
409
468
  description: 'The ID of the item to delete',
410
469
  },
411
470
  },
412
- required: ['actorId', 'itemId'],
471
+ required: ['itemId'],
413
472
  },
414
473
  },
415
474
  ];
@@ -1532,7 +1591,7 @@ export const combatMutationTools = [
1532
1591
  },
1533
1592
  {
1534
1593
  name: 'start_combat',
1535
- description: 'Start a new combat encounter, seeding combatants from tokens: pass explicit tokenIds, or omit them to seed every token on the scene. Defaults to the active scene when sceneId is omitted. Use when: a fight begins and no combat is running. Do not use when: a combat is already active - check get_combat_state first, since this always creates an additional encounter. ' +
1594
+ description: 'Start a new combat encounter, seeding combatants from tokens: pass explicit tokenIds, or omit them to seed every token on the scene. Defaults to the active scene when sceneId is omitted. The encounter begins at round 1, turn 0, as when the GM clicks Begin Combat in Foundry. Use when: a fight begins and no combat is running. Do not use when: a combat is already active - check get_combat_state first, since this always creates an additional encounter. ' +
1536
1595
  WRITE_GATE,
1537
1596
  inputSchema: {
1538
1597
  type: 'object',
@@ -1606,7 +1665,7 @@ export const tokenMutationTools = [
1606
1665
  },
1607
1666
  {
1608
1667
  name: 'apply_status_effect',
1609
- description: 'Apply or remove a status condition (e.g. "prone", "stunned") on a token\'s actor. Set active=false to remove. Matches by status id, so re-applying or clearing-when-absent is a no-op. Use when: a condition is gained or lost. Do not use when: changing numeric state such as HP or exhaustion - use update_actor_attributes. ' +
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. ' +
1610
1669
  WRITE_GATE +
1611
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.',
1612
1671
  inputSchema: {
@@ -1629,6 +1688,10 @@ export const tokenMutationTools = [
1629
1688
  type: 'string',
1630
1689
  description: 'Optional Scene ID to scope the token lookup',
1631
1690
  },
1691
+ createOptions: {
1692
+ type: 'object',
1693
+ description: "Optional creation options the game system reads when a status is created (at most 10 keys, 1 KiB of JSON; not the core's own options such as parent or keepId). Only with active=true, through the companion module 0.6.0 or later",
1694
+ },
1632
1695
  },
1633
1696
  required: ['tokenId', 'statusId'],
1634
1697
  },
@@ -2142,7 +2205,7 @@ export const worldTools = [
2142
2205
  },
2143
2206
  {
2144
2207
  name: 'refresh_world_data',
2145
- description: 'Force a re-fetch of the cached world data from the FoundryVTT server. Reads are normally served from a cache that follows live document changes for as long as the connection holds, so this is rarely needed. When the connection drops and comes back with the same session, the world is reloaded on its own in the background. Use when: get_health_status still flags the cache as stale (that reload failed, or changes arrived too fast to replay); or a read still looks stale after an out-of-band change - notably edits to unlinked (synthetic) token actors, which the live update feed does not cover. Refreshes the cache only; it does not modify the world.',
2208
+ description: 'Force a re-fetch of the cached world data from the FoundryVTT server. Reads are normally served from a cache that follows live document changes for as long as the connection holds, so this is rarely needed. When the connection drops and comes back with the same session, the world is reloaded on its own in the background. Use when: get_health_status still flags the cache as stale (that reload failed, or changes arrived too fast to replay); or a read still looks stale after an out-of-band change. Refreshes the cache only; it does not modify the world.',
2146
2209
  inputSchema: {
2147
2210
  type: 'object',
2148
2211
  properties: {},
@@ -2520,7 +2583,7 @@ export const moduleBridgeTools = [
2520
2583
  },
2521
2584
  {
2522
2585
  name: 'get_document_schema',
2523
- description: "Introspect the connected game system's real DataModel schema for an Actor or Item type - the exact field names, types, string-enum choices, and default values that type accepts, read live from the running system (works for any installed system - Cyberpunk RED, D&D 5e, PF2e, etc - not a hardcoded list). Returns a nested JSON tree: each field has `type` (Number/String/Boolean/Schema/Array/…), `required`, `choices` for constrained strings, and `initial` for its default value; `fields` holds nested sub-fields, `element` describes an array's entries. Requires the companion Foundry module to be installed, enabled, and connected - fails with a clear error otherwise. Use when: building a `system` payload for create_world_actor/create_actor_item/create_full_actor and you do not already know that type's exact field names - call this once per type, then reuse the answer. Do not use when: you already know the schema from a prior call in this session - re-querying wastes a round trip; the schema does not change during a session.",
2586
+ description: "Introspect the connected game system's real DataModel schema for an Actor or Item type - the exact field names, types, string-enum choices, and default values that type accepts, read live from the running system. Works with any installed game system. Returns a nested JSON tree: each field has `type` (Number/String/Boolean/Schema/Array/…), `required`, `choices` for constrained strings, and `initial` for its default value; `fields` holds nested sub-fields, `element` describes an array's entries; `persisted: false` marks a computed field that is never stored (writing it has no effect), and `min`, `max`, `integer` and `positive` bound numbers. A type the system declares only by template.json has no schema: the answer then lists its default values, with types inferred from them and marked `inferred: true` (module 0.6.0 or later). Requires the companion Foundry module to be installed, enabled, and connected - fails with a clear error otherwise. Use when: building a `system` payload for create_world_actor/create_actor_item/create_full_actor and you do not already know that type's exact field names - call this once per type, then reuse the answer. Do not use when: you already know the schema from a prior call in this session - re-querying wastes a round trip; the schema does not change during a session.",
2524
2587
  inputSchema: {
2525
2588
  type: 'object',
2526
2589
  properties: {
@@ -2562,7 +2625,8 @@ export const moduleBridgeTools = [
2562
2625
  },
2563
2626
  {
2564
2627
  name: 'roll_and_post',
2565
- description: 'Evaluate a dice formula using Foundry\'s native Roll engine and post it directly to chat as a rendered, clickable roll card. Supports full Foundry dice syntax (e.g. "4d6kh3", "1d20r1", exploding dice) that the local parser rejects. Requires the companion Foundry module.',
2628
+ description: 'Evaluate a dice formula using Foundry\'s native Roll engine and post it directly to chat as a rendered, clickable roll card. Supports full Foundry dice syntax (e.g. "4d6kh3", "1d20r1", exploding dice) that the local parser rejects. Requires the companion Foundry module. ' +
2629
+ MODULE_WRITE_GATE,
2566
2630
  inputSchema: {
2567
2631
  type: 'object',
2568
2632
  properties: {
@@ -2623,7 +2687,7 @@ export const moduleBridgeTools = [
2623
2687
  {
2624
2688
  name: 'set_target',
2625
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. " +
2626
- WRITE_GATE,
2690
+ MODULE_WRITE_GATE,
2627
2691
  inputSchema: {
2628
2692
  type: 'object',
2629
2693
  properties: {
@@ -2646,6 +2710,36 @@ export const moduleBridgeTools = [
2646
2710
  required: ['tokenIds'],
2647
2711
  },
2648
2712
  },
2713
+ {
2714
+ name: 'get_actor_stats',
2715
+ description: "Read the actor's prepared system data, including values the system computes and does not store, as compact JSON. The cached world behind get_actor_details only holds stored data. Give actorId for a world actor, or sceneId + tokenId for one token on a map: a linked token reads its world actor, an unlinked token its own copy (base actor plus the token's changes). paths narrows the answer to some fields; an answer over maxBytes is refused with the size of each top-level key, so you can choose paths. Requires the companion Foundry module 0.6.0 or later. Use when: you need a value the game system derives (a maximum, a total, a modifier) or the current state of one token. Do not use when: you need items, effects or the stored source only - use get_actor_inventory, list_actor_effects or get_actor_details.",
2716
+ inputSchema: {
2717
+ type: 'object',
2718
+ properties: {
2719
+ actorId: {
2720
+ type: 'string',
2721
+ description: "The world actor's id. With sceneId + tokenId, optional: it must be the token's actor",
2722
+ },
2723
+ sceneId: {
2724
+ type: 'string',
2725
+ description: 'Scene of the token to read, together with tokenId',
2726
+ },
2727
+ tokenId: {
2728
+ type: 'string',
2729
+ description: 'Token to read (an unlinked token has its own data), together with sceneId',
2730
+ },
2731
+ paths: {
2732
+ type: 'array',
2733
+ items: { type: 'string' },
2734
+ description: 'Optional dot paths into system (a "system." prefix is accepted), at most 50. The answer then holds "values" keyed by path and the "missing" paths instead of the whole "system"',
2735
+ },
2736
+ maxBytes: {
2737
+ type: 'number',
2738
+ description: 'Largest answer accepted, in bytes of compact JSON (default 32768, at most 65536)',
2739
+ },
2740
+ },
2741
+ },
2742
+ },
2649
2743
  {
2650
2744
  name: 'get_targets',
2651
2745
  description: 'List the current target selections of all connected users on the active canvas. Returns each user with the tokens they currently have targeted. Requires the companion Foundry module. Use when: checking who players are aiming at or focusing on.',
@@ -2657,7 +2751,7 @@ export const moduleBridgeTools = [
2657
2751
  {
2658
2752
  name: 'ping_canvas',
2659
2753
  description: "Emit an animated canvas ping at specific pixel coordinates on the active scene's view, drawing every connected player's camera and attention to that exact location. Requires the companion Foundry module. Use when: pointing out a trap, landmark, or hidden detail on the map. " +
2660
- WRITE_GATE,
2754
+ MODULE_WRITE_GATE,
2661
2755
  inputSchema: {
2662
2756
  type: 'object',
2663
2757
  properties: {
@@ -2674,7 +2768,7 @@ export const moduleBridgeTools = [
2674
2768
  {
2675
2769
  name: 'set_pause',
2676
2770
  description: 'Pause or unpause the game clock. When paused, token movement and real-time combat timers freeze for players. Requires the companion Foundry module. Use when: stepping away, narrating a long cutscene, or resolving a complex rules question. ' +
2677
- WRITE_GATE,
2771
+ MODULE_WRITE_GATE,
2678
2772
  inputSchema: {
2679
2773
  type: 'object',
2680
2774
  properties: {
@@ -2687,18 +2781,18 @@ export const moduleBridgeTools = [
2687
2781
  },
2688
2782
  {
2689
2783
  name: 'upload_asset',
2690
- description: "Upload a file (image, audio, etc.) into FoundryVTT's Data storage via the GM browser's FilePicker, returning the Foundry-relative path to feed directly into create_scene (backgroundSrc), create_tile (src), or create_sound (path). Provide exactly one of contentBase64 (base64-encoded file content) or sourcePath (an absolute path readable by this MCP server, which base64-encodes it server-side). Rejects payloads over 8 MiB. Requires the companion Foundry module. Use when: adding new map art, tokens, or audio the world does not already have. " +
2691
- WRITE_GATE,
2784
+ description: "Upload a file (image, audio, etc.) into FoundryVTT's Data storage via the GM browser's FilePicker, returning the Foundry-relative path to feed directly into create_scene (backgroundSrc), create_tile (src), or create_sound (path). Provide exactly one of contentBase64 (base64-encoded file content) or sourcePath (a file inside the folder named by FOUNDRY_UPLOAD_SOURCE_DIR, which the server reads; refused when that setting is unset). Only media files: .png, .jpg, .jpeg, .webp, .gif, .mp3, .ogg, .wav, .m4a, .webm, .mp4, and filename must have the source file's extension. targetDir is a folder relative to the Data storage (no \"..\", no absolute path) and filename a plain file name. Rejects files over 8 MiB. Requires the companion Foundry module. Use when: adding new map art, tokens, or audio the world does not already have. " +
2785
+ MODULE_WRITE_GATE,
2692
2786
  inputSchema: {
2693
2787
  type: 'object',
2694
2788
  properties: {
2695
2789
  targetDir: {
2696
2790
  type: 'string',
2697
- description: 'Data-relative destination folder (e.g. "assets/uploads")',
2791
+ description: 'Destination folder relative to the Data storage (e.g. "assets/uploads"); no ".." and no absolute path',
2698
2792
  },
2699
2793
  filename: {
2700
2794
  type: 'string',
2701
- description: 'Destination filename, including extension',
2795
+ description: 'Destination file name with a media extension (e.g. "map.png"), no folder',
2702
2796
  },
2703
2797
  contentBase64: {
2704
2798
  type: 'string',
@@ -2706,11 +2800,11 @@ export const moduleBridgeTools = [
2706
2800
  },
2707
2801
  sourcePath: {
2708
2802
  type: 'string',
2709
- description: 'Absolute filesystem path readable by this MCP server. Mutually exclusive with contentBase64.',
2803
+ description: 'Path of a file inside the FOUNDRY_UPLOAD_SOURCE_DIR folder (refused when that setting is unset). Mutually exclusive with contentBase64.',
2710
2804
  },
2711
2805
  mimeType: {
2712
2806
  type: 'string',
2713
- description: 'Optional MIME type override; inferred from the filename extension if omitted',
2807
+ description: 'Optional MIME type; must be the one of the filename extension, which is used when omitted',
2714
2808
  },
2715
2809
  },
2716
2810
  required: ['targetDir', 'filename'],
@@ -2728,7 +2822,7 @@ export const moduleBridgeTools = [
2728
2822
  export const effectTools = [
2729
2823
  {
2730
2824
  name: 'create_actor_effect',
2731
- description: "Create a general-purpose ActiveEffect on an actor with mechanical changes (attribute modifiers) and/or a duration - not just a status toggle (use apply_status_effect for that). Give actorId alone for a world-linked actor, or actorId plus the sceneId+tokenId pair together for an unlinked token's synthetic actor. changes[].mode is a named FoundryVTT ACTIVE_EFFECT_MODES combine rule (add/multiply/override/upgrade/downgrade/custom), not a raw number. Use when: applying a spell buff, a debuff, or an equipment bonus with a real mechanical effect. Do not use when: toggling a simple named condition (prone, stunned) - use apply_status_effect. " +
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. ' +
2732
2826
  WRITE_GATE,
2733
2827
  inputSchema: {
2734
2828
  type: 'object',
@@ -2795,7 +2889,7 @@ export const effectTools = [
2795
2889
  },
2796
2890
  {
2797
2891
  name: 'update_actor_effect',
2798
- description: "Update fields on an existing ActiveEffect - every field replaces the corresponding one on the existing document, omitted fields are left as they are. Same actorId/sceneId+tokenId resolution as create_actor_effect. Use when: a buff's remaining duration changes, or its magnitude scales. Do not use when: the effect should end - use delete_actor_effect. " +
2892
+ description: "Update fields on an existing ActiveEffect - every field replaces the corresponding one on the existing document, omitted fields are left as they are. Same actorId/sceneId+tokenId resolution as create_actor_effect: on an unlinked token only that token changes, even for an effect it inherits from its base actor. Use when: a buff's remaining duration changes, or its magnitude scales. Do not use when: the effect should end - use delete_actor_effect. " +
2799
2893
  WRITE_GATE,
2800
2894
  inputSchema: {
2801
2895
  type: 'object',
@@ -2853,7 +2947,7 @@ export const effectTools = [
2853
2947
  },
2854
2948
  {
2855
2949
  name: 'delete_actor_effect',
2856
- description: 'Delete an ActiveEffect from an actor. Same actorId/sceneId+tokenId resolution as create_actor_effect. ' +
2950
+ description: 'Delete an ActiveEffect from an actor. Same actorId/sceneId+tokenId resolution as create_actor_effect: on an unlinked token only that token loses the effect, even one it inherits from its base actor. ' +
2857
2951
  CONFIRM_FIRST +
2858
2952
  ' ' +
2859
2953
  WRITE_GATE,
@@ -2876,13 +2970,24 @@ export const effectTools = [
2876
2970
  },
2877
2971
  {
2878
2972
  name: 'list_actor_effects',
2879
- description: "List the ActiveEffects on a world-linked actor, read from the cached world snapshot (no socket round trip). Only reaches a top-level Actor document - an unlinked token's synthetic per-token actor is not independently listable this way. Use when: checking what buffs/debuffs are currently active on an actor before applying another.",
2973
+ description: "List the ActiveEffects on an actor, read from the cached world snapshot (no socket round trip). Give actorId for a world actor, or sceneId + tokenId for one token: an unlinked token lists its own effects (those it inherits from its base actor and its own, without the ones removed from it), a linked token its world actor's. Use when: checking what buffs/debuffs are currently active on an actor before applying another.",
2880
2974
  inputSchema: {
2881
2975
  type: 'object',
2882
2976
  properties: {
2883
- actorId: { type: 'string', description: "The actor's own document id" },
2977
+ actorId: {
2978
+ type: 'string',
2979
+ description: "The actor's own document id (omit when giving sceneId + tokenId)",
2980
+ },
2981
+ sceneId: {
2982
+ type: 'string',
2983
+ description: 'Scene id of the token, required together with tokenId',
2984
+ },
2985
+ tokenId: {
2986
+ type: 'string',
2987
+ description: "Token id: lists the effects of that token's own actor (base actor and the token's changes merged, for an unlinked token) instead of actorId",
2988
+ },
2884
2989
  },
2885
- required: ['actorId'],
2990
+ required: [],
2886
2991
  },
2887
2992
  },
2888
2993
  ];
@@ -16,9 +16,13 @@ import { withToolError } from './utils.js';
16
16
  * The post-update value of every patched path is echoed back.
17
17
  */
18
18
  export async function handleUpdateActorAttribute(args, foundryClient) {
19
- const { actorId, patch } = args;
20
- if (!actorId || typeof actorId !== 'string') {
21
- throw new McpError(ErrorCode.InvalidParams, 'actorId is required and must be a string');
19
+ const { actorId, sceneId, tokenId, patch } = args;
20
+ const byToken = typeof tokenId === 'string' && tokenId.length > 0;
21
+ if (byToken && (typeof sceneId !== 'string' || !sceneId)) {
22
+ throw new McpError(ErrorCode.InvalidParams, 'sceneId is required together with tokenId');
23
+ }
24
+ if (!byToken && (!actorId || typeof actorId !== 'string')) {
25
+ throw new McpError(ErrorCode.InvalidParams, 'actorId (or sceneId + tokenId) is required and must be a string');
22
26
  }
23
27
  if (patch === null ||
24
28
  typeof patch !== 'object' ||
@@ -27,7 +31,9 @@ export async function handleUpdateActorAttribute(args, foundryClient) {
27
31
  throw new McpError(ErrorCode.InvalidParams, 'patch is required and must be a non-empty object of dot-path attributes');
28
32
  }
29
33
  return withToolError('update actor attributes', async () => {
30
- const result = await foundryClient.updateActorAttribute(actorId, patch);
34
+ const result = byToken
35
+ ? await foundryClient.updateTokenActorAttribute(sceneId, tokenId, patch)
36
+ : await foundryClient.updateActorAttribute(actorId, patch);
31
37
  const updatedList = Object.entries(result.updatedAttributes)
32
38
  .map(([path, value]) => `- **${path}** → ${String(value)}`)
33
39
  .join('\n');
@@ -36,7 +42,7 @@ export async function handleUpdateActorAttribute(args, foundryClient) {
36
42
  {
37
43
  type: 'text',
38
44
  text: `⚔️ **Actor Attributes Updated**
39
- **Actor ID:** ${actorId}
45
+ ${byToken ? `**Token ID:** ${tokenId} (scene ${sceneId})` : `**Actor ID:** ${actorId}`}
40
46
  **Status:** ${result.success ? 'Success' : 'Failed'}
41
47
 
42
48
  **Updated attributes** (dot-paths into actor.system):
@@ -50,7 +56,7 @@ ${updatedList}`,
50
56
  * Handles creating a new top-level Actor document (NPC/character sheet).
51
57
  */
52
58
  export async function handleCreateWorldActor(args, foundryClient) {
53
- const { name, type, system, folder } = args;
59
+ const { name, type, system, folder, flags } = args;
54
60
  if (!name || typeof name !== 'string') {
55
61
  throw new McpError(ErrorCode.InvalidParams, 'name is required and must be a string');
56
62
  }
@@ -58,7 +64,7 @@ export async function handleCreateWorldActor(args, foundryClient) {
58
64
  throw new McpError(ErrorCode.InvalidParams, 'type is required and must be a string');
59
65
  }
60
66
  return withToolError('create world actor', async () => {
61
- const actor = await foundryClient.createWorldActor(name, type, system, folder);
67
+ const actor = await foundryClient.createWorldActor(name, type, system, folder, flags);
62
68
  return {
63
69
  content: [
64
70
  {
@@ -0,0 +1,80 @@
1
+ /**
2
+ * @fileoverview Which actor an actor tool addresses: a world actor by `actorId`,
3
+ * or one token's actor by `sceneId` + `tokenId`.
4
+ *
5
+ * An unlinked token has an actor of its own (its base actor plus the token's
6
+ * delta); a linked token shares its world actor, so it addresses that actor.
7
+ */
8
+ import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
9
+ /**
10
+ * Resolves `actorId`, or `sceneId` + `tokenId` (together; an `actorId` given
11
+ * as well must be the token's actor).
12
+ *
13
+ * @param options.actorRequired - `actorId` is required even with a token
14
+ * @throws McpError when the arguments don't name one actor, or the token isn't
15
+ * in the cache or carries another actor
16
+ */
17
+ export function resolveActorTarget(args, foundryClient, options = {}) {
18
+ const { actorId, sceneId, tokenId } = args;
19
+ if (actorId !== undefined && (typeof actorId !== 'string' || !actorId)) {
20
+ throw new McpError(ErrorCode.InvalidParams, 'actorId must be a non-empty string');
21
+ }
22
+ const hasScene = sceneId !== undefined;
23
+ const hasToken = tokenId !== undefined;
24
+ if (hasScene !== hasToken) {
25
+ throw new McpError(ErrorCode.InvalidParams, 'sceneId and tokenId must be supplied together (for one token on a scene) or not at all');
26
+ }
27
+ if (actorId === undefined && (options.actorRequired || !hasToken)) {
28
+ throw new McpError(ErrorCode.InvalidParams, options.actorRequired
29
+ ? 'actorId is required and must be a string'
30
+ : 'actorId (or sceneId + tokenId) is required and must be a string');
31
+ }
32
+ if (!hasToken && actorId !== undefined) {
33
+ return { kind: 'actor', actorId };
34
+ }
35
+ if (typeof sceneId !== 'string' || !sceneId || typeof tokenId !== 'string' || !tokenId) {
36
+ throw new McpError(ErrorCode.InvalidParams, 'sceneId and tokenId must be non-empty strings');
37
+ }
38
+ let resolved;
39
+ try {
40
+ resolved = foundryClient.resolveTokenActor(tokenId, sceneId, actorId);
41
+ }
42
+ catch (error) {
43
+ throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
44
+ }
45
+ const name = resolved.token.name;
46
+ return {
47
+ kind: 'token',
48
+ actorId: resolved.actorId,
49
+ sceneId,
50
+ tokenId,
51
+ linked: resolved.linked,
52
+ ...(typeof name === 'string' && name ? { tokenName: name } : {}),
53
+ };
54
+ }
55
+ /**
56
+ * The embedded-document parent UUID for a target: `Actor.<id>` for a world
57
+ * actor or a linked token, the token's synthetic actor otherwise (which the
58
+ * client sends to the token's ActorDelta).
59
+ */
60
+ export function actorParentUuid(target) {
61
+ return isUnlinkedToken(target)
62
+ ? `Scene.${target.sceneId}.Token.${target.tokenId}.Actor.${target.actorId}`
63
+ : `Actor.${target.actorId}`;
64
+ }
65
+ /** Whether a target is an unlinked token, whose actor is its own rather than a world actor. */
66
+ export function isUnlinkedToken(target) {
67
+ return target.kind === 'token' && !target.linked;
68
+ }
69
+ /**
70
+ * A header line naming the token, for an unlinked token's actor; empty
71
+ * otherwise, so a world actor's output reads as it always has.
72
+ */
73
+ export function tokenHeaderLine(target) {
74
+ if (!isUnlinkedToken(target)) {
75
+ return '';
76
+ }
77
+ const name = target.tokenName ? `${target.tokenName} (${target.tokenId})` : target.tokenId;
78
+ return `**Token:** ${name} on scene ${target.sceneId} - unlinked: its own copy of actor ${target.actorId}\n`;
79
+ }
80
+ //# sourceMappingURL=actor-target.js.map