@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.
@@ -20,7 +20,7 @@ import { handleCreateActorItem, handleDeleteActorItem, handleUpdateActorItem, }
20
20
  import { handleSearchItems } from './handlers/items.js';
21
21
  import { handleAddJournalPage, handleCreateJournalEntry, handleDeleteJournalEntry, handleUpdateJournalEntry, handleUpdateJournalPage, } from './handlers/journal-mutations.js';
22
22
  import { handleGetJournal, handleSearchJournals } from './handlers/journals.js';
23
- import { handleCaptureScene, handleGetDocumentSchema, handleGetTargets, handleImportCompendiumActor, handlePingCanvas, handleRollAndPost, handleSearchCompendiumContent, handleSetPause, handleSetTarget, handleUploadAsset, } from './handlers/module-bridge.js';
23
+ import { handleCaptureScene, handleGetActorStats, handleGetDocumentSchema, handleGetTargets, handleImportCompendiumActor, handlePingCanvas, handleRollAndPost, handleSearchCompendiumContent, handleSetPause, handleSetTarget, handleUploadAsset, } from './handlers/module-bridge.js';
24
24
  import { handleCreateDrawing, handleCreateLight, handleCreateNote, handleCreateRegion, handleCreateSound, handleCreateTemplate, handleDeleteDrawing, handleDeleteLight, handleDeleteNote, handleDeleteRegion, handleDeleteSound, handleDeleteTemplate, handleUpdateLight, } from './handlers/placeable-mutations.js';
25
25
  import { handleReadResource } from './handlers/resources.js';
26
26
  import { handleCreateRollTable, handleDeleteRollTable, handleListRollTables, handleRollTable, } from './handlers/roll-tables.js';
