@agimon-ai/mcp-proxy 0.10.5 → 0.10.7

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/dist/index.d.cts DELETED
@@ -1,1368 +0,0 @@
1
- import * as _$_modelcontextprotocol_sdk_server_index_js0 from "@modelcontextprotocol/sdk/server/index.js";
2
- import { Server } from "@modelcontextprotocol/sdk/server/index.js";
3
- import { CallToolResult, GetPromptResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
4
- import { z } from "zod";
5
- import { NodeTelemetryHandle } from "@agimon-ai/log-sink-mcp";
6
-
7
- //#region src/types/index.d.ts
8
- /**
9
- * Tool definition for MCP
10
- * @property name - The unique name of the tool
11
- * @property description - Human-readable description of what the tool does
12
- * @property inputSchema - JSON Schema defining the tool's input parameters
13
- */
14
- interface ToolDefinition {
15
- name: string;
16
- description: string;
17
- inputSchema: Record<string, unknown>;
18
- _meta?: Record<string, unknown>;
19
- }
20
- /**
21
- * Base tool interface following MCP SDK patterns
22
- * @template TInput - The type of input the tool accepts
23
- */
24
- interface Tool<TInput = unknown> {
25
- getDefinition(): ToolDefinition | Promise<ToolDefinition>;
26
- getInputSchema(): z.ZodObject<z.ZodRawShape>;
27
- execute(input: TInput): Promise<CallToolResult>;
28
- }
29
- /**
30
- * Transport mode constants
31
- */
32
- declare const TRANSPORT_MODE: {
33
- readonly STDIO: "stdio";
34
- readonly HTTP: "http";
35
- readonly SSE: "sse";
36
- };
37
- /**
38
- * Transport mode type derived from TRANSPORT_MODE constants
39
- */
40
- type TransportMode = (typeof TRANSPORT_MODE)[keyof typeof TRANSPORT_MODE];
41
- /**
42
- * Transport configuration options
43
- * @property mode - The transport mode to use (stdio, http, or sse)
44
- * @property port - Port number for HTTP/SSE modes (not used for STDIO)
45
- * @property host - Host address for HTTP/SSE modes (not used for STDIO)
46
- */
47
- interface TransportConfig {
48
- mode: TransportMode;
49
- port: number;
50
- host?: string;
51
- }
52
- /**
53
- * Base interface for all transport handlers
54
- */
55
- interface TransportHandler {
56
- start(): Promise<void>;
57
- stop(): Promise<void>;
58
- }
59
- /**
60
- * HTTP transport specific types
61
- */
62
- interface HttpTransportHandler$1 extends TransportHandler {
63
- getPort(): number;
64
- getHost(): string;
65
- }
66
- /**
67
- * Runtime state persisted for HTTP mcp-proxy instances.
68
- * @property serverId - Unique mcp-proxy server identifier
69
- * @property host - Host bound by the HTTP transport
70
- * @property port - Port bound by the HTTP transport
71
- * @property transport - Transport mode for the runtime record
72
- * @property shutdownToken - Secret token required for admin shutdown requests
73
- * @property startedAt - ISO timestamp when the runtime started
74
- * @property pid - Process ID of the running mcp-proxy process
75
- * @property configPath - Optional path to the config file used to start the server
76
- */
77
- interface RuntimeStateRecord {
78
- serverId: string;
79
- host: string;
80
- port: number;
81
- transport: 'http';
82
- shutdownToken: string;
83
- startedAt: string;
84
- pid: number;
85
- configPath?: string;
86
- }
87
- /**
88
- * Optional admin settings for HTTP transport lifecycle actions.
89
- * @property serverId - Server identifier surfaced via health responses
90
- * @property shutdownToken - Secret token accepted by the admin shutdown endpoint
91
- * @property onShutdownRequested - Callback invoked after a valid shutdown request is received
92
- */
93
- interface HttpTransportAdminOptions {
94
- serverId?: string;
95
- shutdownToken?: string;
96
- onShutdownRequested?: () => Promise<void>;
97
- }
98
- /**
99
- * Health payload exposed by HTTP transport.
100
- * @property status - Health status string for liveness checks
101
- * @property transport - Transport mode for the serving endpoint
102
- * @property serverId - Optional server identifier for target verification
103
- */
104
- interface HttpTransportHealthResponse {
105
- status: 'ok';
106
- transport: 'http';
107
- serverId?: string;
108
- }
109
- /**
110
- * Admin shutdown response payload.
111
- * @property ok - Whether shutdown request handling succeeded
112
- * @property message - Human-readable outcome message
113
- * @property serverId - Optional server identifier associated with this response
114
- */
115
- interface HttpTransportShutdownResponse {
116
- ok: boolean;
117
- message: string;
118
- serverId?: string;
119
- }
120
- /**
121
- * Runtime record lookup filters.
122
- * @property host - Optional host filter for runtime discovery
123
- * @property port - Optional port filter for runtime discovery
124
- */
125
- interface RuntimeLookupOptions {
126
- host?: string;
127
- port?: number;
128
- }
129
- /**
130
- * Runtime service contract.
131
- */
132
- interface RuntimeStateManager {
133
- /**
134
- * Persist a runtime state record.
135
- * @param record - Runtime metadata to persist
136
- * @returns Promise that resolves when write completes
137
- */
138
- write(record: RuntimeStateRecord): Promise<void>;
139
- /**
140
- * Read a runtime state record by server ID.
141
- * @param serverId - Target mcp-proxy server identifier
142
- * @returns Matching runtime record, or null when no record exists
143
- */
144
- read(serverId: string): Promise<RuntimeStateRecord | null>;
145
- /**
146
- * List all persisted runtime records.
147
- * @returns Array of runtime records
148
- */
149
- list(): Promise<RuntimeStateRecord[]>;
150
- /**
151
- * Remove a runtime state record by server ID.
152
- * @param serverId - Target mcp-proxy server identifier
153
- * @returns Promise that resolves when delete completes
154
- */
155
- remove(serverId: string): Promise<void>;
156
- }
157
- /**
158
- * Remote MCP server configuration types
159
- */
160
- type McpServerTransportType = 'stdio' | 'http' | 'sse';
161
- /**
162
- * Configuration for stdio-based MCP server connections
163
- * @property command - The command to execute to start the server
164
- * @property args - Optional arguments to pass to the command
165
- * @property env - Optional environment variables for the subprocess
166
- */
167
- interface McpStdioConfig {
168
- command: string;
169
- args?: string[];
170
- env?: Record<string, string>;
171
- }
172
- /**
173
- * Configuration for HTTP-based MCP server connections
174
- * @property url - The URL of the HTTP endpoint
175
- * @property headers - Optional HTTP headers to include in requests
176
- */
177
- interface McpHttpConfig {
178
- url: string;
179
- headers?: Record<string, string>;
180
- }
181
- /**
182
- * Configuration for SSE-based MCP server connections
183
- * @property url - The URL of the SSE endpoint
184
- * @property headers - Optional HTTP headers to include in requests
185
- */
186
- interface McpSseConfig {
187
- url: string;
188
- headers?: Record<string, string>;
189
- }
190
- /**
191
- * Union type for MCP server transport configurations
192
- * - McpStdioConfig: Used for local subprocess communication via stdio (has 'command' property)
193
- * - McpHttpConfig: Used for HTTP-based remote connections (has 'url' property)
194
- * - McpSseConfig: Used for Server-Sent Events streaming connections (has 'url' property)
195
- *
196
- * Note: McpHttpConfig and McpSseConfig have identical structure. Discrimination between
197
- * them should be done using the transport type field in McpServerConfig, not by
198
- * structural inspection of the config object.
199
- */
200
- type McpServerTransportConfig = McpStdioConfig | McpHttpConfig | McpSseConfig;
201
- /**
202
- * Configuration for an MCP server connection
203
- * @property name - Unique identifier for the server
204
- * @property instruction - Optional instruction text describing the server's purpose
205
- * @property toolBlacklist - Optional list of tool names to exclude from this server
206
- * @property omitToolDescription - Whether to omit tool descriptions in listings
207
- * @property prompts - Optional prompts configuration for skill conversion
208
- * @property transport - The transport type (stdio, http, or sse)
209
- * @property config - Transport-specific configuration options
210
- * @property timeout - Optional connection timeout in milliseconds (default: 30000)
211
- * @property disabled - Whether this server is disabled and should not be started
212
- */
213
- interface McpServerConfig {
214
- name: string;
215
- instruction?: string;
216
- toolBlacklist?: string[];
217
- omitToolDescription?: boolean;
218
- prompts?: Record<string, PromptConfig>;
219
- transport: McpServerTransportType;
220
- config: McpServerTransportConfig;
221
- timeout?: number;
222
- /** Optional per-request timeout in milliseconds for tool calls (default: 60000 from MCP SDK) */
223
- requestTimeout?: number;
224
- disabled?: boolean;
225
- }
226
- /**
227
- * Skills configuration
228
- * @property paths - Array of paths to skills directories
229
- */
230
- interface SkillsConfig {
231
- paths: string[];
232
- }
233
- /**
234
- * Prompt skill configuration for converting prompts to executable skills
235
- * @property name - Skill name identifier
236
- * @property description - Skill description shown in describe_tools
237
- * @property folder - Optional folder path for skill resources
238
- */
239
- interface PromptSkillConfig {
240
- name: string;
241
- description: string;
242
- folder?: string;
243
- }
244
- /**
245
- * Prompt configuration that can be converted to a skill
246
- * @property skill - Optional skill conversion configuration
247
- */
248
- interface PromptConfig {
249
- skill?: PromptSkillConfig;
250
- }
251
- /**
252
- * Remote configuration response containing MCP server definitions
253
- * @property id - Optional unique server identifier
254
- * @property mcpServers - Map of server names to their configurations
255
- * @property skills - Optional skills configuration with paths
256
- */
257
- interface RemoteMcpConfiguration {
258
- id?: string;
259
- proxy?: {
260
- type?: string;
261
- port?: number;
262
- host?: string;
263
- };
264
- mcpServers: Record<string, McpServerConfig>;
265
- skills?: SkillsConfig;
266
- }
267
- /**
268
- * MCP tool information returned from listTools
269
- * @property name - The tool name
270
- * @property description - Human-readable description
271
- * @property inputSchema - JSON Schema for tool inputs
272
- */
273
- interface McpToolInfo {
274
- name: string;
275
- description?: string;
276
- inputSchema: Record<string, unknown>;
277
- _meta?: Record<string, unknown>;
278
- }
279
- /**
280
- * MCP resource information returned from listResources
281
- * @property uri - Resource URI
282
- * @property name - Display name
283
- * @property description - Human-readable description
284
- * @property mimeType - Optional MIME type
285
- */
286
- interface McpResourceInfo {
287
- uri: string;
288
- name?: string;
289
- description?: string;
290
- mimeType?: string;
291
- }
292
- /**
293
- * MCP prompt information returned from listPrompts
294
- * @property name - Prompt name
295
- * @property description - Human-readable description
296
- * @property arguments - Optional argument definitions
297
- */
298
- interface McpPromptInfo {
299
- name: string;
300
- description?: string;
301
- arguments?: Array<{
302
- name: string;
303
- description?: string;
304
- required?: boolean;
305
- }>;
306
- }
307
- /**
308
- * MCP client connection interface for communicating with remote MCP servers
309
- * @property serverName - The name identifier for this server connection
310
- * @property serverInstruction - Optional instruction text for the server
311
- * @property toolBlacklist - Optional list of tool names to exclude
312
- * @property omitToolDescription - Whether to omit tool descriptions
313
- * @property prompts - Optional prompts configuration for skill conversion
314
- * @property transport - The transport type used for this connection
315
- */
316
- interface McpClientConnection {
317
- serverName: string;
318
- serverInstruction?: string;
319
- toolBlacklist?: string[];
320
- omitToolDescription?: boolean;
321
- prompts?: Record<string, PromptConfig>;
322
- transport: McpServerTransportType;
323
- /** List available tools from the server */
324
- listTools(): Promise<McpToolInfo[]>;
325
- /** List available resources from the server */
326
- listResources(): Promise<McpResourceInfo[]>;
327
- /** List available prompts from the server */
328
- listPrompts(): Promise<McpPromptInfo[]>;
329
- /** Call a tool with the given name and arguments */
330
- callTool(name: string, args: Record<string, unknown>, options?: {
331
- timeout?: number;
332
- }): Promise<CallToolResult>;
333
- /** Read a resource by URI */
334
- readResource(uri: string): Promise<ReadResourceResult>;
335
- /** Get a prompt by name with optional arguments */
336
- getPrompt(name: string, args?: Record<string, unknown>): Promise<GetPromptResult>;
337
- /** Close the connection */
338
- close(): Promise<void>;
339
- }
340
- /**
341
- * Cached prompt-based skill metadata.
342
- * Used to avoid re-fetching prompt front matter during startup discovery.
343
- */
344
- interface CachedPromptSkillInfo {
345
- promptName: string;
346
- skill: PromptSkillConfig;
347
- autoDetected?: boolean;
348
- }
349
- /**
350
- * Cached server metadata used for startup-time capability discovery.
351
- */
352
- interface CachedServerDefinition {
353
- serverName: string;
354
- serverInstruction?: string;
355
- omitToolDescription?: boolean;
356
- toolBlacklist?: string[];
357
- tools: McpToolInfo[];
358
- resources: McpResourceInfo[];
359
- prompts: McpPromptInfo[];
360
- promptSkills: CachedPromptSkillInfo[];
361
- }
362
- /**
363
- * Cached file-based skill metadata.
364
- */
365
- interface CachedFileSkillInfo {
366
- name: string;
367
- description: string;
368
- location: 'project' | 'user';
369
- basePath: string;
370
- }
371
- /**
372
- * Cache file storing precomputed definitions for mcp-proxy startup.
373
- */
374
- interface DefinitionsCacheFile {
375
- version: 1;
376
- oneMcpVersion?: string;
377
- generatedAt: string;
378
- configPath?: string;
379
- configHash?: string;
380
- serverId?: string;
381
- servers: Record<string, CachedServerDefinition>;
382
- skills: CachedFileSkillInfo[];
383
- failures: Array<{
384
- serverName: string;
385
- error: string;
386
- }>;
387
- }
388
- /**
389
- * Skill metadata from YAML frontmatter in SKILL.md files
390
- * @property name - Skill identifier used with skill__ prefix
391
- * @property description - Short description shown in describe_tools
392
- * @property license - Optional license information
393
- */
394
- interface SkillMetadata {
395
- name: string;
396
- description: string;
397
- license?: string;
398
- }
399
- /**
400
- * Skill definition loaded from skill files
401
- * @property name - Skill identifier used with skill__ prefix
402
- * @property description - Short description shown in describe_tools
403
- * @property location - Where the skill was loaded from ('project' or 'user')
404
- * @property content - The markdown content of the skill (without frontmatter)
405
- * @property basePath - The directory path where the skill is located
406
- */
407
- interface Skill {
408
- name: string;
409
- description: string;
410
- location: 'project' | 'user';
411
- content: string;
412
- basePath: string;
413
- }
414
- //#endregion
415
- //#region src/services/logger.d.ts
416
- interface LoggerLike {
417
- trace(message: string, data?: unknown): void;
418
- debug(message: string, data?: unknown): void;
419
- info(message: string, data?: unknown): void;
420
- warn(message: string, data?: unknown): void;
421
- error(message: string, data?: unknown): void;
422
- getTraceContext?(): {
423
- traceId?: string;
424
- spanId?: string;
425
- };
426
- }
427
- interface ProxyLoggerHandle extends LoggerLike {
428
- backend: NodeTelemetryHandle['backend'];
429
- enabled: boolean;
430
- endpoint?: string;
431
- filePath?: string;
432
- flush(): Promise<void>;
433
- shutdown(): Promise<void>;
434
- }
435
- interface ProxyLoggerOptions {
436
- env?: NodeJS.ProcessEnv;
437
- workspaceRoot?: string;
438
- serviceName?: string;
439
- serviceVersion?: string;
440
- logDir?: string;
441
- logFileName?: string;
442
- maxFileSizeBytes?: number;
443
- maxFileCount?: number;
444
- }
445
- declare function createProxyLogger(options?: ProxyLoggerOptions): Promise<ProxyLoggerHandle>;
446
- //#endregion
447
- //#region src/services/ConfigFetcherService.d.ts
448
- interface ConfigFetcherOptions {
449
- configFilePath?: string;
450
- cacheTtlMs?: number;
451
- useCache?: boolean;
452
- remoteCacheTtlMs?: number;
453
- }
454
- /**
455
- * Service for fetching and caching MCP server configurations from local file and remote sources
456
- * Supports merging multiple remote configs with local config
457
- */
458
- declare class ConfigFetcherService {
459
- private configFilePath?;
460
- private cacheTtlMs;
461
- private cachedConfig;
462
- private lastFetchTime;
463
- private remoteConfigCache;
464
- private logger;
465
- constructor(options: ConfigFetcherOptions, logger?: LoggerLike);
466
- /**
467
- * Fetch MCP configuration from local file and remote sources with caching
468
- * Merges remote configs with local config based on merge strategy
469
- * @param forceRefresh - Force reload from source, bypassing cache
470
- */
471
- fetchConfiguration(forceRefresh?: boolean): Promise<RemoteMcpConfiguration>;
472
- /**
473
- * Load raw configuration data from a local file (supports JSON and YAML)
474
- * Returns unparsed config data to allow access to remoteConfigs
475
- */
476
- private loadRawConfigFromFile;
477
- /**
478
- * Parse raw config data using Zod schema
479
- * Filters out remoteConfigs to avoid including them in the final config
480
- */
481
- private parseConfig;
482
- /**
483
- * Load configuration from a remote URL with caching
484
- *
485
- * SECURITY NOTE: This method fetches remote configs based on URLs from the local config file.
486
- * This is intentional and safe because:
487
- * 1. URLs are user-controlled via their local config file (not external input)
488
- * 2. SSRF protection validates URLs before fetching (blocks private IPs, enforces HTTPS)
489
- * 3. Users explicitly opt-in to remote configs in their local configuration
490
- * 4. This enables centralized config management (intended feature, not a vulnerability)
491
- *
492
- * CodeQL alert "file-access-to-http" is a false positive here - we're not leaking
493
- * file contents to arbitrary URLs, we're fetching configs from user-specified sources.
494
- */
495
- private loadFromUrl;
496
- /**
497
- * Interpolate environment variables in a string
498
- * Supports ${VAR_NAME} syntax
499
- */
500
- private interpolateEnvVars;
501
- /**
502
- * Merge two MCP configurations based on the specified merge strategy
503
- * @param localConfig Configuration loaded from local file
504
- * @param remoteConfig Configuration loaded from remote URL
505
- * @param mergeStrategy Strategy for merging configs
506
- * @returns Merged configuration
507
- */
508
- private mergeConfigurations;
509
- /**
510
- * Clear the cached configuration
511
- */
512
- clearCache(): void;
513
- /**
514
- * Check if cache is valid
515
- */
516
- isCacheValid(): boolean;
517
- }
518
- //#endregion
519
- //#region src/services/McpClientManagerService.d.ts
520
- /**
521
- * Service for managing MCP client connections to remote servers
522
- */
523
- declare class McpClientManagerService {
524
- private clients;
525
- private serverConfigs;
526
- private connectionPromises;
527
- private logger;
528
- private readonly repositoryPath;
529
- constructor(logger?: LoggerLike, repositoryPath?: string);
530
- /**
531
- * Kill all stdio MCP server child processes.
532
- * Delegates to disconnectAll() so each client closes its child process and
533
- * releases the corresponding process-registry lease before shutdown exits.
534
- */
535
- cleanupChildProcesses(): Promise<void>;
536
- /**
537
- * Connect to an MCP server based on its configuration with timeout
538
- * Uses the timeout from server config, falling back to default (30s)
539
- */
540
- connectToServer(serverName: string, config: McpServerConfig): Promise<void>;
541
- registerServerConfigs(configs: Record<string, McpServerConfig>): void;
542
- getKnownServerNames(): string[];
543
- getServerRequestTimeout(serverName: string): number | undefined;
544
- ensureConnected(serverName: string): Promise<McpClientConnection>;
545
- private createConnection;
546
- /**
547
- * Perform the actual connection to MCP server
548
- */
549
- private performConnection;
550
- private connectStdioClient;
551
- private connectHttpClient;
552
- private connectSseClient;
553
- /**
554
- * Get a connected client by server name
555
- */
556
- getClient(serverName: string): McpClientConnection | undefined;
557
- /**
558
- * Get all connected clients
559
- */
560
- getAllClients(): McpClientConnection[];
561
- /**
562
- * Disconnect from a specific server
563
- */
564
- disconnectServer(serverName: string): Promise<void>;
565
- /**
566
- * Disconnect from all servers
567
- */
568
- disconnectAll(): Promise<void>;
569
- /**
570
- * Check if a server is connected
571
- */
572
- isConnected(serverName: string): boolean;
573
- }
574
- //#endregion
575
- //#region src/services/SkillService.d.ts
576
- /**
577
- * Service for loading and managing skills from configured skill directories.
578
- *
579
- * Skills are markdown files with YAML frontmatter that can be invoked via
580
- * the skill__ prefix in describe_tools and use_tool.
581
- *
582
- * Skills are only enabled when explicitly configured via the `skills.paths` array
583
- * in the MCP config.
584
- *
585
- * @example
586
- * // Config with skills enabled:
587
- * // skills:
588
- * // paths:
589
- * // - ".claude/skills"
590
- * // - "/absolute/path/to/skills"
591
- *
592
- * const skillService = new SkillService('/project/root', ['.claude/skills']);
593
- * const skills = await skillService.getSkills();
594
- */
595
- declare class SkillService {
596
- private cwd;
597
- private skillPaths;
598
- private cachedSkills;
599
- private skillsByName;
600
- /** Active file watchers for skill directories */
601
- private watchers;
602
- /** Polling timers used when native file watching is unavailable */
603
- private pollingTimers;
604
- /** Callback invoked when cache is invalidated due to file changes */
605
- private onCacheInvalidated?;
606
- private logger;
607
- /**
608
- * Creates a new SkillService instance
609
- * @param cwd - Current working directory for resolving relative paths
610
- * @param skillPaths - Array of paths to skills directories
611
- * @param options - Optional configuration
612
- * @param options.onCacheInvalidated - Callback invoked when cache is invalidated due to file changes
613
- */
614
- constructor(cwd: string, skillPaths: string[], options?: {
615
- onCacheInvalidated?: () => void;
616
- }, logger?: LoggerLike);
617
- /**
618
- * Get all available skills from configured directories.
619
- * Results are cached after first load.
620
- *
621
- * Skills from earlier entries in the config take precedence over
622
- * skills with the same name from later entries.
623
- *
624
- * @returns Array of loaded skills
625
- * @throws SkillLoadError if a critical error occurs during loading
626
- */
627
- getSkills(): Promise<Skill[]>;
628
- /**
629
- * Get a specific skill by name with O(1) lookup from cache.
630
- * @param name - The skill name (without skill__ prefix)
631
- * @returns The skill if found, undefined otherwise
632
- */
633
- getSkill(name: string): Promise<Skill | undefined>;
634
- /**
635
- * Clears the cached skills to force a fresh reload on the next getSkills() or getSkill() call.
636
- * Use this when skill files have been modified on disk.
637
- */
638
- clearCache(): void;
639
- /**
640
- * Starts watching skill directories for changes to SKILL.md files.
641
- * When changes are detected, the cache is automatically invalidated.
642
- *
643
- * Uses Node.js fs.watch with recursive option for efficient directory monitoring.
644
- * Only invalidates cache when SKILL.md files are modified.
645
- *
646
- * @example
647
- * const skillService = new SkillService(cwd, skillPaths, {
648
- * onCacheInvalidated: () => console.log('Skills cache invalidated')
649
- * });
650
- * await skillService.startWatching();
651
- */
652
- startWatching(): Promise<void>;
653
- /**
654
- * Stops all active file watchers.
655
- * Should be called when the service is being disposed.
656
- */
657
- stopWatching(): void;
658
- /**
659
- * Watches a directory for changes to SKILL.md files.
660
- * @param dirPath - Directory path to watch
661
- * @param signal - AbortSignal to stop watching
662
- */
663
- private watchDirectory;
664
- private invalidateCache;
665
- private isWatchResourceLimitError;
666
- private startPollingDirectory;
667
- private createSkillSnapshot;
668
- private collectSkillSnapshots;
669
- private snapshotsEqual;
670
- /**
671
- * Load skills from a directory.
672
- * Supports both flat structure (SKILL.md) and nested structure (name/SKILL.md).
673
- *
674
- * @param dirPath - Path to the skills directory
675
- * @param location - Whether this is a 'project' or 'user' skill directory
676
- * @returns Array of successfully loaded skills (skips invalid skills)
677
- * @throws SkillLoadError if there's a critical I/O error
678
- *
679
- * @example
680
- * // Load skills from project directory
681
- * const skills = await this.loadSkillsFromDirectory('/path/to/.claude/skills', 'project');
682
- * // Returns: [{ name: 'pdf', description: '...', location: 'project', ... }]
683
- */
684
- private loadSkillsFromDirectory;
685
- /**
686
- * Load a single skill file and parse its frontmatter.
687
- * Supports multi-line YAML values using literal (|) and folded (>) block scalars.
688
- *
689
- * @param filePath - Path to the SKILL.md file
690
- * @param location - Whether this is a 'project' or 'user' skill
691
- * @returns The loaded skill, or null if the file is invalid (missing required frontmatter)
692
- * @throws SkillLoadError if there's an I/O error reading the file
693
- *
694
- * @example
695
- * // Load a skill from a file
696
- * const skill = await this.loadSkillFile('/path/to/pdf/SKILL.md', 'project');
697
- * // Returns: { name: 'pdf', description: 'PDF skill', location: 'project', content: '...', basePath: '/path/to/pdf' }
698
- * // Returns null if frontmatter is missing name or description
699
- */
700
- private loadSkillFile;
701
- }
702
- //#endregion
703
- //#region src/services/DefinitionsCacheService.d.ts
704
- interface DefinitionsCacheServiceOptions {
705
- cacheData?: DefinitionsCacheFile;
706
- }
707
- interface PromptSkillMatch {
708
- serverName: string;
709
- promptName: string;
710
- skill: PromptSkillConfig;
711
- autoDetected?: boolean;
712
- }
713
- interface CollectOptions {
714
- serverId?: string;
715
- configPath?: string;
716
- configHash?: string;
717
- oneMcpVersion?: string;
718
- }
719
- declare class DefinitionsCacheService {
720
- private clientManager;
721
- private skillService?;
722
- private cacheData?;
723
- private liveDefinitionsPromise;
724
- private mergedDefinitionsPromise;
725
- private logger;
726
- constructor(clientManager: McpClientManagerService, skillService?: SkillService, options?: DefinitionsCacheServiceOptions, logger?: LoggerLike);
727
- static readFromFile(filePath: string): Promise<DefinitionsCacheFile>;
728
- static writeToFile(filePath: string, cache: DefinitionsCacheFile): Promise<void>;
729
- static getDefaultCachePath(configFilePath: string): string;
730
- static generateConfigHash(config: unknown): string;
731
- static isCacheValid(cache: DefinitionsCacheFile, options: {
732
- configHash?: string;
733
- oneMcpVersion?: string;
734
- }): boolean;
735
- static clearFile(filePath: string): Promise<void>;
736
- clearLiveCache(): void;
737
- setCacheData(cacheData?: DefinitionsCacheFile): void;
738
- collectForCache(options?: CollectOptions): Promise<DefinitionsCacheFile>;
739
- getDefinitions(): Promise<DefinitionsCacheFile>;
740
- getServerDefinitions(): Promise<CachedServerDefinition[]>;
741
- getServersForTool(toolName: string): Promise<string[]>;
742
- getToolSchema(serverName: string, toolName: string): Promise<Record<string, unknown> | undefined>;
743
- getServersForResource(uri: string): Promise<string[]>;
744
- getPromptSkillByName(skillName: string): Promise<PromptSkillMatch | undefined>;
745
- getCachedFileSkills(): Promise<CachedFileSkillInfo[]>;
746
- private getLiveDefinitions;
747
- private collectLiveDefinitions;
748
- private collectFileSkills;
749
- private toCachedFileSkill;
750
- private listPromptsSafe;
751
- private listResourcesSafe;
752
- private collectPromptSkillsForClient;
753
- }
754
- //#endregion
755
- //#region src/services/RuntimeStateService.d.ts
756
- /**
757
- * Runtime state persistence implementation.
758
- */
759
- declare class RuntimeStateService implements RuntimeStateManager {
760
- private runtimeDir;
761
- private logger;
762
- constructor(runtimeDir?: string, logger?: LoggerLike);
763
- /**
764
- * Resolve default runtime directory under the user's home cache path.
765
- * @returns Absolute runtime directory path
766
- */
767
- static getDefaultRuntimeDir(): string;
768
- /**
769
- * Build runtime state file path for a given server ID.
770
- * @param serverId - Target mcp-proxy server identifier
771
- * @returns Absolute runtime file path
772
- */
773
- private getRecordPath;
774
- /**
775
- * Persist a runtime state record.
776
- * @param record - Runtime metadata to persist
777
- * @returns Promise that resolves when write completes
778
- */
779
- write(record: RuntimeStateRecord): Promise<void>;
780
- /**
781
- * Read a runtime state record by server ID.
782
- * @param serverId - Target mcp-proxy server identifier
783
- * @returns Matching runtime record, or null when no record exists
784
- */
785
- read(serverId: string): Promise<RuntimeStateRecord | null>;
786
- /**
787
- * List all persisted runtime records.
788
- * @returns Array of runtime records
789
- */
790
- list(): Promise<RuntimeStateRecord[]>;
791
- /**
792
- * Remove a runtime state record by server ID.
793
- * @param serverId - Target mcp-proxy server identifier
794
- * @returns Promise that resolves when delete completes
795
- */
796
- remove(serverId: string): Promise<void>;
797
- }
798
- //#endregion
799
- //#region src/services/StopServerService/types.d.ts
800
- /**
801
- * Stop request options.
802
- * @property serverId - Explicit mcp-proxy server identifier to stop
803
- * @property host - Host fallback for runtime lookup
804
- * @property port - Port fallback for runtime lookup
805
- * @property token - Optional shutdown token override
806
- * @property force - Skip server ID verification against /health when true
807
- * @property timeoutMs - Maximum time to wait for shutdown completion
808
- */
809
- interface StopServerRequest {
810
- serverId?: string;
811
- host?: string;
812
- port?: number;
813
- token?: string;
814
- force?: boolean;
815
- timeoutMs?: number;
816
- }
817
- /**
818
- * Stop command result payload.
819
- * @property ok - Whether the shutdown completed successfully
820
- * @property serverId - Stopped mcp-proxy server identifier
821
- * @property host - Host that served the runtime
822
- * @property port - Port that served the runtime
823
- * @property message - Human-readable shutdown result message
824
- */
825
- interface StopServerResult {
826
- ok: true;
827
- serverId: string;
828
- host: string;
829
- port: number;
830
- message: string;
831
- }
832
- //#endregion
833
- //#region src/services/StopServerService/StopServerService.d.ts
834
- /**
835
- * Service for resolving runtime targets and stopping them safely.
836
- */
837
- declare class StopServerService {
838
- private runtimeStateService;
839
- private logger;
840
- constructor(runtimeStateService?: RuntimeStateManager, logger?: LoggerLike);
841
- /**
842
- * Resolve a target runtime and stop it cooperatively.
843
- * @param request - Stop request options
844
- * @returns Stop result payload
845
- */
846
- stop(request: StopServerRequest): Promise<StopServerResult>;
847
- /**
848
- * Resolve a runtime record from explicit ID or a unique host/port pair.
849
- * @param request - Stop request options
850
- * @returns Matching runtime record
851
- */
852
- private resolveRuntime;
853
- /**
854
- * Read the runtime health payload.
855
- * @param runtime - Runtime to query
856
- * @param timeoutMs - Request timeout in milliseconds
857
- * @returns Reachability status and optional payload
858
- */
859
- private fetchHealth;
860
- /**
861
- * Send authenticated shutdown request to the admin endpoint.
862
- * @param runtime - Runtime to stop
863
- * @param shutdownToken - Bearer token for the admin endpoint
864
- * @param timeoutMs - Request timeout in milliseconds
865
- * @returns Parsed shutdown response payload
866
- */
867
- private requestShutdown;
868
- /**
869
- * Poll until the target runtime is no longer reachable.
870
- * @param runtime - Runtime expected to stop
871
- * @param timeoutMs - Maximum wait time in milliseconds
872
- * @returns Promise that resolves when shutdown is observed
873
- */
874
- private waitForShutdown;
875
- /**
876
- * Perform a fetch with an abort timeout.
877
- * @param url - Target URL
878
- * @param init - Fetch options
879
- * @param timeoutMs - Timeout in milliseconds
880
- * @returns Fetch response
881
- */
882
- private fetchWithTimeout;
883
- }
884
- //#endregion
885
- //#region src/tools/DescribeToolsTool.d.ts
886
- /**
887
- * Input schema for the DescribeToolsTool
888
- * @property toolNames - Array of tool names to get detailed information about
889
- */
890
- declare const DescribeToolsToolInputSchema: z.ZodObject<{
891
- toolNames: z.ZodArray<z.ZodString>;
892
- }, z.core.$strip>;
893
- type DescribeToolsToolInput = z.infer<typeof DescribeToolsToolInputSchema>;
894
- /**
895
- * DescribeToolsTool provides progressive disclosure of MCP tools and skills.
896
- *
897
- * This tool lists available tools from all connected MCP servers and skills
898
- * from the configured skills directories. Users can query for specific tools
899
- * or skills to get detailed input schemas and descriptions.
900
- *
901
- * Tool naming conventions:
902
- * - Unique tools: use plain name (e.g., "browser_click")
903
- * - Clashing tools: use serverName__toolName format (e.g., "playwright__click")
904
- * - Skills: use skill__skillName format (e.g., "skill__pdf")
905
- *
906
- * @example
907
- * const tool = new DescribeToolsTool(clientManager, skillService);
908
- * const definition = await tool.getDefinition();
909
- * const result = await tool.execute({ toolNames: ['browser_click', 'skill__pdf'] });
910
- */
911
- declare class DescribeToolsTool implements Tool<DescribeToolsToolInput> {
912
- static readonly TOOL_NAME = "describe_tools";
913
- private clientManager;
914
- private skillService;
915
- private definitionsCacheService;
916
- private readonly liquid;
917
- /** Unique server identifier for this mcp-proxy instance */
918
- private serverId;
919
- /**
920
- * Creates a new DescribeToolsTool instance
921
- * @param clientManager - The MCP client manager for accessing remote servers
922
- * @param skillService - Optional skill service for loading skills
923
- * @param serverId - Unique server identifier for this mcp-proxy instance
924
- */
925
- constructor(clientManager: McpClientManagerService, skillService?: SkillService, serverId?: string, definitionsCacheService?: DefinitionsCacheService);
926
- /**
927
- * Clears the cached auto-detected skills from prompt front-matter.
928
- * Use this when prompt configurations may have changed or when
929
- * the skill service cache is invalidated.
930
- */
931
- clearAutoDetectedSkillsCache(): void;
932
- /**
933
- * Collects skills derived from prompt configurations across all connected MCP servers.
934
- * Includes both explicitly configured prompts and auto-detected skills from front-matter.
935
- *
936
- * @returns Array of skill template data derived from prompts
937
- */
938
- private collectPromptSkills;
939
- /**
940
- * Finds a prompt-based skill by name from all connected MCP servers.
941
- * Searches both explicitly configured prompts and auto-detected skills from front-matter.
942
- *
943
- * @param skillName - The skill name to search for
944
- * @returns Object with serverName, promptName, and skill config, or undefined if not found
945
- */
946
- private findPromptSkill;
947
- /**
948
- * Retrieves skill content from a prompt-based skill configuration.
949
- * Fetches the prompt from the MCP server and extracts text content.
950
- * Handles both explicitly configured prompts and auto-detected skills from front-matter.
951
- *
952
- * @param skillName - The skill name being requested
953
- * @returns SkillDescription if found and successfully fetched, undefined otherwise
954
- */
955
- private getPromptSkillContent;
956
- /**
957
- * Builds the combined toolkit description using a single Liquid template.
958
- *
959
- * Collects all tools from connected MCP servers and all skills, then renders
960
- * them together using the toolkit-description.liquid template.
961
- *
962
- * Tool names are prefixed with serverName__ when the same tool exists
963
- * on multiple servers. Skill names are prefixed with skill__ when they
964
- * clash with MCP tools or other skills.
965
- *
966
- * @returns Object with rendered description and set of all tool names
967
- */
968
- private buildToolkitDescription;
969
- /**
970
- * Gets the tool definition including available tools and skills in a unified format.
971
- *
972
- * The definition includes:
973
- * - All MCP tools from connected servers
974
- * - All available skills (file-based and prompt-based)
975
- * - Unified instructions for querying capability details
976
- *
977
- * Tool names are prefixed with serverName__ when clashing.
978
- * Skill names are prefixed with skill__ when clashing.
979
- *
980
- * @returns Tool definition with description and input schema
981
- */
982
- getInputSchema(): z.ZodObject<z.ZodRawShape>;
983
- getDefinition(): Promise<ToolDefinition>;
984
- private runLookups;
985
- /**
986
- * Executes tool description lookup for the requested tool and skill names.
987
- *
988
- * Handles three types of lookups:
989
- * 1. skill__name - Returns skill information from SkillService
990
- * 2. serverName__toolName - Returns tool from specific server
991
- * 3. plainToolName - Returns tool(s) from all servers (multiple if clashing)
992
- *
993
- * @param input - Object containing toolNames array
994
- * @returns CallToolResult with tool/skill descriptions or error
995
- */
996
- execute(rawInput: Record<string, unknown>): Promise<CallToolResult>;
997
- }
998
- //#endregion
999
- //#region src/tools/SearchListToolsTool.d.ts
1000
- declare const SearchListToolsToolInputSchema: z.ZodObject<{
1001
- capability: z.ZodOptional<z.ZodString>;
1002
- serverName: z.ZodOptional<z.ZodString>;
1003
- }, z.core.$strip>;
1004
- type SearchListToolsToolInput = z.infer<typeof SearchListToolsToolInputSchema>;
1005
- declare class SearchListToolsTool implements Tool<SearchListToolsToolInput> {
1006
- readonly _clientManager: unknown;
1007
- private readonly definitionsCacheService;
1008
- static readonly TOOL_NAME = "list_tools";
1009
- constructor(_clientManager: unknown, definitionsCacheService: DefinitionsCacheService);
1010
- private formatToolName;
1011
- getInputSchema(): z.ZodObject<z.ZodRawShape>;
1012
- getDefinition(): Promise<ToolDefinition>;
1013
- execute(rawInput: Record<string, unknown>): Promise<CallToolResult>;
1014
- }
1015
- //#endregion
1016
- //#region src/tools/UseToolTool.d.ts
1017
- /**
1018
- * Input schema for UseToolTool
1019
- * @property toolName - Name of the tool or skill to execute
1020
- * @property toolArgs - Arguments to pass to the tool (from describe_tools schema)
1021
- */
1022
- declare const UseToolToolInputSchema: z.ZodObject<{
1023
- toolName: z.ZodString;
1024
- toolArgs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
1025
- }, z.core.$strip>;
1026
- type UseToolToolInput = z.infer<typeof UseToolToolInputSchema>;
1027
- /**
1028
- * UseToolTool executes MCP tools and skills with proper error handling.
1029
- *
1030
- * This tool supports three invocation patterns:
1031
- * 1. skill__skillName - Invokes a skill from the configured skills directory
1032
- * 2. serverName__toolName - Invokes a tool on a specific MCP server
1033
- * 3. plainToolName - Searches all servers for a unique tool match
1034
- *
1035
- * @example
1036
- * const tool = new UseToolTool(clientManager, skillService);
1037
- * await tool.execute({ toolName: 'skill__pdf' }); // Invoke a skill
1038
- * await tool.execute({ toolName: 'playwright__browser_click', toolArgs: { ref: 'btn' } });
1039
- */
1040
- declare class UseToolTool implements Tool<UseToolToolInput> {
1041
- static readonly TOOL_NAME = "use_tool";
1042
- private clientManager;
1043
- private skillService;
1044
- private definitionsCacheService;
1045
- /** Unique server identifier for this mcp-proxy instance */
1046
- private serverId;
1047
- /**
1048
- * Creates a new UseToolTool instance
1049
- * @param clientManager - The MCP client manager for accessing remote servers
1050
- * @param skillService - Optional skill service for loading and executing skills
1051
- * @param serverId - Unique server identifier for this mcp-proxy instance
1052
- */
1053
- constructor(clientManager: McpClientManagerService, skillService?: SkillService, serverId?: string, definitionsCacheService?: DefinitionsCacheService);
1054
- /**
1055
- * Returns the MCP tool definition with name, description, and input schema.
1056
- *
1057
- * The definition describes how to use this tool to execute MCP tools or skills,
1058
- * including the skill__ prefix format for skill invocations.
1059
- *
1060
- * @returns The tool definition conforming to MCP spec
1061
- */
1062
- getInputSchema(): z.ZodObject<z.ZodRawShape>;
1063
- getDefinition(): ToolDefinition;
1064
- /**
1065
- * Returns guidance message for skill invocation.
1066
- *
1067
- * Skills are not executed via use_tool - they provide instructions that should
1068
- * be followed directly. This method returns a message directing users to use
1069
- * describe_tools to get the skill details and follow its instructions.
1070
- *
1071
- * @param skill - The skill that was requested
1072
- * @returns CallToolResult with guidance message
1073
- */
1074
- /**
1075
- * Coerce toolArgs using the downstream tool's cached JSON Schema.
1076
- * Converts the schema to Zod and runs coerceArgs so that string-encoded
1077
- * objects/arrays are parsed before being forwarded to the downstream server.
1078
- */
1079
- private coerceToolArgs;
1080
- private executeSkill;
1081
- /**
1082
- * Finds a prompt-based skill by name from all connected MCP servers.
1083
- *
1084
- * @param skillName - The skill name to search for
1085
- * @returns PromptSkillMatch if found, undefined otherwise
1086
- */
1087
- private findPromptSkill;
1088
- /**
1089
- * Returns guidance message for prompt-based skill invocation.
1090
- *
1091
- * @param promptSkill - The prompt skill match that was found
1092
- * @returns CallToolResult with guidance message
1093
- */
1094
- private executePromptSkill;
1095
- /**
1096
- * Executes a tool or skill based on the provided input.
1097
- *
1098
- * Handles three invocation patterns:
1099
- * 1. skill__skillName - Routes to skill execution via SkillService
1100
- * 2. serverName__toolName - Routes to specific MCP server
1101
- * 3. plainToolName - Searches all servers for unique match
1102
- *
1103
- * Edge cases:
1104
- * - Returns error if skill not found when using skill__ prefix
1105
- * - Returns error if tool is blacklisted on target server
1106
- * - Returns disambiguation message if tool exists on multiple servers
1107
- *
1108
- * @param input - The tool/skill name and optional arguments
1109
- * @returns CallToolResult with execution output or error
1110
- */
1111
- execute(rawInput: Record<string, unknown>): Promise<CallToolResult>;
1112
- }
1113
- //#endregion
1114
- //#region src/transports/http.d.ts
1115
- /**
1116
- * HTTP transport handler using Streamable HTTP (protocol version 2025-03-26)
1117
- * Provides stateful session management with resumability support
1118
- *
1119
- * Uses a hybrid server architecture:
1120
- * - Raw Node.js createServer for /mcp routes (MCP SDK needs native req/res)
1121
- * - Hono for REST routes (/health, /admin/shutdown)
1122
- */
1123
- declare class HttpTransportHandler implements HttpTransportHandler$1 {
1124
- private serverFactory;
1125
- private honoApp;
1126
- private server;
1127
- private sessionManager;
1128
- private config;
1129
- private adminOptions?;
1130
- private adminRateLimiter;
1131
- private logger;
1132
- constructor(serverFactory: () => Server | Promise<Server>, config: TransportConfig, adminOptions?: HttpTransportAdminOptions, logger?: LoggerLike);
1133
- private setupHonoRoutes;
1134
- private isAuthorizedShutdownRequest;
1135
- private handleAdminShutdownRequest;
1136
- /**
1137
- * Handle MCP protocol requests (POST/GET/DELETE /mcp)
1138
- * Uses raw Node.js req/res as required by MCP SDK
1139
- */
1140
- private handleMcpRequest;
1141
- private handlePostRequest;
1142
- private handleGetRequest;
1143
- private handleDeleteRequest;
1144
- start(): Promise<void>;
1145
- stop(): Promise<void>;
1146
- getPort(): number;
1147
- getHost(): string;
1148
- }
1149
- //#endregion
1150
- //#region src/transports/sse.d.ts
1151
- /**
1152
- * SSE (Server-Sent Events) transport handler
1153
- * Legacy transport for backwards compatibility (protocol version 2024-11-05)
1154
- * Uses separate endpoints: /sse for SSE stream (GET) and /messages for client messages (POST)
1155
- */
1156
- declare class SseTransportHandler implements HttpTransportHandler$1 {
1157
- private serverFactory;
1158
- private honoApp;
1159
- private server;
1160
- private sessionManager;
1161
- private config;
1162
- private logger;
1163
- constructor(serverFactory: Server | (() => Server), config: TransportConfig, logger?: LoggerLike);
1164
- private setupHonoRoutes;
1165
- private handleSseConnection;
1166
- private handlePostMessage;
1167
- start(): Promise<void>;
1168
- stop(): Promise<void>;
1169
- getPort(): number;
1170
- getHost(): string;
1171
- }
1172
- //#endregion
1173
- //#region src/transports/stdio.d.ts
1174
- /**
1175
- * Stdio transport handler for MCP server
1176
- * Used for command-line and direct integrations
1177
- */
1178
- declare class StdioTransportHandler implements TransportHandler {
1179
- private server;
1180
- private transport;
1181
- private logger;
1182
- constructor(server: Server, logger?: LoggerLike);
1183
- start(): Promise<void>;
1184
- stop(): Promise<void>;
1185
- }
1186
- //#endregion
1187
- //#region src/transports/stdio-http.d.ts
1188
- interface StdioHttpProxyTransportConfig {
1189
- endpoint: URL;
1190
- resolveEndpoint?: () => Promise<URL>;
1191
- }
1192
- /**
1193
- * Transport that serves MCP over stdio and forwards MCP requests to an HTTP endpoint.
1194
- * Automatically reconnects to the HTTP backend with exponential backoff when the
1195
- * connection is lost (e.g. backend crash + restart).
1196
- */
1197
- declare class StdioHttpTransportHandler implements TransportHandler {
1198
- private endpoint;
1199
- private readonly resolveEndpoint?;
1200
- private stdioProxyServer;
1201
- private stdioTransport;
1202
- private httpClient;
1203
- private logger;
1204
- private readonly MAX_RECONNECT_ATTEMPTS;
1205
- private readonly RECONNECT_BASE_MS;
1206
- private readonly RECONNECT_MAX_MS;
1207
- constructor(config: StdioHttpProxyTransportConfig, logger?: LoggerLike);
1208
- start(): Promise<void>;
1209
- stop(): Promise<void>;
1210
- private createAndConnectClient;
1211
- private registerElicitationHandler;
1212
- private reconnectWithBackoff;
1213
- private withReconnect;
1214
- private createProxyServer;
1215
- }
1216
- //#endregion
1217
- //#region src/container/index.d.ts
1218
- /**
1219
- * Configuration options for creating an MCP proxy container.
1220
- */
1221
- interface ServerOptions {
1222
- configFilePath?: string;
1223
- noCache?: boolean;
1224
- skills?: {
1225
- paths: string[];
1226
- };
1227
- serverId?: string;
1228
- definitionsCachePath?: string;
1229
- clearDefinitionsCache?: boolean;
1230
- proxyMode?: 'meta' | 'flat' | 'search';
1231
- onServerIdResolved?: (serverId: string) => Promise<void> | void;
1232
- }
1233
- /**
1234
- * Shared services and tools for multi-session HTTP transport.
1235
- */
1236
- interface SharedServices {
1237
- clientManager: McpClientManagerService;
1238
- definitionsCacheService: DefinitionsCacheService;
1239
- skillService?: SkillService;
1240
- describeTools: DescribeToolsTool;
1241
- useTool: UseToolTool;
1242
- searchListTools: SearchListToolsTool;
1243
- serverId: string;
1244
- proxyMode: 'meta' | 'flat' | 'search';
1245
- dispose: () => Promise<void>;
1246
- }
1247
- interface HttpTransportAdminOptions$1 {
1248
- serverId: string;
1249
- shutdownToken: string;
1250
- onShutdownRequested: () => Promise<void>;
1251
- }
1252
- /**
1253
- * Create the shared proxy container for a session or server startup.
1254
- *
1255
- * This is the composition root for the package: it owns service wiring,
1256
- * cache warmup, and cleanup for all proxy-specific resources.
1257
- */
1258
- declare function createProxyContainer(options?: ServerOptions): Promise<SharedServices>;
1259
- /**
1260
- * Create a sessionless stdio transport handler from the shared server factory.
1261
- */
1262
- declare function createStdioTransportHandler(createServer: () => Promise<_$_modelcontextprotocol_sdk_server_index_js0.Server>): Promise<StdioTransportHandler>;
1263
- /**
1264
- * Create an SSE transport handler from the shared server factory.
1265
- */
1266
- declare function createSseTransportHandler(createServer: () => Promise<_$_modelcontextprotocol_sdk_server_index_js0.Server>, config: TransportConfig): Promise<SseTransportHandler>;
1267
- /**
1268
- * Create an HTTP transport handler from shared services.
1269
- */
1270
- declare function createHttpTransportHandler(createServer: () => Promise<_$_modelcontextprotocol_sdk_server_index_js0.Server>, config: TransportConfig, adminOptions?: HttpTransportAdminOptions$1): HttpTransportHandler;
1271
- /**
1272
- * Create a stdio-http transport handler from an endpoint URL.
1273
- */
1274
- declare function createStdioHttpTransportHandler(endpoint: URL): StdioHttpTransportHandler;
1275
- /**
1276
- * Backward-compatible alias for the shared-service composition root.
1277
- */
1278
- declare function initializeSharedServices(options?: ServerOptions): Promise<SharedServices>;
1279
- //#endregion
1280
- //#region src/server/index.d.ts
1281
- /**
1282
- * Initialize shared services and tools once for use across multiple sessions.
1283
- * Use with createSessionServer() for HTTP transport where multiple agents
1284
- * connect concurrently. This avoids duplicating downstream connections,
1285
- * file watchers, caches, and tool instances per session.
1286
- */
1287
- /**
1288
- * Create a lightweight per-session MCP Server instance that delegates
1289
- * to shared services and tools. Use with createProxyContainer()
1290
- * for multi-session HTTP transport.
1291
- */
1292
- declare function createSessionServer(shared: SharedServices): Promise<Server>;
1293
- /**
1294
- * Create a single MCP server instance (backward-compatible wrapper).
1295
- * For multi-session HTTP transport, use createProxyContainer() + createSessionServer() instead.
1296
- */
1297
- declare function createServer(options?: ServerOptions): Promise<Server>;
1298
- //#endregion
1299
- //#region src/utils/findConfigFile.d.ts
1300
- /**
1301
- * Config File Finder Utility
1302
- *
1303
- * DESIGN PATTERNS:
1304
- * - Utility function pattern for reusable logic
1305
- * - Fail-fast pattern with early returns
1306
- * - Environment variable configuration pattern
1307
- *
1308
- * CODING STANDARDS:
1309
- * - Use sync filesystem operations for config discovery (performance)
1310
- * - Check PROJECT_PATH environment variable first
1311
- * - Fall back to current working directory
1312
- * - Support both .yaml and .json extensions
1313
- * - Return null if no config file is found
1314
- *
1315
- * AVOID:
1316
- * - Throwing errors (return null instead for optional config)
1317
- * - Hardcoded file names without extension variants
1318
- * - Ignoring environment variables
1319
- */
1320
- /**
1321
- * Find MCP configuration file by checking PROJECT_PATH first, then cwd
1322
- * Looks for both mcp-config.yaml and mcp-config.json
1323
- *
1324
- * @returns Absolute path to config file, or null if not found
1325
- */
1326
- declare function findConfigFile(): string | null;
1327
- //#endregion
1328
- //#region src/utils/generateServerId.d.ts
1329
- /**
1330
- * generateServerId Utilities
1331
- *
1332
- * DESIGN PATTERNS:
1333
- * - Pure functions with no side effects
1334
- * - Single responsibility per function
1335
- * - Functional programming approach
1336
- *
1337
- * CODING STANDARDS:
1338
- * - Export individual functions, not classes
1339
- * - Use descriptive function names with verbs
1340
- * - Add JSDoc comments for complex logic
1341
- * - Keep functions small and focused
1342
- *
1343
- * AVOID:
1344
- * - Side effects (mutating external state)
1345
- * - Stateful logic (use services for state)
1346
- * - Complex external dependencies
1347
- */
1348
- /**
1349
- * Generate a short, human-readable server ID.
1350
- *
1351
- * Uses Node.js crypto.randomBytes for cryptographically secure randomness
1352
- * with rejection sampling to avoid modulo bias.
1353
- *
1354
- * The generated ID:
1355
- * - Is 6 characters long by default
1356
- * - Uses only lowercase alphanumeric characters
1357
- * - Excludes confusing characters (0, O, 1, l, I)
1358
- *
1359
- * @param length - Length of the ID to generate (default: 6)
1360
- * @returns A random, human-readable ID
1361
- *
1362
- * @example
1363
- * generateServerId() // "abc234"
1364
- * generateServerId(4) // "x7mn"
1365
- */
1366
- declare function generateServerId(length?: number): string;
1367
- //#endregion
1368
- export { CachedFileSkillInfo, CachedPromptSkillInfo, CachedServerDefinition, ConfigFetcherService, DefinitionsCacheFile, DefinitionsCacheService, DescribeToolsTool, HttpTransportAdminOptions, HttpTransportHandler, HttpTransportHealthResponse, HttpTransportShutdownResponse, type LoggerLike, McpClientConnection, McpClientManagerService, McpHttpConfig, McpPromptInfo, McpResourceInfo, McpServerConfig, McpServerTransportConfig, McpServerTransportType, McpSseConfig, McpStdioConfig, McpToolInfo, PromptConfig, PromptSkillConfig, type ProxyLoggerHandle, type ProxyLoggerOptions, RemoteMcpConfiguration, RuntimeLookupOptions, RuntimeStateManager, RuntimeStateRecord, RuntimeStateService, SearchListToolsTool, type ServerOptions, type SharedServices, Skill, SkillMetadata, SkillService, SkillsConfig, SseTransportHandler, StdioHttpTransportHandler, StdioTransportHandler, type StopServerRequest, type StopServerResult, StopServerService, TRANSPORT_MODE, Tool, ToolDefinition, TransportConfig, TransportHandler, TransportMode, UseToolTool, createHttpTransportHandler, createProxyContainer, createProxyLogger, createServer, createSessionServer, createSseTransportHandler, createStdioHttpTransportHandler, createStdioTransportHandler, findConfigFile, generateServerId, initializeSharedServices };