@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.
- package/README.md +16 -13
- package/dist/core.js +25 -1
- package/dist/foundry/client.js +293 -19
- package/dist/foundry/module-bridge.js +125 -6
- package/dist/foundry/world-cache.js +206 -8
- package/dist/shared/control.js +6 -1
- package/dist/shared/protocol.js +4 -0
- package/dist/tools/definitions.js +125 -28
- package/dist/tools/handlers/actor-mutations.js +13 -7
- package/dist/tools/handlers/actor-target.js +80 -0
- package/dist/tools/handlers/actors.js +25 -12
- package/dist/tools/handlers/combat-mutations.js +3 -2
- package/dist/tools/handlers/combat.js +48 -17
- package/dist/tools/handlers/diagnostics.js +1 -1
- package/dist/tools/handlers/effects.js +23 -24
- package/dist/tools/handlers/item-mutations.js +23 -21
- package/dist/tools/handlers/module-bridge.js +131 -2
- package/dist/tools/handlers/token-mutations.js +151 -16
- package/dist/tools/router.js +6 -23
- package/dist/tools/tool-dependencies.js +14 -1
- package/package.json +2 -2
|
@@ -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
|
|
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: [
|
|
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: [
|
|
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: ['
|
|
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: ['
|
|
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: ['
|
|
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
|
|
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: ['
|
|
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
|
|
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
|
|
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
|
|
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:
|
|
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
|
|
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: {
|
|
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: [
|
|
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
|
-
|
|
21
|
-
|
|
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 =
|
|
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
|
-
|
|
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
|
-
|
|
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 =
|
|
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
|
|
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 =
|
|
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: [
|
|
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
|
|
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
|
|
146
|
+
**Still acting:** ${combatantName(acting, combat, foundryClient)} (turn ${turn + 1} of ${combat.combatants.length})`;
|
|
146
147
|
}
|
|
147
148
|
}
|
|
148
149
|
return {
|