@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.
- package/LICENSE +22 -0
- package/README.md +457 -2
- package/dist/character/manager.js +208 -0
- package/dist/cli/checks.js +307 -0
- package/dist/cli/config-file.js +120 -0
- package/dist/cli/init.js +414 -0
- package/dist/cli/prompt.js +117 -0
- package/dist/cli/snippets.js +64 -0
- package/dist/combat/manager.js +371 -0
- package/dist/config/env-layers.js +49 -0
- package/dist/config/index.js +298 -0
- package/dist/config/sources.js +201 -0
- package/dist/core.js +481 -0
- package/dist/diagnostics/client.js +291 -0
- package/dist/diagnostics/types.js +94 -0
- package/dist/foundry/auth.js +224 -0
- package/dist/foundry/browser-detect.js +170 -0
- package/dist/foundry/client.js +5874 -0
- package/dist/foundry/dice-formula.js +154 -0
- package/dist/foundry/event-log.js +298 -0
- package/dist/foundry/headless-gm-session.js +857 -0
- package/dist/foundry/journal-conflicts.js +141 -0
- package/dist/foundry/journal-history.js +90 -0
- package/dist/foundry/journal-integrity.js +322 -0
- package/dist/foundry/message-author.js +19 -0
- package/dist/foundry/module-bridge.js +441 -0
- package/dist/foundry/types.js +52 -0
- package/dist/foundry/world-cache.js +386 -0
- package/dist/index.js +107 -0
- package/dist/mcp-server.js +65 -0
- package/dist/server.js +159 -0
- package/dist/shared/build-order.js +134 -0
- package/dist/shared/config-hash.js +62 -0
- package/dist/shared/config-notice.js +55 -0
- package/dist/shared/control.js +291 -0
- package/dist/shared/daemon-link.js +135 -0
- package/dist/shared/daemon.js +311 -0
- package/dist/shared/ipc-client.js +200 -0
- package/dist/shared/ipc-server.js +316 -0
- package/dist/shared/paths.js +79 -0
- package/dist/shared/protocol.js +230 -0
- package/dist/shared/relay-config.js +65 -0
- package/dist/shared/relay.js +120 -0
- package/dist/shared/rotating-log.js +57 -0
- package/dist/shared/spawn.js +39 -0
- package/dist/shared/state-file.js +33 -0
- package/dist/shared/token.js +62 -0
- package/dist/shared/version.js +57 -0
- package/dist/tools/base.js +74 -0
- package/dist/tools/definitions.js +3109 -0
- package/dist/tools/handlers/actor-mutations.js +128 -0
- package/dist/tools/handlers/actors.js +114 -0
- package/dist/tools/handlers/chat-mutations.js +49 -0
- package/dist/tools/handlers/chat.js +38 -0
- package/dist/tools/handlers/combat-mutations.js +215 -0
- package/dist/tools/handlers/combat-order.js +94 -0
- package/dist/tools/handlers/combat.js +51 -0
- package/dist/tools/handlers/compendium.js +83 -0
- package/dist/tools/handlers/diagnostics.js +450 -0
- package/dist/tools/handlers/dice.js +54 -0
- package/dist/tools/handlers/effects.js +103 -0
- package/dist/tools/handlers/events.js +50 -0
- package/dist/tools/handlers/generation.js +258 -0
- package/dist/tools/handlers/item-mutations.js +132 -0
- package/dist/tools/handlers/items.js +53 -0
- package/dist/tools/handlers/journal-mutations.js +230 -0
- package/dist/tools/handlers/journals.js +80 -0
- package/dist/tools/handlers/module-bridge.js +421 -0
- package/dist/tools/handlers/placeable-mutations.js +272 -0
- package/dist/tools/handlers/resources.js +203 -0
- package/dist/tools/handlers/roll-tables.js +97 -0
- package/dist/tools/handlers/scene-mutations.js +159 -0
- package/dist/tools/handlers/scenes.js +355 -0
- package/dist/tools/handlers/settings.js +53 -0
- package/dist/tools/handlers/tile-mutations.js +56 -0
- package/dist/tools/handlers/token-mutations.js +356 -0
- package/dist/tools/handlers/users.js +59 -0
- package/dist/tools/handlers/utils.js +48 -0
- package/dist/tools/handlers/wall-mutations.js +98 -0
- package/dist/tools/handlers/world-documents.js +222 -0
- package/dist/tools/handlers/world.js +92 -0
- package/dist/tools/index.js +25 -0
- package/dist/tools/new-router.js +97 -0
- package/dist/tools/registry.js +79 -0
- package/dist/tools/resources.js +63 -0
- package/dist/tools/router.js +688 -0
- package/dist/tools/tool-dependencies.js +194 -0
- package/dist/tools/write-tools.js +97 -0
- package/dist/utils/cache-instance.js +30 -0
- package/dist/utils/cache.js +205 -0
- package/dist/utils/diagnostics.js +332 -0
- package/dist/utils/guards.js +17 -0
- package/dist/utils/image-size.js +160 -0
- package/dist/utils/log-args.js +47 -0
- package/dist/utils/logger.js +203 -0
- package/dist/utils/mcp-errors.js +47 -0
- package/dist/utils/refusal.js +30 -0
- package/dist/utils/sanitize.js +22 -0
- package/dist/utils/serial-queue.js +22 -0
- package/package.json +124 -4
|
@@ -0,0 +1,298 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Configuration management for FoundryVTT MCP Server
|
|
3
|
+
*
|
|
4
|
+
* This module validates the configuration resolved by `sources.ts` (environment,
|
|
5
|
+
* `.env`, configuration file, defaults) using Zod schemas.
|
|
6
|
+
*
|
|
7
|
+
* @version 0.1.0
|
|
8
|
+
* @author FoundryVTT MCP Team
|
|
9
|
+
*/
|
|
10
|
+
import { z } from 'zod';
|
|
11
|
+
import { describeSource, missingConfigMessage, resolveSettings, } from './sources.js';
|
|
12
|
+
/**
|
|
13
|
+
* Zod schema for validating server configuration
|
|
14
|
+
*
|
|
15
|
+
* Defines the structure and validation rules for all configuration options,
|
|
16
|
+
* including server settings, FoundryVTT connection details, and caching options.
|
|
17
|
+
*/
|
|
18
|
+
const ConfigSchema = z.object({
|
|
19
|
+
serverName: z.string().default('foundryvtt-mcp'),
|
|
20
|
+
logLevel: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
|
|
21
|
+
nodeEnv: z.enum(['development', 'production', 'test']).default('development'),
|
|
22
|
+
foundry: z.object({
|
|
23
|
+
url: z
|
|
24
|
+
.string()
|
|
25
|
+
.url('Invalid FoundryVTT URL - must include protocol (http:// or https://)')
|
|
26
|
+
.refine((url) => {
|
|
27
|
+
try {
|
|
28
|
+
const parsed = new URL(url);
|
|
29
|
+
return parsed.protocol === 'http:' || parsed.protocol === 'https:';
|
|
30
|
+
}
|
|
31
|
+
catch {
|
|
32
|
+
return false;
|
|
33
|
+
}
|
|
34
|
+
}, 'URL must use http:// or https:// protocol')
|
|
35
|
+
.refine((url) => {
|
|
36
|
+
try {
|
|
37
|
+
const parsed = new URL(url);
|
|
38
|
+
// Warning for localhost in production
|
|
39
|
+
if (process.env.NODE_ENV === 'production' &&
|
|
40
|
+
(parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1')) {
|
|
41
|
+
console.warn('⚠️ Warning: Using localhost URL in production environment');
|
|
42
|
+
}
|
|
43
|
+
return true;
|
|
44
|
+
}
|
|
45
|
+
catch {
|
|
46
|
+
return false;
|
|
47
|
+
}
|
|
48
|
+
}, 'URL validation failed'),
|
|
49
|
+
apiKey: z.string().optional(),
|
|
50
|
+
username: z.string().optional(),
|
|
51
|
+
password: z.string().optional(),
|
|
52
|
+
userId: z.string().optional(),
|
|
53
|
+
socketPath: z.string().default('/socket.io/'),
|
|
54
|
+
timeout: z.number().default(10000),
|
|
55
|
+
retryAttempts: z.number().default(3),
|
|
56
|
+
retryDelay: z.number().default(1000),
|
|
57
|
+
writeEnabled: z.boolean().default(false),
|
|
58
|
+
}),
|
|
59
|
+
cache: z.object({
|
|
60
|
+
enabled: z.boolean().default(true),
|
|
61
|
+
ttlSeconds: z.number().default(300), // 5 minutes
|
|
62
|
+
maxSize: z.number().default(1000),
|
|
63
|
+
}),
|
|
64
|
+
/**
|
|
65
|
+
* WebSocket relay for the companion Foundry module (canvas-only tools:
|
|
66
|
+
* scene screenshots, etc.). Disabled by default — most tools need only
|
|
67
|
+
* the Socket.IO document API, not a browser-side module.
|
|
68
|
+
*/
|
|
69
|
+
moduleBridge: z.object({
|
|
70
|
+
enabled: z.boolean().default(false),
|
|
71
|
+
port: z.number().default(31415),
|
|
72
|
+
}),
|
|
73
|
+
/**
|
|
74
|
+
* Invisible GM/Assistant-GM browser session that hosts the module bridge
|
|
75
|
+
* without a human needing to manually open and log into a second Foundry
|
|
76
|
+
* browser tab. Only launched when `moduleBridge` is also enabled — it
|
|
77
|
+
* exists purely to give the companion module somewhere GM-tier to run.
|
|
78
|
+
*
|
|
79
|
+
* By default (no `username`, or the same one as `foundry.username`) the
|
|
80
|
+
* page shares `FoundryClient`'s own session: one account, one cookie, no
|
|
81
|
+
* `/join` of its own. A different `username` (with its `password`, which
|
|
82
|
+
* falls back to `foundry.password`) is the advanced two-account mode: the
|
|
83
|
+
* page logs that account in through the `/join` form.
|
|
84
|
+
*/
|
|
85
|
+
headlessGm: z.object({
|
|
86
|
+
enabled: z.boolean().default(true),
|
|
87
|
+
username: z.string().optional(),
|
|
88
|
+
password: z.string().optional(),
|
|
89
|
+
executablePath: z.string().optional(),
|
|
90
|
+
}),
|
|
91
|
+
/**
|
|
92
|
+
* Local filesystem access to FoundryVTT's `Data` directory — the same
|
|
93
|
+
* directory the running Foundry server serves scene backgrounds and tile
|
|
94
|
+
* textures from (`assets/...` paths in Scene/Tile documents resolve
|
|
95
|
+
* relative to it). Optional: unset unless the MCP server runs on the same
|
|
96
|
+
* host as FoundryVTT. Enables `list_scene_assets` (browsing available map
|
|
97
|
+
* and prop art) and lets `create_scene`/`create_tile` read an image's
|
|
98
|
+
* real pixel dimensions from disk instead of requiring the caller to
|
|
99
|
+
* supply them by hand.
|
|
100
|
+
*/
|
|
101
|
+
assets: z.object({
|
|
102
|
+
dataPath: z.string().optional(),
|
|
103
|
+
}),
|
|
104
|
+
/**
|
|
105
|
+
* In-memory world-event ring backing `watch_events` — the cursor-addressed
|
|
106
|
+
* activity log an agent long-polls instead of re-calling
|
|
107
|
+
* `get_chat_messages`/`get_combat_state` in a loop.
|
|
108
|
+
*/
|
|
109
|
+
events: z.object({
|
|
110
|
+
bufferSize: z.number().default(500),
|
|
111
|
+
defaultWaitMs: z.number().default(25000),
|
|
112
|
+
}),
|
|
113
|
+
/**
|
|
114
|
+
* Shared-process mode: MCP clients start lightweight stdio relays that
|
|
115
|
+
* forward tool calls to one long-lived background process owning the
|
|
116
|
+
* FoundryVTT connection, the module bridge and the headless GM session.
|
|
117
|
+
* `enabled: false` keeps the all-in-one process (one connection per
|
|
118
|
+
* client-spawned instance).
|
|
119
|
+
*/
|
|
120
|
+
shared: z.object({
|
|
121
|
+
enabled: z.boolean().default(true),
|
|
122
|
+
/** Minutes with no relay connected before the shared process exits; 0 = never. */
|
|
123
|
+
idleTimeoutMinutes: z.number().min(0).default(5),
|
|
124
|
+
}),
|
|
125
|
+
});
|
|
126
|
+
/**
|
|
127
|
+
* No usable configuration: no FOUNDRY_URL anywhere, or a value that does not
|
|
128
|
+
* validate. The message says where the configuration file is expected and
|
|
129
|
+
* what it needs (see {@link missingConfigMessage}).
|
|
130
|
+
*/
|
|
131
|
+
export class ConfigError extends Error {
|
|
132
|
+
name = 'ConfigError';
|
|
133
|
+
}
|
|
134
|
+
function int(value) {
|
|
135
|
+
return value ? parseInt(value, 10) : undefined;
|
|
136
|
+
}
|
|
137
|
+
function bool(value) {
|
|
138
|
+
return value !== undefined ? value === 'true' : undefined;
|
|
139
|
+
}
|
|
140
|
+
/** The raw configuration object the schema validates, from resolved settings. */
|
|
141
|
+
function rawConfig(v) {
|
|
142
|
+
return {
|
|
143
|
+
serverName: v.MCP_SERVER_NAME,
|
|
144
|
+
logLevel: v.LOG_LEVEL,
|
|
145
|
+
nodeEnv: v.NODE_ENV,
|
|
146
|
+
foundry: {
|
|
147
|
+
url: v.FOUNDRY_URL,
|
|
148
|
+
apiKey: v.FOUNDRY_API_KEY,
|
|
149
|
+
username: v.FOUNDRY_USERNAME,
|
|
150
|
+
password: v.FOUNDRY_PASSWORD,
|
|
151
|
+
userId: v.FOUNDRY_USER_ID,
|
|
152
|
+
socketPath: v.FOUNDRY_SOCKET_PATH,
|
|
153
|
+
timeout: int(v.FOUNDRY_TIMEOUT),
|
|
154
|
+
retryAttempts: int(v.FOUNDRY_RETRY_ATTEMPTS),
|
|
155
|
+
retryDelay: int(v.FOUNDRY_RETRY_DELAY),
|
|
156
|
+
writeEnabled: bool(v.FOUNDRY_WRITE_ENABLED),
|
|
157
|
+
},
|
|
158
|
+
cache: {
|
|
159
|
+
enabled: bool(v.CACHE_ENABLED),
|
|
160
|
+
ttlSeconds: int(v.CACHE_TTL_SECONDS),
|
|
161
|
+
maxSize: int(v.CACHE_MAX_SIZE),
|
|
162
|
+
},
|
|
163
|
+
moduleBridge: {
|
|
164
|
+
enabled: bool(v.FOUNDRY_MODULE_BRIDGE_ENABLED),
|
|
165
|
+
port: int(v.FOUNDRY_MODULE_BRIDGE_PORT),
|
|
166
|
+
},
|
|
167
|
+
headlessGm: {
|
|
168
|
+
enabled: bool(v.FOUNDRY_HEADLESS_GM_ENABLED),
|
|
169
|
+
username: v.FOUNDRY_HEADLESS_GM_USERNAME,
|
|
170
|
+
password: v.FOUNDRY_HEADLESS_GM_PASSWORD,
|
|
171
|
+
executablePath: v.FOUNDRY_HEADLESS_GM_EXECUTABLE_PATH,
|
|
172
|
+
},
|
|
173
|
+
assets: {
|
|
174
|
+
dataPath: v.FOUNDRY_DATA_PATH,
|
|
175
|
+
},
|
|
176
|
+
events: {
|
|
177
|
+
bufferSize: int(v.FOUNDRY_EVENT_BUFFER_SIZE),
|
|
178
|
+
defaultWaitMs: int(v.FOUNDRY_EVENT_WAIT_MS),
|
|
179
|
+
},
|
|
180
|
+
shared: {
|
|
181
|
+
enabled: v.FOUNDRY_MCP_SHARED !== undefined ? v.FOUNDRY_MCP_SHARED !== 'false' : undefined,
|
|
182
|
+
idleTimeoutMinutes: v.FOUNDRY_MCP_IDLE_TIMEOUT_MINUTES
|
|
183
|
+
? Number(v.FOUNDRY_MCP_IDLE_TIMEOUT_MINUTES)
|
|
184
|
+
: undefined,
|
|
185
|
+
},
|
|
186
|
+
};
|
|
187
|
+
}
|
|
188
|
+
/** Schema path → environment variable, to name the setting in an error. */
|
|
189
|
+
const PATH_TO_SETTING = {
|
|
190
|
+
'foundry.url': 'FOUNDRY_URL',
|
|
191
|
+
logLevel: 'LOG_LEVEL',
|
|
192
|
+
nodeEnv: 'NODE_ENV',
|
|
193
|
+
'shared.idleTimeoutMinutes': 'FOUNDRY_MCP_IDLE_TIMEOUT_MINUTES',
|
|
194
|
+
};
|
|
195
|
+
/**
|
|
196
|
+
* Validates resolved settings into a configuration.
|
|
197
|
+
*
|
|
198
|
+
* @throws {ConfigError} with the full explanation when there is none usable
|
|
199
|
+
*/
|
|
200
|
+
export function configFromSettings(settings) {
|
|
201
|
+
if (!settings.values.FOUNDRY_URL) {
|
|
202
|
+
throw new ConfigError(missingConfigMessage(settings, 'FOUNDRY_URL is not set.'));
|
|
203
|
+
}
|
|
204
|
+
const parsed = ConfigSchema.safeParse(rawConfig(settings.values));
|
|
205
|
+
if (parsed.success) {
|
|
206
|
+
return parsed.data;
|
|
207
|
+
}
|
|
208
|
+
const problems = parsed.error.issues.map((issue) => {
|
|
209
|
+
const where = issue.path.join('.');
|
|
210
|
+
const name = PATH_TO_SETTING[where];
|
|
211
|
+
const source = name
|
|
212
|
+
? ` (${name}, from ${describeSource(settings.sources[name], settings)})`
|
|
213
|
+
: '';
|
|
214
|
+
return `${where}: ${issue.message}${source}`;
|
|
215
|
+
});
|
|
216
|
+
throw new ConfigError(missingConfigMessage(settings, `invalid settings — ${problems.join('; ')}.`));
|
|
217
|
+
}
|
|
218
|
+
/**
|
|
219
|
+
* Resolves and validates the configuration of this process.
|
|
220
|
+
*
|
|
221
|
+
* @throws {ConfigError} when there is none usable
|
|
222
|
+
*/
|
|
223
|
+
function loadConfig() {
|
|
224
|
+
const settings = resolveSettings();
|
|
225
|
+
_settings = settings;
|
|
226
|
+
return configFromSettings(settings);
|
|
227
|
+
}
|
|
228
|
+
/**
|
|
229
|
+
* Cached configuration instance
|
|
230
|
+
*/
|
|
231
|
+
let _config = null;
|
|
232
|
+
/** The settings the cached configuration was built from. */
|
|
233
|
+
let _settings = null;
|
|
234
|
+
/**
|
|
235
|
+
* Gets the global configuration instance
|
|
236
|
+
*
|
|
237
|
+
* This loads and caches the configuration on first access, allowing tests
|
|
238
|
+
* to set environment variables before triggering configuration validation.
|
|
239
|
+
* Throws {@link ConfigError} on access while no usable configuration exists;
|
|
240
|
+
* the next access tries again.
|
|
241
|
+
*
|
|
242
|
+
* @returns Validated configuration object
|
|
243
|
+
* @example
|
|
244
|
+
* ```typescript
|
|
245
|
+
* import { config } from './config/index.js';
|
|
246
|
+
*
|
|
247
|
+
* console.log(`Connecting to ${config.foundry.url}`);
|
|
248
|
+
* ```
|
|
249
|
+
*/
|
|
250
|
+
export const config = new Proxy({}, {
|
|
251
|
+
get(_target, prop) {
|
|
252
|
+
if (_config === null) {
|
|
253
|
+
_config = loadConfig();
|
|
254
|
+
}
|
|
255
|
+
return _config[prop];
|
|
256
|
+
},
|
|
257
|
+
});
|
|
258
|
+
/**
|
|
259
|
+
* Returns the whole validated configuration as a plain object. Unlike the
|
|
260
|
+
* {@link config} proxy it can be enumerated (e.g. to fingerprint it).
|
|
261
|
+
*
|
|
262
|
+
* @throws {ConfigError} when there is none usable (not cached: the next call retries)
|
|
263
|
+
*/
|
|
264
|
+
export function getConfig() {
|
|
265
|
+
if (_config === null) {
|
|
266
|
+
_config = loadConfig();
|
|
267
|
+
}
|
|
268
|
+
return _config;
|
|
269
|
+
}
|
|
270
|
+
/** The configuration, or the error that explains why there is none. */
|
|
271
|
+
export function tryGetConfig() {
|
|
272
|
+
try {
|
|
273
|
+
return { config: getConfig() };
|
|
274
|
+
}
|
|
275
|
+
catch (error) {
|
|
276
|
+
if (error instanceof ConfigError) {
|
|
277
|
+
return { error };
|
|
278
|
+
}
|
|
279
|
+
throw error;
|
|
280
|
+
}
|
|
281
|
+
}
|
|
282
|
+
/** Settings the current configuration was resolved from (resolving them if needed). */
|
|
283
|
+
export function configSettings() {
|
|
284
|
+
if (_settings === null) {
|
|
285
|
+
_settings = resolveSettings();
|
|
286
|
+
}
|
|
287
|
+
return _settings;
|
|
288
|
+
}
|
|
289
|
+
/**
|
|
290
|
+
* Resets the cached configuration - used for testing, and by a relay that
|
|
291
|
+
* re-reads its settings before each handshake
|
|
292
|
+
* @internal
|
|
293
|
+
*/
|
|
294
|
+
export function resetConfig() {
|
|
295
|
+
_config = null;
|
|
296
|
+
_settings = null;
|
|
297
|
+
}
|
|
298
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Where every setting comes from.
|
|
3
|
+
*
|
|
4
|
+
* One configuration file shared by every MCP client (`config.env`, dotenv
|
|
5
|
+
* syntax, the same names as the environment variables), under the client's
|
|
6
|
+
* own environment and an optional development `.env`. Per setting, the first
|
|
7
|
+
* layer that defines it wins:
|
|
8
|
+
*
|
|
9
|
+
* 1. the environment (the MCP client's `env` block, or the system)
|
|
10
|
+
* 2. `.env` in the working directory
|
|
11
|
+
* 3. the configuration file
|
|
12
|
+
* 4. the built-in default
|
|
13
|
+
*
|
|
14
|
+
* The provenance of each setting is kept, for `status` and for the shared
|
|
15
|
+
* process's "the file is authoritative" rule (see `shared/daemon.ts`).
|
|
16
|
+
* Kept free of config/logger imports: `status` and `stop` resolve settings
|
|
17
|
+
* without a valid configuration.
|
|
18
|
+
*/
|
|
19
|
+
import { readFileSync, statSync } from 'node:fs';
|
|
20
|
+
import os from 'node:os';
|
|
21
|
+
import path from 'node:path';
|
|
22
|
+
import dotenv from 'dotenv';
|
|
23
|
+
import { defaultStateDir } from '../shared/paths.js';
|
|
24
|
+
import { processSettings, readDotenv } from './env-layers.js';
|
|
25
|
+
/** Every setting the server reads, by environment variable name. */
|
|
26
|
+
export const KNOWN_SETTINGS = [
|
|
27
|
+
'FOUNDRY_URL',
|
|
28
|
+
'FOUNDRY_USERNAME',
|
|
29
|
+
'FOUNDRY_PASSWORD',
|
|
30
|
+
'FOUNDRY_USER_ID',
|
|
31
|
+
'FOUNDRY_API_KEY',
|
|
32
|
+
'FOUNDRY_SOCKET_PATH',
|
|
33
|
+
'FOUNDRY_WRITE_ENABLED',
|
|
34
|
+
'FOUNDRY_TIMEOUT',
|
|
35
|
+
'FOUNDRY_RETRY_ATTEMPTS',
|
|
36
|
+
'FOUNDRY_RETRY_DELAY',
|
|
37
|
+
'FOUNDRY_MODULE_BRIDGE_ENABLED',
|
|
38
|
+
'FOUNDRY_MODULE_BRIDGE_PORT',
|
|
39
|
+
'FOUNDRY_HEADLESS_GM_ENABLED',
|
|
40
|
+
'FOUNDRY_HEADLESS_GM_USERNAME',
|
|
41
|
+
'FOUNDRY_HEADLESS_GM_PASSWORD',
|
|
42
|
+
'FOUNDRY_HEADLESS_GM_EXECUTABLE_PATH',
|
|
43
|
+
'FOUNDRY_DATA_PATH',
|
|
44
|
+
'FOUNDRY_EVENT_BUFFER_SIZE',
|
|
45
|
+
'FOUNDRY_EVENT_WAIT_MS',
|
|
46
|
+
'FOUNDRY_MCP_SHARED',
|
|
47
|
+
'FOUNDRY_MCP_IDLE_TIMEOUT_MINUTES',
|
|
48
|
+
'CACHE_ENABLED',
|
|
49
|
+
'CACHE_TTL_SECONDS',
|
|
50
|
+
'CACHE_MAX_SIZE',
|
|
51
|
+
'LOG_LEVEL',
|
|
52
|
+
'NODE_ENV',
|
|
53
|
+
'MCP_SERVER_NAME',
|
|
54
|
+
];
|
|
55
|
+
/**
|
|
56
|
+
* Settings that locate the configuration itself: from the environment or
|
|
57
|
+
* `.env` only — the file cannot say where the file is.
|
|
58
|
+
*/
|
|
59
|
+
export const BOOTSTRAP_SETTINGS = ['FOUNDRY_MCP_CONFIG', 'FOUNDRY_MCP_STATE_DIR'];
|
|
60
|
+
/** Never shown: `status` and logs print `<set>` instead. */
|
|
61
|
+
export function isSecretSetting(name) {
|
|
62
|
+
return /PASSWORD|API_KEY|TOKEN|SECRET/.test(name);
|
|
63
|
+
}
|
|
64
|
+
/** The value as `status` may print it. */
|
|
65
|
+
export function displayValue(name, value) {
|
|
66
|
+
if (value === undefined) {
|
|
67
|
+
return '';
|
|
68
|
+
}
|
|
69
|
+
return isSecretSetting(name) ? '<set>' : value;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Path of the configuration file: `FOUNDRY_MCP_CONFIG`, else
|
|
73
|
+
* `<FOUNDRY_MCP_STATE_DIR>/config.env`, else `%LOCALAPPDATA%\foundryvtt-mcp\config.env`
|
|
74
|
+
* (Windows) or `$XDG_CONFIG_HOME/foundryvtt-mcp/config.env`
|
|
75
|
+
* (`~/.config/foundryvtt-mcp/config.env` without it).
|
|
76
|
+
*/
|
|
77
|
+
export function configFilePath(env = processSettings(), platform = process.platform) {
|
|
78
|
+
if (env.FOUNDRY_MCP_CONFIG) {
|
|
79
|
+
return path.resolve(env.FOUNDRY_MCP_CONFIG);
|
|
80
|
+
}
|
|
81
|
+
if (env.FOUNDRY_MCP_STATE_DIR || platform === 'win32') {
|
|
82
|
+
return path.join(defaultStateDir(platform, env), 'config.env');
|
|
83
|
+
}
|
|
84
|
+
const base = env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
|
|
85
|
+
return path.join(base, 'foundryvtt-mcp', 'config.env');
|
|
86
|
+
}
|
|
87
|
+
/** Reads and parses the configuration file; a missing file is not an error. */
|
|
88
|
+
export function readConfigFile(file, platform = process.platform) {
|
|
89
|
+
const state = { path: file, found: false, error: null, warning: null };
|
|
90
|
+
let text;
|
|
91
|
+
try {
|
|
92
|
+
text = readFileSync(file, 'utf8');
|
|
93
|
+
}
|
|
94
|
+
catch (error) {
|
|
95
|
+
if (error.code !== 'ENOENT') {
|
|
96
|
+
state.error = `cannot read the configuration file: ${error.message}`;
|
|
97
|
+
}
|
|
98
|
+
return { state, values: {} };
|
|
99
|
+
}
|
|
100
|
+
state.found = true;
|
|
101
|
+
if (platform !== 'win32') {
|
|
102
|
+
try {
|
|
103
|
+
if ((statSync(file).mode & 0o077) !== 0) {
|
|
104
|
+
state.warning = `${file} can be read by other users and holds passwords: run \`chmod 600 ${file}\``;
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
catch {
|
|
108
|
+
// Unreadable metadata: no warning rather than a false one.
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
try {
|
|
112
|
+
return { state, values: dotenv.parse(text) };
|
|
113
|
+
}
|
|
114
|
+
catch (error) {
|
|
115
|
+
state.error = `cannot parse the configuration file: ${error.message}`;
|
|
116
|
+
return { state, values: {} };
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
/** Every known setting with its effective value and where it comes from. */
|
|
120
|
+
export function resolveSettings(options = {}) {
|
|
121
|
+
const platform = options.platform ?? process.platform;
|
|
122
|
+
const env = options.env ?? process.env;
|
|
123
|
+
const cwd = options.cwd ?? process.cwd();
|
|
124
|
+
const dotenvFile = readDotenv(cwd, platform, env);
|
|
125
|
+
const located = { ...dotenvFile.values, ...env };
|
|
126
|
+
const { state: file, values: fromFile } = readConfigFile(configFilePath(located, platform), platform);
|
|
127
|
+
const layers = options.fileOnly
|
|
128
|
+
? [['file', fromFile]]
|
|
129
|
+
: [
|
|
130
|
+
['env', env],
|
|
131
|
+
['.env', dotenvFile.values],
|
|
132
|
+
['file', fromFile],
|
|
133
|
+
];
|
|
134
|
+
const values = {};
|
|
135
|
+
const sources = {};
|
|
136
|
+
for (const name of KNOWN_SETTINGS) {
|
|
137
|
+
sources[name] = 'default';
|
|
138
|
+
for (const [source, layer] of layers) {
|
|
139
|
+
const value = layer[name];
|
|
140
|
+
if (value !== undefined) {
|
|
141
|
+
values[name] = value;
|
|
142
|
+
sources[name] = source;
|
|
143
|
+
break;
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
return {
|
|
148
|
+
values,
|
|
149
|
+
sources,
|
|
150
|
+
file,
|
|
151
|
+
dotenvPath: options.fileOnly ? null : dotenvFile.path,
|
|
152
|
+
};
|
|
153
|
+
}
|
|
154
|
+
/** e.g. "14 from file, 2 from env". */
|
|
155
|
+
export function summarizeSources(sources) {
|
|
156
|
+
const counts = new Map();
|
|
157
|
+
for (const source of Object.values(sources)) {
|
|
158
|
+
if (source !== 'default') {
|
|
159
|
+
counts.set(source, (counts.get(source) ?? 0) + 1);
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
const order = ['file', 'env', '.env'];
|
|
163
|
+
const parts = order
|
|
164
|
+
.filter((source) => counts.has(source))
|
|
165
|
+
.map((source) => `${counts.get(source)} from ${source}`);
|
|
166
|
+
return parts.length > 0 ? parts.join(', ') : 'nothing set (defaults only)';
|
|
167
|
+
}
|
|
168
|
+
/** Human wording of a source, for notes and errors. */
|
|
169
|
+
export function describeSource(source, settings) {
|
|
170
|
+
switch (source) {
|
|
171
|
+
case 'env':
|
|
172
|
+
return "the client's env block (or the system environment)";
|
|
173
|
+
case '.env':
|
|
174
|
+
return settings?.dotenvPath ? settings.dotenvPath : '.env in the working directory';
|
|
175
|
+
case 'file':
|
|
176
|
+
return settings ? settings.file.path : 'the configuration file';
|
|
177
|
+
case 'default':
|
|
178
|
+
return 'the default';
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
/**
|
|
182
|
+
* What to tell a user with no usable configuration: where the file is
|
|
183
|
+
* expected and what it needs at minimum.
|
|
184
|
+
*/
|
|
185
|
+
export function missingConfigMessage(settings, problem) {
|
|
186
|
+
const { file } = settings;
|
|
187
|
+
const where = file.found
|
|
188
|
+
? `the configuration file ${file.path}`
|
|
189
|
+
: `${file.path} (this file does not exist yet)`;
|
|
190
|
+
return [
|
|
191
|
+
`FoundryVTT MCP is not configured: ${problem}`,
|
|
192
|
+
`Put the settings in ${where}, one KEY=value per line, at least:`,
|
|
193
|
+
' FOUNDRY_URL=http://localhost:30000',
|
|
194
|
+
' FOUNDRY_USERNAME=mcp-api',
|
|
195
|
+
" FOUNDRY_PASSWORD='your password'",
|
|
196
|
+
"Put each value between '…' (between `…` if it contains an apostrophe), or set the same",
|
|
197
|
+
'variables in the env block of your MCP client. See SETUP_GUIDE.md (Configuration).',
|
|
198
|
+
...(file.error ? [`Note: ${file.error}`] : []),
|
|
199
|
+
].join('\n');
|
|
200
|
+
}
|
|
201
|
+
//# sourceMappingURL=sources.js.map
|