@g33ks/foundryvtt-mcp 2.1.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -81,30 +81,46 @@ export const actorTools = [
81
81
  },
82
82
  {
83
83
  name: 'get_actor_details',
84
- description: 'Get details for one actor by id: type, level, current/max HP, AC and ability scores; no biography or description text is returned (the description line always reads "No description available."). Use when: you have an actorId and need its current HP or ability scores - notably as the read-before-write step for update_actor_attributes. Do not use when: you only have a name - run search_actors first; or you need the ids of items the actor owns, which this tool does not return (no tool in this server lists owned-item ids - ask the user for the itemId).',
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. 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
85
  inputSchema: {
86
86
  type: 'object',
87
87
  properties: {
88
88
  actorId: {
89
89
  type: 'string',
90
- description: 'The ID of the actor to retrieve',
90
+ description: 'The ID of the actor to retrieve (omit when giving sceneId + tokenId)',
91
+ },
92
+ sceneId: {
93
+ type: 'string',
94
+ description: 'Scene id of the token, required together with tokenId',
95
+ },
96
+ tokenId: {
97
+ type: 'string',
98
+ 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
99
  },
92
100
  },
93
- required: ['actorId'],
101
+ required: [],
94
102
  },
95
103
  },
96
104
  {
97
105
  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.",
106
+ 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
107
  inputSchema: {
100
108
  type: 'object',
101
109
  properties: {
102
110
  actorId: {
103
111
  type: 'string',
104
- description: 'The ID of the actor whose inventory to list',
112
+ description: 'The ID of the actor whose inventory to list (omit when giving sceneId + tokenId)',
113
+ },
114
+ sceneId: {
115
+ type: 'string',
116
+ description: 'Scene id of the token, required together with tokenId',
117
+ },
118
+ tokenId: {
119
+ type: 'string',
120
+ 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
121
  },
106
122
  },
107
- required: ['actorId'],
123
+ required: [],
108
124
  },
109
125
  },
110
126
  ];
@@ -117,14 +133,22 @@ export const actorTools = [
117
133
  export const actorMutationTools = [
118
134
  {
119
135
  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). ' +
136
+ 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
137
  WRITE_GATE,
122
138
  inputSchema: {
123
139
  type: 'object',
124
140
  properties: {
125
141
  actorId: {
126
142
  type: 'string',
127
- description: 'The ID of the actor to update',
143
+ description: 'The ID of the actor to update (omit when giving sceneId + tokenId)',
144
+ },
145
+ sceneId: {
146
+ type: 'string',
147
+ description: 'Scene id of the token to update, required together with tokenId',
148
+ },
149
+ tokenId: {
150
+ type: 'string',
151
+ description: "Token id: updates that token's own actor (its delta, for an unlinked token) instead of actorId",
128
152
  },
129
153
  patch: {
130
154
  type: 'object',
@@ -135,7 +159,7 @@ export const actorMutationTools = [
135
159
  },
136
160
  },
137
161
  },
138
- required: ['actorId', 'patch'],
162
+ required: ['patch'],
139
163
  },
140
164
  },
141
165
  {
@@ -161,6 +185,10 @@ export const actorMutationTools = [
161
185
  type: 'string',
162
186
  description: 'Optional Folder document id to file the actor under',
163
187
  },
188
+ flags: {
189
+ type: 'object',
190
+ 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',
191
+ },
164
192
  },
165
193
  required: ['name', 'type'],
166
194
  },
