@g33ks/foundryvtt-mcp 0.0.0-stage → 2.1.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.
Files changed (100) hide show
  1. package/LICENSE +22 -0
  2. package/README.md +457 -2
  3. package/dist/character/manager.js +208 -0
  4. package/dist/cli/checks.js +307 -0
  5. package/dist/cli/config-file.js +120 -0
  6. package/dist/cli/init.js +414 -0
  7. package/dist/cli/prompt.js +117 -0
  8. package/dist/cli/snippets.js +64 -0
  9. package/dist/combat/manager.js +371 -0
  10. package/dist/config/env-layers.js +49 -0
  11. package/dist/config/index.js +298 -0
  12. package/dist/config/sources.js +201 -0
  13. package/dist/core.js +481 -0
  14. package/dist/diagnostics/client.js +291 -0
  15. package/dist/diagnostics/types.js +94 -0
  16. package/dist/foundry/auth.js +224 -0
  17. package/dist/foundry/browser-detect.js +170 -0
  18. package/dist/foundry/client.js +5874 -0
  19. package/dist/foundry/dice-formula.js +154 -0
  20. package/dist/foundry/event-log.js +298 -0
  21. package/dist/foundry/headless-gm-session.js +857 -0
  22. package/dist/foundry/journal-conflicts.js +141 -0
  23. package/dist/foundry/journal-history.js +90 -0
  24. package/dist/foundry/journal-integrity.js +322 -0
  25. package/dist/foundry/message-author.js +19 -0
  26. package/dist/foundry/module-bridge.js +441 -0
  27. package/dist/foundry/types.js +52 -0
  28. package/dist/foundry/world-cache.js +386 -0
  29. package/dist/index.js +107 -0
  30. package/dist/mcp-server.js +65 -0
  31. package/dist/server.js +159 -0
  32. package/dist/shared/build-order.js +134 -0
  33. package/dist/shared/config-hash.js +62 -0
  34. package/dist/shared/config-notice.js +55 -0
  35. package/dist/shared/control.js +291 -0
  36. package/dist/shared/daemon-link.js +135 -0
  37. package/dist/shared/daemon.js +311 -0
  38. package/dist/shared/ipc-client.js +200 -0
  39. package/dist/shared/ipc-server.js +316 -0
  40. package/dist/shared/paths.js +79 -0
  41. package/dist/shared/protocol.js +230 -0
  42. package/dist/shared/relay-config.js +65 -0
  43. package/dist/shared/relay.js +120 -0
  44. package/dist/shared/rotating-log.js +57 -0
  45. package/dist/shared/spawn.js +39 -0
  46. package/dist/shared/state-file.js +33 -0
  47. package/dist/shared/token.js +62 -0
  48. package/dist/shared/version.js +57 -0
  49. package/dist/tools/base.js +74 -0
  50. package/dist/tools/definitions.js +3109 -0
  51. package/dist/tools/handlers/actor-mutations.js +128 -0
  52. package/dist/tools/handlers/actors.js +114 -0
  53. package/dist/tools/handlers/chat-mutations.js +49 -0
  54. package/dist/tools/handlers/chat.js +38 -0
  55. package/dist/tools/handlers/combat-mutations.js +215 -0
  56. package/dist/tools/handlers/combat-order.js +94 -0
  57. package/dist/tools/handlers/combat.js +51 -0
  58. package/dist/tools/handlers/compendium.js +83 -0
  59. package/dist/tools/handlers/diagnostics.js +450 -0
  60. package/dist/tools/handlers/dice.js +54 -0
  61. package/dist/tools/handlers/effects.js +103 -0
  62. package/dist/tools/handlers/events.js +50 -0
  63. package/dist/tools/handlers/generation.js +258 -0
  64. package/dist/tools/handlers/item-mutations.js +132 -0
  65. package/dist/tools/handlers/items.js +53 -0
  66. package/dist/tools/handlers/journal-mutations.js +230 -0
  67. package/dist/tools/handlers/journals.js +80 -0
  68. package/dist/tools/handlers/module-bridge.js +421 -0
  69. package/dist/tools/handlers/placeable-mutations.js +272 -0
  70. package/dist/tools/handlers/resources.js +203 -0
  71. package/dist/tools/handlers/roll-tables.js +97 -0
  72. package/dist/tools/handlers/scene-mutations.js +159 -0
  73. package/dist/tools/handlers/scenes.js +355 -0
  74. package/dist/tools/handlers/settings.js +53 -0
  75. package/dist/tools/handlers/tile-mutations.js +56 -0
  76. package/dist/tools/handlers/token-mutations.js +356 -0
  77. package/dist/tools/handlers/users.js +59 -0
  78. package/dist/tools/handlers/utils.js +48 -0
  79. package/dist/tools/handlers/wall-mutations.js +98 -0
  80. package/dist/tools/handlers/world-documents.js +222 -0
  81. package/dist/tools/handlers/world.js +92 -0
  82. package/dist/tools/index.js +25 -0
  83. package/dist/tools/new-router.js +97 -0
  84. package/dist/tools/registry.js +79 -0
  85. package/dist/tools/resources.js +63 -0
  86. package/dist/tools/router.js +688 -0
  87. package/dist/tools/tool-dependencies.js +194 -0
  88. package/dist/tools/write-tools.js +97 -0
  89. package/dist/utils/cache-instance.js +30 -0
  90. package/dist/utils/cache.js +205 -0
  91. package/dist/utils/diagnostics.js +332 -0
  92. package/dist/utils/guards.js +17 -0
  93. package/dist/utils/image-size.js +160 -0
  94. package/dist/utils/log-args.js +47 -0
  95. package/dist/utils/logger.js +203 -0
  96. package/dist/utils/mcp-errors.js +47 -0
  97. package/dist/utils/refusal.js +30 -0
  98. package/dist/utils/sanitize.js +22 -0
  99. package/dist/utils/serial-queue.js +22 -0
  100. package/package.json +124 -4