@@ -66,22 +66,14 @@ export async function routeToolRequest(name, args, foundryClient, diagnosticsCli
66
66
  // Actor tools
67
67
  case 'search_actors':
68
68
  return handleSearchActors(args, foundryClient);
69
+ // actorId, or sceneId + tokenId: the handlers check which (actor-target.ts)
69
70
  case 'get_actor_details':
70
- if (!('actorId' in args) || typeof args.actorId !== 'string') {
71
- throw new Error('Missing required parameter: actorId');
72
- }
73
71
  return handleGetActorDetails(args, foundryClient);
74
72
  case 'get_actor_inventory':
75
- if (!('actorId' in args) || typeof args.actorId !== 'string') {
76
- throw new Error('Missing required parameter: actorId');
77
- }
78
73
  return handleGetActorInventory(args, foundryClient);
79
74
  // Actor mutation tools (laurigates/foundryvtt-mcp#143) — WRITE via the Socket.IO modifyDocument
80
75
  // protocol (foundryClient); require FOUNDRY_WRITE_ENABLED=true + a GM user.
81
76
  case 'update_actor_attributes':
82
- if (!('actorId' in args) || typeof args.actorId !== 'string') {
83
- throw new Error('Missing required parameter: actorId');
84
- }
85
77
  if (!('patch' in args) || typeof args.patch !== 'object' || args.patch === null) {
86
78
  throw new Error('Missing required parameter: patch');
87
79
  }
@@ -118,18 +110,13 @@ export async function routeToolRequest(name, args, foundryClient, diagnosticsCli
118
110
  return handleSearchCompendium(args, foundryClient);
119
111
  // Item mutation tools (WRITE) — Socket.IO modifyDocument protocol
120
112
  // (foundryClient); require FOUNDRY_WRITE_ENABLED=true + a GM user.
113
+ // actorId, or sceneId + tokenId: the handlers check which (actor-target.ts)
121
114
  case 'create_actor_item':
122
- if (!('actorId' in args) || typeof args.actorId !== 'string') {
123
- throw new Error('Missing required parameter: actorId');
124
- }
125
115
  if (!('source' in args) || typeof args.source !== 'object' || args.source === null) {
126
116
  throw new Error('Missing required parameter: source');
127
117
  }
128
118
  return handleCreateActorItem(args, foundryClient, moduleBridge);
129
119
  case 'update_actor_item':
130
- if (!('actorId' in args) || typeof args.actorId !== 'string') {
131
- throw new Error('Missing required parameter: actorId');
132
- }
133
120
  if (!('itemId' in args) || typeof args.itemId !== 'string') {
134
121
  throw new Error('Missing required parameter: itemId');
135
122
  }
@@ -138,9 +125,6 @@ export async function routeToolRequest(name, args, foundryClient, diagnosticsCli
138
125
  }
139
126
  return handleUpdateActorItem(args, foundryClient);
140
127
  case 'delete_actor_item':
141
- if (!('actorId' in args) || typeof args.actorId !== 'string') {
142
- throw new Error('Missing required parameter: actorId');
143
- }
144
128
  if (!('itemId' in args) || typeof args.itemId !== 'string') {
145
129
  throw new Error('Missing required parameter: itemId');
146
130
  }
@@ -345,7 +329,7 @@ export async function routeToolRequest(name, args, foundryClient, diagnosticsCli
345
329
  if (!('statusId' in args) || typeof args.statusId !== 'string') {
346
330
  throw new Error('Missing required parameter: statusId');
347
331
  }
348
- return handleApplyStatusEffect(args, foundryClient);
332
+ return handleApplyStatusEffect(args, foundryClient, moduleBridge);
349
333
  case 'spawn_token':
350
334
  if (!('actorId' in args) || typeof args.actorId !== 'string') {
351
335
  throw new Error('Missing required parameter: actorId');
@@ -477,7 +461,7 @@ export async function routeToolRequest(name, args, foundryClient, diagnosticsCli
477
461
  if (!('formula' in args) || typeof args.formula !== 'string') {
478
462
  throw new Error('Missing required parameter: formula');
479
463
  }
480
- return handleRollAndPost(args, moduleBridge);
464
+ return handleRollAndPost(args, foundryClient, moduleBridge);
481
465
  case 'import_compendium_actor':
482
466
  if (!('compendiumId' in args) || typeof args.compendiumId !== 'string') {
483
467
  throw new Error('Missing required parameter: compendiumId');
@@ -490,7 +474,9 @@ export async function routeToolRequest(name, args, foundryClient, diagnosticsCli
490
474
  if (!('tokenIds' in args) || !Array.isArray(args.tokenIds)) {
491
475
  throw new Error('Missing required parameter: tokenIds');
492
476
  }
493
- return handleSetTarget(args, moduleBridge);
477
+ return handleSetTarget(args, foundryClient, moduleBridge);
478
+ case 'get_actor_stats':
479
+ return handleGetActorStats(args, foundryClient, moduleBridge);
494
480
  case 'get_targets':
495
481
  return handleGetTargets(args, moduleBridge);
496
482
  case 'ping_canvas':
@@ -500,9 +486,9 @@ export async function routeToolRequest(name, args, foundryClient, diagnosticsCli
500
486
  if (!('y' in args) || typeof args.y !== 'number') {
501
487
  throw new Error('Missing required parameter: y');
502
488
  }
503
- return handlePingCanvas(args, moduleBridge);
489
+ return handlePingCanvas(args, foundryClient, moduleBridge);
504
490
  case 'set_pause':
505
- return handleSetPause(args, moduleBridge);
491
+ return handleSetPause(args, foundryClient, moduleBridge);
506
492
  case 'upload_asset':
507
493
  if (!('targetDir' in args) || typeof args.targetDir !== 'string') {
508
494
  throw new Error('Missing required parameter: targetDir');
@@ -510,7 +496,7 @@ export async function routeToolRequest(name, args, foundryClient, diagnosticsCli
510
496
  if (!('filename' in args) || typeof args.filename !== 'string') {
511
497
  throw new Error('Missing required parameter: filename');
512
498
  }
513
- return handleUploadAsset(args, moduleBridge);
499
+ return handleUploadAsset(args, foundryClient, moduleBridge);
514
500
  // World-event tools (read-only)
515
501
  case 'watch_events':
516
502
  return handleWatchEvents(args, foundryClient);
@@ -670,9 +656,6 @@ export async function routeToolRequest(name, args, foundryClient, diagnosticsCli
670
656
  }
671
657
  return handleDeleteActorEffect(args, foundryClient);
672
658
  case 'list_actor_effects':
673
- if (!('actorId' in args) || typeof args.actorId !== 'string') {
674
- throw new Error('Missing required parameter: actorId');
675
- }
676
659
  return handleListActorEffects(args, foundryClient);
677
660
  default:
678
661
  throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
@@ -126,6 +126,8 @@ const TOOL_DEPENDENCIES = new Map([
126
126
  ['import_compendium_actor', 'socket+bridge'],
127
127
  // The module only for a compendium source; see needsBridge.
128
128
  ['create_actor_item', 'socket+bridge'],
129
+ // Checks its target against the cache, then reads it through the module.
130
+ ['get_actor_stats', 'socket+bridge'],
129
131
  ['capture_scene', 'bridge'],
130
132
  ['get_document_schema', 'bridge'],
131
133
  ['search_compendium_content', 'bridge'],
@@ -146,6 +148,13 @@ const TOOL_DEPENDENCIES = new Map([
146
148
  ['list_scene_assets', 'local'],
147
149
  ['get_health_status', 'health'],
148
150
  ]);
151
+ /**
152
+ * Socket tools that go through the companion module when it is there:
153
+ * FoundryCore waits for a module on its way as it does for a module tool,
154
+ * but never refuses the call because of it; the tool then falls back to the
155
+ * socket.
156
+ */
157
+ const PREFERS_BRIDGE_TOOLS = new Set(['apply_status_effect']);
149
158
  /** Every `foundry://` resource reads the cache, except the REST diagnostics. */
150
159
  const RESOURCE_DEPENDENCIES = new Map([
151
160
  ['foundry://actors', 'socket'],
@@ -173,9 +182,13 @@ export function resourceDependency(uri) {
173
182
  export function waitsForSocket(dependency) {
174
183
  return dependency === undefined || dependency === 'socket' || dependency === 'socket+bridge';
175
184
  }
185
+ /** True when the tool uses the companion module if it can (see {@link PREFERS_BRIDGE_TOOLS}). */
186
+ export function prefersBridge(name) {
187
+ return PREFERS_BRIDGE_TOOLS.has(name);
188
+ }
176
189
  /**
177
190
  * True when this call goes through the companion module: every `bridge`
178
- * tool, `import_compendium_actor`, and `create_actor_item` from a
191
+ * tool, `import_compendium_actor`, `get_actor_stats`, and `create_actor_item` from a
179
192
  * compendium source (an inline item needs only the socket).
180
193
  */
181
194
  export function needsBridge(name, args) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@g33ks/foundryvtt-mcp",
3
- "version": "2.1.0",
3
+ "version": "2.2.1",
4
4
  "description": "Model Context Protocol server for FoundryVTT integration",
5
5
  "bin": {
6
6
  "foundryvtt-mcp": "dist/index.js"
@@ -92,7 +92,7 @@
92
92
  "rimraf": "^6.1.4",
93
93
  "tsx": "^4.22.4",
94
94
  "typescript": "^6.0.3",
95
- "vitest": "^4.1.12"
95
+ "vitest": "^5.1.0"
96
96
  },
97
97
  "engines": {
98
98
  "node": ">=22"