@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,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