@@ -331,14 +359,22 @@ export const compendiumTools = [
331
359
  export const itemMutationTools = [
332
360
  {
333
361
  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. ' +
362
+ 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
363
  WRITE_GATE,
336
364
  inputSchema: {
337
365
  type: 'object',
338
366
  properties: {
339
367
  actorId: {
340
368
  type: 'string',
341
- description: 'The ID of the actor to add the item to',
369
+ description: 'The ID of the actor to add the item to (omit when giving sceneId + tokenId)',
370
+ },
371
+ sceneId: {
372
+ type: 'string',
373
+ description: 'Scene id of the token, required together with tokenId',
374
+ },
375
+ tokenId: {
376
+ type: 'string',
377
+ description: "Token id: adds the item to that token's own actor instead of actorId (only that token, for an unlinked token)",
342
378
  },
343
379
  source: {
344
380
  type: 'object',
@@ -365,19 +401,27 @@ export const itemMutationTools = [
365
401
  required: ['type'],
366
402
  },
367
403
  },
368
- required: ['actorId', 'source'],
404
+ required: ['source'],
369
405
  },
370
406
  },
371
407
  {
372
408
  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. " +
409
+ 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
410
  WRITE_GATE,
375
411
  inputSchema: {
376
412
  type: 'object',
377
413
  properties: {
378
414
  actorId: {
379
415
  type: 'string',
380
- description: 'The ID of the actor that owns the item',
416
+ description: 'The ID of the actor that owns the item (omit when giving sceneId + tokenId)',
417
+ },
418
+ sceneId: {
419
+ type: 'string',
420
+ description: 'Scene id of the token, required together with tokenId',
421
+ },
422
+ tokenId: {
423
+ type: 'string',
424
+ description: "Token id: changes the item on that token's own actor instead of actorId (only that token, for an unlinked token)",
381
425
  },
382
426
  itemId: {
383
427
  type: 'string',
@@ -388,12 +432,12 @@ export const itemMutationTools = [
388
432
  description: 'JSON merge patch applied to item.system; nested paths supported (e.g. activities.{id}.consumption.targets)',
389
433
  },
390
434
  },
391
- required: ['actorId', 'itemId', 'patch'],
435
+ required: ['itemId', 'patch'],
392
436
  },
393
437
  },
394
438
  {
395
439
  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. " +
440
+ 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
441
  CONFIRM_FIRST +
398
442
  ' ' +
399
443
  WRITE_GATE,
@@ -402,14 +446,22 @@ export const itemMutationTools = [
402
446
  properties: {
403
447
  actorId: {
404
448
  type: 'string',
405
- description: 'The ID of the actor that owns the item',
449
+ description: 'The ID of the actor that owns the item (omit when giving sceneId + tokenId)',
450
+ },
451
+ sceneId: {
452
+ type: 'string',
453
+ description: 'Scene id of the token, required together with tokenId',
454
+ },
455
+ tokenId: {
456
+ type: 'string',
457
+ description: "Token id: deletes the item from that token's own actor instead of actorId (only that token, for an unlinked token)",
406
458
  },
407
459
  itemId: {
408
460
  type: 'string',
409
461
  description: 'The ID of the item to delete',
410
462
  },
411
463
  },
412
- required: ['actorId', 'itemId'],
464
+ required: ['itemId'],
413
465
  },
414
466
  },
415
467
  ];
@@ -1532,7 +1584,7 @@ export const combatMutationTools = [
1532
1584
  },
1533
1585
  {
1534
1586
  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. ' +
1587
+ 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
1588
  WRITE_GATE,
1537
1589
  inputSchema: {
1538
1590
  type: 'object',
@@ -1606,7 +1658,7 @@ export const tokenMutationTools = [
1606
1658
  },
1607
1659
  {
1608
1660
  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. ' +
1661
+ 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
1662
  WRITE_GATE +
1611
1663
  ' 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
1664
  inputSchema: {
@@ -1629,6 +1681,10 @@ export const tokenMutationTools = [
1629
1681
  type: 'string',
1630
1682
  description: 'Optional Scene ID to scope the token lookup',
1631
1683
  },
1684
+ createOptions: {
1685
+ type: 'object',
1686
+ 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",
1687
+ },
1632
1688
  },
1633
1689
  required: ['tokenId', 'statusId'],
1634
1690
  },
@@ -2142,7 +2198,7 @@ export const worldTools = [
2142
2198
  },
2143
2199
  {
2144
2200
  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.',
2201
+ 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
2202
  inputSchema: {
2147
2203
  type: 'object',
2148
2204
  properties: {},
@@ -2520,7 +2576,7 @@ export const moduleBridgeTools = [
2520
2576
  },
2521
2577
  {
2522
2578
  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.",
2579
+ 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
2580
  inputSchema: {
2525
2581
  type: 'object',
2526
2582
  properties: {
@@ -2646,6 +2702,36 @@ export const moduleBridgeTools = [
2646
2702
  required: ['tokenIds'],
2647
2703
  },
2648
2704
  },
2705
+ {
2706
+ name: 'get_actor_stats',
2707
+ 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.",
2708
+ inputSchema: {
2709
+ type: 'object',
2710
+ properties: {
2711
+ actorId: {
2712
+ type: 'string',
2713
+ description: "The world actor's id. With sceneId + tokenId, optional: it must be the token's actor",
2714
+ },
2715
+ sceneId: {
2716
+ type: 'string',
2717
+ description: 'Scene of the token to read, together with tokenId',
2718
+ },
2719
+ tokenId: {
2720
+ type: 'string',
2721
+ description: 'Token to read (an unlinked token has its own data), together with sceneId',
2722
+ },
2723
+ paths: {
2724
+ type: 'array',
2725
+ items: { type: 'string' },
2726
+ 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"',
2727
+ },
2728
+ maxBytes: {
2729
+ type: 'number',
2730
+ description: 'Largest answer accepted, in bytes of compact JSON (default 32768, at most 65536)',
2731
+ },
2732
+ },
2733
+ },
2734
+ },
2649
2735
  {
2650
2736
  name: 'get_targets',
2651
2737
  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.',
@@ -2728,7 +2814,7 @@ export const moduleBridgeTools = [
2728
2814
  export const effectTools = [
2729
2815
  {
2730
2816
  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. " +
2817
+ 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
2818
  WRITE_GATE,
2733
2819
  inputSchema: {
2734
2820
  type: 'object',
@@ -2795,7 +2881,7 @@ export const effectTools = [
2795
2881
  },
2796
2882
  {
2797
2883
  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. " +
2884
+ 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
2885
  WRITE_GATE,
2800
2886
  inputSchema: {
2801
2887
  type: 'object',
@@ -2853,7 +2939,7 @@ export const effectTools = [
2853
2939
  },
2854
2940
  {
2855
2941
  name: 'delete_actor_effect',
2856
- description: 'Delete an ActiveEffect from an actor. Same actorId/sceneId+tokenId resolution as create_actor_effect. ' +
2942
+ 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
2943
  CONFIRM_FIRST +
2858
2944
  ' ' +
2859
2945
  WRITE_GATE,
@@ -2876,13 +2962,24 @@ export const effectTools = [
2876
2962
  },
2877
2963
  {
2878
2964
  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.",
2965
+ 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
2966
  inputSchema: {
2881
2967
  type: 'object',
2882
2968
  properties: {
2883
- actorId: { type: 'string', description: "The actor's own document id" },
2969
+ actorId: {
2970
+ type: 'string',
2971
+ description: "The actor's own document id (omit when giving sceneId + tokenId)",
2972
+ },
2973
+ sceneId: {
2974
+ type: 'string',
2975
+ description: 'Scene id of the token, required together with tokenId',
2976
+ },
2977
+ tokenId: {
2978
+ type: 'string',
2979
+ 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",
2980
+ },
2884
2981
  },
2885
- required: ['actorId'],
2982
+ required: [],
2886
2983
  },
2887
2984
  },
2888
2985
  ];
@@ -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
@@ -4,6 +4,7 @@
4
4
  * Handles searching for actors and retrieving detailed actor information.
5
5
  */
6
6
  import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
7
+ import { isUnlinkedToken, resolveActorTarget, tokenHeaderLine, } from './actor-target.js';
7
8
  import { withToolError } from './utils.js';
8
9
  /**
9
10
  * Handles actor search requests
@@ -43,15 +44,19 @@ ${actorList || 'No actors found matching the criteria.'}
43
44
  });
44
45
  }
45
46
  /**
46
- * Handles detailed actor information requests
47
+ * Handles detailed actor information requests: a world actor by `actorId`,
48
+ * or one token's actor by `sceneId` + `tokenId` (an unlinked token's own
49
+ * HP and stats, base actor and delta merged).
47
50
  */
48
51
  export async function handleGetActorDetails(args, foundryClient) {
49
- const { actorId } = args;
50
- if (!actorId || typeof actorId !== 'string') {
52
+ if (args.actorId !== undefined && (typeof args.actorId !== 'string' || !args.actorId)) {
51
53
  throw new McpError(ErrorCode.InvalidParams, 'Actor ID is required and must be a string');
52
54
  }
55
+ const target = resolveActorTarget(args, foundryClient);
53
56
  return withToolError('get actor details', async () => {
54
- const actor = await foundryClient.getActor(actorId);
57
+ const actor = isUnlinkedToken(target)
58
+ ? foundryClient.getTokenActor(target.tokenId, target.sceneId)
59
+ : await foundryClient.getActor(target.actorId);
55
60
  const abilities = actor.abilities
56
61
  ? Object.entries(actor.abilities)
57
62
  .map(([key, ability]) => `**${key.toUpperCase()}:** ${ability.value} (${ability.mod >= 0 ? '+' : ''}${ability.mod})`)
@@ -62,7 +67,7 @@ export async function handleGetActorDetails(args, foundryClient) {
62
67
  {
63
68
  type: 'text',
64
69
  text: `🎭 **Actor Details: ${actor.name}**
65
- **Type:** ${actor.type}
70
+ ${tokenHeaderLine(target)}**Type:** ${actor.type}
66
71
  **Level:** ${actor.level || 'Unknown'}
67
72
  **Hit Points:** ${actor.hp?.value || 'Unknown'}/${actor.hp?.max || 'Unknown'}
68
73
  **Armor Class:** ${actor.ac?.value || 'Unknown'}
@@ -81,17 +86,25 @@ ${abilities}
81
86
  *
82
87
  * Reads full `system` data from the cached worldData, unlike
83
88
  * `get_actor_details`, which only reports the actor's own top-level stats.
89
+ * For an unlinked token, the items are its base actor's and its delta's
90
+ * merged (see `FoundryClient.getTokenActorItems`).
84
91
  */
85
92
  export async function handleGetActorInventory(args, foundryClient) {
86
- const { actorId } = args;
87
- if (!actorId || typeof actorId !== 'string') {
88
- throw new McpError(ErrorCode.InvalidParams, 'actorId is required and must be a string');
89
- }
93
+ const target = resolveActorTarget(args, foundryClient);
90
94
  return withToolError('get actor inventory', async () => {
91
- const items = foundryClient.getActorItems(actorId);
95
+ const items = isUnlinkedToken(target)
96
+ ? (foundryClient.getTokenActorItems(target.tokenId, target.sceneId) ?? [])
97
+ : foundryClient.getActorItems(target.actorId);
92
98
  if (items.length === 0) {
93
99
  return {
94
- content: [{ type: 'text', text: `Actor ${actorId} owns no items.` }],
100
+ content: [
101
+ {
102
+ type: 'text',
103
+ text: isUnlinkedToken(target)
104
+ ? `${tokenHeaderLine(target)}Token ${target.tokenId}'s actor owns no items.`
105
+ : `Actor ${target.actorId} owns no items.`,
106
+ },
107
+ ],
95
108
  };
96
109
  }
97
110
  const formatted = items
@@ -105,7 +118,7 @@ export async function handleGetActorInventory(args, foundryClient) {
105
118
  content: [
106
119
  {
107
120
  type: 'text',
108
- text: `🎒 **Actor Inventory** (${items.length} item${items.length !== 1 ? 's' : ''})\n\n${formatted}`,
121
+ text: `🎒 **Actor Inventory** (${items.length} item${items.length !== 1 ? 's' : ''})\n${tokenHeaderLine(target)}\n${formatted}`,
109
122
  },
110
123
  ],
111
124
  };
@@ -8,6 +8,7 @@
8
8
  * protocol), and the connected user needs GM/owner permission.
9
9
  */
10
10
  import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
11
+ import { combatantName } from './combat.js';
11
12
  import { getCurrentCombatant, getTurnOrder, turnIndexAfterInitiativeChange, } from './combat-order.js';
12
13
  import { withToolError } from './utils.js';
13
14
  /**
@@ -66,7 +67,7 @@ export async function handleNextTurn(args, foundryClient) {
66
67
  const { turn, round } = computeNextTurn(combat, skipDefeated);
67
68
  await foundryClient.updateCombat(combat._id, { turn, round });
68
69
  const current = getTurnOrder(combat)[turn];
69
- const currentName = current ? current.name : 'unknown';
70
+ const currentName = current ? combatantName(current, combat, foundryClient) : 'unknown';
70
71
  return {
71
72
  content: [
72
73
  {
@@ -142,7 +143,7 @@ export async function handleSetInitiative(args, foundryClient) {
142
143
  if (turn !== undefined && turn !== combat.turn) {
143
144
  await foundryClient.updateCombat(resolvedCombatId, { turn });
144
145
  reanchored = `
145
- **Still acting:** ${acting.name} (turn ${turn + 1} of ${combat.combatants.length})`;
146
+ **Still acting:** ${combatantName(acting, combat, foundryClient)} (turn ${turn + 1} of ${combat.combatants.length})`;
146
147
  }
147
148
  }
148
149
  return {