@@ -0,0 +1,230 @@
1
+ /**
2
+ * @fileoverview Journal entry and page mutation tool handlers
3
+ *
4
+ * WRITE operations — require FOUNDRY_WRITE_ENABLED=true and an active Socket.IO
5
+ * connection (mutations use the core `modifyDocument` protocol). `JournalEntry`
6
+ * is a top-level document, so entry writes have no parent to scope them to;
7
+ * `JournalEntryPage` writes are scoped to their parent entry.
8
+ */
9
+ import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
10
+ import { journalVersion } from '../../foundry/journal-integrity.js';
11
+ import { VISIBILITY_LEVELS } from '../../foundry/types.js';
12
+ import { refusalError } from '../../utils/refusal.js';
13
+ import { withJournalWarnings, withToolError } from './utils.js';
14
+ /** Version token of a page body as returned by the server. */
15
+ function pageVersion(page) {
16
+ return journalVersion(page?.text?.content ?? '');
17
+ }
18
+ /** Human-readable summary of who can see the entry, for the tool response. */
19
+ const VISIBILITY_SUMMARY = {
20
+ 'gm-only': 'GM only',
21
+ observer: 'all players (read-only)',
22
+ owner: 'all players (read/write)',
23
+ };
24
+ /**
25
+ * Handles creating a journal entry with one or more text pages.
26
+ */
27
+ export async function handleCreateJournalEntry(args, foundryClient) {
28
+ const { name, pages, folder, visibility } = args;
29
+ if (!name || typeof name !== 'string') {
30
+ throw new McpError(ErrorCode.InvalidParams, 'name is required and must be a string');
31
+ }
32
+ if (!Array.isArray(pages) || pages.length === 0) {
33
+ throw new McpError(ErrorCode.InvalidParams, 'pages is required and must contain at least one page');
34
+ }
35
+ for (const page of pages) {
36
+ if (!page ||
37
+ typeof page !== 'object' ||
38
+ typeof page.name !== 'string' ||
39
+ typeof page.content !== 'string') {
40
+ throw new McpError(ErrorCode.InvalidParams, 'each page requires a name and content string');
41
+ }
42
+ }
43
+ if (visibility !== undefined && !(visibility in VISIBILITY_LEVELS)) {
44
+ throw new McpError(ErrorCode.InvalidParams, `visibility must be one of: ${Object.keys(VISIBILITY_LEVELS).join(', ')}`);
45
+ }
46
+ return withToolError('create journal entry', async () => {
47
+ const journal = await foundryClient.createJournalEntry(name, pages, folder, visibility);
48
+ const pageLines = (journal.pages ?? []).map((p) => `- ${p.name} — ID: ${p._id} — version: ${pageVersion(p)}`);
49
+ return withJournalWarnings(foundryClient, {
50
+ content: [
51
+ {
52
+ type: 'text',
53
+ text: `📓 **Journal Entry Created**
54
+ **Name:** ${journal.name}
55
+ **ID:** ${journal._id}
56
+ **Pages:** ${journal.pages?.length ?? pages.length}
57
+ **Visible to:** ${VISIBILITY_SUMMARY[visibility ?? 'gm-only']}${pageLines.length > 0 ? `\n${pageLines.join('\n')}` : ''}`,
58
+ },
59
+ ],
60
+ });
61
+ });
62
+ }
63
+ const PAGE_UPDATE_MODES = ['replace', 'append'];
64
+ function requireId(value, field) {
65
+ if (!value || typeof value !== 'string') {
66
+ throw new McpError(ErrorCode.InvalidParams, `${field} is required and must be a string`);
67
+ }
68
+ }
69
+ /**
70
+ * Handles editing one page of a journal entry: replacing its name and/or
71
+ * content, or appending HTML to the end of its content.
72
+ */
73
+ export async function handleUpdateJournalPage(args, foundryClient) {
74
+ const { journalId, pageId, name, content, expectedVersion } = args;
75
+ const mode = args.mode ?? 'replace';
76
+ requireId(journalId, 'journalId');
77
+ requireId(pageId, 'pageId');
78
+ if (!PAGE_UPDATE_MODES.includes(mode)) {
79
+ throw new McpError(ErrorCode.InvalidParams, `mode must be one of: ${PAGE_UPDATE_MODES.join(', ')}`);
80
+ }
81
+ if (name !== undefined && (typeof name !== 'string' || !name)) {
82
+ throw new McpError(ErrorCode.InvalidParams, 'name must be a non-empty string');
83
+ }
84
+ if (content !== undefined && typeof content !== 'string') {
85
+ throw new McpError(ErrorCode.InvalidParams, 'content must be a string');
86
+ }
87
+ if (mode === 'append') {
88
+ if (!content) {
89
+ throw new McpError(ErrorCode.InvalidParams, 'append mode requires non-empty content');
90
+ }
91
+ if (name !== undefined) {
92
+ throw new McpError(ErrorCode.InvalidParams, 'name cannot be changed in append mode - use mode "replace" to rename the page');
93
+ }
94
+ }
95
+ else if (name === undefined && content === undefined) {
96
+ throw new McpError(ErrorCode.InvalidParams, 'replace mode requires a name or content');
97
+ }
98
+ if (expectedVersion !== undefined && (typeof expectedVersion !== 'string' || !expectedVersion)) {
99
+ throw new McpError(ErrorCode.InvalidParams, 'expectedVersion must be a non-empty string');
100
+ }
101
+ if (mode === 'replace' && content !== undefined && !expectedVersion) {
102
+ throw refusalError(ErrorCode.InvalidParams, 'Replacing a page body requires expectedVersion: call get_journal with raw: true, ' +
103
+ 'rewrite the page from that HTML, and pass the version printed for the page.');
104
+ }
105
+ return withToolError('update journal page', async () => {
106
+ let written;
107
+ if (mode === 'append') {
108
+ written = await foundryClient.appendJournalPage(journalId, pageId, content, expectedVersion);
109
+ }
110
+ else {
111
+ const patch = {};
112
+ if (name !== undefined) {
113
+ patch.name = name;
114
+ }
115
+ if (content !== undefined) {
116
+ patch.content = content;
117
+ }
118
+ if (expectedVersion !== undefined) {
119
+ patch.expectedVersion = expectedVersion;
120
+ }
121
+ written = await foundryClient.updateJournalPage(journalId, pageId, patch);
122
+ }
123
+ const lines = [
124
+ ...written.notices,
125
+ ...(written.notices.length > 0 ? [''] : []),
126
+ '📝 **Journal Page Updated**',
127
+ `**Journal:** ${written.journalName} (${journalId})`,
128
+ `**Page:** ${written.page.name} (${pageId})`,
129
+ `**Mode:** ${mode}`,
130
+ `**Version:** ${written.version}`,
131
+ ];
132
+ return withJournalWarnings(foundryClient, {
133
+ content: [{ type: 'text', text: lines.join('\n') }],
134
+ });
135
+ });
136
+ }
137
+ /**
138
+ * Handles adding a new text page to an existing journal entry.
139
+ */
140
+ export async function handleAddJournalPage(args, foundryClient) {
141
+ const { journalId, name, content } = args;
142
+ requireId(journalId, 'journalId');
143
+ if (!name || typeof name !== 'string') {
144
+ throw new McpError(ErrorCode.InvalidParams, 'name is required and must be a string');
145
+ }
146
+ if (typeof content !== 'string') {
147
+ throw new McpError(ErrorCode.InvalidParams, 'content is required and must be a string');
148
+ }
149
+ return withToolError('add journal page', async () => {
150
+ const page = await foundryClient.addJournalPage(journalId, { name, content });
151
+ const journal = foundryClient.getJournal(journalId);
152
+ return withJournalWarnings(foundryClient, {
153
+ content: [
154
+ {
155
+ type: 'text',
156
+ text: `📄 **Journal Page Added**
157
+ **Journal:** ${journal?.name ?? journalId} (${journalId})
158
+ **Page:** ${page?.name ?? name} (${page?._id ?? 'unknown id'})
159
+ **Version:** ${pageVersion(page)}`,
160
+ },
161
+ ],
162
+ });
163
+ });
164
+ }
165
+ /**
166
+ * Handles renaming, refiling, or changing the visibility of a journal entry.
167
+ */
168
+ export async function handleUpdateJournalEntry(args, foundryClient) {
169
+ const { journalId, name, folder, visibility } = args;
170
+ requireId(journalId, 'journalId');
171
+ if (name === undefined && folder === undefined && visibility === undefined) {
172
+ throw new McpError(ErrorCode.InvalidParams, 'at least one of name, folder or visibility is required');
173
+ }
174
+ if (name !== undefined && (typeof name !== 'string' || !name)) {
175
+ throw new McpError(ErrorCode.InvalidParams, 'name must be a non-empty string');
176
+ }
177
+ if (folder !== undefined && typeof folder !== 'string') {
178
+ throw new McpError(ErrorCode.InvalidParams, 'folder must be a string');
179
+ }
180
+ if (visibility !== undefined && !(visibility in VISIBILITY_LEVELS)) {
181
+ throw new McpError(ErrorCode.InvalidParams, `visibility must be one of: ${Object.keys(VISIBILITY_LEVELS).join(', ')}`);
182
+ }
183
+ return withToolError('update journal entry', async () => {
184
+ const patch = {};
185
+ if (name !== undefined) {
186
+ patch.name = name;
187
+ }
188
+ if (folder !== undefined) {
189
+ patch.folder = folder;
190
+ }
191
+ if (visibility !== undefined) {
192
+ patch.visibility = visibility;
193
+ }
194
+ await foundryClient.updateJournalEntry(journalId, patch);
195
+ const journal = foundryClient.getJournal(journalId);
196
+ const lines = [
197
+ '📓 **Journal Entry Updated**',
198
+ `**Entry:** ${journal?.name ?? name ?? journalId} (${journalId})`,
199
+ ];
200
+ if (folder !== undefined) {
201
+ lines.push(`**Folder:** ${folder}`);
202
+ }
203
+ if (visibility !== undefined) {
204
+ lines.push(`**Visible to:** ${VISIBILITY_SUMMARY[visibility]}`);
205
+ }
206
+ return withJournalWarnings(foundryClient, {
207
+ content: [{ type: 'text', text: lines.join('\n') }],
208
+ });
209
+ });
210
+ }
211
+ /**
212
+ * Handles permanently deleting a journal entry.
213
+ */
214
+ export async function handleDeleteJournalEntry(args, foundryClient) {
215
+ const { journalId } = args;
216
+ if (!journalId || typeof journalId !== 'string') {
217
+ throw new McpError(ErrorCode.InvalidParams, 'journalId is required and must be a string');
218
+ }
219
+ return withToolError('delete journal entry', async () => {
220
+ const target = foundryClient.getJournal(journalId);
221
+ const name = target?.name ?? journalId;
222
+ await foundryClient.deleteJournalEntry(journalId);
223
+ return withJournalWarnings(foundryClient, {
224
+ content: [
225
+ { type: 'text', text: `🗑️ **Journal Entry Deleted**\n**Entry:** ${name} (${journalId})` },
226
+ ],
227
+ });
228
+ });
229
+ }
230
+ //# sourceMappingURL=journal-mutations.js.map
@@ -0,0 +1,80 @@
1
+ /**
2
+ * Journal entry tool handlers
3
+ */
4
+ import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
5
+ import { journalVersion } from '../../foundry/journal-integrity.js';
6
+ import { stripHtml } from '../../utils/sanitize.js';
7
+ import { withJournalWarnings, withToolError } from './utils.js';
8
+ /** Shown on cache-served journal reads while the snapshot is stale (laurigates/foundryvtt-mcp#217). */
9
+ const STALE_JOURNAL_NOTICE = '⚠️ **Stale:** this comes from a cached snapshot that stopped following live changes when ' +
10
+ 'the connection dropped. Use `raw: true` to read the entry from the server, or ' +
11
+ '`refresh_world_data` to resync everything.';
12
+ export async function handleSearchJournals(args, foundryClient) {
13
+ return withToolError('search journals', async () => {
14
+ const results = foundryClient.searchJournals(args.query);
15
+ const limit = args.limit || 10;
16
+ const limited = results.slice(0, limit);
17
+ if (limited.length === 0) {
18
+ return withJournalWarnings(foundryClient, {
19
+ content: [
20
+ {
21
+ type: 'text',
22
+ text: `No journals found matching "${args.query}".`,
23
+ },
24
+ ],
25
+ });
26
+ }
27
+ const formatted = limited
28
+ .map((j) => {
29
+ const pageCount = j.pages?.length || 0;
30
+ return `- **${j.name}** (${pageCount} page${pageCount !== 1 ? 's' : ''}) — ID: ${j._id}`;
31
+ })
32
+ .join('\n');
33
+ return withJournalWarnings(foundryClient, {
34
+ content: [
35
+ {
36
+ type: 'text',
37
+ text: `**Journal Search** — "${args.query}" (${results.length} results)\n\n${formatted}`,
38
+ },
39
+ ],
40
+ });
41
+ });
42
+ }
43
+ export async function handleGetJournal(args, foundryClient) {
44
+ return withToolError('get journal', async () => {
45
+ const raw = args.raw === true;
46
+ // raw reads the entry from the server: its HTML and version tokens are
47
+ // what update_journal_page will be checked against.
48
+ const journal = raw
49
+ ? await foundryClient.fetchJournalEntry(args.journalId)
50
+ : foundryClient.getJournal(args.journalId);
51
+ if (!journal) {
52
+ throw new McpError(ErrorCode.InvalidParams, `Journal not found: ${args.journalId}`);
53
+ }
54
+ const pages = journal.pages
55
+ ?.map((p) => {
56
+ const heading = `### ${p.name} — ID: ${p._id}`;
57
+ // raw returns the stored HTML untouched so a caller can rewrite the
58
+ // page with update_journal_page without losing markup or text.
59
+ if (raw) {
60
+ const body = p.text?.content ?? '';
61
+ return `${heading}\nversion: ${journalVersion(body)}\n${body}`;
62
+ }
63
+ const content = stripHtml(p.text?.content || '')
64
+ .trim()
65
+ .slice(0, 500);
66
+ return `${heading}\n${content}${content.length >= 500 ? '...' : ''}`;
67
+ })
68
+ .join('\n\n') || 'No pages.';
69
+ const stale = !raw && foundryClient.isWorldDataStale() ? `${STALE_JOURNAL_NOTICE}\n\n` : '';
70
+ return withJournalWarnings(foundryClient, {
71
+ content: [
72
+ {
73
+ type: 'text',
74
+ text: `${stale}**Journal: ${journal.name}**\nID: ${journal._id}\n\n${pages}`,
75
+ },
76
+ ],
77
+ });
78
+ });
79
+ }
80
+ //# sourceMappingURL=journals.js.map