@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.
- package/README.md +17 -13
- package/dist/config/index.js +6 -0
- package/dist/config/sources.js +1 -0
- package/dist/core.js +28 -1
- package/dist/foundry/client.js +333 -21
- package/dist/foundry/module-bridge.js +125 -6
- package/dist/foundry/world-cache.js +206 -8
- package/dist/shared/config-hash.js +1 -0
- package/dist/shared/control.js +6 -1
- package/dist/shared/protocol.js +4 -0
- package/dist/tools/definitions.js +143 -38
- 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 +240 -23
- package/dist/tools/handlers/token-mutations.js +151 -16
- package/dist/tools/router.js +11 -28
- package/dist/tools/tool-dependencies.js +14 -1
- package/package.json +2 -2
|
@@ -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
|
|
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: [
|
|
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: [
|
|
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: ['
|
|
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: ['
|
|
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: ['
|
|
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
|
|
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: ['
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 (
|
|
2691
|
-
|
|
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: '
|
|
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
|
|
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: '
|
|
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
|
|
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:
|
|
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
|
|
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: {
|
|
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: [
|
|
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
|
-
|
|
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
|