dsh-project-mcp 0.2.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/src/parse.ts ADDED
@@ -0,0 +1,637 @@
1
+ /**
2
+ * MCP document parsing for `dsh-project-mcp`.
3
+ *
4
+ * Reads Kimi Code / Claude-style documents (`{ "mcpServers": { ... } }`) and
5
+ * converts every entry into an `@deepseek-ai/dsh-mcp-client` config. The module
6
+ * is intentionally free of Cordis and of ambient process state: environment,
7
+ * project dotenv values, plugin-level `inputs` and credential values are
8
+ * injected through {@link ResolveContext}, so the whole conversion is
9
+ * unit-testable.
10
+ *
11
+ * Error policy: a broken row never blocks the document. It becomes an entry
12
+ * with `error` set, which the runtime surfaces as an `error` row.
13
+ *
14
+ * @module dsh-project-mcp/parse
15
+ */
16
+
17
+ import { readFileSync } from 'node:fs'
18
+ import type { Config as McpClientConfig } from '@deepseek-ai/dsh-mcp-client'
19
+
20
+ /**
21
+ * `serverName` accepted by mcp-client; anything else cannot own a tool
22
+ * namespace (`mcp__<serverName>__<rawName>`).
23
+ */
24
+ export const SERVER_NAME_PATTERN = /^[A-Za-z0-9_-]{1,32}$/
25
+
26
+ /** Whole-string `${NAME}` / `${input:NAME}` reference. */
27
+ const WHOLE_REF_PATTERN = /^\$\{(.+)\}$/
28
+
29
+ /** Any `${...}` reference inside a longer string. */
30
+ const INLINE_REF_PATTERN = /\$\{([^}]+)\}/g
31
+
32
+ /** The same grammar, read through `matchAll` where every reference is needed. */
33
+ const REFERENCE_PATTERN = /\$\{([^}]+)\}/g
34
+
35
+ /** Prefix selecting the interactive-input namespace of a reference. */
36
+ const INPUT_PREFIX = 'input:'
37
+
38
+ /** Maximum length of a generated `serverName`. */
39
+ const MAX_SERVER_NAME_LENGTH = 32
40
+
41
+ /** Severity of a parse diagnostic. */
42
+ export type IssueLevel = 'error' | 'warning'
43
+
44
+ /** One diagnostic produced while reading a document. */
45
+ export interface ParseIssue {
46
+ /** Absolute path of the document (or a pseudo-path for in-memory input). */
47
+ source: string
48
+ /** Server key the diagnostic belongs to, when it is entry-scoped. */
49
+ server?: string
50
+ /** Whether the entry is unusable (`error`) or merely notable (`warning`). */
51
+ level: IssueLevel
52
+ /** Human-readable description. */
53
+ message: string
54
+ /**
55
+ * Stable wire code of `message` (`projectMcp.host` namespace), for
56
+ * client-side translation. Additive: `message` keeps its byte-identical
57
+ * English and stays the fallback, and behavioural matches key on this field
58
+ * — never on the prose, which the client may have translated.
59
+ */
60
+ code?: string
61
+ /** Flat params of {@link ParseIssue.code}, stringified at emission. */
62
+ params?: Record<string, string>
63
+ }
64
+
65
+ /** One parsed `mcpServers` entry: exactly one of `config` / `error` is set. */
66
+ export interface ParsedEntry {
67
+ /** Key in `mcpServers` (or the sanitized form of it). */
68
+ name: string
69
+ /** `false` only for an explicit `enabled: false` / `disabled: true`. */
70
+ enabled: boolean
71
+ /** Absolute path of the document the entry came from. */
72
+ source: string
73
+ /** mcp-client config, ready to mount. */
74
+ config?: McpClientConfig
75
+ /** Why the entry cannot be mounted. */
76
+ error?: string
77
+ /**
78
+ * Stable wire code of `error` (`projectMcp.host` namespace) — the path by
79
+ * which a parse failure becomes a translated `row.detail` on the client.
80
+ */
81
+ errorCode?: string
82
+ /** Flat params of {@link ParsedEntry.errorCode}, stringified at emission. */
83
+ errorParams?: Record<string, string>
84
+ }
85
+
86
+ /** External values needed to expand `${...}` references. */
87
+ export interface ResolveContext {
88
+ /** Ambient environment (`process.env`). */
89
+ env: Record<string, string | undefined>
90
+ /** Project-local dotenv values (`<project>/.env`, then `<project>/.dsh/.env`). */
91
+ dotenv: Record<string, string>
92
+ /** Plugin-level `inputs` config: explicit `${input:NAME}` values. */
93
+ inputs: Record<string, string>
94
+ /** Values read from the DSH credentials file. */
95
+ secrets: Record<string, string>
96
+ /**
97
+ * Identity of the three value sources above, so a caller that caches whole
98
+ * parsed documents can tell "the same values answered this parse" from "the
99
+ * files moved". Opaque here: the parser never reads it.
100
+ */
101
+ stamp?: string
102
+ /** Project root used as the default `cwd` of stdio servers. */
103
+ projectRoot: string
104
+ /** Timeout applied to every generated config. */
105
+ toolCallTimeoutMs: number
106
+ /** Whether a failed initial connection should reject the mount. */
107
+ failOnStartupError: boolean
108
+ }
109
+
110
+ /** Result of parsing one document. */
111
+ export interface ParsedDocument {
112
+ /** Entries in document order. */
113
+ entries: ParsedEntry[]
114
+ /** Diagnostics for the document itself and for individual entries. */
115
+ issues: ParseIssue[]
116
+ /** `false` when the file could not be read or held no server map. */
117
+ ok: boolean
118
+ }
119
+
120
+ type Resolution =
121
+ | { ok: true; value: string }
122
+ | { ok: false; message: string; code: string; params?: Record<string, string> }
123
+
124
+ /** Expand every `${...}` reference inside `value`. */
125
+ export function expandValue(value: string, ctx: ResolveContext): Resolution {
126
+ const whole = WHOLE_REF_PATTERN.exec(value)
127
+ if (whole !== null) return resolveRef(whole[1] as string, ctx)
128
+ let failure: Extract<Resolution, { ok: false }> | undefined
129
+ const replaced = value.replace(INLINE_REF_PATTERN, (match, ref: string) => {
130
+ const resolved = resolveRef(ref, ctx)
131
+ if (resolved.ok) return resolved.value
132
+ failure ??= resolved
133
+ return match
134
+ })
135
+ if (failure !== undefined) return failure
136
+ return { ok: true, value: replaced }
137
+ }
138
+
139
+ /**
140
+ * Whether `value` contains at least one `${...}` reference.
141
+ *
142
+ * A value written as a reference does not live in the declaring document, so
143
+ * an editor is shown the key without it and a save keeps the declared text
144
+ * instead of substituting the resolved value.
145
+ * @param value - declared string value.
146
+ * @returns `true` when the value carries a reference.
147
+ */
148
+ export function hasReference(value: string): boolean {
149
+ return /\$\{[^}]+\}/.test(value)
150
+ }
151
+
152
+ /**
153
+ * Whether any `${...}` reference of `value` is answered from outside the
154
+ * process — by the project's `.env` or by the credentials file.
155
+ *
156
+ * Provenance only, mirroring {@link resolveRef}'s own fallback order (plugin
157
+ * inputs, then the project dotenv values, then `process.env`, then credentials):
158
+ * a value whose reference falls through to one of the two external maps is
159
+ * marked `fromCredentials` in a snapshot — the flag the editor reads as "do not
160
+ * write the resolved value back" — and stays as declared.
161
+ * @param value - declared string value.
162
+ * @param ctx - same resolve context the mount path uses.
163
+ * @returns `true` when at least one reference was answered externally.
164
+ */
165
+ export function referencesCredentials(value: string, ctx: ResolveContext): boolean {
166
+ for (const match of value.matchAll(REFERENCE_PATTERN)) {
167
+ const ref = match[1]?.trim() ?? ''
168
+ const isInput = ref.startsWith(INPUT_PREFIX)
169
+ const key = (isInput ? ref.slice(INPUT_PREFIX.length) : ref).trim()
170
+ if (key === '') continue
171
+ if (isInput && firstSet(ctx.inputs[key]) !== undefined) continue
172
+ if (firstSet(ctx.dotenv[key]) !== undefined) return true
173
+ if (firstSet(ctx.env[key]) !== undefined) continue
174
+ if (firstSet(ctx.secrets[key]) !== undefined) return true
175
+ }
176
+ return false
177
+ }
178
+
179
+ /**
180
+ * Resolve one `${...}` reference.
181
+ *
182
+ * `${input:NAME}` is answered by the plugin's own `inputs`, then by the same
183
+ * chain a plain `${NAME}` uses, so a project can keep using the prefix its
184
+ * `mcp.json` already carries. The chain is project-local first: the project's
185
+ * dotenv documents, then the ambient environment, then the global credentials
186
+ * file. An empty string counts as unset at every step.
187
+ */
188
+ function resolveRef(ref: string, ctx: ResolveContext): Resolution {
189
+ const name = ref.trim()
190
+ if (name.startsWith(INPUT_PREFIX)) {
191
+ const key = name.slice(INPUT_PREFIX.length).trim()
192
+ if (key === '') return { ok: false, message: 'empty ${input:} reference', code: 'parse.ref.empty' }
193
+ const explicit = firstSet(ctx.inputs[key])
194
+ if (explicit !== undefined) return { ok: true, value: explicit }
195
+ const value = projectValue(ctx, key)
196
+ if (value === undefined) {
197
+ return {
198
+ ok: false,
199
+ message: `input "${key}" is not set (looked in plugin inputs, the project .env, the environment, and the credentials file)`,
200
+ code: 'parse.ref.inputUnset',
201
+ params: { key },
202
+ }
203
+ }
204
+ return { ok: true, value }
205
+ }
206
+ const value = projectValue(ctx, name)
207
+ if (value === undefined) {
208
+ return {
209
+ ok: false,
210
+ message: `variable "${name}" is not set (looked in the project .env, the environment, and the credentials file)`,
211
+ code: 'parse.ref.varUnset',
212
+ params: { name },
213
+ }
214
+ }
215
+ return { ok: true, value }
216
+ }
217
+
218
+ /** Project dotenv → ambient environment → credentials, for one key. */
219
+ function projectValue(ctx: ResolveContext, key: string): string | undefined {
220
+ return firstSet(ctx.dotenv[key], ctx.env[key], ctx.secrets[key])
221
+ }
222
+
223
+ /** The first non-empty value, or `undefined` when every source was unset. */
224
+ function firstSet(...values: (string | undefined)[]): string | undefined {
225
+ for (const value of values) {
226
+ if (value !== undefined && value !== '') return value
227
+ }
228
+ return undefined
229
+ }
230
+
231
+ /** Sanitize an arbitrary `mcpServers` key into a valid `serverName`. */
232
+ export function slugifyServerName(name: string): string {
233
+ const slug = name
234
+ .replace(/[^A-Za-z0-9_-]+/g, '-')
235
+ .replace(/^-+|-+$/g, '')
236
+ return slug.slice(0, MAX_SERVER_NAME_LENGTH)
237
+ }
238
+
239
+ /**
240
+ * Parse the text of one MCP document.
241
+ * @param text - raw file content.
242
+ * @param source - absolute path used for diagnostics and for entry `source`.
243
+ * @param ctx - values used to expand references and to fill config defaults.
244
+ * @returns parsed entries plus diagnostics; `ok` reports whether a server map was found.
245
+ */
246
+ export function parseDocument(text: string, source: string, ctx: ResolveContext): ParsedDocument {
247
+ const issues: ParseIssue[] = []
248
+ let data: unknown
249
+ try {
250
+ data = JSON.parse(text) as unknown
251
+ } catch (error) {
252
+ return {
253
+ entries: [],
254
+ issues: [
255
+ {
256
+ source,
257
+ level: 'error',
258
+ message: `invalid JSON: ${errorText(error)}`,
259
+ code: 'parse.json.invalid',
260
+ params: { error: errorText(error) },
261
+ },
262
+ ],
263
+ ok: false,
264
+ }
265
+ }
266
+ const servers = extractServerMap(data)
267
+ if (servers === null) {
268
+ return {
269
+ entries: [],
270
+ issues: [
271
+ {
272
+ source,
273
+ level: 'error',
274
+ message: 'expected an object with an "mcpServers" object',
275
+ code: 'parse.doc.notObject',
276
+ },
277
+ ],
278
+ ok: false,
279
+ }
280
+ }
281
+ const entries: ParsedEntry[] = []
282
+ const seen = new Set<string>()
283
+ for (const [key, raw] of Object.entries(servers)) {
284
+ const name = sanitizeName(key, source, issues)
285
+ if (name === undefined) continue
286
+ if (seen.has(name)) {
287
+ const message = `serverName "${name}" is declared twice in this document`
288
+ const code = 'parse.server.duplicateName'
289
+ const params = { name }
290
+ issues.push({ source, server: name, level: 'error', message, code, params })
291
+ entries.push({ name, enabled: false, source, error: message, errorCode: code, errorParams: params })
292
+ continue
293
+ }
294
+ seen.add(name)
295
+ entries.push(toEntry(name, raw, source, ctx, issues))
296
+ }
297
+ return { entries, issues, ok: true }
298
+ }
299
+
300
+ /** Read and parse one document; a missing file yields `undefined`. */
301
+ export function parseDocumentFile(path: string, ctx: ResolveContext): ParsedDocument | undefined {
302
+ let text: string
303
+ try {
304
+ text = readFileSync(path, 'utf8')
305
+ } catch {
306
+ return undefined
307
+ }
308
+ return parseDocument(text, path, ctx)
309
+ }
310
+
311
+ /**
312
+ * Extract a `name -> entry` map from a document: `mcpServers`, `servers`, or a
313
+ * bare flat map whose values all look like server entries.
314
+ * @param data - parsed document (or any JSON value).
315
+ * @returns the server map, or `null` when the value holds none.
316
+ */
317
+ export function extractServerMap(data: unknown): Record<string, unknown> | null {
318
+ if (data === null || typeof data !== 'object' || Array.isArray(data)) return null
319
+ const record = data as Record<string, unknown>
320
+ for (const key of ['mcpServers', 'servers'] as const) {
321
+ const container = record[key]
322
+ if (container !== null && typeof container === 'object' && !Array.isArray(container)) {
323
+ return container as Record<string, unknown>
324
+ }
325
+ }
326
+ const values = Object.values(record)
327
+ if (values.length === 0) return null
328
+ const looksFlat = values.every(
329
+ (value) => value !== null && typeof value === 'object' && !Array.isArray(value),
330
+ )
331
+ return looksFlat ? record : null
332
+ }
333
+
334
+ /**
335
+ * Bring a `mcpServers` key into the `serverName` alphabet, or reject it when
336
+ * nothing usable remains. A rename is a warning, not an error: the entry stays
337
+ * mountable and only its tool namespace changes.
338
+ */
339
+ function sanitizeName(key: string, source: string, issues: ParseIssue[]): string | undefined {
340
+ if (SERVER_NAME_PATTERN.test(key)) return key
341
+ const slug = slugifyServerName(key)
342
+ if (slug === '') {
343
+ issues.push({
344
+ source,
345
+ server: key,
346
+ level: 'error',
347
+ message: `"${key}" cannot be converted into a valid serverName (${String(SERVER_NAME_PATTERN)})`,
348
+ code: 'parse.server.badName',
349
+ params: { key, pattern: String(SERVER_NAME_PATTERN) },
350
+ })
351
+ return undefined
352
+ }
353
+ issues.push({
354
+ source,
355
+ server: slug,
356
+ level: 'warning',
357
+ message: `serverName "${key}" is not a valid mcp-client name; using "${slug}"`,
358
+ code: 'parse.server.renamedName',
359
+ params: { key, slug },
360
+ })
361
+ return slug
362
+ }
363
+
364
+ function toEntry(
365
+ name: string,
366
+ raw: unknown,
367
+ source: string,
368
+ ctx: ResolveContext,
369
+ issues: ParseIssue[],
370
+ ): ParsedEntry {
371
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
372
+ return fail(name, source, issues, 'entry must be an object', 'parse.entry.notObject')
373
+ }
374
+ const record = raw as Record<string, unknown>
375
+ const enabled = record.enabled !== false && record.disabled !== true
376
+
377
+ const declared = record.type ?? record.transport
378
+ if (declared !== undefined && typeof declared !== 'string') {
379
+ return fail(name, source, issues, '"type" must be a string', 'parse.entry.badType')
380
+ }
381
+ const normalized = declared === undefined ? undefined : declared.toLowerCase()
382
+ if (
383
+ normalized !== undefined
384
+ && !['stdio', 'http', 'streamable-http', 'sse'].includes(normalized)
385
+ ) {
386
+ return fail(name, source, issues, '"type" must be one of "stdio", "http", "streamable-http" or "sse"', 'parse.entry.typeUnknown')
387
+ }
388
+ const hasUrl = record.url !== undefined
389
+ const useHttp = normalized === undefined ? hasUrl : normalized !== 'stdio'
390
+ return useHttp
391
+ ? buildHttpEntry(name, record, source, ctx, issues, enabled)
392
+ : buildStdioEntry(name, record, source, ctx, issues, enabled)
393
+ }
394
+
395
+ function buildStdioEntry(
396
+ name: string,
397
+ record: Record<string, unknown>,
398
+ source: string,
399
+ ctx: ResolveContext,
400
+ issues: ParseIssue[],
401
+ enabled: boolean,
402
+ ): ParsedEntry {
403
+ const command = record.command
404
+ if (typeof command !== 'string' || command === '') {
405
+ return fail(name, source, issues, 'stdio servers require a "command"', 'parse.entry.noCommand')
406
+ }
407
+ const args = stringArray(record.args)
408
+ if (args === undefined) return fail(name, source, issues, '"args" must be an array of strings', 'parse.entry.badArgs')
409
+ const env = stringRecord(record.env)
410
+ if (env === undefined) return fail(name, source, issues, '"env" must be an object of strings', 'parse.entry.badEnv')
411
+ if (record.cwd !== undefined && typeof record.cwd !== 'string') {
412
+ return fail(name, source, issues, '"cwd" must be a string', 'parse.entry.badCwd')
413
+ }
414
+
415
+ const expandedCommand = expandValue(command, ctx)
416
+ if (!expandedCommand.ok) return fail(name, source, issues, expandedCommand.message, expandedCommand.code, expandedCommand.params)
417
+ const expandedArgs = expandAll(args, ctx)
418
+ if (!expandedArgs.ok) return fail(name, source, issues, expandedArgs.message, expandedArgs.code, expandedArgs.params)
419
+ const expandedEnv = expandRecord(env, ctx)
420
+ if (!expandedEnv.ok) return fail(name, source, issues, expandedEnv.message, expandedEnv.code, expandedEnv.params)
421
+ const expandedCwd = expandValue(
422
+ typeof record.cwd === 'string' && record.cwd !== '' ? record.cwd : ctx.projectRoot,
423
+ ctx,
424
+ )
425
+ if (!expandedCwd.ok) return fail(name, source, issues, expandedCwd.message, expandedCwd.code, expandedCwd.params)
426
+
427
+ return {
428
+ name,
429
+ enabled,
430
+ source,
431
+ config: {
432
+ transport: 'stdio',
433
+ serverName: name,
434
+ command: expandedCommand.value,
435
+ args: expandedArgs.value,
436
+ env: expandedEnv.value,
437
+ cwd: expandedCwd.value,
438
+ toolCallTimeoutMs: ctx.toolCallTimeoutMs,
439
+ failOnStartupError: ctx.failOnStartupError,
440
+ },
441
+ }
442
+ }
443
+
444
+ function buildHttpEntry(
445
+ name: string,
446
+ record: Record<string, unknown>,
447
+ source: string,
448
+ ctx: ResolveContext,
449
+ issues: ParseIssue[],
450
+ enabled: boolean,
451
+ ): ParsedEntry {
452
+ const url = record.url
453
+ if (typeof url !== 'string' || url === '') {
454
+ return fail(name, source, issues, 'http servers require a "url"', 'parse.entry.noUrl')
455
+ }
456
+ const headers = stringRecord(record.headers)
457
+ if (headers === undefined) {
458
+ return fail(name, source, issues, '"headers" must be an object of strings', 'parse.entry.badHeaders')
459
+ }
460
+ const expandedUrl = expandValue(url, ctx)
461
+ if (!expandedUrl.ok) return fail(name, source, issues, expandedUrl.message, expandedUrl.code, expandedUrl.params)
462
+ const expandedHeaders = expandRecord(headers, ctx)
463
+ if (!expandedHeaders.ok) return fail(name, source, issues, expandedHeaders.message, expandedHeaders.code, expandedHeaders.params)
464
+ return {
465
+ name,
466
+ enabled,
467
+ source,
468
+ config: {
469
+ transport: 'streamable-http',
470
+ serverName: name,
471
+ url: expandedUrl.value,
472
+ headers: expandedHeaders.value,
473
+ toolCallTimeoutMs: ctx.toolCallTimeoutMs,
474
+ failOnStartupError: ctx.failOnStartupError,
475
+ },
476
+ }
477
+ }
478
+
479
+ function fail(
480
+ name: string,
481
+ source: string,
482
+ issues: ParseIssue[],
483
+ message: string,
484
+ code: string,
485
+ params?: Record<string, string>,
486
+ ): ParsedEntry {
487
+ issues.push({
488
+ source,
489
+ server: name,
490
+ level: 'error',
491
+ message,
492
+ code,
493
+ ...(params === undefined ? {} : { params }),
494
+ })
495
+ return {
496
+ name,
497
+ enabled: false,
498
+ source,
499
+ error: message,
500
+ errorCode: code,
501
+ ...(params === undefined ? {} : { errorParams: params }),
502
+ }
503
+ }
504
+
505
+ function expandAll(values: string[], ctx: ResolveContext): { ok: true; value: string[] } | Extract<Resolution, { ok: false }> {
506
+ const result: string[] = []
507
+ for (const value of values) {
508
+ const expanded = expandValue(value, ctx)
509
+ if (!expanded.ok) return expanded
510
+ result.push(expanded.value)
511
+ }
512
+ return { ok: true, value: result }
513
+ }
514
+
515
+ function expandRecord(
516
+ record: Record<string, string>,
517
+ ctx: ResolveContext,
518
+ ): { ok: true; value: Record<string, string> } | Extract<Resolution, { ok: false }> {
519
+ const result: Record<string, string> = {}
520
+ for (const [key, value] of Object.entries(record)) {
521
+ const expanded = expandValue(value, ctx)
522
+ if (!expanded.ok) {
523
+ return {
524
+ ok: false,
525
+ message: `${key}: ${expanded.message}`,
526
+ // `{name}` deliberately carries the inner failure's English prose: the wrapper
527
+ // covers three inner shapes (varUnset / inputUnset / empty ref) whose sentences
528
+ // and params differ and collide with the flat `{key}` grammar, so no single
529
+ // translated template can fill back byte-identically. Accepted partial
530
+ // translation — F-48 ledger Ruling 4; only the wrapper punctuation localizes.
531
+ code: 'parse.ref.failedInKey',
532
+ params: { key, name: expanded.message },
533
+ }
534
+ }
535
+ result[key] = expanded.value
536
+ }
537
+ return { ok: true, value: result }
538
+ }
539
+
540
+ function stringArray(value: unknown): string[] | undefined {
541
+ if (value === undefined) return []
542
+ if (!Array.isArray(value)) return undefined
543
+ const result: string[] = []
544
+ for (const item of value) {
545
+ if (typeof item !== 'string') return undefined
546
+ result.push(item)
547
+ }
548
+ return result
549
+ }
550
+
551
+ function stringRecord(value: unknown): Record<string, string> | undefined {
552
+ if (value === undefined) return {}
553
+ if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
554
+ const result: Record<string, string> = {}
555
+ for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
556
+ if (typeof item !== 'string') return undefined
557
+ result[key] = item
558
+ }
559
+ return result
560
+ }
561
+
562
+ /**
563
+ * Merge per-document entry lists in priority order; a later document overrides
564
+ * an earlier entry with the same `serverName`, keeping the position where that
565
+ * name first appeared.
566
+ * @param groups - entry lists from lowest to highest priority.
567
+ * @returns merged entries plus the names that were overridden.
568
+ */
569
+ export function mergeEntries(groups: ParsedEntry[][]): { entries: ParsedEntry[]; overridden: string[] } {
570
+ const merged = new Map<string, ParsedEntry>()
571
+ const overridden: string[] = []
572
+ for (const group of groups) {
573
+ for (const entry of group) {
574
+ if (merged.has(entry.name)) overridden.push(entry.name)
575
+ merged.set(entry.name, entry)
576
+ }
577
+ }
578
+ return { entries: [...merged.values()], overridden }
579
+ }
580
+
581
+ /** Parse a YAML-ish credentials file into a flat string map. */
582
+ export function parseCredentials(text: string): Record<string, string> {
583
+ const result: Record<string, string> = {}
584
+ for (const line of text.split(/\r?\n/)) {
585
+ const match = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*?)\s*$/.exec(line)
586
+ if (match === null) continue
587
+ const value = (match[2] as string).replace(/^(['"])(.*)\1$/, '$2')
588
+ if (value === '') continue
589
+ result[match[1] as string] = value
590
+ }
591
+ return result
592
+ }
593
+
594
+ /**
595
+ * Parse a dotenv document into a flat string map.
596
+ *
597
+ * The subset a project needs next to its `mcp.json`: one `KEY=value` per line,
598
+ * an optional `export `, single or double quotes, and `#` comments — on their
599
+ * own line, or after whitespace on a value line. Double quotes understand the
600
+ * usual escapes (`\n`, `\r`, `\t`, `\"`, `\\`); single quotes stay literal. An
601
+ * empty value is skipped, exactly as {@link parseCredentials} skips one, so
602
+ * `${NAME}` sees "unset" either way.
603
+ * @param text - dotenv document contents.
604
+ * @returns the values it declares, in first-wins order of the map.
605
+ */
606
+ export function parseEnvFile(text: string): Record<string, string> {
607
+ const result: Record<string, string> = {}
608
+ for (const line of text.split(/\r?\n/)) {
609
+ const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/.exec(line)
610
+ if (match === null) continue
611
+ const key = match[1] as string
612
+ const value = unquoteEnvValue(match[2] as string)
613
+ if (value === '') continue
614
+ result[key] = value
615
+ }
616
+ return result
617
+ }
618
+
619
+ /** One dotenv value: unquoted (with an optional trailing comment), or quoted. */
620
+ function unquoteEnvValue(raw: string): string {
621
+ if (raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) {
622
+ return raw
623
+ .slice(1, -1)
624
+ .replace(/\\n/g, '\n')
625
+ .replace(/\\r/g, '\r')
626
+ .replace(/\\t/g, '\t')
627
+ .replace(/\\"/g, '"')
628
+ .replace(/\\\\/g, '\\')
629
+ }
630
+ if (raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2) return raw.slice(1, -1)
631
+ const comment = raw.indexOf(' #')
632
+ return (comment === -1 ? raw : raw.slice(0, comment)).trim()
633
+ }
634
+
635
+ function errorText(error: unknown): string {
636
+ return error instanceof Error ? error.message : String(error)
637
+ }