@agimon-ai/mcp-proxy 0.4.0

package/dist/src-DQ_MagA0.mjs

@@ -0,0 +1,4779 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { access, mkdir, readFile, readdir, rm, stat, unlink, watch, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import yaml from "js-yaml";
+import { z } from "zod";
+import { existsSync } from "node:fs";
+import { Liquid } from "liquidjs";
+import { createNodeTelemetry } from "@agimon-ai/log-sink-mcp";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { promisify } from "node:util";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import express from "express";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+//#region src/utils/mcpConfigSchema.ts
+/**
+* mcpConfigSchema Utilities
+*
+* DESIGN PATTERNS:
+* - Schema-based validation using Zod
+* - Pure functions with no side effects
+* - Type inference from schemas
+* - Transformation from Claude Code format to internal format
+*
+* CODING STANDARDS:
+* - Export individual functions and schemas
+* - Use descriptive function names with verbs
+* - Add JSDoc comments for complex logic
+* - Keep functions small and focused
+*
+* AVOID:
+* - Side effects (mutating external state)
+* - Stateful logic (use services for state)
+* - Loosely typed configs (use Zod for runtime safety)
+*/
+/**
+* Interpolate environment variables in a string
+* Supports ${VAR_NAME} syntax
+*
+* This function replaces environment variable placeholders with their actual values.
+* If an environment variable is not defined, the placeholder is kept as-is and a warning is logged.
+*
+* Examples:
+* - "${HOME}/data" → "/Users/username/data"
+* - "Bearer ${API_KEY}" → "Bearer sk-abc123xyz"
+* - "${DATABASE_URL}/api" → "postgres://localhost:5432/mydb/api"
+*
+* Supported locations for environment variable interpolation:
+* - Stdio config: command, args, env values
+* - HTTP/SSE config: url, header values
+*
+* @param value - String that may contain environment variable references
+* @returns String with environment variables replaced
+*/
+function interpolateEnvVars(value) {
+	return value.replace(/\$\{([^}]+)\}/g, (_, varName) => {
+		const envValue = process.env[varName];
+		if (envValue === void 0) {
+			console.warn(`Environment variable ${varName} is not defined, keeping placeholder`);
+			return `\${${varName}}`;
+		}
+		return envValue;
+	});
+}
+/**
+* Recursively interpolate environment variables in an object
+*
+* @param obj - Object that may contain environment variable references
+* @returns Object with environment variables replaced
+*/
+function interpolateEnvVarsInObject(obj) {
+	if (typeof obj === "string") return interpolateEnvVars(obj);
+	if (Array.isArray(obj)) return obj.map((item) => interpolateEnvVarsInObject(item));
+	if (obj !== null && typeof obj === "object") {
+		const result = {};
+		for (const [key, value] of Object.entries(obj)) result[key] = interpolateEnvVarsInObject(value);
+		return result;
+	}
+	return obj;
+}
+/**
+* Private IP range patterns for SSRF protection
+* Covers both IPv4 and IPv6 loopback, private, and link-local ranges
+*/
+const PRIVATE_IP_PATTERNS = [
+	/^127\./,
+	/^10\./,
+	/^172\.(1[6-9]|2\d|3[01])\./,
+	/^192\.168\./,
+	/^169\.254\./,
+	/^0\./,
+	/^224\./,
+	/^240\./,
+	/^localhost$/i,
+	/^.*\.localhost$/i,
+	/^\[::\]/,
+	/^\[::1\]/,
+	/^\[0:0:0:0:0:0:0:1\]/,
+	/^\[0{1,4}:0{1,4}:0{1,4}:0{1,4}:0{1,4}:0{1,4}:0{1,4}:1\]/i,
+	/^\[fe80:/i,
+	/^\[fc00:/i,
+	/^\[fd00:/i,
+	/^\[::ffff:127\./i,
+	/^\[::ffff:7f[0-9a-f]{2}:/i,
+	/^\[::ffff:10\./i,
+	/^\[::ffff:a[0-9a-f]{2}:/i,
+	/^\[::ffff:172\.(1[6-9]|2\d|3[01])\./i,
+	/^\[::ffff:ac1[0-9a-f]:/i,
+	/^\[::ffff:192\.168\./i,
+	/^\[::ffff:c0a8:/i,
+	/^\[::ffff:169\.254\./i,
+	/^\[::ffff:a9fe:/i,
+	/^\[::ffff:0\./i,
+	/^\[::127\./i,
+	/^\[::7f[0-9a-f]{2}:/i,
+	/^\[::10\./i,
+	/^\[::a[0-9a-f]{2}:/i,
+	/^\[::192\.168\./i,
+	/^\[::c0a8:/i
+];
+/**
+* Validate URL for SSRF protection
+*
+* @param url - The URL to validate (after env var interpolation)
+* @param security - Security settings
+* @throws Error if URL is unsafe
+*/
+function validateUrlSecurity(url, security) {
+	const allowPrivateIPs = security?.allowPrivateIPs ?? false;
+	const enforceHttps = security?.enforceHttps ?? true;
+	let parsedUrl;
+	try {
+		parsedUrl = new URL(url);
+	} catch (_error) {
+		throw new Error(`Invalid URL format: ${url}`);
+	}
+	const protocol = parsedUrl.protocol.replace(":", "");
+	if (enforceHttps && protocol !== "https") throw new Error(`HTTPS is required for security. URL uses '${protocol}://'. Set security.enforceHttps: false to allow HTTP.`);
+	if (protocol !== "http" && protocol !== "https") throw new Error(`Invalid URL protocol '${protocol}://'. Only http:// and https:// are allowed.`);
+	if (!allowPrivateIPs) {
+		const hostname = parsedUrl.hostname.toLowerCase();
+		if (PRIVATE_IP_PATTERNS.some((pattern) => pattern.test(hostname))) throw new Error(`Private IP addresses and localhost are blocked for security (${hostname}). Set security.allowPrivateIPs: true to allow internal networks.`);
+	}
+}
+/**
+* Validate a remote config source against its validation rules
+*
+* @param source - Remote config source with validation rules
+* @throws Error if validation fails
+*/
+function validateRemoteConfigSource(source) {
+	const interpolatedUrl = interpolateEnvVars(source.url);
+	validateUrlSecurity(interpolatedUrl, source.security);
+	if (!source.validation) return;
+	if (source.validation.url) {
+		if (!new RegExp(source.validation.url).test(interpolatedUrl)) throw new Error(`Remote config URL "${interpolatedUrl}" does not match validation pattern: ${source.validation.url}`);
+	}
+	if (source.validation.headers && Object.keys(source.validation.headers).length > 0) {
+		if (!source.headers) {
+			const requiredHeaders = Object.keys(source.validation.headers);
+			throw new Error(`Remote config is missing required headers: ${requiredHeaders.join(", ")}`);
+		}
+		for (const [headerName, pattern] of Object.entries(source.validation.headers)) {
+			if (!(headerName in source.headers)) throw new Error(`Remote config is missing required header: ${headerName}`);
+			const interpolatedHeaderValue = interpolateEnvVars(source.headers[headerName]);
+			if (!new RegExp(pattern).test(interpolatedHeaderValue)) throw new Error(`Remote config header "${headerName}" value "${interpolatedHeaderValue}" does not match validation pattern: ${pattern}`);
+		}
+	}
+}
+/**
+* Claude Code / Claude Desktop standard MCP config format
+* This is the format users write in their config files
+*/
+/**
+* Prompt skill configuration schema
+* Converts a prompt to an executable skill
+*/
+const PromptSkillConfigSchema = z.object({
+	name: z.string(),
+	description: z.string(),
+	folder: z.string().optional()
+});
+/**
+* Prompt configuration schema
+* Supports converting prompts to skills
+*/
+const PromptConfigSchema = z.object({ skill: PromptSkillConfigSchema.optional() });
+const AdditionalConfigSchema = z.object({
+	instruction: z.string().optional(),
+	toolBlacklist: z.array(z.string()).optional(),
+	omitToolDescription: z.boolean().optional(),
+	prompts: z.record(z.string(), PromptConfigSchema).optional()
+}).optional();
+const ClaudeCodeStdioServerSchema = z.object({
+	command: z.string(),
+	args: z.array(z.string()).optional(),
+	env: z.record(z.string(), z.string()).optional(),
+	disabled: z.boolean().optional(),
+	instruction: z.string().optional(),
+	timeout: z.number().positive().optional(),
+	requestTimeout: z.number().positive().optional(),
+	config: AdditionalConfigSchema
+});
+const ClaudeCodeHttpServerSchema = z.object({
+	url: z.string().url(),
+	headers: z.record(z.string(), z.string()).optional(),
+	type: z.enum(["http", "sse"]).optional(),
+	disabled: z.boolean().optional(),
+	instruction: z.string().optional(),
+	timeout: z.number().positive().optional(),
+	requestTimeout: z.number().positive().optional(),
+	config: AdditionalConfigSchema
+});
+const ClaudeCodeServerConfigSchema = z.union([ClaudeCodeStdioServerSchema, ClaudeCodeHttpServerSchema]);
+const RemoteConfigValidationSchema = z.object({
+	url: z.string().optional(),
+	headers: z.record(z.string(), z.string()).optional()
+}).optional();
+const RemoteConfigSecuritySchema = z.object({
+	allowPrivateIPs: z.boolean().optional(),
+	enforceHttps: z.boolean().optional()
+}).optional();
+const RemoteConfigSourceSchema = z.object({
+	url: z.string(),
+	headers: z.record(z.string(), z.string()).optional(),
+	validation: RemoteConfigValidationSchema,
+	security: RemoteConfigSecuritySchema,
+	mergeStrategy: z.enum([
+		"local-priority",
+		"remote-priority",
+		"merge-deep"
+	]).optional()
+});
+/**
+* Skills configuration schema
+*/
+const SkillsConfigSchema = z.object({ paths: z.array(z.string()) });
+/**
+* Full Claude Code MCP configuration schema
+*/
+const ClaudeCodeMcpConfigSchema = z.object({
+	id: z.string().optional(),
+	mcpServers: z.record(z.string(), ClaudeCodeServerConfigSchema),
+	remoteConfigs: z.array(RemoteConfigSourceSchema).optional(),
+	skills: SkillsConfigSchema.optional()
+});
+/**
+* Internal MCP config format
+* This is the normalized format used internally by the proxy
+*/
+const McpStdioConfigSchema = z.object({
+	command: z.string(),
+	args: z.array(z.string()).optional(),
+	env: z.record(z.string(), z.string()).optional()
+});
+const McpHttpConfigSchema = z.object({
+	url: z.string().url(),
+	headers: z.record(z.string(), z.string()).optional()
+});
+const McpSseConfigSchema = z.object({
+	url: z.string().url(),
+	headers: z.record(z.string(), z.string()).optional()
+});
+/**
+* Internal prompt skill configuration schema
+*/
+const InternalPromptSkillConfigSchema = z.object({
+	name: z.string(),
+	description: z.string(),
+	folder: z.string().optional()
+});
+/**
+* Internal prompt configuration schema
+*/
+const InternalPromptConfigSchema = z.object({ skill: InternalPromptSkillConfigSchema.optional() });
+const McpServerConfigSchema = z.discriminatedUnion("transport", [
+	z.object({
+		name: z.string(),
+		instruction: z.string().optional(),
+		toolBlacklist: z.array(z.string()).optional(),
+		omitToolDescription: z.boolean().optional(),
+		prompts: z.record(z.string(), InternalPromptConfigSchema).optional(),
+		timeout: z.number().positive().optional(),
+		requestTimeout: z.number().positive().optional(),
+		transport: z.literal("stdio"),
+		config: McpStdioConfigSchema
+	}),
+	z.object({
+		name: z.string(),
+		instruction: z.string().optional(),
+		toolBlacklist: z.array(z.string()).optional(),
+		omitToolDescription: z.boolean().optional(),
+		prompts: z.record(z.string(), InternalPromptConfigSchema).optional(),
+		timeout: z.number().positive().optional(),
+		requestTimeout: z.number().positive().optional(),
+		transport: z.literal("http"),
+		config: McpHttpConfigSchema
+	}),
+	z.object({
+		name: z.string(),
+		instruction: z.string().optional(),
+		toolBlacklist: z.array(z.string()).optional(),
+		omitToolDescription: z.boolean().optional(),
+		prompts: z.record(z.string(), InternalPromptConfigSchema).optional(),
+		timeout: z.number().positive().optional(),
+		requestTimeout: z.number().positive().optional(),
+		transport: z.literal("sse"),
+		config: McpSseConfigSchema
+	})
+]);
+/**
+* Full internal MCP configuration schema
+*/
+const InternalMcpConfigSchema = z.object({
+	id: z.string().optional(),
+	mcpServers: z.record(z.string(), McpServerConfigSchema),
+	skills: SkillsConfigSchema.optional()
+});
+/**
+* Transform Claude Code config to internal format
+* Converts standard Claude Code MCP configuration to normalized internal format
+*
+* @param claudeConfig - Claude Code format configuration
+* @returns Internal format configuration
+*/
+function transformClaudeCodeConfig(claudeConfig) {
+	const transformedServers = {};
+	for (const [serverName, serverConfig] of Object.entries(claudeConfig.mcpServers)) {
+		if ("disabled" in serverConfig && serverConfig.disabled === true) continue;
+		if ("command" in serverConfig) {
+			const stdioConfig = serverConfig;
+			const interpolatedCommand = interpolateEnvVars(stdioConfig.command);
+			const interpolatedArgs = stdioConfig.args?.map((arg) => interpolateEnvVars(arg));
+			const interpolatedEnv = stdioConfig.env ? interpolateEnvVarsInObject(stdioConfig.env) : void 0;
+			transformedServers[serverName] = {
+				name: serverName,
+				instruction: stdioConfig.instruction || stdioConfig.config?.instruction,
+				toolBlacklist: stdioConfig.config?.toolBlacklist,
+				omitToolDescription: stdioConfig.config?.omitToolDescription,
+				prompts: stdioConfig.config?.prompts,
+				timeout: stdioConfig.timeout,
+				requestTimeout: stdioConfig.requestTimeout,
+				transport: "stdio",
+				config: {
+					command: interpolatedCommand,
+					args: interpolatedArgs,
+					env: interpolatedEnv
+				}
+			};
+		} else if ("url" in serverConfig) {
+			const httpConfig = serverConfig;
+			const transport = httpConfig.type === "sse" ? "sse" : "http";
+			const interpolatedUrl = interpolateEnvVars(httpConfig.url);
+			const interpolatedHeaders = httpConfig.headers ? interpolateEnvVarsInObject(httpConfig.headers) : void 0;
+			transformedServers[serverName] = {
+				name: serverName,
+				instruction: httpConfig.instruction || httpConfig.config?.instruction,
+				toolBlacklist: httpConfig.config?.toolBlacklist,
+				omitToolDescription: httpConfig.config?.omitToolDescription,
+				prompts: httpConfig.config?.prompts,
+				timeout: httpConfig.timeout,
+				requestTimeout: httpConfig.requestTimeout,
+				transport,
+				config: {
+					url: interpolatedUrl,
+					headers: interpolatedHeaders
+				}
+			};
+		}
+	}
+	return {
+		id: claudeConfig.id,
+		mcpServers: transformedServers,
+		skills: claudeConfig.skills
+	};
+}
+/**
+* Parse and validate MCP config from raw JSON
+* Validates against Claude Code format, transforms to internal format, and validates result
+*
+* @param rawConfig - Raw JSON configuration object
+* @returns Validated and transformed internal configuration
+* @throws ZodError if validation fails
+*/
+function parseMcpConfig(rawConfig) {
+	const internalConfig = transformClaudeCodeConfig(ClaudeCodeMcpConfigSchema.parse(rawConfig));
+	return InternalMcpConfigSchema.parse(internalConfig);
+}
+
+//#endregion
+//#region src/utils/findConfigFile.ts
+/**
+* Config File Finder Utility
+*
+* DESIGN PATTERNS:
+* - Utility function pattern for reusable logic
+* - Fail-fast pattern with early returns
+* - Environment variable configuration pattern
+*
+* CODING STANDARDS:
+* - Use sync filesystem operations for config discovery (performance)
+* - Check PROJECT_PATH environment variable first
+* - Fall back to current working directory
+* - Support both .yaml and .json extensions
+* - Return null if no config file is found
+*
+* AVOID:
+* - Throwing errors (return null instead for optional config)
+* - Hardcoded file names without extension variants
+* - Ignoring environment variables
+*/
+/**
+* Find MCP configuration file by checking PROJECT_PATH first, then cwd
+* Looks for both mcp-config.yaml and mcp-config.json
+*
+* @returns Absolute path to config file, or null if not found
+*/
+function findConfigFile() {
+	const configFileNames = [
+		"mcp-config.yaml",
+		"mcp-config.yml",
+		"mcp-config.json"
+	];
+	const projectPath = process.env.PROJECT_PATH;
+	if (projectPath) for (const fileName of configFileNames) {
+		const configPath = resolve(projectPath, fileName);
+		if (existsSync(configPath)) return configPath;
+	}
+	const cwd = process.cwd();
+	for (const fileName of configFileNames) {
+		const configPath = join(cwd, fileName);
+		if (existsSync(configPath)) return configPath;
+	}
+	return null;
+}
+
+//#endregion
+//#region src/utils/parseToolName.ts
+/**
+* Parse tool name to extract server and actual tool name
+* Supports both plain tool names and prefixed format: {serverName}__{toolName}
+*
+* @param toolName - The tool name to parse (e.g., "my_tool" or "server__my_tool")
+* @returns Parsed result with optional serverName and actualToolName
+*
+* @example
+* parseToolName("my_tool") // { actualToolName: "my_tool" }
+* parseToolName("server__my_tool") // { serverName: "server", actualToolName: "my_tool" }
+*/
+function parseToolName(toolName) {
+	const separatorIndex = toolName.indexOf("__");
+	if (separatorIndex > 0) return {
+		serverName: toolName.substring(0, separatorIndex),
+		actualToolName: toolName.substring(separatorIndex + 2)
+	};
+	return { actualToolName: toolName };
+}
+
+//#endregion
+//#region src/utils/parseFrontMatter.ts
+/**
+* Parses YAML front matter from a string content.
+* Front matter must be at the start of the content, delimited by `---`.
+*
+* Supports:
+* - Simple key: value pairs
+* - Literal block scalar (|) for multi-line preserving newlines
+* - Folded block scalar (>) for multi-line folding to single line
+*
+* @param content - The content string that may contain front matter
+* @returns Object with parsed front matter (or null) and remaining content
+*
+* @example
+* const result = parseFrontMatter(`---
+* name: my-skill
+* description: A skill description
+* ---
+* The actual content here`);
+* // result.frontMatter = { name: 'my-skill', description: 'A skill description' }
+* // result.content = 'The actual content here'
+*
+* @example
+* // Multi-line with literal block scalar
+* const result = parseFrontMatter(`---
+* name: my-skill
+* description: |
+*   Line 1
+*   Line 2
+* ---
+* Content`);
+* // result.frontMatter.description = 'Line 1\nLine 2'
+*/
+function parseFrontMatter(content) {
+	const trimmedContent = content.trimStart();
+	if (!trimmedContent.startsWith("---")) return {
+		frontMatter: null,
+		content
+	};
+	const endDelimiterIndex = trimmedContent.indexOf("\n---", 3);
+	if (endDelimiterIndex === -1) return {
+		frontMatter: null,
+		content
+	};
+	const yamlContent = trimmedContent.slice(4, endDelimiterIndex).trim();
+	if (!yamlContent) return {
+		frontMatter: null,
+		content
+	};
+	const frontMatter = {};
+	const lines = yamlContent.split("\n");
+	let currentKey = null;
+	let currentValue = [];
+	let multiLineMode = null;
+	let baseIndent = 0;
+	const saveCurrentKey = () => {
+		if (currentKey && currentValue.length > 0) if (multiLineMode === "literal") frontMatter[currentKey] = currentValue.join("\n").trimEnd();
+		else if (multiLineMode === "folded") frontMatter[currentKey] = currentValue.join(" ").trim();
+		else frontMatter[currentKey] = currentValue.join("").trim();
+		currentKey = null;
+		currentValue = [];
+		multiLineMode = null;
+		baseIndent = 0;
+	};
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		const trimmedLine = line.trim();
+		const colonIndex = line.indexOf(":");
+		if (colonIndex !== -1 && !line.startsWith(" ") && !line.startsWith("	")) {
+			saveCurrentKey();
+			const key = line.slice(0, colonIndex).trim();
+			let value = line.slice(colonIndex + 1).trim();
+			if (value === "|" || value === "|-") {
+				currentKey = key;
+				multiLineMode = "literal";
+				if (i + 1 < lines.length) {
+					const match = lines[i + 1].match(/^(\s+)/);
+					baseIndent = match ? match[1].length : 2;
+				}
+			} else if (value === ">" || value === ">-") {
+				currentKey = key;
+				multiLineMode = "folded";
+				if (i + 1 < lines.length) {
+					const match = lines[i + 1].match(/^(\s+)/);
+					baseIndent = match ? match[1].length : 2;
+				}
+			} else {
+				if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
+				if (key && value) frontMatter[key] = value;
+			}
+		} else if (multiLineMode && currentKey) {
+			const lineIndent = line.match(/^(\s*)/)?.[1].length || 0;
+			if (trimmedLine === "") currentValue.push("");
+			else if (lineIndent >= baseIndent) {
+				const unindentedLine = line.slice(baseIndent);
+				currentValue.push(unindentedLine);
+			} else saveCurrentKey();
+		}
+	}
+	saveCurrentKey();
+	return {
+		frontMatter,
+		content: trimmedContent.slice(endDelimiterIndex + 4).trimStart()
+	};
+}
+/**
+* Checks if parsed front matter contains valid skill metadata.
+* A valid skill front matter must have both `name` and `description` fields.
+*
+* @param frontMatter - The parsed front matter object
+* @returns True if front matter contains valid skill metadata
+*/
+function isValidSkillFrontMatter(frontMatter) {
+	return frontMatter !== null && typeof frontMatter.name === "string" && frontMatter.name.length > 0 && typeof frontMatter.description === "string" && frontMatter.description.length > 0;
+}
+/**
+* Extracts skill front matter from content if present and valid.
+*
+* @param content - The content string that may contain skill front matter
+* @returns Object with skill metadata and content, or null if no valid skill front matter
+*/
+function extractSkillFrontMatter(content) {
+	const { frontMatter, content: remainingContent } = parseFrontMatter(content);
+	if (frontMatter && isValidSkillFrontMatter(frontMatter)) return {
+		skill: {
+			name: frontMatter.name,
+			description: frontMatter.description
+		},
+		content: remainingContent
+	};
+	return null;
+}
+
+//#endregion
+//#region src/utils/generateServerId.ts
+/**
+* generateServerId Utilities
+*
+* DESIGN PATTERNS:
+* - Pure functions with no side effects
+* - Single responsibility per function
+* - Functional programming approach
+*
+* CODING STANDARDS:
+* - Export individual functions, not classes
+* - Use descriptive function names with verbs
+* - Add JSDoc comments for complex logic
+* - Keep functions small and focused
+*
+* AVOID:
+* - Side effects (mutating external state)
+* - Stateful logic (use services for state)
+* - Complex external dependencies
+*/
+/**
+* Character set for generating human-readable IDs.
+* Excludes confusing characters: 0, O, 1, l, I
+*/
+const CHARSET = "23456789abcdefghjkmnpqrstuvwxyz";
+/**
+* Default length for generated server IDs (6 characters)
+*/
+const DEFAULT_ID_LENGTH = 6;
+/**
+* Generate a short, human-readable server ID.
+*
+* Uses Node.js crypto.randomBytes for cryptographically secure randomness
+* with rejection sampling to avoid modulo bias.
+*
+* The generated ID:
+* - Is 6 characters long by default
+* - Uses only lowercase alphanumeric characters
+* - Excludes confusing characters (0, O, 1, l, I)
+*
+* @param length - Length of the ID to generate (default: 6)
+* @returns A random, human-readable ID
+*
+* @example
+* generateServerId() // "abc234"
+* generateServerId(4) // "x7mn"
+*/
+function generateServerId(length = DEFAULT_ID_LENGTH) {
+	const charsetLength = 31;
+	const maxUnbiased = Math.floor(256 / charsetLength) * charsetLength - 1;
+	let result = "";
+	let remaining = length;
+	while (remaining > 0) {
+		const bytes = randomBytes(remaining);
+		for (let i = 0; i < bytes.length && remaining > 0; i++) {
+			const byte = bytes[i];
+			if (byte > maxUnbiased) continue;
+			result += CHARSET[byte % charsetLength];
+			remaining--;
+		}
+	}
+	return result;
+}
+
+//#endregion
+//#region src/constants/index.ts
+/**
+* Shared constants for mcp-proxy package
+*/
+/**
+* Prefix added to skill names when they clash with MCP tool names.
+* This ensures skills can be uniquely identified even when a tool has the same name.
+*/
+const SKILL_PREFIX = "skill__";
+/**
+* Log prefix for skill detection messages.
+* Used to easily filter skill detection logs in stderr output.
+*/
+const LOG_PREFIX_SKILL_DETECTION = "[skill-detection]";
+/**
+* Log prefix for general MCP capability discovery messages.
+*/
+const LOG_PREFIX_CAPABILITY_DISCOVERY = "[capability-discovery]";
+/**
+* Prefix for prompt-based skill locations.
+* Format: "prompt:{serverName}:{promptName}"
+*/
+const PROMPT_LOCATION_PREFIX = "prompt:";
+/**
+* Default server ID used when no ID is provided via CLI or config.
+* This fallback is used when auto-generation also fails.
+*/
+const DEFAULT_SERVER_ID = "unknown";
+
+//#endregion
+//#region src/services/DefinitionsCacheService.ts
+/**
+* DefinitionsCacheService
+*
+* Provides shared discovery, caching, and serialization for startup-time MCP
+* capability metadata. This avoids repeated remote enumeration during
+* mcp-serve startup and describe_tools generation.
+*/
+function isYamlPath(filePath) {
+	return filePath.endsWith(".yaml") || filePath.endsWith(".yml");
+}
+function toErrorMessage$3(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function sanitizeConfigPathForFilename(configFilePath) {
+	const absoluteConfigPath = resolve(configFilePath);
+	const normalizedPath = absoluteConfigPath.length >= 2 && absoluteConfigPath[1] === ":" && (absoluteConfigPath[0] >= "A" && absoluteConfigPath[0] <= "Z" || absoluteConfigPath[0] >= "a" && absoluteConfigPath[0] <= "z") ? `${absoluteConfigPath[0].toLowerCase()}${absoluteConfigPath.slice(1)}` : absoluteConfigPath;
+	let result = "";
+	let previousWasUnderscore = false;
+	for (const char of normalizedPath) {
+		if (char >= "a" && char <= "z" || char >= "A" && char <= "Z" || char >= "0" && char <= "9" || char === "." || char === "_" || char === "-") {
+			result += char;
+			previousWasUnderscore = false;
+			continue;
+		}
+		if (!previousWasUnderscore) {
+			result += "_";
+			previousWasUnderscore = true;
+		}
+	}
+	let start = 0;
+	let end = result.length;
+	while (start < end && result[start] === "_") start += 1;
+	while (end > start && result[end - 1] === "_") end -= 1;
+	return result.slice(start, end);
+}
+function cloneCache(cache) {
+	return {
+		...cache,
+		failures: [...cache.failures ?? []],
+		skills: (cache.skills ?? []).map((skill) => ({ ...skill })),
+		servers: Object.fromEntries(Object.entries(cache.servers).map(([serverName, server]) => [serverName, {
+			...server,
+			tools: (server.tools ?? []).map((tool) => ({ ...tool })),
+			resources: (server.resources ?? []).map((resource) => ({ ...resource })),
+			prompts: (server.prompts ?? []).map((prompt) => ({
+				...prompt,
+				arguments: prompt.arguments?.map((arg) => ({ ...arg }))
+			})),
+			promptSkills: (server.promptSkills ?? []).map((promptSkill) => ({
+				...promptSkill,
+				skill: { ...promptSkill.skill }
+			}))
+		}]))
+	};
+}
+var DefinitionsCacheService = class {
+	clientManager;
+	skillService;
+	cacheData;
+	liveDefinitionsPromise = null;
+	mergedDefinitionsPromise = null;
+	logger;
+	constructor(clientManager, skillService, options, logger = console) {
+		this.clientManager = clientManager;
+		this.skillService = skillService;
+		this.cacheData = options?.cacheData;
+		this.logger = logger;
+	}
+	static async readFromFile(filePath) {
+		const content = await readFile(filePath, "utf-8");
+		const parsed = isYamlPath(filePath) ? yaml.load(content) : JSON.parse(content);
+		if (!parsed || typeof parsed !== "object") throw new Error("Definitions cache must be an object");
+		const cache = parsed;
+		if (cache.version !== 1 || !cache.servers) throw new Error("Definitions cache is missing required fields");
+		return {
+			...cache,
+			failures: Array.isArray(cache.failures) ? cache.failures : [],
+			skills: Array.isArray(cache.skills) ? cache.skills : [],
+			servers: Object.fromEntries(Object.entries(cache.servers).map(([serverName, server]) => [serverName, {
+				...server,
+				tools: Array.isArray(server.tools) ? server.tools : [],
+				resources: Array.isArray(server.resources) ? server.resources : [],
+				prompts: Array.isArray(server.prompts) ? server.prompts : [],
+				promptSkills: Array.isArray(server.promptSkills) ? server.promptSkills : []
+			}]))
+		};
+	}
+	static async writeToFile(filePath, cache) {
+		const serialized = isYamlPath(filePath) ? yaml.dump(cache, { noRefs: true }) : JSON.stringify(cache, null, 2);
+		await mkdir(dirname(filePath), { recursive: true });
+		await writeFile(filePath, serialized, "utf-8");
+	}
+	static getDefaultCachePath(configFilePath) {
+		const sanitizedPath = sanitizeConfigPathForFilename(configFilePath);
+		return join(homedir(), ".aicode-toolkit", `${sanitizedPath}.definitions-cache.json`);
+	}
+	static generateConfigHash(config) {
+		return createHash("sha256").update(JSON.stringify(config)).digest("hex");
+	}
+	static isCacheValid(cache, options) {
+		if (options.configHash && cache.configHash && cache.configHash !== options.configHash) return false;
+		if (options.oneMcpVersion && cache.oneMcpVersion && cache.oneMcpVersion !== options.oneMcpVersion) return false;
+		return true;
+	}
+	static async clearFile(filePath) {
+		await rm(filePath, { force: true });
+	}
+	clearLiveCache() {
+		this.liveDefinitionsPromise = null;
+		this.mergedDefinitionsPromise = null;
+	}
+	setCacheData(cacheData) {
+		this.cacheData = cacheData;
+		this.mergedDefinitionsPromise = null;
+	}
+	async collectForCache(options) {
+		const liveDefinitions = await this.collectLiveDefinitions(options);
+		this.setCacheData(liveDefinitions);
+		this.liveDefinitionsPromise = Promise.resolve(cloneCache(liveDefinitions));
+		return cloneCache(liveDefinitions);
+	}
+	async getDefinitions() {
+		if (this.mergedDefinitionsPromise) return this.mergedDefinitionsPromise;
+		this.mergedDefinitionsPromise = (async () => {
+			const clients = this.clientManager.getAllClients();
+			if (!this.cacheData) return this.getLiveDefinitions();
+			const missingServers = clients.map((client) => client.serverName).filter((serverName) => !this.cacheData?.servers[serverName]);
+			if (missingServers.length === 0) return cloneCache(this.cacheData);
+			const liveDefinitions = await this.getLiveDefinitions();
+			const merged = cloneCache(this.cacheData);
+			for (const serverName of missingServers) {
+				const serverDefinition = liveDefinitions.servers[serverName];
+				if (serverDefinition) merged.servers[serverName] = serverDefinition;
+			}
+			const failureMap = /* @__PURE__ */ new Map();
+			for (const failure of [...merged.failures, ...liveDefinitions.failures]) failureMap.set(failure.serverName, failure.error);
+			merged.failures = Array.from(failureMap.entries()).map(([serverName, error]) => ({
+				serverName,
+				error
+			}));
+			if (merged.skills.length === 0 && liveDefinitions.skills.length > 0) merged.skills = liveDefinitions.skills.map((skill) => ({ ...skill }));
+			return merged;
+		})();
+		return this.mergedDefinitionsPromise;
+	}
+	async getServerDefinitions() {
+		const definitions = await this.getDefinitions();
+		const serverOrder = this.clientManager.getKnownServerNames();
+		if (serverOrder.length === 0) return Object.values(definitions.servers);
+		return serverOrder.map((serverName) => definitions.servers[serverName]).filter((server) => server !== void 0);
+	}
+	async getServersForTool(toolName) {
+		return (await this.getServerDefinitions()).filter((serverDefinition) => serverDefinition.tools.some((tool) => tool.name === toolName)).map((serverDefinition) => serverDefinition.serverName);
+	}
+	async getServersForResource(uri) {
+		return (await this.getServerDefinitions()).filter((serverDefinition) => serverDefinition.resources.some((resource) => resource.uri === uri)).map((serverDefinition) => serverDefinition.serverName);
+	}
+	async getPromptSkillByName(skillName) {
+		const definitions = await this.getDefinitions();
+		for (const [serverName, server] of Object.entries(definitions.servers)) for (const promptSkill of server.promptSkills) if (promptSkill.skill.name === skillName) return {
+			serverName,
+			promptName: promptSkill.promptName,
+			skill: promptSkill.skill,
+			autoDetected: promptSkill.autoDetected
+		};
+	}
+	async getCachedFileSkills() {
+		return (await this.getDefinitions()).skills.map((skill) => ({ ...skill }));
+	}
+	async getLiveDefinitions() {
+		if (!this.liveDefinitionsPromise) this.liveDefinitionsPromise = this.collectLiveDefinitions();
+		return this.liveDefinitionsPromise;
+	}
+	async collectLiveDefinitions(options) {
+		const clients = this.clientManager.getAllClients();
+		const failures = [];
+		const servers = {};
+		const serverResults = await Promise.all(clients.map(async (client) => {
+			try {
+				const tools = await client.listTools();
+				const resources = await this.listResourcesSafe(client);
+				const prompts = await this.listPromptsSafe(client);
+				const blacklist = new Set(client.toolBlacklist || []);
+				const filteredTools = tools.filter((tool) => !blacklist.has(tool.name));
+				const promptSkills = await this.collectPromptSkillsForClient(client, prompts);
+				return {
+					serverName: client.serverName,
+					serverInstruction: client.serverInstruction,
+					omitToolDescription: client.omitToolDescription,
+					toolBlacklist: client.toolBlacklist,
+					tools: filteredTools.map((tool) => ({
+						name: tool.name,
+						description: tool.description,
+						inputSchema: tool.inputSchema,
+						_meta: tool._meta
+					})),
+					resources,
+					prompts,
+					promptSkills
+				};
+			} catch (error) {
+				failures.push({
+					serverName: client.serverName,
+					error: toErrorMessage$3(error)
+				});
+				return null;
+			}
+		}));
+		for (const serverDefinition of serverResults) if (serverDefinition) servers[serverDefinition.serverName] = serverDefinition;
+		return {
+			version: 1,
+			oneMcpVersion: options?.oneMcpVersion,
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			configPath: options?.configPath,
+			configHash: options?.configHash,
+			serverId: options?.serverId,
+			servers,
+			skills: await this.collectFileSkills(),
+			failures
+		};
+	}
+	async collectFileSkills() {
+		if (!this.skillService) return [];
+		return (await this.skillService.getSkills()).map((skill) => this.toCachedFileSkill(skill));
+	}
+	toCachedFileSkill(skill) {
+		return {
+			name: skill.name,
+			description: skill.description,
+			location: skill.location,
+			basePath: skill.basePath
+		};
+	}
+	async listPromptsSafe(client) {
+		try {
+			return (await client.listPrompts()).map((prompt) => ({
+				name: prompt.name,
+				description: prompt.description,
+				arguments: prompt.arguments?.map((arg) => ({ ...arg }))
+			}));
+		} catch (error) {
+			this.logger.warn(`${LOG_PREFIX_SKILL_DETECTION} Failed to list prompts from ${client.serverName}: ${toErrorMessage$3(error)}`);
+			return [];
+		}
+	}
+	async listResourcesSafe(client) {
+		try {
+			return (await client.listResources()).map((resource) => ({
+				uri: resource.uri,
+				name: resource.name,
+				description: resource.description,
+				mimeType: resource.mimeType
+			}));
+		} catch (error) {
+			this.logger.warn(`${LOG_PREFIX_CAPABILITY_DISCOVERY} Failed to list resources from ${client.serverName}: ${toErrorMessage$3(error)}`);
+			return [];
+		}
+	}
+	async collectPromptSkillsForClient(client, prompts) {
+		const configuredPromptNames = new Set(client.prompts ? Object.keys(client.prompts) : []);
+		const promptSkills = [];
+		if (client.prompts) {
+			for (const [promptName, promptConfig] of Object.entries(client.prompts)) if (promptConfig.skill) promptSkills.push({
+				promptName,
+				skill: { ...promptConfig.skill }
+			});
+		}
+		const autoDetectedSkills = await Promise.all(prompts.map(async (prompt) => {
+			if (configuredPromptNames.has(prompt.name)) return null;
+			try {
+				const skillExtraction = extractSkillFrontMatter((await client.getPrompt(prompt.name)).messages?.map((message) => {
+					const content = message.content;
+					if (typeof content === "string") return content;
+					if (content && typeof content === "object" && "text" in content) return String(content.text);
+					return "";
+				}).join("\n") || "");
+				if (!skillExtraction) return null;
+				return {
+					promptName: prompt.name,
+					skill: skillExtraction.skill,
+					autoDetected: true
+				};
+			} catch (error) {
+				this.logger.warn(`${LOG_PREFIX_SKILL_DETECTION} Failed to fetch prompt '${prompt.name}' from ${client.serverName}: ${toErrorMessage$3(error)}`);
+				return null;
+			}
+		}));
+		for (const autoDetectedSkill of autoDetectedSkills) if (autoDetectedSkill) promptSkills.push(autoDetectedSkill);
+		return promptSkills;
+	}
+};
+
+//#endregion
+//#region src/templates/toolkit-description.liquid?raw
+var toolkit_description_default = "<toolkit id=\"{{ serverId }}\">\n<instruction>\nBefore you use any capabilities below, you MUST call this tool with a list of names to learn how to use them properly; this includes:\n- For tools: Arguments schema needed to pass to use_tool\n- For skills: Detailed instructions that will expand when invoked (Prefer to be explored first when relevant)\n\nThis tool is optimized for batch queries - you can request multiple capabilities at once for better performance.\n\nHow to invoke:\n- For MCP tools: Use use_tool with toolName and toolArgs based on the schema\n- For skills: Use this tool with the skill name to get expanded instructions\n</instruction>\n\n<available_capabilities>\n{% for server in servers -%}\n<group name=\"{{ server.name }}\">\n{% if server.instruction -%}\n<group_instruction>{{ server.instruction }}</group_instruction>\n{% endif -%}\n{% if server.omitToolDescription -%}\n{% for toolName in server.toolNames -%}\n<item name=\"{{ toolName }}\"></item>\n{% endfor -%}\n{% else -%}\n{% for tool in server.tools -%}\n<item name=\"{{ tool.displayName }}\"><description>{{ tool.description | default: \"No description\" }}</description></item>\n{% endfor -%}\n{% endif -%}\n</group>\n{% endfor -%}\n{% if skills.size > 0 -%}\n<group name=\"skills\">\n{% for skill in skills -%}\n<item name=\"{{ skill.displayName }}\"><description>{{ skill.description }}</description></item>\n{% endfor -%}\n</group>\n{% endif -%}\n</available_capabilities>\n</toolkit>\n";
+
+//#endregion
+//#region src/tools/DescribeToolsTool.ts
+/**
+* Formats skill instructions with the loading command message prefix.
+* This message is used by Claude Code to indicate that a skill is being loaded.
+*
+* @param name - The skill name
+* @param instructions - The raw skill instructions/content
+* @returns Formatted instructions with command message prefix
+*/
+function formatSkillInstructions(name, instructions) {
+	return `<command-message>The "${name}" skill is loading</command-message>\n${instructions}`;
+}
+/**
+* DescribeToolsTool provides progressive disclosure of MCP tools and skills.
+*
+* This tool lists available tools from all connected MCP servers and skills
+* from the configured skills directories. Users can query for specific tools
+* or skills to get detailed input schemas and descriptions.
+*
+* Tool naming conventions:
+* - Unique tools: use plain name (e.g., "browser_click")
+* - Clashing tools: use serverName__toolName format (e.g., "playwright__click")
+* - Skills: use skill__skillName format (e.g., "skill__pdf")
+*
+* @example
+* const tool = new DescribeToolsTool(clientManager, skillService);
+* const definition = await tool.getDefinition();
+* const result = await tool.execute({ toolNames: ['browser_click', 'skill__pdf'] });
+*/
+var DescribeToolsTool = class DescribeToolsTool {
+	static TOOL_NAME = "describe_tools";
+	clientManager;
+	skillService;
+	definitionsCacheService;
+	liquid = new Liquid();
+	/** Cache for auto-detected skills from prompt front-matter */
+	autoDetectedSkillsCache = null;
+	/** Unique server identifier for this mcp-proxy instance */
+	serverId;
+	/**
+	* Creates a new DescribeToolsTool instance
+	* @param clientManager - The MCP client manager for accessing remote servers
+	* @param skillService - Optional skill service for loading skills
+	* @param serverId - Unique server identifier for this mcp-proxy instance
+	*/
+	constructor(clientManager, skillService, serverId, definitionsCacheService) {
+		this.clientManager = clientManager;
+		this.skillService = skillService;
+		this.serverId = serverId || DEFAULT_SERVER_ID;
+		this.definitionsCacheService = definitionsCacheService || new DefinitionsCacheService(clientManager, skillService);
+	}
+	/**
+	* Clears the cached auto-detected skills from prompt front-matter.
+	* Use this when prompt configurations may have changed or when
+	* the skill service cache is invalidated.
+	*/
+	clearAutoDetectedSkillsCache() {
+		this.autoDetectedSkillsCache = null;
+		this.definitionsCacheService.clearLiveCache();
+	}
+	/**
+	* Detects and caches skills from prompt front-matter across all connected MCP servers.
+	* Fetches all prompts and checks their content for YAML front-matter with name/description.
+	* Results are cached to avoid repeated fetches.
+	*
+	* Error Handling Strategy:
+	* - Errors are logged to stderr but do not fail the overall detection process
+	* - This ensures partial results are returned even if some servers/prompts fail
+	* - Common failure reasons: server temporarily unavailable, prompt requires arguments,
+	*   network timeout, or server doesn't support listPrompts
+	* - Errors are prefixed with [skill-detection] for easy filtering in logs
+	*
+	* @returns Array of auto-detected skills from prompt front-matter
+	*/
+	async detectSkillsFromPromptFrontMatter() {
+		if (this.autoDetectedSkillsCache !== null) return this.autoDetectedSkillsCache;
+		const clients = this.clientManager.getAllClients();
+		let listPromptsFailures = 0;
+		let fetchPromptFailures = 0;
+		const autoDetectedSkills = (await Promise.all(clients.map(async (client) => {
+			const detectedSkills = [];
+			const configuredPromptNames = new Set(client.prompts ? Object.keys(client.prompts) : []);
+			try {
+				const prompts = await client.listPrompts();
+				if (!prompts || prompts.length === 0) return detectedSkills;
+				const promptResults = await Promise.all(prompts.map(async (promptInfo) => {
+					if (configuredPromptNames.has(promptInfo.name)) return null;
+					try {
+						const skillExtraction = extractSkillFrontMatter(((await client.getPrompt(promptInfo.name)).messages || []).map((m) => {
+							const content = m.content;
+							if (typeof content === "string") return content;
+							if (content && typeof content === "object" && "text" in content) return String(content.text);
+							return "";
+						}).join("\n"));
+						if (skillExtraction) return {
+							serverName: client.serverName,
+							promptName: promptInfo.name,
+							skill: skillExtraction.skill
+						};
+						return null;
+					} catch (error) {
+						fetchPromptFailures++;
+						console.error(`${LOG_PREFIX_SKILL_DETECTION} Failed to fetch prompt '${promptInfo.name}' from ${client.serverName}: ${error instanceof Error ? error.message : "Unknown error"}`);
+						return null;
+					}
+				}));
+				for (const result of promptResults) if (result) detectedSkills.push(result);
+			} catch (error) {
+				listPromptsFailures++;
+				console.error(`${LOG_PREFIX_SKILL_DETECTION} Failed to list prompts from ${client.serverName}: ${error instanceof Error ? error.message : "Unknown error"}`);
+			}
+			return detectedSkills;
+		}))).flat();
+		if (listPromptsFailures > 0 || fetchPromptFailures > 0) console.error(`${LOG_PREFIX_SKILL_DETECTION} Completed with ${listPromptsFailures} server failure(s) and ${fetchPromptFailures} prompt failure(s). Detected ${autoDetectedSkills.length} skill(s).`);
+		this.autoDetectedSkillsCache = autoDetectedSkills;
+		return autoDetectedSkills;
+	}
+	/**
+	* Collects skills derived from prompt configurations across all connected MCP servers.
+	* Includes both explicitly configured prompts and auto-detected skills from front-matter.
+	*
+	* @returns Array of skill template data derived from prompts
+	*/
+	async collectPromptSkills() {
+		const promptSkills = [];
+		const serverDefinitions = await this.definitionsCacheService.getServerDefinitions();
+		for (const serverDefinition of serverDefinitions) for (const promptSkill of serverDefinition.promptSkills) promptSkills.push({
+			name: promptSkill.skill.name,
+			displayName: promptSkill.skill.name,
+			description: promptSkill.skill.description
+		});
+		return promptSkills;
+	}
+	/**
+	* Finds a prompt-based skill by name from all connected MCP servers.
+	* Searches both explicitly configured prompts and auto-detected skills from front-matter.
+	*
+	* @param skillName - The skill name to search for
+	* @returns Object with serverName, promptName, and skill config, or undefined if not found
+	*/
+	async findPromptSkill(skillName) {
+		if (!skillName) return void 0;
+		return await this.definitionsCacheService.getPromptSkillByName(skillName);
+	}
+	/**
+	* Retrieves skill content from a prompt-based skill configuration.
+	* Fetches the prompt from the MCP server and extracts text content.
+	* Handles both explicitly configured prompts and auto-detected skills from front-matter.
+	*
+	* @param skillName - The skill name being requested
+	* @returns SkillDescription if found and successfully fetched, undefined otherwise
+	*/
+	async getPromptSkillContent(skillName) {
+		const promptSkill = await this.findPromptSkill(skillName);
+		if (!promptSkill) return void 0;
+		try {
+			const rawInstructions = (await (await this.clientManager.ensureConnected(promptSkill.serverName)).getPrompt(promptSkill.promptName)).messages?.map((m) => {
+				const content = m.content;
+				if (typeof content === "string") return content;
+				if (content && typeof content === "object" && "text" in content) return String(content.text);
+				return "";
+			}).join("\n") || "";
+			return {
+				name: promptSkill.skill.name,
+				location: promptSkill.skill.folder || `${PROMPT_LOCATION_PREFIX}${promptSkill.serverName}/${promptSkill.promptName}`,
+				instructions: formatSkillInstructions(promptSkill.skill.name, rawInstructions)
+			};
+		} catch (error) {
+			console.error(`Failed to get prompt-based skill '${skillName}': ${error instanceof Error ? error.message : "Unknown error"}`);
+			return;
+		}
+	}
+	/**
+	* Builds the combined toolkit description using a single Liquid template.
+	*
+	* Collects all tools from connected MCP servers and all skills, then renders
+	* them together using the toolkit-description.liquid template.
+	*
+	* Tool names are prefixed with serverName__ when the same tool exists
+	* on multiple servers. Skill names are prefixed with skill__ when they
+	* clash with MCP tools or other skills.
+	*
+	* @returns Object with rendered description and set of all tool names
+	*/
+	async buildToolkitDescription() {
+		const serverDefinitions = await this.definitionsCacheService.getServerDefinitions();
+		const toolToServers = /* @__PURE__ */ new Map();
+		for (const serverDefinition of serverDefinitions) for (const tool of serverDefinition.tools) {
+			if (!toolToServers.has(tool.name)) toolToServers.set(tool.name, []);
+			toolToServers.get(tool.name)?.push(serverDefinition.serverName);
+		}
+		/**
+		* Formats tool name with server prefix if the tool exists on multiple servers
+		*/
+		const formatToolName = (toolName, serverName) => {
+			return (toolToServers.get(toolName) || []).length > 1 ? `${serverName}__${toolName}` : toolName;
+		};
+		const allToolNames = /* @__PURE__ */ new Set();
+		const servers = serverDefinitions.map((serverDefinition) => {
+			const formattedTools = serverDefinition.tools.map((t) => ({
+				displayName: formatToolName(t.name, serverDefinition.serverName),
+				description: t.description
+			}));
+			for (const tool of formattedTools) allToolNames.add(tool.displayName);
+			return {
+				name: serverDefinition.serverName,
+				instruction: serverDefinition.serverInstruction,
+				omitToolDescription: serverDefinition.omitToolDescription || false,
+				tools: formattedTools,
+				toolNames: formattedTools.map((t) => t.displayName)
+			};
+		});
+		const [rawSkills, cachedSkills, promptSkills] = await Promise.all([
+			this.skillService ? this.skillService.getSkills() : Promise.resolve([]),
+			this.definitionsCacheService.getCachedFileSkills(),
+			this.collectPromptSkills()
+		]);
+		const seenSkillNames = /* @__PURE__ */ new Set();
+		const allSkillsData = [];
+		for (const skill of rawSkills) if (!seenSkillNames.has(skill.name)) {
+			seenSkillNames.add(skill.name);
+			allSkillsData.push({
+				name: skill.name,
+				displayName: skill.name,
+				description: skill.description
+			});
+		}
+		for (const skill of cachedSkills) if (!seenSkillNames.has(skill.name)) {
+			seenSkillNames.add(skill.name);
+			allSkillsData.push({
+				name: skill.name,
+				displayName: skill.name,
+				description: skill.description
+			});
+		}
+		for (const skill of promptSkills) if (!seenSkillNames.has(skill.name)) {
+			seenSkillNames.add(skill.name);
+			allSkillsData.push(skill);
+		}
+		const skills = allSkillsData.map((skill) => {
+			const clashesWithMcpTool = allToolNames.has(skill.name);
+			return {
+				name: skill.name,
+				displayName: clashesWithMcpTool ? `${SKILL_PREFIX}${skill.name}` : skill.name,
+				description: skill.description
+			};
+		});
+		return {
+			content: await this.liquid.parseAndRender(toolkit_description_default, {
+				servers,
+				skills,
+				serverId: this.serverId
+			}),
+			toolNames: allToolNames
+		};
+	}
+	/**
+	* Gets the tool definition including available tools and skills in a unified format.
+	*
+	* The definition includes:
+	* - All MCP tools from connected servers
+	* - All available skills (file-based and prompt-based)
+	* - Unified instructions for querying capability details
+	*
+	* Tool names are prefixed with serverName__ when clashing.
+	* Skill names are prefixed with skill__ when clashing.
+	*
+	* @returns Tool definition with description and input schema
+	*/
+	async getDefinition() {
+		const { content } = await this.buildToolkitDescription();
+		return {
+			name: DescribeToolsTool.TOOL_NAME,
+			description: content,
+			inputSchema: {
+				type: "object",
+				properties: { toolNames: {
+					type: "array",
+					items: {
+						type: "string",
+						minLength: 1
+					},
+					description: "List of tool names to get detailed information about",
+					minItems: 1
+				} },
+				required: ["toolNames"],
+				additionalProperties: false
+			}
+		};
+	}
+	/**
+	* Executes tool description lookup for the requested tool and skill names.
+	*
+	* Handles three types of lookups:
+	* 1. skill__name - Returns skill information from SkillService
+	* 2. serverName__toolName - Returns tool from specific server
+	* 3. plainToolName - Returns tool(s) from all servers (multiple if clashing)
+	*
+	* @param input - Object containing toolNames array
+	* @returns CallToolResult with tool/skill descriptions or error
+	*/
+	async execute(input) {
+		try {
+			const { toolNames } = input;
+			const serverDefinitions = await this.definitionsCacheService.getServerDefinitions();
+			if (!toolNames || toolNames.length === 0) return {
+				content: [{
+					type: "text",
+					text: "No tool names provided. Please specify at least one tool name."
+				}],
+				isError: true
+			};
+			const serverToolsMap = /* @__PURE__ */ new Map();
+			const toolToServers = /* @__PURE__ */ new Map();
+			for (const serverDefinition of serverDefinitions) {
+				const typedTools = serverDefinition.tools.map((tool) => ({
+					name: tool.name,
+					description: tool.description,
+					inputSchema: tool.inputSchema
+				}));
+				serverToolsMap.set(serverDefinition.serverName, typedTools);
+				for (const tool of typedTools) {
+					if (!toolToServers.has(tool.name)) toolToServers.set(tool.name, []);
+					toolToServers.get(tool.name)?.push(serverDefinition.serverName);
+				}
+			}
+			const lookupResults = await Promise.all(toolNames.map(async (requestedName) => {
+				const result$1 = {
+					tools: [],
+					skills: [],
+					notFound: null
+				};
+				if (requestedName.startsWith(SKILL_PREFIX)) {
+					const skillName = requestedName.slice(SKILL_PREFIX.length);
+					if (this.skillService) {
+						const skill = await this.skillService.getSkill(skillName);
+						if (skill) {
+							result$1.skills.push({
+								name: skill.name,
+								location: skill.basePath,
+								instructions: formatSkillInstructions(skill.name, skill.content)
+							});
+							return result$1;
+						}
+					}
+					const promptSkillContent = await this.getPromptSkillContent(skillName);
+					if (promptSkillContent) {
+						result$1.skills.push(promptSkillContent);
+						return result$1;
+					}
+					result$1.notFound = requestedName;
+					return result$1;
+				}
+				const { serverName, actualToolName } = parseToolName(requestedName);
+				if (serverName) {
+					const serverTools = serverToolsMap.get(serverName);
+					if (!serverTools) {
+						result$1.notFound = requestedName;
+						return result$1;
+					}
+					const tool = serverTools.find((t) => t.name === actualToolName);
+					if (tool) result$1.tools.push({
+						server: serverName,
+						tool: {
+							name: tool.name,
+							description: tool.description,
+							inputSchema: tool.inputSchema
+						}
+					});
+					else result$1.notFound = requestedName;
+					return result$1;
+				}
+				const servers = toolToServers.get(actualToolName);
+				if (!servers || servers.length === 0) {
+					if (this.skillService) {
+						const skill = await this.skillService.getSkill(actualToolName);
+						if (skill) {
+							result$1.skills.push({
+								name: skill.name,
+								location: skill.basePath,
+								instructions: formatSkillInstructions(skill.name, skill.content)
+							});
+							return result$1;
+						}
+					}
+					const promptSkillContent = await this.getPromptSkillContent(actualToolName);
+					if (promptSkillContent) {
+						result$1.skills.push(promptSkillContent);
+						return result$1;
+					}
+					result$1.notFound = requestedName;
+					return result$1;
+				}
+				if (servers.length === 1) {
+					const server = servers[0];
+					const tool = serverToolsMap.get(server).find((t) => t.name === actualToolName);
+					result$1.tools.push({
+						server,
+						tool: {
+							name: tool.name,
+							description: tool.description,
+							inputSchema: tool.inputSchema
+						}
+					});
+				} else for (const server of servers) {
+					const tool = serverToolsMap.get(server).find((t) => t.name === actualToolName);
+					result$1.tools.push({
+						server,
+						tool: {
+							name: tool.name,
+							description: tool.description,
+							inputSchema: tool.inputSchema
+						}
+					});
+				}
+				return result$1;
+			}));
+			const foundTools = [];
+			const foundSkills = [];
+			const notFoundItems = [];
+			for (const result$1 of lookupResults) {
+				foundTools.push(...result$1.tools);
+				foundSkills.push(...result$1.skills);
+				if (result$1.notFound) notFoundItems.push(result$1.notFound);
+			}
+			if (foundTools.length === 0 && foundSkills.length === 0) return {
+				content: [{
+					type: "text",
+					text: `None of the requested tools/skills found.\nRequested: ${toolNames.join(", ")}\nUse describe_tools to see available tools and skills.`
+				}],
+				isError: true
+			};
+			const result = {};
+			const nextSteps = [];
+			if (foundTools.length > 0) {
+				result.tools = foundTools;
+				nextSteps.push("For MCP tools: Use the use_tool function with toolName and toolArgs based on the inputSchema above.");
+			}
+			if (foundSkills.length > 0) {
+				result.skills = foundSkills;
+				nextSteps.push(`For skill, just follow skill's description to continue.`);
+			}
+			if (nextSteps.length > 0) result.nextSteps = nextSteps;
+			if (notFoundItems.length > 0) {
+				result.notFound = notFoundItems;
+				result.warnings = [`Items not found: ${notFoundItems.join(", ")}`];
+			}
+			return { content: [{
+				type: "text",
+				text: JSON.stringify(result, null, 2)
+			}] };
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: `Error describing tools: ${error instanceof Error ? error.message : "Unknown error"}`
+				}],
+				isError: true
+			};
+		}
+	}
+};
+
+//#endregion
+//#region src/utils/toolCapabilities.ts
+const TOOL_CAPABILITIES_META_KEY = "agiflowai/capabilities";
+function getToolCapabilities(tool) {
+	const rawCapabilities = tool._meta?.[TOOL_CAPABILITIES_META_KEY];
+	if (!Array.isArray(rawCapabilities)) return [];
+	return rawCapabilities.filter((value) => typeof value === "string");
+}
+function getUniqueSortedCapabilities(tools) {
+	return Array.from(new Set(tools.flatMap((tool) => getToolCapabilities(tool)))).sort();
+}
+
+//#endregion
+//#region src/tools/SearchListToolsTool.ts
+var SearchListToolsTool = class SearchListToolsTool {
+	static TOOL_NAME = "list_tools";
+	constructor(_clientManager, definitionsCacheService) {
+		this._clientManager = _clientManager;
+		this.definitionsCacheService = definitionsCacheService;
+	}
+	formatToolName(toolName, serverName, toolToServers) {
+		return (toolToServers.get(toolName) || []).length > 1 ? `${serverName}__${toolName}` : toolName;
+	}
+	async getDefinition() {
+		const serverDefinitions = await this.definitionsCacheService.getServerDefinitions();
+		const capabilitySummary = serverDefinitions.length > 0 ? serverDefinitions.map((server) => {
+			const capabilities = getUniqueSortedCapabilities(server.tools);
+			const summary = capabilities.length > 0 ? capabilities.join(", ") : server.serverInstruction || "No capability summary available";
+			return `${server.serverName}: ${summary}`;
+		}).join("\n") : "No proxied servers available.";
+		return {
+			name: SearchListToolsTool.TOOL_NAME,
+			description: `Search proxied MCP tools by server capability summary.\n\nAvailable capabilities:\n${capabilitySummary}`,
+			inputSchema: {
+				type: "object",
+				properties: {
+					capability: {
+						type: "string",
+						description: "Optional capability filter. Matches explicit capability tags first, then server summaries, server names, tool names, and tool descriptions."
+					},
+					serverName: {
+						type: "string",
+						description: "Optional server name filter."
+					}
+				},
+				additionalProperties: false
+			}
+		};
+	}
+	async execute(input) {
+		const serverDefinitions = await this.definitionsCacheService.getServerDefinitions();
+		const capabilityFilter = input.capability?.trim().toLowerCase();
+		const serverNameFilter = input.serverName?.trim().toLowerCase();
+		const toolToServers = /* @__PURE__ */ new Map();
+		for (const serverDefinition of serverDefinitions) for (const tool of serverDefinition.tools) {
+			if (!toolToServers.has(tool.name)) toolToServers.set(tool.name, []);
+			toolToServers.get(tool.name)?.push(serverDefinition.serverName);
+		}
+		const filteredServers = serverDefinitions.filter((serverDefinition) => {
+			if (serverNameFilter && serverDefinition.serverName.toLowerCase() !== serverNameFilter) return false;
+			if (!capabilityFilter) return true;
+			if ((serverDefinition.serverInstruction?.toLowerCase() || "").includes(capabilityFilter)) return true;
+			if (getUniqueSortedCapabilities(serverDefinition.tools).some((capability) => capability.toLowerCase().includes(capabilityFilter))) return true;
+			return serverDefinition.tools.some((tool) => {
+				const toolName = this.formatToolName(tool.name, serverDefinition.serverName, toolToServers);
+				const toolCapabilities = getToolCapabilities(tool);
+				return toolName.toLowerCase().includes(capabilityFilter) || (tool.description || "").toLowerCase().includes(capabilityFilter) || toolCapabilities.some((capability) => capability.toLowerCase().includes(capabilityFilter));
+			});
+		}).map((serverDefinition) => ({
+			server: serverDefinition.serverName,
+			capabilities: getUniqueSortedCapabilities(serverDefinition.tools),
+			summary: serverDefinition.serverInstruction,
+			tools: serverDefinition.tools.map((tool) => ({
+				name: this.formatToolName(tool.name, serverDefinition.serverName, toolToServers),
+				description: serverDefinition.omitToolDescription ? void 0 : tool.description,
+				capabilities: getToolCapabilities(tool)
+			}))
+		})).filter((server) => server.tools.length > 0);
+		const result = { servers: filteredServers };
+		return {
+			content: [{
+				type: "text",
+				text: JSON.stringify(result, null, 2)
+			}],
+			isError: filteredServers.length === 0 ? true : void 0
+		};
+	}
+};
+
+//#endregion
+//#region src/tools/UseToolTool.ts
+/**
+* UseToolTool executes MCP tools and skills with proper error handling.
+*
+* This tool supports three invocation patterns:
+* 1. skill__skillName - Invokes a skill from the configured skills directory
+* 2. serverName__toolName - Invokes a tool on a specific MCP server
+* 3. plainToolName - Searches all servers for a unique tool match
+*
+* @example
+* const tool = new UseToolTool(clientManager, skillService);
+* await tool.execute({ toolName: 'skill__pdf' }); // Invoke a skill
+* await tool.execute({ toolName: 'playwright__browser_click', toolArgs: { ref: 'btn' } });
+*/
+var UseToolTool = class UseToolTool {
+	static TOOL_NAME = "use_tool";
+	clientManager;
+	skillService;
+	definitionsCacheService;
+	/** Unique server identifier for this mcp-proxy instance */
+	serverId;
+	/**
+	* Creates a new UseToolTool instance
+	* @param clientManager - The MCP client manager for accessing remote servers
+	* @param skillService - Optional skill service for loading and executing skills
+	* @param serverId - Unique server identifier for this mcp-proxy instance
+	*/
+	constructor(clientManager, skillService, serverId, definitionsCacheService) {
+		this.clientManager = clientManager;
+		this.skillService = skillService;
+		this.definitionsCacheService = definitionsCacheService || new DefinitionsCacheService(clientManager, skillService);
+		this.serverId = serverId || DEFAULT_SERVER_ID;
+	}
+	/**
+	* Returns the MCP tool definition with name, description, and input schema.
+	*
+	* The definition describes how to use this tool to execute MCP tools or skills,
+	* including the skill__ prefix format for skill invocations.
+	*
+	* @returns The tool definition conforming to MCP spec
+	*/
+	getDefinition() {
+		return {
+			name: UseToolTool.TOOL_NAME,
+			description: `Execute an MCP tool (NOT Skill) with provided arguments. You MUST call describe_tools first to discover the tool's correct arguments. Then to use tool:
+- Provide toolName and toolArgs based on the schema
+- If multiple servers provide the same tool, specify serverName
+
+IMPORTANT: Only use tools discovered from describe_tools with id="${this.serverId}".
+`,
+			inputSchema: {
+				type: "object",
+				properties: {
+					toolName: {
+						type: "string",
+						description: "Name of the tool to execute",
+						minLength: 1
+					},
+					toolArgs: {
+						type: "object",
+						description: "Arguments to pass to the tool, as discovered from describe_tools"
+					}
+				},
+				required: ["toolName"],
+				additionalProperties: false
+			}
+		};
+	}
+	/**
+	* Returns guidance message for skill invocation.
+	*
+	* Skills are not executed via use_tool - they provide instructions that should
+	* be followed directly. This method returns a message directing users to use
+	* describe_tools to get the skill details and follow its instructions.
+	*
+	* @param skill - The skill that was requested
+	* @returns CallToolResult with guidance message
+	*/
+	executeSkill(skill) {
+		return { content: [{
+			type: "text",
+			text: `Skill "${skill.name}" found. Skills provide instructions and should not be executed via use_tool.\n\nUse describe_tools to view the skill details at: ${skill.basePath}\n\nThen follow the skill's instructions directly.`
+		}] };
+	}
+	/**
+	* Finds a prompt-based skill by name from all connected MCP servers.
+	*
+	* @param skillName - The skill name to search for
+	* @returns PromptSkillMatch if found, undefined otherwise
+	*/
+	async findPromptSkill(skillName) {
+		if (!skillName) return void 0;
+		return await this.definitionsCacheService.getPromptSkillByName(skillName);
+	}
+	/**
+	* Returns guidance message for prompt-based skill invocation.
+	*
+	* @param promptSkill - The prompt skill match that was found
+	* @returns CallToolResult with guidance message
+	*/
+	executePromptSkill(promptSkill) {
+		const location = promptSkill.skill.folder || `prompt:${promptSkill.serverName}/${promptSkill.promptName}`;
+		return { content: [{
+			type: "text",
+			text: `Skill "${promptSkill.skill.name}" found. Skills provide instructions and should not be executed via use_tool.\n\nUse describe_tools to view the skill details at: ${location}\n\nThen follow the skill's instructions directly.`
+		}] };
+	}
+	/**
+	* Executes a tool or skill based on the provided input.
+	*
+	* Handles three invocation patterns:
+	* 1. skill__skillName - Routes to skill execution via SkillService
+	* 2. serverName__toolName - Routes to specific MCP server
+	* 3. plainToolName - Searches all servers for unique match
+	*
+	* Edge cases:
+	* - Returns error if skill not found when using skill__ prefix
+	* - Returns error if tool is blacklisted on target server
+	* - Returns disambiguation message if tool exists on multiple servers
+	*
+	* @param input - The tool/skill name and optional arguments
+	* @returns CallToolResult with execution output or error
+	*/
+	async execute(input) {
+		try {
+			const { toolName: inputToolName, toolArgs = {} } = input;
+			if (inputToolName.startsWith(SKILL_PREFIX)) {
+				const skillName = inputToolName.slice(SKILL_PREFIX.length);
+				if (this.skillService) {
+					const skill = await this.skillService.getSkill(skillName);
+					if (skill) return this.executeSkill(skill);
+				}
+				const promptSkill = await this.findPromptSkill(skillName);
+				if (promptSkill) return this.executePromptSkill(promptSkill);
+				return {
+					content: [{
+						type: "text",
+						text: `Skill "${skillName}" not found. Use describe_tools to see available skills.`
+					}],
+					isError: true
+				};
+			}
+			const knownServerNames = this.clientManager.getKnownServerNames();
+			const { serverName, actualToolName } = parseToolName(inputToolName);
+			if (serverName) try {
+				const client = await this.clientManager.ensureConnected(serverName);
+				if (client.toolBlacklist?.includes(actualToolName)) return {
+					content: [{
+						type: "text",
+						text: `Tool "${actualToolName}" is blacklisted on server "${serverName}" and cannot be executed.`
+					}],
+					isError: true
+				};
+				const reqTimeout = this.clientManager.getServerRequestTimeout(serverName);
+				return await client.callTool(actualToolName, toolArgs, reqTimeout ? { timeout: reqTimeout } : void 0);
+			} catch (error) {
+				return {
+					content: [{
+						type: "text",
+						text: `Failed to call tool "${actualToolName}" on server "${serverName}". Available servers: ${knownServerNames.join(", ")}. ${error instanceof Error ? error.message : "Unknown error"}`
+					}],
+					isError: true
+				};
+			}
+			const matchingServers = await this.definitionsCacheService.getServersForTool(actualToolName);
+			if (matchingServers.length === 0) {
+				if (this.skillService) {
+					const skill = await this.skillService.getSkill(actualToolName);
+					if (skill) return this.executeSkill(skill);
+				}
+				const promptSkill = await this.findPromptSkill(actualToolName);
+				if (promptSkill) return this.executePromptSkill(promptSkill);
+				return {
+					content: [{
+						type: "text",
+						text: `Tool or skill "${actualToolName}" not found. Use describe_tools to see available tools and skills.`
+					}],
+					isError: true
+				};
+			}
+			if (matchingServers.length > 1) return {
+				content: [{
+					type: "text",
+					text: `Tool "${actualToolName}" found on multiple servers. Use prefixed format to specify: ${matchingServers.map((s) => `${s}__${actualToolName}`).join(", ")}`
+				}],
+				isError: true
+			};
+			try {
+				const targetServerName = matchingServers[0];
+				const client = await this.clientManager.ensureConnected(targetServerName);
+				const targetReqTimeout = this.clientManager.getServerRequestTimeout(targetServerName);
+				return await client.callTool(actualToolName, toolArgs, targetReqTimeout ? { timeout: targetReqTimeout } : void 0);
+			} catch (error) {
+				return {
+					content: [{
+						type: "text",
+						text: `Failed to call tool "${actualToolName}": ${error instanceof Error ? error.message : "Unknown error"}`
+					}],
+					isError: true
+				};
+			}
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: `Error executing tool: ${error instanceof Error ? error.message : "Unknown error"}`
+				}],
+				isError: true
+			};
+		}
+	}
+};
+
+//#endregion
+//#region src/services/RemoteConfigCacheService.ts
+/**
+* RemoteConfigCacheService
+*
+* DESIGN PATTERNS:
+* - Service pattern for cache management
+* - Single responsibility principle
+* - File-based caching with TTL support
+*
+* CODING STANDARDS:
+* - Use async/await for asynchronous operations
+* - Handle file system errors gracefully
+* - Keep cache organized by URL hash
+* - Implement automatic cache expiration
+*
+* AVOID:
+* - Storing sensitive data in cache (headers with tokens)
+* - Unbounded cache growth
+* - Missing error handling for file operations
+*/
+/**
+* Service for caching remote MCP configurations
+*/
+var RemoteConfigCacheService = class {
+	cacheDir;
+	cacheTTL;
+	readEnabled;
+	writeEnabled;
+	logger;
+	constructor(options, logger = console) {
+		this.cacheDir = join(tmpdir(), "mcp-proxy-cache", "remote-configs");
+		this.cacheTTL = options?.ttl || 3600 * 1e3;
+		this.readEnabled = options?.readEnabled !== void 0 ? options.readEnabled : true;
+		this.writeEnabled = options?.writeEnabled !== void 0 ? options.writeEnabled : true;
+		this.logger = logger;
+	}
+	/**
+	* Generate a hash key from remote config URL
+	* Only uses URL for hashing to avoid caching credentials in the key
+	*/
+	generateCacheKey(url) {
+		return createHash("sha256").update(url).digest("hex");
+	}
+	/**
+	* Get the cache file path for a given cache key
+	*/
+	getCacheFilePath(cacheKey) {
+		return join(this.cacheDir, `${cacheKey}.json`);
+	}
+	/**
+	* Initialize cache directory
+	* Uses mkdir with recursive option which handles existing directories gracefully
+	* (no TOCTOU race condition from existsSync check)
+	*/
+	async ensureCacheDir() {
+		try {
+			await mkdir(this.cacheDir, { recursive: true });
+		} catch (error) {
+			if (error?.code !== "EEXIST") throw error;
+		}
+	}
+	/**
+	* Get cached data for a remote config URL
+	*/
+	async get(url) {
+		if (!this.readEnabled) return null;
+		try {
+			await this.ensureCacheDir();
+			const cacheKey = this.generateCacheKey(url);
+			const cacheFilePath = this.getCacheFilePath(cacheKey);
+			if (!existsSync(cacheFilePath)) return null;
+			const cacheContent = await readFile(cacheFilePath, "utf-8");
+			const cacheEntry = JSON.parse(cacheContent);
+			const now = Date.now();
+			if (now > cacheEntry.expiresAt) {
+				await unlink(cacheFilePath).catch(() => {});
+				return null;
+			}
+			const expiresInSeconds = Math.round((cacheEntry.expiresAt - now) / 1e3);
+			this.logger.debug(`Remote config cache hit for ${url} (expires in ${expiresInSeconds}s)`);
+			return cacheEntry.data;
+		} catch (error) {
+			this.logger.warn(`Failed to read remote config cache for ${url}`, error);
+			return null;
+		}
+	}
+	/**
+	* Set cached data for a remote config URL
+	*/
+	async set(url, data) {
+		if (!this.writeEnabled) return;
+		try {
+			await this.ensureCacheDir();
+			const cacheKey = this.generateCacheKey(url);
+			const cacheFilePath = this.getCacheFilePath(cacheKey);
+			const now = Date.now();
+			const cacheEntry = {
+				data,
+				timestamp: now,
+				expiresAt: now + this.cacheTTL,
+				url
+			};
+			await writeFile(cacheFilePath, JSON.stringify(cacheEntry, null, 2), "utf-8");
+			this.logger.debug(`Cached remote config for ${url} (TTL: ${Math.round(this.cacheTTL / 1e3)}s)`);
+		} catch (error) {
+			this.logger.warn(`Failed to write remote config cache for ${url}`, error);
+		}
+	}
+	/**
+	* Clear cache for a specific URL
+	*/
+	async clear(url) {
+		try {
+			const cacheKey = this.generateCacheKey(url);
+			const cacheFilePath = this.getCacheFilePath(cacheKey);
+			if (existsSync(cacheFilePath)) {
+				await unlink(cacheFilePath);
+				this.logger.info(`Cleared remote config cache for ${url}`);
+			}
+		} catch (error) {
+			this.logger.warn(`Failed to clear remote config cache for ${url}`, error);
+		}
+	}
+	/**
+	* Clear all cached remote configs
+	*/
+	async clearAll() {
+		try {
+			if (!existsSync(this.cacheDir)) return;
+			const files = await readdir(this.cacheDir);
+			const deletePromises = files.filter((file) => file.endsWith(".json")).map((file) => unlink(join(this.cacheDir, file)).catch((error) => {
+				this.logger.debug(`Failed to delete remote config cache file ${file}`, error);
+			}));
+			await Promise.all(deletePromises);
+			this.logger.info(`Cleared all remote config cache entries (${files.length} files)`);
+		} catch (error) {
+			this.logger.warn("Failed to clear all remote config cache", error);
+		}
+	}
+	/**
+	* Clean up expired cache entries
+	*/
+	async cleanExpired() {
+		try {
+			if (!existsSync(this.cacheDir)) return;
+			const now = Date.now();
+			const jsonFiles = (await readdir(this.cacheDir)).filter((file) => file.endsWith(".json"));
+			const expiredCount = (await Promise.all(jsonFiles.map(async (file) => {
+				const filePath = join(this.cacheDir, file);
+				try {
+					const content = await readFile(filePath, "utf-8");
+					if (now > JSON.parse(content).expiresAt) {
+						await unlink(filePath);
+						return true;
+					}
+					return false;
+				} catch (error) {
+					await unlink(filePath).catch(() => {
+						this.logger.debug(`Failed to delete corrupt cache file ${filePath}`, error);
+					});
+					this.logger.warn(`Removed unreadable remote config cache file ${filePath}`, error);
+					return true;
+				}
+			}))).filter(Boolean).length;
+			if (expiredCount > 0) this.logger.info(`Cleaned up ${expiredCount} expired remote config cache entries`);
+		} catch (error) {
+			this.logger.warn("Failed to clean expired remote config cache", error);
+		}
+	}
+	/**
+	* Get cache statistics
+	*/
+	async getStats() {
+		try {
+			if (!existsSync(this.cacheDir)) return {
+				totalEntries: 0,
+				totalSize: 0
+			};
+			const jsonFiles = (await readdir(this.cacheDir)).filter((file) => file.endsWith(".json"));
+			const totalSize = (await Promise.all(jsonFiles.map(async (file) => {
+				const filePath = join(this.cacheDir, file);
+				try {
+					const content = await readFile(filePath, "utf-8");
+					return Buffer.byteLength(content, "utf-8");
+				} catch {
+					return 0;
+				}
+			}))).reduce((sum, size) => sum + size, 0);
+			return {
+				totalEntries: jsonFiles.length,
+				totalSize
+			};
+		} catch (error) {
+			this.logger.warn("Failed to get remote config cache stats", error);
+			return {
+				totalEntries: 0,
+				totalSize: 0
+			};
+		}
+	}
+	/**
+	* Check if read from cache is enabled
+	*/
+	isReadEnabled() {
+		return this.readEnabled;
+	}
+	/**
+	* Check if write to cache is enabled
+	*/
+	isWriteEnabled() {
+		return this.writeEnabled;
+	}
+	/**
+	* Set read enabled state
+	*/
+	setReadEnabled(enabled) {
+		this.readEnabled = enabled;
+	}
+	/**
+	* Set write enabled state
+	*/
+	setWriteEnabled(enabled) {
+		this.writeEnabled = enabled;
+	}
+};
+
+//#endregion
+//#region src/services/ConfigFetcherService.ts
+/**
+* ConfigFetcherService
+*
+* DESIGN PATTERNS:
+* - Service pattern for business logic encapsulation
+* - Single responsibility principle
+* - Caching pattern for performance optimization
+*
+* CODING STANDARDS:
+* - Use async/await for asynchronous operations
+* - Throw descriptive errors for error cases
+* - Keep methods focused and well-named
+* - Document complex logic with comments
+*
+* AVOID:
+* - Mixing concerns (keep focused on single domain)
+* - Direct tool implementation (services should be tool-agnostic)
+*/
+/**
+* Service for fetching and caching MCP server configurations from local file and remote sources
+* Supports merging multiple remote configs with local config
+*/
+var ConfigFetcherService = class {
+	configFilePath;
+	cacheTtlMs;
+	cachedConfig = null;
+	lastFetchTime = 0;
+	remoteConfigCache;
+	logger;
+	constructor(options, logger = console) {
+		this.configFilePath = options.configFilePath;
+		this.cacheTtlMs = options.cacheTtlMs || 6e4;
+		this.logger = logger;
+		const useCache = options.useCache !== void 0 ? options.useCache : true;
+		this.remoteConfigCache = new RemoteConfigCacheService({
+			ttl: options.remoteCacheTtlMs || 3600 * 1e3,
+			readEnabled: useCache,
+			writeEnabled: true
+		}, logger);
+		if (!this.configFilePath) throw new Error("configFilePath must be provided");
+	}
+	/**
+	* Fetch MCP configuration from local file and remote sources with caching
+	* Merges remote configs with local config based on merge strategy
+	* @param forceRefresh - Force reload from source, bypassing cache
+	*/
+	async fetchConfiguration(forceRefresh = false) {
+		const now = Date.now();
+		if (!forceRefresh && this.cachedConfig && now - this.lastFetchTime < this.cacheTtlMs) return this.cachedConfig;
+		const localConfigData = await this.loadRawConfigFromFile();
+		const remoteConfigSources = localConfigData.remoteConfigs || [];
+		let mergedConfig = await this.parseConfig(localConfigData);
+		const remoteConfigPromises = remoteConfigSources.map(async (remoteSource) => {
+			try {
+				validateRemoteConfigSource(remoteSource);
+				return {
+					config: await this.loadFromUrl(remoteSource),
+					mergeStrategy: remoteSource.mergeStrategy || "local-priority",
+					url: remoteSource.url
+				};
+			} catch (error) {
+				this.logger.warn(`Failed to fetch remote config from ${remoteSource.url}`, error);
+				return null;
+			}
+		});
+		const remoteConfigResults = await Promise.all(remoteConfigPromises);
+		for (const result of remoteConfigResults) if (result !== null) mergedConfig = this.mergeConfigurations(mergedConfig, result.config, result.mergeStrategy);
+		if (!mergedConfig.mcpServers || typeof mergedConfig.mcpServers !== "object") throw new Error("Invalid MCP configuration: missing or invalid mcpServers");
+		this.cachedConfig = mergedConfig;
+		this.lastFetchTime = now;
+		return mergedConfig;
+	}
+	/**
+	* Load raw configuration data from a local file (supports JSON and YAML)
+	* Returns unparsed config data to allow access to remoteConfigs
+	*/
+	async loadRawConfigFromFile() {
+		if (!this.configFilePath) throw new Error("No config file path provided");
+		if (!existsSync(this.configFilePath)) throw new Error(`Config file not found: ${this.configFilePath}`);
+		try {
+			const content = await readFile(this.configFilePath, "utf-8");
+			let rawConfig;
+			if (this.configFilePath.endsWith(".yaml") || this.configFilePath.endsWith(".yml")) rawConfig = yaml.load(content);
+			else rawConfig = JSON.parse(content);
+			return rawConfig;
+		} catch (error) {
+			if (error instanceof Error) throw new Error(`Failed to load config file: ${error.message}`);
+			throw new Error("Failed to load config file: Unknown error");
+		}
+	}
+	/**
+	* Parse raw config data using Zod schema
+	* Filters out remoteConfigs to avoid including them in the final config
+	*/
+	async parseConfig(rawConfig) {
+		try {
+			const { remoteConfigs, ...configWithoutRemote } = rawConfig;
+			return parseMcpConfig(configWithoutRemote);
+		} catch (error) {
+			if (error instanceof Error) throw new Error(`Failed to parse config: ${error.message}`);
+			throw new Error("Failed to parse config: Unknown error");
+		}
+	}
+	/**
+	* Load configuration from a remote URL with caching
+	*
+	* SECURITY NOTE: This method fetches remote configs based on URLs from the local config file.
+	* This is intentional and safe because:
+	* 1. URLs are user-controlled via their local config file (not external input)
+	* 2. SSRF protection validates URLs before fetching (blocks private IPs, enforces HTTPS)
+	* 3. Users explicitly opt-in to remote configs in their local configuration
+	* 4. This enables centralized config management (intended feature, not a vulnerability)
+	*
+	* CodeQL alert "file-access-to-http" is a false positive here - we're not leaking
+	* file contents to arbitrary URLs, we're fetching configs from user-specified sources.
+	*/
+	async loadFromUrl(source) {
+		try {
+			const interpolatedUrl = this.interpolateEnvVars(source.url);
+			const cachedConfig = await this.remoteConfigCache.get(interpolatedUrl);
+			if (cachedConfig) return cachedConfig;
+			const interpolatedHeaders = source.headers ? Object.fromEntries(Object.entries(source.headers).map(([key, value]) => [key, this.interpolateEnvVars(value)])) : {};
+			const response = await fetch(interpolatedUrl, { headers: interpolatedHeaders });
+			if (!response.ok) throw new Error(`Failed to fetch remote config: ${response.status} ${response.statusText}`);
+			const config = parseMcpConfig(await response.json());
+			await this.remoteConfigCache.set(interpolatedUrl, config);
+			return config;
+		} catch (error) {
+			if (error instanceof Error) throw new Error(`Failed to fetch remote config from ${source.url}: ${error.message}`, { cause: error });
+			throw new Error(`Failed to fetch remote config from ${source.url}: Unknown error`);
+		}
+	}
+	/**
+	* Interpolate environment variables in a string
+	* Supports ${VAR_NAME} syntax
+	*/
+	interpolateEnvVars(value) {
+		return value.replace(/\$\{([^}]+)\}/g, (_, varName) => {
+			const envValue = process.env[varName];
+			if (envValue === void 0) {
+				this.logger.warn(`Environment variable ${varName} is not defined, keeping placeholder`);
+				return `\${${varName}}`;
+			}
+			return envValue;
+		});
+	}
+	/**
+	* Merge two MCP configurations based on the specified merge strategy
+	* @param localConfig Configuration loaded from local file
+	* @param remoteConfig Configuration loaded from remote URL
+	* @param mergeStrategy Strategy for merging configs
+	* @returns Merged configuration
+	*/
+	mergeConfigurations(localConfig, remoteConfig, mergeStrategy) {
+		switch (mergeStrategy) {
+			case "local-priority": return {
+				id: localConfig.id ?? remoteConfig.id,
+				mcpServers: {
+					...remoteConfig.mcpServers,
+					...localConfig.mcpServers
+				},
+				skills: localConfig.skills ?? remoteConfig.skills
+			};
+			case "remote-priority": return {
+				id: remoteConfig.id ?? localConfig.id,
+				mcpServers: {
+					...localConfig.mcpServers,
+					...remoteConfig.mcpServers
+				},
+				skills: remoteConfig.skills ?? localConfig.skills
+			};
+			case "merge-deep": {
+				const merged = { ...remoteConfig.mcpServers };
+				for (const [serverName, localServerConfig] of Object.entries(localConfig.mcpServers)) if (merged[serverName]) {
+					const remoteServer = merged[serverName];
+					const mergedConfig = {
+						...remoteServer.config,
+						...localServerConfig.config
+					};
+					const remoteEnv = "env" in remoteServer.config ? remoteServer.config.env : void 0;
+					const localEnv = "env" in localServerConfig.config ? localServerConfig.config.env : void 0;
+					if (remoteEnv || localEnv) mergedConfig.env = {
+						...remoteEnv || {},
+						...localEnv || {}
+					};
+					const remoteHeaders = "headers" in remoteServer.config ? remoteServer.config.headers : void 0;
+					const localHeaders = "headers" in localServerConfig.config ? localServerConfig.config.headers : void 0;
+					if (remoteHeaders || localHeaders) mergedConfig.headers = {
+						...remoteHeaders || {},
+						...localHeaders || {}
+					};
+					merged[serverName] = {
+						...remoteServer,
+						...localServerConfig,
+						config: mergedConfig
+					};
+				} else merged[serverName] = localServerConfig;
+				return {
+					id: localConfig.id ?? remoteConfig.id,
+					mcpServers: merged,
+					skills: localConfig.skills ?? remoteConfig.skills
+				};
+			}
+			default: throw new Error(`Unknown merge strategy: ${mergeStrategy}`);
+		}
+	}
+	/**
+	* Clear the cached configuration
+	*/
+	clearCache() {
+		this.cachedConfig = null;
+		this.lastFetchTime = 0;
+	}
+	/**
+	* Check if cache is valid
+	*/
+	isCacheValid() {
+		const now = Date.now();
+		return this.cachedConfig !== null && now - this.lastFetchTime < this.cacheTtlMs;
+	}
+};
+
+//#endregion
+//#region src/services/logger.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toLogOptions(data) {
+	if (data === void 0) return;
+	if (data instanceof Error) return { exception: data };
+	if (isRecord(data) && ("attributes" in data || "exception" in data || "context" in data)) return data;
+	if (isRecord(data)) return { attributes: data };
+	return { attributes: { value: data } };
+}
+function createLoggerFacade(handle) {
+	const logger = handle.logger;
+	return {
+		backend: handle.backend,
+		enabled: handle.enabled,
+		endpoint: handle.endpoint,
+		filePath: handle.filePath,
+		trace(message, data) {
+			logger.trace(message, toLogOptions(data));
+		},
+		debug(message, data) {
+			logger.debug(message, toLogOptions(data));
+		},
+		info(message, data) {
+			logger.info(message, toLogOptions(data));
+		},
+		warn(message, data) {
+			logger.warn(message, toLogOptions(data));
+		},
+		error(message, data) {
+			logger.error(message, toLogOptions(data));
+		},
+		getTraceContext() {
+			return logger.getTraceContext();
+		},
+		flush: () => handle.flush(),
+		shutdown: () => handle.shutdown()
+	};
+}
+async function createProxyLogger(options = {}) {
+	return createLoggerFacade(await createNodeTelemetry({
+		env: options.env,
+		workspaceRoot: options.workspaceRoot,
+		serviceName: options.serviceName ?? "@agimon-ai/mcp-proxy",
+		serviceVersion: options.serviceVersion,
+		logDir: options.logDir,
+		logFileName: options.logFileName,
+		maxFileSizeBytes: options.maxFileSizeBytes,
+		maxFileCount: options.maxFileCount
+	}));
+}
+
+//#endregion
+//#region src/services/McpClientManagerService.ts
+/** Default connection timeout in milliseconds (30 seconds) */
+const DEFAULT_CONNECTION_TIMEOUT_MS = 3e4;
+/**
+* Checks if an error is a session-related error from an HTTP backend
+* (e.g., downstream server restarted and no longer recognizes the session ID).
+*/
+function isSessionError(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return message.includes("unknown session") || message.includes("Session not found");
+}
+/**
+* MCP Client wrapper for managing individual server connections
+* This is an internal class used by McpClientManagerService
+*/
+var McpClient = class {
+	serverName;
+	serverInstruction;
+	toolBlacklist;
+	omitToolDescription;
+	prompts;
+	transport;
+	logger;
+	client;
+	childProcess;
+	connected = false;
+	reconnectFn;
+	constructor(serverName, transport, client, logger, config) {
+		this.serverName = serverName;
+		this.serverInstruction = config.instruction;
+		this.toolBlacklist = config.toolBlacklist;
+		this.omitToolDescription = config.omitToolDescription;
+		this.prompts = config.prompts;
+		this.transport = transport;
+		this.logger = logger;
+		this.client = client;
+	}
+	setChildProcess(process$1) {
+		this.childProcess = process$1;
+	}
+	setConnected(connected) {
+		this.connected = connected;
+	}
+	/**
+	* Sets a reconnection function that creates a fresh Client and transport.
+	* Called automatically by withSessionRetry when a session error is detected
+	* (e.g., downstream HTTP server restarted and the old session ID is invalid).
+	*/
+	setReconnectFn(fn) {
+		this.reconnectFn = fn;
+	}
+	/**
+	* Wraps an operation with automatic retry on session errors.
+	* If the operation fails with a session error (e.g., downstream server restarted),
+	* reconnects and retries once.
+	*/
+	async withSessionRetry(operation) {
+		try {
+			return await operation();
+		} catch (error) {
+			if (!this.reconnectFn || !isSessionError(error)) throw error;
+			this.logger.warn(`Session error for ${this.serverName}, reconnecting: ${error instanceof Error ? error.message : String(error)}`);
+			try {
+				await this.client.close();
+			} catch (closeError) {
+				this.logger.warn(`Failed to close stale client for ${this.serverName}`, closeError);
+			}
+			const result = await this.reconnectFn();
+			this.client = result.client;
+			if (result.childProcess) this.childProcess = result.childProcess;
+			return await operation();
+		}
+	}
+	async listTools() {
+		if (!this.connected) throw new Error(`Client for ${this.serverName} is not connected`);
+		return this.withSessionRetry(async () => {
+			return (await this.client.listTools()).tools;
+		});
+	}
+	async listResources() {
+		if (!this.connected) throw new Error(`Client for ${this.serverName} is not connected`);
+		return this.withSessionRetry(async () => {
+			return (await this.client.listResources()).resources;
+		});
+	}
+	async listPrompts() {
+		if (!this.connected) throw new Error(`Client for ${this.serverName} is not connected`);
+		return this.withSessionRetry(async () => {
+			return (await this.client.listPrompts()).prompts;
+		});
+	}
+	async callTool(name, args, options) {
+		if (!this.connected) throw new Error(`Client for ${this.serverName} is not connected`);
+		return this.withSessionRetry(async () => {
+			const requestOptions = options?.timeout ? { timeout: options.timeout } : void 0;
+			return await this.client.callTool({
+				name,
+				arguments: args
+			}, void 0, requestOptions);
+		});
+	}
+	async readResource(uri) {
+		if (!this.connected) throw new Error(`Client for ${this.serverName} is not connected`);
+		return this.withSessionRetry(async () => {
+			return await this.client.readResource({ uri });
+		});
+	}
+	async getPrompt(name, args) {
+		if (!this.connected) throw new Error(`Client for ${this.serverName} is not connected`);
+		return this.withSessionRetry(async () => {
+			return await this.client.getPrompt({
+				name,
+				arguments: args
+			});
+		});
+	}
+	async close() {
+		if (this.childProcess) this.childProcess.kill();
+		await this.client.close();
+		this.connected = false;
+	}
+};
+/**
+* Service for managing MCP client connections to remote servers
+*/
+var McpClientManagerService = class {
+	clients = /* @__PURE__ */ new Map();
+	serverConfigs = /* @__PURE__ */ new Map();
+	connectionPromises = /* @__PURE__ */ new Map();
+	logger;
+	constructor(logger = console) {
+		this.logger = logger;
+	}
+	/**
+	* Synchronously kill all stdio MCP server child processes.
+	* Must be called by the owner (e.g. transport/command layer) during shutdown.
+	*/
+	cleanupChildProcesses() {
+		for (const [serverName, client] of this.clients) try {
+			const childProcess = client["childProcess"];
+			if (childProcess && !childProcess.killed) {
+				this.logger.info(`Killing stdio MCP server: ${serverName} (PID: ${childProcess.pid})`);
+				childProcess.kill("SIGTERM");
+				setTimeout(() => {
+					if (!childProcess.killed) {
+						this.logger.warn(`Force killing stdio MCP server: ${serverName} (PID: ${childProcess.pid})`);
+						childProcess.kill("SIGKILL");
+					}
+				}, 1e3);
+			}
+		} catch (error) {
+			this.logger.warn(`Failed to kill child process for ${serverName}`, error);
+		}
+	}
+	/**
+	* Connect to an MCP server based on its configuration with timeout
+	* Uses the timeout from server config, falling back to default (30s)
+	*/
+	async connectToServer(serverName, config) {
+		this.serverConfigs.set(serverName, config);
+		await this.ensureConnected(serverName);
+	}
+	registerServerConfigs(configs) {
+		for (const [serverName, config] of Object.entries(configs)) this.serverConfigs.set(serverName, config);
+	}
+	getKnownServerNames() {
+		return Array.from(this.serverConfigs.keys());
+	}
+	getServerRequestTimeout(serverName) {
+		return this.serverConfigs.get(serverName)?.requestTimeout;
+	}
+	async ensureConnected(serverName) {
+		const existingClient = this.clients.get(serverName);
+		if (existingClient) return existingClient;
+		const inflightConnection = this.connectionPromises.get(serverName);
+		if (inflightConnection) return await inflightConnection;
+		const config = this.serverConfigs.get(serverName);
+		if (!config) throw new Error(`No configuration found for server "${serverName}"`);
+		const connectionPromise = this.createConnection(serverName, config);
+		this.connectionPromises.set(serverName, connectionPromise);
+		try {
+			return await connectionPromise;
+		} finally {
+			this.connectionPromises.delete(serverName);
+		}
+	}
+	async createConnection(serverName, config) {
+		const timeoutMs = config.timeout ?? DEFAULT_CONNECTION_TIMEOUT_MS;
+		const client = new Client({
+			name: `@agimon-ai/mcp-proxy-client`,
+			version: "0.1.0"
+		}, { capabilities: {} });
+		const mcpClient = new McpClient(serverName, config.transport, client, this.logger, {
+			instruction: config.instruction,
+			toolBlacklist: config.toolBlacklist,
+			omitToolDescription: config.omitToolDescription,
+			prompts: config.prompts
+		});
+		try {
+			await Promise.race([this.performConnection(mcpClient, config), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error(`Connection timeout after ${timeoutMs}ms`)), timeoutMs))]);
+			mcpClient.setConnected(true);
+			if (config.transport === "http" || config.transport === "sse") mcpClient.setReconnectFn(async () => {
+				try {
+					const newClient = new Client({
+						name: "@agimon-ai/mcp-proxy-client",
+						version: "0.1.0"
+					}, { capabilities: {} });
+					const newMcpClient = new McpClient(serverName, config.transport, newClient, this.logger, {});
+					await this.performConnection(newMcpClient, config);
+					return { client: newClient };
+				} catch (error) {
+					this.logger.warn(`Failed to reconnect to ${serverName}`, error);
+					throw error;
+				}
+			});
+			if (!mcpClient.serverInstruction) try {
+				const serverInstruction = mcpClient["client"].getInstructions();
+				if (serverInstruction) mcpClient.serverInstruction = serverInstruction;
+			} catch (error) {
+				this.logger.warn(`Failed to get server instruction from ${serverName}`, error);
+			}
+			this.clients.set(serverName, mcpClient);
+			return mcpClient;
+		} catch (error) {
+			await mcpClient.close();
+			throw error;
+		}
+	}
+	/**
+	* Perform the actual connection to MCP server
+	*/
+	async performConnection(mcpClient, config) {
+		if (config.transport === "stdio") await this.connectStdioClient(mcpClient, config.config);
+		else if (config.transport === "http") await this.connectHttpClient(mcpClient, config.config);
+		else if (config.transport === "sse") await this.connectSseClient(mcpClient, config.config);
+		else throw new Error(`Unsupported transport type: ${config.transport}`);
+	}
+	async connectStdioClient(mcpClient, config) {
+		const transport = new StdioClientTransport({
+			command: config.command,
+			args: config.args,
+			env: {
+				...process.env,
+				...config.env ?? {}
+			}
+		});
+		await mcpClient["client"].connect(transport);
+		const childProcess = transport["_process"];
+		if (childProcess) mcpClient.setChildProcess(childProcess);
+	}
+	async connectHttpClient(mcpClient, config) {
+		const transport = new StreamableHTTPClientTransport(new URL(config.url), { requestInit: config.headers ? { headers: config.headers } : void 0 });
+		await mcpClient["client"].connect(transport);
+	}
+	async connectSseClient(mcpClient, config) {
+		const transport = new SSEClientTransport(new URL(config.url));
+		await mcpClient["client"].connect(transport);
+	}
+	/**
+	* Get a connected client by server name
+	*/
+	getClient(serverName) {
+		return this.clients.get(serverName);
+	}
+	/**
+	* Get all connected clients
+	*/
+	getAllClients() {
+		return Array.from(this.clients.values());
+	}
+	/**
+	* Disconnect from a specific server
+	*/
+	async disconnectServer(serverName) {
+		const client = this.clients.get(serverName);
+		if (client) {
+			await client.close();
+			this.clients.delete(serverName);
+		}
+	}
+	/**
+	* Disconnect from all servers
+	*/
+	async disconnectAll() {
+		const disconnectPromises = Array.from(this.clients.values()).map((client) => client.close());
+		await Promise.all(disconnectPromises);
+		this.clients.clear();
+		this.connectionPromises.clear();
+	}
+	/**
+	* Check if a server is connected
+	*/
+	isConnected(serverName) {
+		return this.clients.has(serverName);
+	}
+};
+
+//#endregion
+//#region src/services/RuntimeStateService.ts
+/**
+* RuntimeStateService
+*
+* Persists runtime metadata for HTTP mcp-proxy instances so external commands
+* (for example `mcp-proxy stop`) can discover and target the correct server.
+*/
+const RUNTIME_DIR_NAME = "runtimes";
+const RUNTIME_FILE_SUFFIX = ".runtime.json";
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+function isRuntimeStateRecord(value) {
+	if (!isObject(value)) return false;
+	return typeof value.serverId === "string" && typeof value.host === "string" && typeof value.port === "number" && value.transport === "http" && typeof value.shutdownToken === "string" && typeof value.startedAt === "string" && typeof value.pid === "number" && (value.configPath === void 0 || typeof value.configPath === "string");
+}
+function toErrorMessage$2(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Runtime state persistence implementation.
+*/
+var RuntimeStateService = class RuntimeStateService {
+	runtimeDir;
+	logger;
+	constructor(runtimeDir, logger = console) {
+		this.runtimeDir = runtimeDir ?? RuntimeStateService.getDefaultRuntimeDir();
+		this.logger = logger;
+	}
+	/**
+	* Resolve default runtime directory under the user's home cache path.
+	* @returns Absolute runtime directory path
+	*/
+	static getDefaultRuntimeDir() {
+		return join(homedir(), ".aicode-toolkit", "mcp-proxy", RUNTIME_DIR_NAME);
+	}
+	/**
+	* Build runtime state file path for a given server ID.
+	* @param serverId - Target mcp-proxy server identifier
+	* @returns Absolute runtime file path
+	*/
+	getRecordPath(serverId) {
+		return join(this.runtimeDir, `${serverId}${RUNTIME_FILE_SUFFIX}`);
+	}
+	/**
+	* Persist a runtime state record.
+	* @param record - Runtime metadata to persist
+	* @returns Promise that resolves when write completes
+	*/
+	async write(record) {
+		await mkdir(this.runtimeDir, { recursive: true });
+		await writeFile(this.getRecordPath(record.serverId), JSON.stringify(record, null, 2), "utf-8");
+	}
+	/**
+	* Read a runtime state record by server ID.
+	* @param serverId - Target mcp-proxy server identifier
+	* @returns Matching runtime record, or null when no record exists
+	*/
+	async read(serverId) {
+		const filePath = this.getRecordPath(serverId);
+		try {
+			const content = await readFile(filePath, "utf-8");
+			const parsed = JSON.parse(content);
+			return isRuntimeStateRecord(parsed) ? parsed : null;
+		} catch (error) {
+			if (isObject(error) && "code" in error && error.code === "ENOENT") return null;
+			throw new Error(`Failed to read runtime state for server '${serverId}' from '${filePath}': ${toErrorMessage$2(error)}`);
+		}
+	}
+	/**
+	* List all persisted runtime records.
+	* @returns Array of runtime records
+	*/
+	async list() {
+		try {
+			const files = (await readdir(this.runtimeDir, { withFileTypes: true })).filter((entry) => entry.isFile() && entry.name.endsWith(RUNTIME_FILE_SUFFIX));
+			return (await Promise.all(files.map(async (file) => {
+				try {
+					const content = await readFile(join(this.runtimeDir, file.name), "utf-8");
+					const parsed = JSON.parse(content);
+					return isRuntimeStateRecord(parsed) ? parsed : null;
+				} catch (error) {
+					this.logger.debug(`Skipping unreadable runtime state file ${file.name}`, error);
+					return null;
+				}
+			}))).filter((record) => record !== null);
+		} catch (error) {
+			if (isObject(error) && "code" in error && error.code === "ENOENT") return [];
+			throw new Error(`Failed to list runtime states from '${this.runtimeDir}': ${toErrorMessage$2(error)}`);
+		}
+	}
+	/**
+	* Remove a runtime state record by server ID.
+	* @param serverId - Target mcp-proxy server identifier
+	* @returns Promise that resolves when delete completes
+	*/
+	async remove(serverId) {
+		await rm(this.getRecordPath(serverId), { force: true });
+	}
+};
+
+//#endregion
+//#region src/services/StopServerService/constants.ts
+/**
+* StopServerService constants.
+*/
+/** Maximum time in milliseconds to wait for a shutdown to complete. */
+const DEFAULT_STOP_TIMEOUT_MS = 5e3;
+/** Minimum timeout in milliseconds for individual health check requests. */
+const HEALTH_REQUEST_TIMEOUT_FLOOR_MS = 250;
+/** Delay in milliseconds between shutdown polling attempts. */
+const SHUTDOWN_POLL_INTERVAL_MS = 200;
+/** Path for the runtime health check endpoint. */
+const HEALTH_CHECK_PATH = "/health";
+/** Path for the authenticated admin shutdown endpoint. */
+const ADMIN_SHUTDOWN_PATH = "/admin/shutdown";
+/** HTTP GET method identifier. */
+const HTTP_METHOD_GET = "GET";
+/** HTTP POST method identifier. */
+const HTTP_METHOD_POST = "POST";
+/** HTTP header name for bearer token authorization. */
+const AUTHORIZATION_HEADER_NAME = "Authorization";
+/** Prefix for bearer token values in the Authorization header. */
+const BEARER_TOKEN_PREFIX = "Bearer ";
+/** HTTP protocol scheme prefix for URL construction. */
+const HTTP_PROTOCOL = "http://";
+/** Separator between host and port in URL construction. */
+const URL_PORT_SEPARATOR = ":";
+/** Loopback hostname. */
+const LOOPBACK_HOST_LOCALHOST = "localhost";
+/** IPv4 loopback address. */
+const LOOPBACK_HOST_IPV4 = "127.0.0.1";
+/** IPv6 loopback address. */
+const LOOPBACK_HOST_IPV6 = "::1";
+/** Hosts that are safe to send admin requests to (loopback only). */
+const ALLOWED_HOSTS = new Set([
+	LOOPBACK_HOST_LOCALHOST,
+	LOOPBACK_HOST_IPV4,
+	LOOPBACK_HOST_IPV6
+]);
+/** Expected status value in a healthy runtime response. */
+const HEALTH_STATUS_OK = "ok";
+/** Expected transport value in a healthy runtime response. */
+const HEALTH_TRANSPORT_HTTP = "http";
+/** Property key for status field in health responses. */
+const KEY_STATUS = "status";
+/** Property key for transport field in health responses. */
+const KEY_TRANSPORT = "transport";
+/** Property key for serverId field in runtime responses. */
+const KEY_SERVER_ID = "serverId";
+/** Property key for ok field in shutdown responses. */
+const KEY_OK = "ok";
+/** Property key for message field in shutdown responses. */
+const KEY_MESSAGE = "message";
+
+//#endregion
+//#region src/services/StopServerService/types.ts
+/**
+* Safely cast a non-null object to a string-keyed record for property access.
+* @param value - Object value already verified as non-null
+* @returns The same value typed as a record
+*/
+function toRecord(value) {
+	return value;
+}
+/**
+* Type guard for health responses.
+* @param value - Candidate payload to validate
+* @returns True when payload matches health response shape
+*/
+function isHealthResponse(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const record = toRecord(value);
+	return KEY_STATUS in record && record[KEY_STATUS] === HEALTH_STATUS_OK && KEY_TRANSPORT in record && record[KEY_TRANSPORT] === HEALTH_TRANSPORT_HTTP && (!(KEY_SERVER_ID in record) || record[KEY_SERVER_ID] === void 0 || typeof record[KEY_SERVER_ID] === "string");
+}
+/**
+* Type guard for shutdown responses.
+* @param value - Candidate payload to validate
+* @returns True when payload matches shutdown response shape
+*/
+function isShutdownResponse(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const record = toRecord(value);
+	return KEY_OK in record && typeof record[KEY_OK] === "boolean" && KEY_MESSAGE in record && typeof record[KEY_MESSAGE] === "string" && (!(KEY_SERVER_ID in record) || record[KEY_SERVER_ID] === void 0 || typeof record[KEY_SERVER_ID] === "string");
+}
+
+//#endregion
+//#region src/services/StopServerService/StopServerService.ts
+/**
+* Format runtime endpoint URL after validating the host is a loopback address.
+* Rejects non-loopback hosts to prevent SSRF via tampered runtime state files.
+* @param runtime - Runtime record to format
+* @param path - Request path to append
+* @returns Full runtime URL
+*/
+function buildRuntimeUrl(runtime, path) {
+	if (!ALLOWED_HOSTS.has(runtime.host)) throw new Error(`Refusing to connect to non-loopback host '${runtime.host}'. Only ${Array.from(ALLOWED_HOSTS).join(", ")} are allowed.`);
+	return `${HTTP_PROTOCOL}${runtime.host}${URL_PORT_SEPARATOR}${runtime.port}${path}`;
+}
+function toErrorMessage$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function sleep(delayMs) {
+	return new Promise((resolve$1) => {
+		setTimeout(resolve$1, delayMs);
+	});
+}
+/**
+* Service for resolving runtime targets and stopping them safely.
+*/
+var StopServerService = class {
+	runtimeStateService;
+	logger;
+	constructor(runtimeStateService = new RuntimeStateService(), logger = console) {
+		this.runtimeStateService = runtimeStateService;
+		this.logger = logger;
+	}
+	/**
+	* Resolve a target runtime and stop it cooperatively.
+	* @param request - Stop request options
+	* @returns Stop result payload
+	*/
+	async stop(request) {
+		const timeoutMs = request.timeoutMs ?? DEFAULT_STOP_TIMEOUT_MS;
+		const runtime = await this.resolveRuntime(request);
+		const health = await this.fetchHealth(runtime, timeoutMs);
+		if (!health.reachable) {
+			await this.runtimeStateService.remove(runtime.serverId);
+			throw new Error(`Runtime '${runtime.serverId}' is not reachable at http://${runtime.host}:${runtime.port}. Removed stale runtime record.`);
+		}
+		if (!request.force && health.payload?.serverId && health.payload.serverId !== runtime.serverId) throw new Error(`Refusing to stop runtime at http://${runtime.host}:${runtime.port}: expected server ID '${runtime.serverId}' but health endpoint reported '${health.payload.serverId}'. Use --force to override.`);
+		const shutdownToken = request.token ?? runtime.shutdownToken;
+		if (!shutdownToken) throw new Error(`No shutdown token available for runtime '${runtime.serverId}'.`);
+		const shutdownResponse = await this.requestShutdown(runtime, shutdownToken, timeoutMs);
+		await this.waitForShutdown(runtime, timeoutMs);
+		await this.runtimeStateService.remove(runtime.serverId);
+		return {
+			ok: true,
+			serverId: runtime.serverId,
+			host: runtime.host,
+			port: runtime.port,
+			message: shutdownResponse.message
+		};
+	}
+	/**
+	* Resolve a runtime record from explicit ID or a unique host/port pair.
+	* @param request - Stop request options
+	* @returns Matching runtime record
+	*/
+	async resolveRuntime(request) {
+		if (request.serverId) {
+			const runtime = await this.runtimeStateService.read(request.serverId);
+			if (!runtime) throw new Error(`No runtime record found for server ID '${request.serverId}'. Start the server with 'mcp-proxy mcp-serve --type http' first.`);
+			return runtime;
+		}
+		if (request.host === void 0 || request.port === void 0) throw new Error("Provide --id or both --host and --port to select a runtime.");
+		const matches = (await this.runtimeStateService.list()).filter((runtime) => runtime.host === request.host && runtime.port === request.port);
+		if (matches.length === 0) throw new Error(`No runtime record found for http://${request.host}:${request.port}. Start the server with 'mcp-proxy mcp-serve --type http' first.`);
+		if (matches.length > 1) throw new Error(`Multiple runtime records match http://${request.host}:${request.port}. Retry with --id to avoid stopping the wrong server.`);
+		return matches[0];
+	}
+	/**
+	* Read the runtime health payload.
+	* @param runtime - Runtime to query
+	* @param timeoutMs - Request timeout in milliseconds
+	* @returns Reachability status and optional payload
+	*/
+	async fetchHealth(runtime, timeoutMs) {
+		try {
+			const response = await this.fetchWithTimeout(buildRuntimeUrl(runtime, HEALTH_CHECK_PATH), { method: HTTP_METHOD_GET }, timeoutMs);
+			if (!response.ok) return { reachable: false };
+			const payload = await response.json();
+			if (!isHealthResponse(payload)) throw new Error("Received invalid health response payload.");
+			return {
+				reachable: true,
+				payload
+			};
+		} catch (error) {
+			this.logger.debug(`Health check failed for ${runtime.serverId}`, error);
+			return { reachable: false };
+		}
+	}
+	/**
+	* Send authenticated shutdown request to the admin endpoint.
+	* @param runtime - Runtime to stop
+	* @param shutdownToken - Bearer token for the admin endpoint
+	* @param timeoutMs - Request timeout in milliseconds
+	* @returns Parsed shutdown response payload
+	*/
+	async requestShutdown(runtime, shutdownToken, timeoutMs) {
+		const response = await this.fetchWithTimeout(buildRuntimeUrl(runtime, ADMIN_SHUTDOWN_PATH), {
+			method: HTTP_METHOD_POST,
+			headers: { [AUTHORIZATION_HEADER_NAME]: `${BEARER_TOKEN_PREFIX}${shutdownToken}` }
+		}, timeoutMs);
+		const payload = await response.json();
+		if (!isShutdownResponse(payload)) throw new Error("Received invalid shutdown response payload.");
+		if (!response.ok || !payload.ok) throw new Error(payload.message);
+		return payload;
+	}
+	/**
+	* Poll until the target runtime is no longer reachable.
+	* @param runtime - Runtime expected to stop
+	* @param timeoutMs - Maximum wait time in milliseconds
+	* @returns Promise that resolves when shutdown is observed
+	*/
+	async waitForShutdown(runtime, timeoutMs) {
+		const deadline = Date.now() + timeoutMs;
+		while (Date.now() < deadline) {
+			if (!(await this.fetchHealth(runtime, Math.max(HEALTH_REQUEST_TIMEOUT_FLOOR_MS, deadline - Date.now()))).reachable) return;
+			await sleep(SHUTDOWN_POLL_INTERVAL_MS);
+		}
+		throw new Error(`Timed out waiting for runtime '${runtime.serverId}' to stop at http://${runtime.host}:${runtime.port}.`);
+	}
+	/**
+	* Perform a fetch with an abort timeout.
+	* @param url - Target URL
+	* @param init - Fetch options
+	* @param timeoutMs - Timeout in milliseconds
+	* @returns Fetch response
+	*/
+	async fetchWithTimeout(url, init, timeoutMs) {
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => {
+			controller.abort();
+		}, timeoutMs);
+		try {
+			return await fetch(url, {
+				...init,
+				signal: controller.signal
+			});
+		} catch (error) {
+			throw new Error(`Request to '${url}' failed: ${toErrorMessage$1(error)}`);
+		} finally {
+			clearTimeout(timeoutId);
+		}
+	}
+};
+
+//#endregion
+//#region src/services/SkillService.ts
+/**
+* SkillService
+*
+* DESIGN PATTERNS:
+* - Service pattern for business logic encapsulation
+* - Single responsibility principle
+* - Lazy loading pattern for skill discovery
+*
+* CODING STANDARDS:
+* - Use async/await for asynchronous operations
+* - Throw descriptive errors for error cases
+* - Keep methods focused and well-named
+* - Document complex logic with comments
+*
+* AVOID:
+* - Mixing concerns (keep focused on single domain)
+* - Direct tool implementation (services should be tool-agnostic)
+*/
+/**
+* Error thrown when skill loading fails
+*/
+var SkillLoadError = class extends Error {
+	constructor(message, filePath, cause) {
+		super(message);
+		this.filePath = filePath;
+		this.cause = cause;
+		this.name = "SkillLoadError";
+	}
+};
+/**
+* Check if a path exists asynchronously
+* @param path - Path to check
+* @returns true if path exists, false otherwise
+* @throws Error for unexpected filesystem errors (permission denied, etc.)
+*/
+async function pathExists(path) {
+	try {
+		await access(path);
+		return true;
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+		throw new Error(`Failed to check path existence for "${path}": ${error instanceof Error ? error.message : "Unknown error"}`);
+	}
+}
+/**
+* Service for loading and managing skills from configured skill directories.
+*
+* Skills are markdown files with YAML frontmatter that can be invoked via
+* the skill__ prefix in describe_tools and use_tool.
+*
+* Skills are only enabled when explicitly configured via the `skills.paths` array
+* in the MCP config.
+*
+* @example
+* // Config with skills enabled:
+* // skills:
+* //   paths:
+* //     - ".claude/skills"
+* //     - "/absolute/path/to/skills"
+*
+* const skillService = new SkillService('/project/root', ['.claude/skills']);
+* const skills = await skillService.getSkills();
+*/
+var SkillService = class {
+	cwd;
+	skillPaths;
+	cachedSkills = null;
+	skillsByName = null;
+	/** Active file watchers for skill directories */
+	watchers = [];
+	/** Polling timers used when native file watching is unavailable */
+	pollingTimers = [];
+	/** Callback invoked when cache is invalidated due to file changes */
+	onCacheInvalidated;
+	logger;
+	/**
+	* Creates a new SkillService instance
+	* @param cwd - Current working directory for resolving relative paths
+	* @param skillPaths - Array of paths to skills directories
+	* @param options - Optional configuration
+	* @param options.onCacheInvalidated - Callback invoked when cache is invalidated due to file changes
+	*/
+	constructor(cwd, skillPaths, options, logger = console) {
+		this.cwd = cwd;
+		this.skillPaths = skillPaths;
+		this.onCacheInvalidated = options?.onCacheInvalidated;
+		this.logger = logger;
+	}
+	/**
+	* Get all available skills from configured directories.
+	* Results are cached after first load.
+	*
+	* Skills from earlier entries in the config take precedence over
+	* skills with the same name from later entries.
+	*
+	* @returns Array of loaded skills
+	* @throws SkillLoadError if a critical error occurs during loading
+	*/
+	async getSkills() {
+		if (this.cachedSkills !== null) return this.cachedSkills;
+		const skills = [];
+		const loadedSkillNames = /* @__PURE__ */ new Set();
+		const allDirSkills = await Promise.all(this.skillPaths.map(async (skillPath) => {
+			const skillsDir = isAbsolute(skillPath) ? skillPath : join(this.cwd, skillPath);
+			return this.loadSkillsFromDirectory(skillsDir, "project");
+		}));
+		for (const dirSkills of allDirSkills) for (const skill of dirSkills) if (!loadedSkillNames.has(skill.name)) {
+			skills.push(skill);
+			loadedSkillNames.add(skill.name);
+		}
+		this.cachedSkills = skills;
+		this.skillsByName = new Map(skills.map((skill) => [skill.name, skill]));
+		return skills;
+	}
+	/**
+	* Get a specific skill by name with O(1) lookup from cache.
+	* @param name - The skill name (without skill__ prefix)
+	* @returns The skill if found, undefined otherwise
+	*/
+	async getSkill(name) {
+		if (this.skillsByName === null) await this.getSkills();
+		return this.skillsByName?.get(name);
+	}
+	/**
+	* Clears the cached skills to force a fresh reload on the next getSkills() or getSkill() call.
+	* Use this when skill files have been modified on disk.
+	*/
+	clearCache() {
+		this.cachedSkills = null;
+		this.skillsByName = null;
+	}
+	/**
+	* Starts watching skill directories for changes to SKILL.md files.
+	* When changes are detected, the cache is automatically invalidated.
+	*
+	* Uses Node.js fs.watch with recursive option for efficient directory monitoring.
+	* Only invalidates cache when SKILL.md files are modified.
+	*
+	* @example
+	* const skillService = new SkillService(cwd, skillPaths, {
+	*   onCacheInvalidated: () => console.log('Skills cache invalidated')
+	* });
+	* await skillService.startWatching();
+	*/
+	async startWatching() {
+		this.stopWatching();
+		const existenceChecks = await Promise.all(this.skillPaths.map(async (skillPath) => {
+			const skillsDir = isAbsolute(skillPath) ? skillPath : join(this.cwd, skillPath);
+			return {
+				skillsDir,
+				exists: await pathExists(skillsDir)
+			};
+		}));
+		for (const { skillsDir, exists } of existenceChecks) {
+			if (!exists) continue;
+			const abortController = new AbortController();
+			this.watchers.push(abortController);
+			this.watchDirectory(skillsDir, abortController.signal).catch((error) => {
+				if (error?.name !== "AbortError") {
+					if (this.isWatchResourceLimitError(error)) {
+						this.startPollingDirectory(skillsDir, abortController.signal);
+						return;
+					}
+					this.logger.warn(`[skill-watcher] Error watching ${skillsDir}: ${error instanceof Error ? error.message : "Unknown error"}`);
+				}
+			});
+		}
+	}
+	/**
+	* Stops all active file watchers.
+	* Should be called when the service is being disposed.
+	*/
+	stopWatching() {
+		for (const controller of this.watchers) controller.abort();
+		this.watchers = [];
+		for (const timer of this.pollingTimers) clearInterval(timer);
+		this.pollingTimers = [];
+	}
+	/**
+	* Watches a directory for changes to SKILL.md files.
+	* @param dirPath - Directory path to watch
+	* @param signal - AbortSignal to stop watching
+	*/
+	async watchDirectory(dirPath, signal) {
+		const watcher = watch(dirPath, {
+			recursive: true,
+			signal
+		});
+		for await (const event of watcher) if (event.filename?.endsWith("SKILL.md")) this.invalidateCache();
+	}
+	invalidateCache() {
+		this.clearCache();
+		this.onCacheInvalidated?.();
+	}
+	isWatchResourceLimitError(error) {
+		return error instanceof Error && "code" in error && (error.code === "EMFILE" || error.code === "ENOSPC");
+	}
+	startPollingDirectory(dirPath, signal) {
+		this.createSkillSnapshot(dirPath).then((initialSnapshot) => {
+			let previousSnapshot = initialSnapshot;
+			const timer = setInterval(() => {
+				if (signal.aborted) {
+					clearInterval(timer);
+					return;
+				}
+				this.createSkillSnapshot(dirPath).then((nextSnapshot) => {
+					if (!this.snapshotsEqual(previousSnapshot, nextSnapshot)) {
+						previousSnapshot = nextSnapshot;
+						this.invalidateCache();
+					}
+				}).catch((error) => {
+					this.logger.warn(`[skill-watcher] Polling failed for ${dirPath}: ${error instanceof Error ? error.message : "Unknown error"}`);
+				});
+			}, 100);
+			this.pollingTimers.push(timer);
+			signal.addEventListener("abort", () => {
+				clearInterval(timer);
+				this.pollingTimers = this.pollingTimers.filter((activeTimer) => activeTimer !== timer);
+			}, { once: true });
+		});
+	}
+	async createSkillSnapshot(dirPath) {
+		const snapshot = /* @__PURE__ */ new Map();
+		await this.collectSkillSnapshots(dirPath, snapshot);
+		return snapshot;
+	}
+	async collectSkillSnapshots(dirPath, snapshot) {
+		let entries;
+		try {
+			entries = await readdir(dirPath);
+		} catch (error) {
+			if (error instanceof Error && "code" in error && error.code === "ENOENT") return;
+			throw error;
+		}
+		await Promise.all(entries.map(async (entry) => {
+			const entryPath = join(dirPath, entry);
+			const entryStat = await stat(entryPath);
+			if (entryStat.isDirectory()) {
+				await this.collectSkillSnapshots(entryPath, snapshot);
+				return;
+			}
+			if (entry === "SKILL.md") snapshot.set(entryPath, entryStat.mtimeMs);
+		}));
+	}
+	snapshotsEqual(left, right) {
+		if (left.size !== right.size) return false;
+		for (const [filePath, mtimeMs] of left) if (right.get(filePath) !== mtimeMs) return false;
+		return true;
+	}
+	/**
+	* Load skills from a directory.
+	* Supports both flat structure (SKILL.md) and nested structure (name/SKILL.md).
+	*
+	* @param dirPath - Path to the skills directory
+	* @param location - Whether this is a 'project' or 'user' skill directory
+	* @returns Array of successfully loaded skills (skips invalid skills)
+	* @throws SkillLoadError if there's a critical I/O error
+	*
+	* @example
+	* // Load skills from project directory
+	* const skills = await this.loadSkillsFromDirectory('/path/to/.claude/skills', 'project');
+	* // Returns: [{ name: 'pdf', description: '...', location: 'project', ... }]
+	*/
+	async loadSkillsFromDirectory(dirPath, location) {
+		const skills = [];
+		try {
+			if (!await pathExists(dirPath)) return skills;
+		} catch (error) {
+			throw new SkillLoadError(`Cannot access skills directory: ${error instanceof Error ? error.message : "Unknown error"}`, dirPath, error instanceof Error ? error : void 0);
+		}
+		let entries;
+		try {
+			entries = await readdir(dirPath);
+		} catch (error) {
+			throw new SkillLoadError(`Failed to read skills directory: ${error instanceof Error ? error.message : "Unknown error"}`, dirPath, error instanceof Error ? error : void 0);
+		}
+		const entryStats = await Promise.all(entries.map(async (entry) => {
+			const entryPath = join(dirPath, entry);
+			try {
+				return {
+					entry,
+					entryPath,
+					stat: await stat(entryPath),
+					error: null
+				};
+			} catch (error) {
+				this.logger.warn(`Skipping entry ${entryPath}: ${error instanceof Error ? error.message : "Unknown error"}`);
+				return {
+					entry,
+					entryPath,
+					stat: null,
+					error
+				};
+			}
+		}));
+		const skillFilesToLoad = [];
+		for (const { entry, entryPath, stat: entryStat } of entryStats) {
+			if (!entryStat) continue;
+			if (entryStat.isDirectory()) {
+				const skillFilePath = join(entryPath, "SKILL.md");
+				skillFilesToLoad.push({
+					filePath: skillFilePath,
+					isRootLevel: false
+				});
+			} else if (entry === "SKILL.md") skillFilesToLoad.push({
+				filePath: entryPath,
+				isRootLevel: true
+			});
+		}
+		const loadResults = await Promise.all(skillFilesToLoad.map(async ({ filePath, isRootLevel }) => {
+			try {
+				if (!isRootLevel && !await pathExists(filePath)) return null;
+				return await this.loadSkillFile(filePath, location);
+			} catch (error) {
+				this.logger.warn(`Skipping skill at ${filePath}: ${error instanceof Error ? error.message : "Unknown error"}`);
+				return null;
+			}
+		}));
+		for (const skill of loadResults) if (skill) skills.push(skill);
+		return skills;
+	}
+	/**
+	* Load a single skill file and parse its frontmatter.
+	* Supports multi-line YAML values using literal (|) and folded (>) block scalars.
+	*
+	* @param filePath - Path to the SKILL.md file
+	* @param location - Whether this is a 'project' or 'user' skill
+	* @returns The loaded skill, or null if the file is invalid (missing required frontmatter)
+	* @throws SkillLoadError if there's an I/O error reading the file
+	*
+	* @example
+	* // Load a skill from a file
+	* const skill = await this.loadSkillFile('/path/to/pdf/SKILL.md', 'project');
+	* // Returns: { name: 'pdf', description: 'PDF skill', location: 'project', content: '...', basePath: '/path/to/pdf' }
+	* // Returns null if frontmatter is missing name or description
+	*/
+	async loadSkillFile(filePath, location) {
+		let fileContent;
+		try {
+			fileContent = await readFile(filePath, "utf-8");
+		} catch (error) {
+			throw new SkillLoadError(`Failed to read skill file: ${error instanceof Error ? error.message : "Unknown error"}`, filePath, error instanceof Error ? error : void 0);
+		}
+		const { frontMatter, content } = parseFrontMatter(fileContent);
+		if (!frontMatter || !frontMatter.name || !frontMatter.description) return null;
+		return {
+			name: frontMatter.name,
+			description: frontMatter.description,
+			location,
+			content,
+			basePath: dirname(filePath)
+		};
+	}
+};
+
+//#endregion
+//#region src/services/PrefetchService/constants.ts
+/**
+* PrefetchService Constants
+*
+* Constants for package manager commands and process configuration.
+*/
+/** Transport type for stdio-based MCP servers */
+const TRANSPORT_STDIO = "stdio";
+/** npx command name */
+const COMMAND_NPX = "npx";
+/** npm command name */
+const COMMAND_NPM = "npm";
+/** pnpx command name (pnpm's npx equivalent) */
+const COMMAND_PNPX = "pnpx";
+/** pnpm command name */
+const COMMAND_PNPM = "pnpm";
+/** uvx command name */
+const COMMAND_UVX = "uvx";
+/** uv command name */
+const COMMAND_UV = "uv";
+/** Path suffix for npx command */
+const COMMAND_NPX_SUFFIX = "/npx";
+/** Path suffix for pnpx command */
+const COMMAND_PNPX_SUFFIX = "/pnpx";
+/** Path suffix for uvx command */
+const COMMAND_UVX_SUFFIX = "/uvx";
+/** Path suffix for uv command */
+const COMMAND_UV_SUFFIX = "/uv";
+/** Run subcommand for uv */
+const ARG_RUN = "run";
+/** Tool subcommand for uv */
+const ARG_TOOL = "tool";
+/** Install subcommand for uv tool and npm/pnpm */
+const ARG_INSTALL = "install";
+/** Add subcommand for pnpm */
+const ARG_ADD = "add";
+/** Global flag for npm/pnpm install */
+const ARG_GLOBAL = "-g";
+/** Flag prefix for command arguments */
+const FLAG_PREFIX = "-";
+/** npx --package flag (long form) */
+const FLAG_PACKAGE_LONG = "--package";
+/** npx -p flag (short form) */
+const FLAG_PACKAGE_SHORT = "-p";
+/** Equals delimiter used in flag=value patterns */
+const EQUALS_DELIMITER = "=";
+/**
+* Regex pattern for valid package names (npm, pnpm, uvx, uv)
+* Allows: @scope/package-name@version, package-name, package_name
+* Prevents shell metacharacters that could enable command injection
+* @example
+* // Valid: '@scope/package@1.0.0', 'my-package', 'my_package', '@org/pkg'
+* // Invalid: 'pkg; rm -rf /', 'pkg$(cmd)', 'pkg`whoami`', 'pkg|cat /etc/passwd'
+*/
+const VALID_PACKAGE_NAME_PATTERN = /^(@[a-zA-Z0-9_-]+\/)?[a-zA-Z0-9._-]+(@[a-zA-Z0-9._-]+)?$/;
+/** Windows platform identifier */
+const PLATFORM_WIN32 = "win32";
+/** Success exit code */
+const EXIT_CODE_SUCCESS = 0;
+/** Stdio option to ignore stream */
+const STDIO_IGNORE = "ignore";
+/** Stdio option to pipe stream */
+const STDIO_PIPE = "pipe";
+
+//#endregion
+//#region src/services/PrefetchService/PrefetchService.ts
+/**
+* PrefetchService
+*
+* DESIGN PATTERNS:
+* - Service pattern for business logic encapsulation
+* - Single responsibility principle
+*
+* CODING STANDARDS:
+* - Use async/await for asynchronous operations
+* - Throw descriptive errors for error cases
+* - Keep methods focused and well-named
+* - Document complex logic with comments
+*
+* AVOID:
+* - Mixing concerns (keep focused on single domain)
+* - Direct tool implementation (services should be tool-agnostic)
+*/
+/**
+* Type guard to check if a config object is an McpStdioConfig
+* @param config - Config object to check
+* @returns True if config has required McpStdioConfig properties
+*/
+function isMcpStdioConfig(config) {
+	return typeof config === "object" && config !== null && "command" in config;
+}
+/**
+* PrefetchService handles pre-downloading packages used by MCP servers.
+* Supports npx (Node.js), uvx (Python/uv), and uv run commands.
+*
+* @example
+* ```typescript
+* const service = new PrefetchService({
+*   mcpConfig: await configFetcher.fetchConfiguration(),
+*   parallel: true,
+* });
+* const packages = service.extractPackages();
+* const summary = await service.prefetch();
+* ```
+*/
+var PrefetchService = class {
+	config;
+	/**
+	* Creates a new PrefetchService instance
+	* @param config - Service configuration options
+	*/
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* Extract all prefetchable packages from the MCP configuration
+	* @returns Array of package info objects
+	*/
+	extractPackages() {
+		const packages = [];
+		const { mcpConfig, filter } = this.config;
+		for (const [serverName, serverConfig] of Object.entries(mcpConfig.mcpServers)) {
+			if (serverConfig.disabled) continue;
+			if (serverConfig.transport !== TRANSPORT_STDIO) continue;
+			if (!isMcpStdioConfig(serverConfig.config)) continue;
+			const packageInfo = this.extractPackageInfo(serverName, serverConfig.config);
+			if (packageInfo) {
+				if (filter && packageInfo.packageManager !== filter) continue;
+				packages.push(packageInfo);
+			}
+		}
+		return packages;
+	}
+	/**
+	* Prefetch all packages from the configuration
+	* @returns Summary of prefetch results
+	* @throws Error if prefetch operation fails unexpectedly
+	*/
+	async prefetch() {
+		try {
+			const packages = this.extractPackages();
+			const results = [];
+			if (packages.length === 0) return {
+				totalPackages: 0,
+				successful: 0,
+				failed: 0,
+				results: []
+			};
+			if (this.config.parallel) {
+				const promises = packages.map(async (pkg) => this.prefetchPackage(pkg));
+				results.push(...await Promise.all(promises));
+			} else for (const pkg of packages) {
+				const result = await this.prefetchPackage(pkg);
+				results.push(result);
+			}
+			const successful = results.filter((r) => r.success).length;
+			const failed = results.filter((r) => !r.success).length;
+			return {
+				totalPackages: packages.length,
+				successful,
+				failed,
+				results
+			};
+		} catch (error) {
+			throw new Error(`Failed to prefetch packages: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	/**
+	* Prefetch a single package
+	* @param pkg - Package info to prefetch
+	* @returns Result of the prefetch operation
+	*/
+	async prefetchPackage(pkg) {
+		try {
+			const [command, ...args] = pkg.fullCommand;
+			const result = await this.runCommand(command, args);
+			return {
+				package: pkg,
+				success: result.success,
+				output: result.output
+			};
+		} catch (error) {
+			return {
+				package: pkg,
+				success: false,
+				output: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	/**
+	* Validate package name to prevent command injection
+	* @param packageName - Package name to validate
+	* @returns True if package name is safe, false otherwise
+	* @remarks Rejects package names containing shell metacharacters
+	* @example
+	* isValidPackageName('@scope/package') // true
+	* isValidPackageName('my-package@1.0.0') // true
+	* isValidPackageName('pkg; rm -rf /') // false (shell injection)
+	* isValidPackageName('pkg$(whoami)') // false (command substitution)
+	*/
+	isValidPackageName(packageName) {
+		return VALID_PACKAGE_NAME_PATTERN.test(packageName);
+	}
+	/**
+	* Extract package info from a server's stdio config
+	* @param serverName - Name of the MCP server
+	* @param config - Stdio configuration for the server
+	* @returns Package info if extractable, null otherwise
+	*/
+	extractPackageInfo(serverName, config) {
+		const command = config.command.toLowerCase();
+		const args = config.args || [];
+		if (command === COMMAND_NPX || command.endsWith(COMMAND_NPX_SUFFIX)) {
+			const packageName = this.extractNpxPackage(args);
+			if (packageName && this.isValidPackageName(packageName)) return {
+				serverName,
+				packageManager: COMMAND_NPX,
+				packageName,
+				fullCommand: [
+					COMMAND_NPM,
+					ARG_INSTALL,
+					ARG_GLOBAL,
+					packageName
+				]
+			};
+		}
+		if (command === COMMAND_PNPX || command.endsWith(COMMAND_PNPX_SUFFIX)) {
+			const packageName = this.extractNpxPackage(args);
+			if (packageName && this.isValidPackageName(packageName)) return {
+				serverName,
+				packageManager: COMMAND_PNPX,
+				packageName,
+				fullCommand: [
+					COMMAND_PNPM,
+					ARG_ADD,
+					ARG_GLOBAL,
+					packageName
+				]
+			};
+		}
+		if (command === COMMAND_UVX || command.endsWith(COMMAND_UVX_SUFFIX)) {
+			const packageName = this.extractUvxPackage(args);
+			if (packageName && this.isValidPackageName(packageName)) return {
+				serverName,
+				packageManager: COMMAND_UVX,
+				packageName,
+				fullCommand: [COMMAND_UVX, packageName]
+			};
+		}
+		if ((command === COMMAND_UV || command.endsWith(COMMAND_UV_SUFFIX)) && args.includes(ARG_RUN)) {
+			const packageName = this.extractUvRunPackage(args);
+			if (packageName && this.isValidPackageName(packageName)) return {
+				serverName,
+				packageManager: COMMAND_UV,
+				packageName,
+				fullCommand: [
+					COMMAND_UV,
+					ARG_TOOL,
+					ARG_INSTALL,
+					packageName
+				]
+			};
+		}
+		return null;
+	}
+	/**
+	* Extract package name from npx command args
+	* @param args - Command arguments
+	* @returns Package name or null
+	* @remarks Handles --package=value, --package value, -p value patterns.
+	*          Falls back to first non-flag argument if no --package/-p flag found.
+	*          Returns null if flag has no value or is followed by another flag.
+	*          When multiple --package flags exist, returns the first valid one.
+	* @example
+	* extractNpxPackage(['--package=@scope/pkg']) // returns '@scope/pkg'
+	* extractNpxPackage(['--package', 'pkg-name']) // returns 'pkg-name'
+	* extractNpxPackage(['-p', 'pkg']) // returns 'pkg'
+	* extractNpxPackage(['-y', 'pkg-name', '--flag']) // returns 'pkg-name' (fallback)
+	* extractNpxPackage(['--package=']) // returns null (empty value)
+	*/
+	extractNpxPackage(args) {
+		for (let i = 0; i < args.length; i++) {
+			const arg = args[i];
+			if (arg.startsWith(FLAG_PACKAGE_LONG + EQUALS_DELIMITER)) return arg.slice(FLAG_PACKAGE_LONG.length + EQUALS_DELIMITER.length) || null;
+			if (arg === FLAG_PACKAGE_LONG && i + 1 < args.length) {
+				const nextArg = args[i + 1];
+				if (!nextArg.startsWith(FLAG_PREFIX)) return nextArg;
+			}
+			if (arg === FLAG_PACKAGE_SHORT && i + 1 < args.length) {
+				const nextArg = args[i + 1];
+				if (!nextArg.startsWith(FLAG_PREFIX)) return nextArg;
+			}
+		}
+		for (const arg of args) {
+			if (arg.startsWith(FLAG_PREFIX)) continue;
+			return arg;
+		}
+		return null;
+	}
+	/**
+	* Extract package name from uvx command args
+	* @param args - Command arguments
+	* @returns Package name or null
+	* @remarks Assumes the first non-flag argument is the package name.
+	*          Handles both single (-) and double (--) dash flags.
+	* @example
+	* extractUvxPackage(['mcp-server-fetch']) // returns 'mcp-server-fetch'
+	* extractUvxPackage(['--quiet', 'pkg-name']) // returns 'pkg-name'
+	*/
+	extractUvxPackage(args) {
+		for (const arg of args) {
+			if (arg.startsWith(FLAG_PREFIX)) continue;
+			return arg;
+		}
+		return null;
+	}
+	/**
+	* Extract package name from uv run command args
+	* @param args - Command arguments
+	* @returns Package name or null
+	* @remarks Looks for the first non-flag argument after the 'run' subcommand.
+	*          Returns null if 'run' is not found in args.
+	* @example
+	* extractUvRunPackage(['run', 'mcp-server']) // returns 'mcp-server'
+	* extractUvRunPackage(['run', '--verbose', 'pkg']) // returns 'pkg'
+	* extractUvRunPackage(['install', 'pkg']) // returns null (no 'run')
+	*/
+	extractUvRunPackage(args) {
+		const runIndex = args.indexOf(ARG_RUN);
+		if (runIndex === -1) return null;
+		for (let i = runIndex + 1; i < args.length; i++) {
+			const arg = args[i];
+			if (arg.startsWith(FLAG_PREFIX)) continue;
+			return arg;
+		}
+		return null;
+	}
+	/**
+	* Run a shell command and capture output
+	* @param command - Command to run
+	* @param args - Command arguments
+	* @returns Promise with success status and output
+	*/
+	runCommand(command, args) {
+		return new Promise((resolve$1) => {
+			const proc = spawn(command, args, {
+				stdio: [
+					STDIO_IGNORE,
+					STDIO_PIPE,
+					STDIO_PIPE
+				],
+				shell: process.platform === PLATFORM_WIN32
+			});
+			let stdout = "";
+			let stderr = "";
+			proc.stdout?.on("data", (data) => {
+				stdout += data.toString();
+			});
+			proc.stderr?.on("data", (data) => {
+				stderr += data.toString();
+			});
+			proc.on("close", (code) => {
+				resolve$1({
+					success: code === EXIT_CODE_SUCCESS,
+					output: stdout || stderr
+				});
+			});
+			proc.on("error", (error) => {
+				resolve$1({
+					success: false,
+					output: error.message
+				});
+			});
+		});
+	}
+};
+
+//#endregion
+//#region src/transports/http.ts
+/**
+* HTTP Transport Handler
+*
+* DESIGN PATTERNS:
+* - Transport handler pattern implementing TransportHandler interface
+* - Session management for stateful connections
+* - Streamable HTTP protocol (2025-03-26) with resumability support
+* - Factory pattern for creating MCP server instances per session
+*
+* CODING STANDARDS:
+* - Use async/await for all asynchronous operations
+* - Implement proper session lifecycle management
+* - Handle errors gracefully with appropriate HTTP status codes
+* - Provide health check endpoint for monitoring
+* - Clean up resources on shutdown
+*
+* AVOID:
+* - Sharing MCP server instances across sessions (use factory pattern)
+* - Forgetting to clean up sessions on disconnect
+* - Missing error handling for request processing
+* - Hardcoded configuration (use TransportConfig)
+*/
+/**
+* HTTP session manager
+*/
+var HttpFullSessionManager = class {
+	sessions = /* @__PURE__ */ new Map();
+	closingSessions = /* @__PURE__ */ new Set();
+	getSession(sessionId) {
+		return this.sessions.get(sessionId);
+	}
+	setSession(sessionId, transport, server) {
+		this.sessions.set(sessionId, {
+			transport,
+			server
+		});
+	}
+	removeSession(sessionId) {
+		this.sessions.delete(sessionId);
+	}
+	isClosing(sessionId) {
+		return this.closingSessions.has(sessionId);
+	}
+	async closeSession(sessionId) {
+		const session = this.sessions.get(sessionId);
+		if (session) {
+			this.closingSessions.add(sessionId);
+			try {
+				await session.server.close();
+			} catch (error) {
+				throw new Error(`Failed to close MCP server for session '${sessionId}': ${toErrorMessage(error)}`);
+			} finally {
+				this.sessions.delete(sessionId);
+				this.closingSessions.delete(sessionId);
+			}
+		}
+	}
+	hasSession(sessionId) {
+		return this.sessions.has(sessionId);
+	}
+	async clear() {
+		try {
+			await Promise.all(Array.from(this.sessions.keys()).map(async (sessionId) => this.closeSession(sessionId)));
+		} catch (error) {
+			throw new Error(`Failed to clear sessions: ${toErrorMessage(error)}`);
+		}
+	}
+};
+function toErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+const ADMIN_RATE_LIMIT_WINDOW_MS = 6e4;
+const ADMIN_RATE_LIMIT_MAX_REQUESTS = 5;
+/**
+* Simple in-memory rate limiter for the admin shutdown endpoint.
+* Tracks request timestamps per IP within a sliding window.
+*/
+var AdminRateLimiter = class {
+	requests = /* @__PURE__ */ new Map();
+	isAllowed(ip) {
+		const now = Date.now();
+		const windowStart = now - ADMIN_RATE_LIMIT_WINDOW_MS;
+		const timestamps = (this.requests.get(ip) ?? []).filter((t) => t > windowStart);
+		if (timestamps.length >= ADMIN_RATE_LIMIT_MAX_REQUESTS) {
+			this.requests.set(ip, timestamps);
+			return false;
+		}
+		timestamps.push(now);
+		this.requests.set(ip, timestamps);
+		return true;
+	}
+};
+/**
+* HTTP transport handler using Streamable HTTP (protocol version 2025-03-26)
+* Provides stateful session management with resumability support
+*/
+var HttpTransportHandler = class {
+	serverFactory;
+	app;
+	server = null;
+	sessionManager;
+	config;
+	adminOptions;
+	adminRateLimiter = new AdminRateLimiter();
+	logger;
+	constructor(serverFactory, config, adminOptions, logger = console) {
+		this.serverFactory = serverFactory;
+		this.app = express();
+		this.sessionManager = new HttpFullSessionManager();
+		this.config = {
+			mode: config.mode,
+			port: config.port ?? 3e3,
+			host: config.host ?? "localhost"
+		};
+		this.adminOptions = adminOptions;
+		this.logger = logger;
+		this.setupMiddleware();
+		this.setupRoutes();
+	}
+	setupMiddleware() {
+		this.app.use(express.json());
+	}
+	setupRoutes() {
+		this.app.post("/mcp", async (req, res) => {
+			try {
+				await this.handlePostRequest(req, res);
+			} catch (error) {
+				this.logger.error(`Failed to handle MCP POST request: ${toErrorMessage(error)}`);
+				res.status(500).json({
+					jsonrpc: "2.0",
+					error: {
+						code: -32603,
+						message: "Failed to handle MCP POST request."
+					},
+					id: null
+				});
+			}
+		});
+		this.app.get("/mcp", async (req, res) => {
+			try {
+				await this.handleGetRequest(req, res);
+			} catch (error) {
+				this.logger.error(`Failed to handle MCP GET request: ${toErrorMessage(error)}`);
+				res.status(500).send("Failed to handle MCP GET request.");
+			}
+		});
+		this.app.delete("/mcp", async (req, res) => {
+			try {
+				await this.handleDeleteRequest(req, res);
+			} catch (error) {
+				this.logger.error(`Failed to handle MCP DELETE request: ${toErrorMessage(error)}`);
+				res.status(500).send("Failed to handle MCP DELETE request.");
+			}
+		});
+		this.app.get("/health", (_req, res) => {
+			const payload = {
+				status: "ok",
+				transport: "http",
+				serverId: this.adminOptions?.serverId
+			};
+			res.json(payload);
+		});
+		this.app.post("/admin/shutdown", async (req, res) => {
+			try {
+				const clientIp = req.ip ?? req.socket.remoteAddress ?? "unknown";
+				if (!this.adminRateLimiter.isAllowed(clientIp)) {
+					const payload = {
+						ok: false,
+						message: "Too many shutdown requests. Try again later.",
+						serverId: this.adminOptions?.serverId
+					};
+					res.status(429).json(payload);
+					return;
+				}
+				await this.handleAdminShutdownRequest(req, res);
+			} catch (error) {
+				this.logger.error(`Failed to process shutdown request: ${toErrorMessage(error)}`);
+				const payload = {
+					ok: false,
+					message: "Failed to process shutdown request.",
+					serverId: this.adminOptions?.serverId
+				};
+				res.status(500).json(payload);
+			}
+		});
+	}
+	isAuthorizedShutdownRequest(req) {
+		const expectedToken = this.adminOptions?.shutdownToken;
+		if (!expectedToken) return false;
+		const authHeader = req.headers.authorization;
+		if (typeof authHeader === "string" && authHeader.startsWith("Bearer ")) return authHeader.slice(7) === expectedToken;
+		const tokenHeader = req.headers["x-mcp-proxy-shutdown-token"];
+		return typeof tokenHeader === "string" && tokenHeader === expectedToken;
+	}
+	async handleAdminShutdownRequest(req, res) {
+		try {
+			if (!this.adminOptions?.onShutdownRequested) {
+				const payload$1 = {
+					ok: false,
+					message: "Shutdown endpoint is not enabled for this server instance.",
+					serverId: this.adminOptions?.serverId
+				};
+				res.status(404).json(payload$1);
+				return;
+			}
+			if (!this.isAuthorizedShutdownRequest(req)) {
+				const payload$1 = {
+					ok: false,
+					message: "Unauthorized shutdown request: invalid or missing shutdown token.",
+					serverId: this.adminOptions?.serverId
+				};
+				res.status(401).json(payload$1);
+				return;
+			}
+			const payload = {
+				ok: true,
+				message: "Shutdown request accepted. Stopping server gracefully.",
+				serverId: this.adminOptions?.serverId
+			};
+			res.json(payload);
+			await this.adminOptions.onShutdownRequested();
+		} catch (error) {
+			throw new Error(`Failed to handle admin shutdown request: ${toErrorMessage(error)}`);
+		}
+	}
+	async handlePostRequest(req, res) {
+		const sessionId = req.headers["mcp-session-id"];
+		let transport;
+		if (sessionId && this.sessionManager.hasSession(sessionId)) transport = this.sessionManager.getSession(sessionId).transport;
+		else if (!sessionId && isInitializeRequest(req.body)) {
+			const mcpServer = await this.serverFactory();
+			transport = new StreamableHTTPServerTransport({
+				sessionIdGenerator: () => randomUUID(),
+				enableJsonResponse: true,
+				onsessioninitialized: (initializedSessionId) => {
+					this.sessionManager.setSession(initializedSessionId, transport, mcpServer);
+				}
+			});
+			transport.onclose = async () => {
+				if (transport.sessionId) try {
+					if (!this.sessionManager.isClosing(transport.sessionId)) this.sessionManager.removeSession(transport.sessionId);
+				} catch (error) {
+					this.logger.warn(`Failed to clean up session '${transport.sessionId}': ${toErrorMessage(error)}`);
+				}
+			};
+			try {
+				await mcpServer.connect(transport);
+			} catch (error) {
+				throw new Error(`Failed to connect MCP server transport for initialization request: ${toErrorMessage(error)}`);
+			}
+		} else {
+			res.status(400).json({
+				jsonrpc: "2.0",
+				error: {
+					code: -32e3,
+					message: sessionId === void 0 ? "Bad Request: missing session ID and request body is not an initialize request." : `Bad Request: unknown session ID '${sessionId}'.`
+				},
+				id: null
+			});
+			return;
+		}
+		try {
+			await transport.handleRequest(req, res, req.body);
+		} catch (error) {
+			throw new Error(`Failed handling MCP transport request: ${toErrorMessage(error)}`);
+		}
+	}
+	async handleGetRequest(req, res) {
+		const sessionId = req.headers["mcp-session-id"];
+		if (!sessionId || !this.sessionManager.hasSession(sessionId)) {
+			res.status(400).send("Invalid or missing session ID");
+			return;
+		}
+		const session = this.sessionManager.getSession(sessionId);
+		try {
+			await session.transport.handleRequest(req, res);
+		} catch (error) {
+			throw new Error(`Failed handling MCP GET request for session '${sessionId}': ${toErrorMessage(error)}`);
+		}
+	}
+	async handleDeleteRequest(req, res) {
+		const sessionId = req.headers["mcp-session-id"];
+		if (!sessionId || !this.sessionManager.hasSession(sessionId)) {
+			res.status(400).send("Invalid or missing session ID");
+			return;
+		}
+		const session = this.sessionManager.getSession(sessionId);
+		try {
+			await session.transport.handleRequest(req, res);
+		} catch (error) {
+			throw new Error(`Failed handling MCP DELETE request for session '${sessionId}': ${toErrorMessage(error)}`);
+		}
+		this.sessionManager.removeSession(sessionId);
+	}
+	async start() {
+		try {
+			const server = this.app.listen(this.config.port, this.config.host);
+			this.server = server;
+			const listeningPromise = (async () => {
+				await once(server, "listening");
+			})();
+			const errorPromise = (async () => {
+				const [error] = await once(server, "error");
+				throw error instanceof Error ? error : new Error(String(error));
+			})();
+			await Promise.race([listeningPromise, errorPromise]);
+			this.logger.info(`@agimon-ai/mcp-proxy MCP server started on http://${this.config.host}:${this.config.port}/mcp`);
+			this.logger.info(`Health check: http://${this.config.host}:${this.config.port}/health`);
+		} catch (error) {
+			this.server = null;
+			throw new Error(`Failed to start HTTP transport: ${toErrorMessage(error)}`);
+		}
+	}
+	async stop() {
+		if (!this.server) return;
+		try {
+			await this.sessionManager.clear();
+		} catch (error) {
+			throw new Error(`Failed to clear sessions during HTTP transport stop: ${toErrorMessage(error)}`);
+		}
+		const closeServer = promisify(this.server.close.bind(this.server));
+		try {
+			await closeServer();
+			this.server = null;
+		} catch (error) {
+			throw new Error(`Failed to stop HTTP transport: ${toErrorMessage(error)}`);
+		}
+	}
+	getPort() {
+		return this.config.port;
+	}
+	getHost() {
+		return this.config.host;
+	}
+};
+
+//#endregion
+//#region src/transports/sse.ts
+/**
+* Session manager for SSE transports
+*/
+var SseSessionManager = class {
+	sessions = /* @__PURE__ */ new Map();
+	closingSessions = /* @__PURE__ */ new Set();
+	getSession(sessionId) {
+		return this.sessions.get(sessionId)?.transport;
+	}
+	setSession(sessionId, transport, server) {
+		this.sessions.set(sessionId, {
+			transport,
+			server
+		});
+	}
+	removeSession(sessionId) {
+		this.sessions.delete(sessionId);
+	}
+	isClosing(sessionId) {
+		return this.closingSessions.has(sessionId);
+	}
+	async closeSession(sessionId) {
+		const session = this.sessions.get(sessionId);
+		if (session) {
+			this.closingSessions.add(sessionId);
+			try {
+				await session.server.close();
+			} finally {
+				this.sessions.delete(sessionId);
+				this.closingSessions.delete(sessionId);
+			}
+		}
+	}
+	async clear() {
+		await Promise.all(Array.from(this.sessions.keys()).map(async (sessionId) => this.closeSession(sessionId)));
+	}
+	hasSession(sessionId) {
+		return this.sessions.has(sessionId);
+	}
+};
+/**
+* SSE (Server-Sent Events) transport handler
+* Legacy transport for backwards compatibility (protocol version 2024-11-05)
+* Uses separate endpoints: /sse for SSE stream (GET) and /messages for client messages (POST)
+*/
+var SseTransportHandler = class {
+	serverFactory;
+	app;
+	server = null;
+	sessionManager;
+	config;
+	logger;
+	constructor(serverFactory, config, logger = console) {
+		this.serverFactory = typeof serverFactory === "function" ? serverFactory : () => serverFactory;
+		this.app = express();
+		this.sessionManager = new SseSessionManager();
+		this.config = {
+			mode: config.mode,
+			port: config.port ?? 3e3,
+			host: config.host ?? "localhost"
+		};
+		this.logger = logger;
+		this.setupMiddleware();
+		this.setupRoutes();
+	}
+	setupMiddleware() {
+		this.app.use(express.json());
+	}
+	setupRoutes() {
+		this.app.get("/sse", async (req, res) => {
+			await this.handleSseConnection(req, res);
+		});
+		this.app.post("/messages", async (req, res) => {
+			await this.handlePostMessage(req, res);
+		});
+		this.app.get("/health", (_req, res) => {
+			res.json({
+				status: "ok",
+				transport: "sse"
+			});
+		});
+	}
+	async handleSseConnection(_req, res) {
+		try {
+			const mcpServer = this.serverFactory();
+			const transport = new SSEServerTransport("/messages", res);
+			this.sessionManager.setSession(transport.sessionId, transport, mcpServer);
+			res.on("close", () => {
+				const sessionId = transport.sessionId;
+				if (sessionId && !this.sessionManager.isClosing(sessionId)) this.sessionManager.removeSession(sessionId);
+			});
+			await mcpServer.connect(transport);
+			this.logger.info(`SSE session established: ${transport.sessionId}`);
+		} catch (error) {
+			this.logger.error("Error handling SSE connection", error);
+			if (!res.headersSent) res.status(500).send("Internal Server Error");
+		}
+	}
+	async handlePostMessage(req, res) {
+		const sessionId = req.query.sessionId;
+		if (!sessionId) {
+			res.status(400).send("Missing sessionId query parameter");
+			return;
+		}
+		const transport = this.sessionManager.getSession(sessionId);
+		if (!transport) {
+			res.status(404).send("No transport found for sessionId");
+			return;
+		}
+		try {
+			await transport.handlePostMessage(req, res, req.body);
+		} catch (error) {
+			this.logger.error("Error handling post message", error);
+			if (!res.headersSent) res.status(500).send("Internal Server Error");
+		}
+	}
+	async start() {
+		return new Promise((resolve$1, reject) => {
+			try {
+				this.server = this.app.listen(this.config.port, this.config.host, () => {
+					this.logger.info(`@agimon-ai/mcp-proxy MCP server started with SSE transport on http://${this.config.host}:${this.config.port}`);
+					this.logger.info(`SSE endpoint: http://${this.config.host}:${this.config.port}/sse`);
+					this.logger.info(`Messages endpoint: http://${this.config.host}:${this.config.port}/messages`);
+					this.logger.info(`Health check: http://${this.config.host}:${this.config.port}/health`);
+					resolve$1();
+				});
+				this.server.on("error", (error) => {
+					reject(error);
+				});
+			} catch (error) {
+				reject(error);
+			}
+		});
+	}
+	async stop() {
+		return new Promise((resolve$1, reject) => {
+			if (this.server) {
+				const server = this.server;
+				(async () => {
+					try {
+						await this.sessionManager.clear();
+						server.close((err) => {
+							if (err) reject(err);
+							else {
+								this.server = null;
+								resolve$1();
+							}
+						});
+					} catch (error) {
+						reject(error);
+					}
+				})();
+			} else resolve$1();
+		});
+	}
+	getPort() {
+		return this.config.port;
+	}
+	getHost() {
+		return this.config.host;
+	}
+};
+
+//#endregion
+//#region src/transports/stdio.ts
+/**
+* Stdio transport handler for MCP server
+* Used for command-line and direct integrations
+*/
+var StdioTransportHandler = class {
+	server;
+	transport = null;
+	logger;
+	constructor(server, logger = console) {
+		this.server = server;
+		this.logger = logger;
+	}
+	async start() {
+		this.transport = new StdioServerTransport();
+		await this.server.connect(this.transport);
+		this.logger.info("@agimon-ai/mcp-proxy MCP server started on stdio");
+	}
+	async stop() {
+		if (this.transport) {
+			await this.transport.close();
+			this.transport = null;
+		}
+	}
+};
+
+//#endregion
+//#region src/transports/stdio-http.ts
+/**
+* STDIO-HTTP Proxy Transport
+*
+* DESIGN PATTERNS:
+* - Transport handler pattern implementing TransportHandler interface
+* - STDIO transport with MCP request forwarding to HTTP backend
+* - Graceful cleanup with error isolation
+*
+* CODING STANDARDS:
+* - Use StdioServerTransport for stdio communication
+* - Reuse a single StreamableHTTP client connection
+* - Wrap async operations with try-catch and descriptive errors
+*
+* AVOID:
+* - Starting HTTP server lifecycle in this transport entry point
+* - Recreating HTTP client per request
+* - Swallowing cleanup failures silently
+*/
+/**
+* Transport that serves MCP over stdio and forwards MCP requests to an HTTP endpoint.
+*/
+var StdioHttpTransportHandler = class {
+	endpoint;
+	stdioProxyServer = null;
+	stdioTransport = null;
+	httpClient = null;
+	logger;
+	constructor(config, logger = console) {
+		this.endpoint = config.endpoint;
+		this.logger = logger;
+	}
+	async start() {
+		try {
+			const httpClientTransport = new StreamableHTTPClientTransport(this.endpoint);
+			const client = new Client({
+				name: "@agimon-ai/mcp-proxy-stdio-http-proxy",
+				version: "0.1.0"
+			}, { capabilities: {} });
+			await client.connect(httpClientTransport);
+			this.httpClient = client;
+			this.stdioProxyServer = this.createProxyServer(client);
+			this.stdioTransport = new StdioServerTransport();
+			await this.stdioProxyServer.connect(this.stdioTransport);
+			this.logger.info(`@agimon-ai/mcp-proxy MCP stdio proxy connected to ${this.endpoint.toString()}`);
+		} catch (error) {
+			await this.stop();
+			throw new Error(`Failed to start stdio-http proxy transport: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	async stop() {
+		const stdioTransport = this.stdioTransport;
+		const stdioProxyServer = this.stdioProxyServer;
+		const httpClient = this.httpClient;
+		this.stdioTransport = null;
+		this.stdioProxyServer = null;
+		this.httpClient = null;
+		const cleanupErrors = [];
+		await Promise.all([
+			(async () => {
+				try {
+					if (stdioTransport) await stdioTransport.close();
+				} catch (error) {
+					cleanupErrors.push(`failed closing stdio transport: ${error instanceof Error ? error.message : String(error)}`);
+				}
+			})(),
+			(async () => {
+				try {
+					if (stdioProxyServer) await stdioProxyServer.close();
+				} catch (error) {
+					cleanupErrors.push(`failed closing stdio proxy server: ${error instanceof Error ? error.message : String(error)}`);
+				}
+			})(),
+			(async () => {
+				try {
+					if (httpClient) await httpClient.close();
+				} catch (error) {
+					cleanupErrors.push(`failed closing http client: ${error instanceof Error ? error.message : String(error)}`);
+				}
+			})()
+		]);
+		if (cleanupErrors.length > 0) throw new Error(`Failed to stop stdio-http proxy transport: ${cleanupErrors.join("; ")}`);
+	}
+	createProxyServer(client) {
+		const proxyServer = new Server({
+			name: "@agimon-ai/mcp-proxy-stdio-http-proxy",
+			version: "0.1.0"
+		}, { capabilities: {
+			tools: {},
+			resources: {},
+			prompts: {}
+		} });
+		proxyServer.setRequestHandler(ListToolsRequestSchema, async () => {
+			try {
+				return await client.listTools();
+			} catch (error) {
+				throw new Error(`Failed forwarding tools/list to HTTP backend: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		});
+		proxyServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+			try {
+				return await client.callTool({
+					name: request.params.name,
+					arguments: request.params.arguments
+				});
+			} catch (error) {
+				throw new Error(`Failed forwarding tools/call (${request.params.name}) to HTTP backend: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		});
+		proxyServer.setRequestHandler(ListResourcesRequestSchema, async () => {
+			try {
+				return await client.listResources();
+			} catch (error) {
+				throw new Error(`Failed forwarding resources/list to HTTP backend: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		});
+		proxyServer.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+			try {
+				return await client.readResource({ uri: request.params.uri });
+			} catch (error) {
+				throw new Error(`Failed forwarding resources/read (${request.params.uri}) to HTTP backend: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		});
+		proxyServer.setRequestHandler(ListPromptsRequestSchema, async () => {
+			try {
+				return await client.listPrompts();
+			} catch (error) {
+				throw new Error(`Failed forwarding prompts/list to HTTP backend: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		});
+		proxyServer.setRequestHandler(GetPromptRequestSchema, async (request) => {
+			try {
+				return await client.getPrompt({
+					name: request.params.name,
+					arguments: request.params.arguments
+				});
+			} catch (error) {
+				throw new Error(`Failed forwarding prompts/get (${request.params.name}) to HTTP backend: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		});
+		return proxyServer;
+	}
+};
+
+//#endregion
+//#region package.json
+var version = "0.3.19";
+
+//#endregion
+//#region src/container/index.ts
+/**
+* Proxy Container
+*
+* DESIGN PATTERNS:
+* - Composition root pattern for wiring proxy services
+* - Factory-based service construction
+* - Single place for runtime service initialization
+*
+* CODING STANDARDS:
+* - Keep service wiring centralized here
+* - Prefer lazy initialization for cache-heavy services
+* - Return a dispose function for owned resources
+*
+* AVOID:
+* - Instantiating proxy services directly in transport or CLI layers
+* - Spreading construction logic across commands
+*/
+function createProxyIoCContainer(logger = console) {
+	return {
+		createConfigFetcherService: (options) => new ConfigFetcherService(options, logger),
+		createClientManagerService: () => new McpClientManagerService(logger),
+		createRuntimeStateService: (runtimeDir) => new RuntimeStateService(runtimeDir, logger),
+		createStopServerService: (runtimeStateService) => new StopServerService(runtimeStateService, logger),
+		createSkillService: (cwd, skillPaths, options) => new SkillService(cwd, skillPaths, options, logger),
+		createDefinitionsCacheService: (clientManager, skillService, options) => new DefinitionsCacheService(clientManager, skillService, options, logger),
+		createPrefetchService: (config) => new PrefetchService(config),
+		createDescribeToolsTool: (clientManager, skillService, serverId, definitionsCacheService) => new DescribeToolsTool(clientManager, skillService, serverId, definitionsCacheService),
+		createUseToolTool: (clientManager, skillService, serverId, definitionsCacheService) => new UseToolTool(clientManager, skillService, serverId, definitionsCacheService),
+		createSearchListToolsTool: (clientManager, definitionsCacheService) => new SearchListToolsTool(clientManager, definitionsCacheService),
+		createStdioTransportHandler: async (createServer$1) => {
+			return new StdioTransportHandler(await createServer$1(), logger);
+		},
+		createSseTransportHandler: async (createServer$1, config) => {
+			return new SseTransportHandler(await createServer$1(), config, logger);
+		},
+		createHttpTransportHandler: (createServer$1, config, adminOptions) => new HttpTransportHandler(createServer$1, config, adminOptions, logger),
+		createStdioHttpTransportHandler: (endpoint) => new StdioHttpTransportHandler({ endpoint }, logger)
+	};
+}
+/**
+* Create the shared proxy container for a session or server startup.
+*
+* This is the composition root for the package: it owns service wiring,
+* cache warmup, and cleanup for all proxy-specific resources.
+*/
+async function createProxyContainer(options) {
+	const telemetry = await createProxyLogger({
+		workspaceRoot: process.cwd(),
+		serviceName: "@agimon-ai/mcp-proxy"
+	});
+	const logger = telemetry;
+	const container = createProxyIoCContainer(logger);
+	const clientManager = container.createClientManagerService();
+	try {
+		let configSkills;
+		let configId;
+		let configHash;
+		let effectiveDefinitionsCachePath;
+		let shouldStartFromCache = false;
+		if (options?.configFilePath) {
+			let config;
+			try {
+				config = await container.createConfigFetcherService({
+					configFilePath: options.configFilePath,
+					useCache: !options.noCache
+				}).fetchConfiguration(options.noCache || false);
+			} catch (error) {
+				throw new Error(`Failed to load MCP configuration from '${options.configFilePath}': ${error instanceof Error ? error.message : String(error)}`);
+			}
+			configSkills = config.skills;
+			configId = config.id;
+			configHash = DefinitionsCacheService.generateConfigHash(config);
+			effectiveDefinitionsCachePath = options.definitionsCachePath || DefinitionsCacheService.getDefaultCachePath(options.configFilePath);
+			clientManager.registerServerConfigs(config.mcpServers);
+			if (options.clearDefinitionsCache && effectiveDefinitionsCachePath) {
+				await DefinitionsCacheService.clearFile(effectiveDefinitionsCachePath);
+				logger.info(`[definitions-cache] Cleared ${effectiveDefinitionsCachePath}`);
+			}
+			if (effectiveDefinitionsCachePath) try {
+				const cacheData = await DefinitionsCacheService.readFromFile(effectiveDefinitionsCachePath);
+				if (DefinitionsCacheService.isCacheValid(cacheData, {
+					configHash,
+					oneMcpVersion: version
+				})) shouldStartFromCache = true;
+			} catch (error) {
+				logger.warn(`[definitions-cache] Failed to inspect ${effectiveDefinitionsCachePath}; falling back to live discovery`, error);
+			}
+			if (!shouldStartFromCache) {
+				const failedConnections = [];
+				const connectionPromises = Object.entries(config.mcpServers).map(async ([serverName, serverConfig]) => {
+					try {
+						await clientManager.connectToServer(serverName, serverConfig);
+						logger.info(`Connected to MCP server: ${serverName}`);
+					} catch (error) {
+						const err = error instanceof Error ? error : new Error(String(error));
+						failedConnections.push({
+							serverName,
+							error: err
+						});
+						logger.warn(`Failed to connect to ${serverName}`, error);
+					}
+				});
+				await Promise.all(connectionPromises);
+				if (failedConnections.length > 0 && failedConnections.length < Object.keys(config.mcpServers).length) logger.warn(`Warning: Some MCP server connections failed: ${failedConnections.map((f) => f.serverName).join(", ")}`);
+				if (failedConnections.length > 0 && failedConnections.length === Object.keys(config.mcpServers).length) throw new Error(`All MCP server connections failed: ${failedConnections.map((f) => `${f.serverName}: ${f.error.message}`).join(", ")}`);
+			} else logger.info(`[definitions-cache] Using cached definitions from ${effectiveDefinitionsCachePath}`);
+		}
+		const serverId = options?.serverId || configId || generateServerId();
+		logger.info(`[mcp-proxy] Server ID: ${serverId}`);
+		const skillPaths = (options?.skills || configSkills)?.paths ?? [];
+		const toolsRef = { describeTools: null };
+		const skillService = skillPaths.length > 0 ? container.createSkillService(process.cwd(), skillPaths, { onCacheInvalidated: () => {
+			toolsRef.describeTools?.clearAutoDetectedSkillsCache();
+		} }) : void 0;
+		let definitionsCacheService;
+		if (effectiveDefinitionsCachePath) try {
+			const cacheData = await DefinitionsCacheService.readFromFile(effectiveDefinitionsCachePath);
+			if (DefinitionsCacheService.isCacheValid(cacheData, {
+				configHash,
+				oneMcpVersion: version
+			})) definitionsCacheService = container.createDefinitionsCacheService(clientManager, skillService, { cacheData });
+			else definitionsCacheService = container.createDefinitionsCacheService(clientManager, skillService);
+		} catch (error) {
+			logger.warn(`[definitions-cache] Failed to load ${effectiveDefinitionsCachePath}, falling back to live discovery: ${error instanceof Error ? error.message : "Unknown error"}`);
+			definitionsCacheService = container.createDefinitionsCacheService(clientManager, skillService);
+		}
+		else definitionsCacheService = container.createDefinitionsCacheService(clientManager, skillService);
+		const proxyMode = options?.proxyMode || "meta";
+		const describeTools = container.createDescribeToolsTool(clientManager, skillService, serverId, definitionsCacheService);
+		const useTool = container.createUseToolTool(clientManager, skillService, serverId, definitionsCacheService);
+		const searchListTools = container.createSearchListToolsTool(clientManager, definitionsCacheService);
+		toolsRef.describeTools = describeTools;
+		if (skillService) skillService.startWatching().catch((error) => {
+			logger.warn(`[skill-watcher] File watcher failed (non-critical): ${error instanceof Error ? error.message : "Unknown error"}`);
+		});
+		if (!shouldStartFromCache && effectiveDefinitionsCachePath && options?.configFilePath) definitionsCacheService.collectForCache({
+			configPath: options.configFilePath,
+			configHash,
+			oneMcpVersion: version,
+			serverId
+		}).then((definitionsCache) => DefinitionsCacheService.writeToFile(effectiveDefinitionsCachePath, definitionsCache)).then(() => {
+			logger.info(`[definitions-cache] Wrote ${effectiveDefinitionsCachePath}`);
+		}).catch((error) => {
+			logger.warn(`[definitions-cache] Failed to persist ${effectiveDefinitionsCachePath}: ${error instanceof Error ? error.message : "Unknown error"}`);
+		});
+		const dispose = async () => {
+			try {
+				await clientManager.disconnectAll();
+			} finally {
+				if (skillService) skillService.stopWatching();
+				await telemetry.shutdown();
+			}
+		};
+		return {
+			clientManager,
+			definitionsCacheService,
+			skillService,
+			describeTools,
+			useTool,
+			searchListTools,
+			serverId,
+			proxyMode,
+			dispose
+		};
+	} catch (error) {
+		await telemetry.shutdown();
+		throw error;
+	}
+}
+/**
+* Create a sessionless stdio transport handler from the shared server factory.
+*/
+async function createStdioTransportHandler(createServer$1) {
+	const server = await createServer$1();
+	return createProxyIoCContainer().createStdioTransportHandler(() => Promise.resolve(server));
+}
+/**
+* Create an SSE transport handler from the shared server factory.
+*/
+async function createSseTransportHandler(createServer$1, config) {
+	const server = await createServer$1();
+	return createProxyIoCContainer().createSseTransportHandler(() => Promise.resolve(server), config);
+}
+/**
+* Create an HTTP transport handler from shared services.
+*/
+function createHttpTransportHandler(createServer$1, config, adminOptions) {
+	return createProxyIoCContainer().createHttpTransportHandler(createServer$1, config, adminOptions);
+}
+/**
+* Create a stdio-http transport handler from an endpoint URL.
+*/
+function createStdioHttpTransportHandler(endpoint) {
+	return createProxyIoCContainer().createStdioHttpTransportHandler(endpoint);
+}
+/**
+* Backward-compatible alias for the shared-service composition root.
+*/
+async function initializeSharedServices(options) {
+	return createProxyContainer(options);
+}
+
+//#endregion
+//#region src/server/index.ts
+/**
+* MCP Server Setup
+*
+* DESIGN PATTERNS:
+* - Factory pattern for server creation
+* - Tool registration pattern
+* - Dependency injection for services
+* - Shared services pattern for multi-session HTTP transport
+*
+* CODING STANDARDS:
+* - Register all tools, resources, and prompts here
+* - Keep server setup modular and extensible
+* - Import tools from ../tools/ and register them in the handlers
+*/
+function summarizeServerTools(serverDefinition) {
+	const toolNames = serverDefinition.tools.map((tool) => tool.name);
+	const capabilities = getUniqueSortedCapabilities(serverDefinition.tools);
+	const capabilitySummary = capabilities.length > 0 ? `; capabilities: ${capabilities.join(", ")}` : "";
+	if (toolNames.length === 0) return `${serverDefinition.serverName} (no tools cached${capabilitySummary})`;
+	return `${serverDefinition.serverName} (${toolNames.join(", ")})${capabilitySummary}`;
+}
+function buildFlatToolDescription(serverDefinition, tool) {
+	const parts = [`Proxied from server "${serverDefinition.serverName}" as tool "${tool.name}".`];
+	if (serverDefinition.serverInstruction) parts.push(`Server summary: ${serverDefinition.serverInstruction}`);
+	if (tool.description && !serverDefinition.omitToolDescription) parts.push(tool.description);
+	const capabilities = getToolCapabilities(tool);
+	if (capabilities.length > 0) parts.push(`Capabilities: ${capabilities.join(", ")}`);
+	return parts.join("\n\n");
+}
+function buildFlatToolDefinitions(serverDefinitions) {
+	const toolToServers = /* @__PURE__ */ new Map();
+	for (const serverDefinition of serverDefinitions) for (const tool of serverDefinition.tools) {
+		if (!toolToServers.has(tool.name)) toolToServers.set(tool.name, []);
+		toolToServers.get(tool.name)?.push(serverDefinition.serverName);
+	}
+	const definitions = [];
+	for (const serverDefinition of serverDefinitions) for (const tool of serverDefinition.tools) {
+		const hasClash = (toolToServers.get(tool.name) || []).length > 1;
+		definitions.push({
+			name: hasClash ? `${serverDefinition.serverName}__${tool.name}` : tool.name,
+			description: buildFlatToolDescription(serverDefinition, tool),
+			inputSchema: tool.inputSchema,
+			_meta: tool._meta
+		});
+	}
+	return definitions;
+}
+async function hasAnySkills(definitionsCacheService, skillService) {
+	const [fileSkills, serverDefinitions] = await Promise.all([skillService ? skillService.getSkills() : definitionsCacheService.getCachedFileSkills(), definitionsCacheService.getServerDefinitions()]);
+	return fileSkills.length > 0 || serverDefinitions.some((server) => server.promptSkills.length > 0);
+}
+function buildSkillsDescribeDefinition(serverDefinitions, serverId) {
+	const proxySummary = serverDefinitions.length > 0 ? serverDefinitions.map(summarizeServerTools).join("; ") : "No proxied servers available.";
+	return {
+		name: DescribeToolsTool.TOOL_NAME,
+		description: `Get detailed skill instructions for file-based skills and prompt-based skills proxied by mcp-proxy.\n\nProxy summary: ${proxySummary}\n\nUse this when you need the full instructions for a skill. For MCP tools, call the flat tool names directly. Only use skills discovered from describe_tools with id="${serverId}".`,
+		inputSchema: {
+			type: "object",
+			properties: { toolNames: {
+				type: "array",
+				items: {
+					type: "string",
+					minLength: 1
+				},
+				description: "List of skill names to get detailed information about",
+				minItems: 1
+			} },
+			required: ["toolNames"],
+			additionalProperties: false
+		}
+	};
+}
+function buildSearchDescribeDefinition(serverDefinitions, serverId) {
+	const summary = serverDefinitions.length > 0 ? serverDefinitions.map(summarizeServerTools).join("; ") : "No proxied servers available.";
+	return {
+		name: DescribeToolsTool.TOOL_NAME,
+		description: `Get detailed schemas and skill instructions for proxied MCP capabilities.\n\nProxy summary: ${summary}\n\nUse list_tools first to search capability summaries and discover tool names. Then use describe_tools to fetch full schemas or skill instructions. Only use capabilities discovered from mcp-proxy id="${serverId}".`,
+		inputSchema: {
+			type: "object",
+			properties: { toolNames: {
+				type: "array",
+				items: {
+					type: "string",
+					minLength: 1
+				},
+				description: "List of tool or skill names to get detailed information about",
+				minItems: 1
+			} },
+			required: ["toolNames"],
+			additionalProperties: false
+		}
+	};
+}
+function buildProxyInstructions(serverDefinitions, mode, includeSkillsTool) {
+	const summary = serverDefinitions.length > 0 ? serverDefinitions.map(summarizeServerTools).join("; ") : "No proxied servers available.";
+	if (mode === "flat") return [
+		"mcp-proxy proxies downstream MCP servers and exposes their tools and resources directly.",
+		`Proxied servers and tools: ${summary}`,
+		includeSkillsTool ? "Skills are still exposed through describe_tools when file-based skills or prompt-backed skills are configured." : "No skills are currently exposed through describe_tools."
+	].join("\n\n");
+	if (mode === "search") return [
+		"mcp-proxy proxies downstream MCP servers in search mode.",
+		`Proxied servers and tools: ${summary}`,
+		"Use list_tools to search capability summaries and discover tool names, describe_tools to fetch schemas or skill instructions, and use_tool to execute tools."
+	].join("\n\n");
+	return [
+		"mcp-proxy proxies downstream MCP servers in meta mode.",
+		`Proxied servers and tools: ${summary}`,
+		"Use describe_tools to inspect capabilities and use_tool to execute them."
+	].join("\n\n");
+}
+/**
+* Initialize shared services and tools once for use across multiple sessions.
+* Use with createSessionServer() for HTTP transport where multiple agents
+* connect concurrently. This avoids duplicating downstream connections,
+* file watchers, caches, and tool instances per session.
+*/
+/**
+* Create a lightweight per-session MCP Server instance that delegates
+* to shared services and tools. Use with createProxyContainer()
+* for multi-session HTTP transport.
+*/
+async function createSessionServer(shared) {
+	const { clientManager, definitionsCacheService, skillService, describeTools, useTool: useToolWithCache, searchListTools, serverId, proxyMode } = shared;
+	const server = new Server({
+		name: "@agimon-ai/mcp-proxy",
+		version: "0.1.0"
+	}, {
+		capabilities: {
+			tools: {},
+			resources: {},
+			prompts: {}
+		},
+		instructions: buildProxyInstructions(await definitionsCacheService.getServerDefinitions(), proxyMode, await hasAnySkills(definitionsCacheService, skillService))
+	});
+	server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: proxyMode === "flat" ? await (async () => {
+		const currentServerDefinitions = await definitionsCacheService.getServerDefinitions();
+		const shouldIncludeSkillsTool = await hasAnySkills(definitionsCacheService, skillService);
+		return [...buildFlatToolDefinitions(currentServerDefinitions), ...shouldIncludeSkillsTool ? [buildSkillsDescribeDefinition(currentServerDefinitions, serverId)] : []];
+	})() : proxyMode === "search" ? await (async () => {
+		return [
+			buildSearchDescribeDefinition(await definitionsCacheService.getServerDefinitions(), serverId),
+			await searchListTools.getDefinition(),
+			useToolWithCache.getDefinition()
+		];
+	})() : [await describeTools.getDefinition(), useToolWithCache.getDefinition()] }));
+	server.setRequestHandler(CallToolRequestSchema, async (request) => {
+		const { name, arguments: args } = request.params;
+		if (name === DescribeToolsTool.TOOL_NAME) try {
+			return await describeTools.execute(args);
+		} catch (error) {
+			throw new Error(`Failed to execute ${name}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (name === UseToolTool.TOOL_NAME) try {
+			return await useToolWithCache.execute(args);
+		} catch (error) {
+			throw new Error(`Failed to execute ${name}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (name === SearchListToolsTool.TOOL_NAME && proxyMode === "search") try {
+			return await searchListTools.execute(args);
+		} catch (error) {
+			throw new Error(`Failed to execute ${name}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (proxyMode === "flat") return await useToolWithCache.execute({
+			toolName: name,
+			toolArgs: args || {}
+		});
+		throw new Error(`Unknown tool: ${name}`);
+	});
+	server.setRequestHandler(ListResourcesRequestSchema, async () => {
+		const currentServerDefinitions = await definitionsCacheService.getServerDefinitions();
+		const resourceToServers = /* @__PURE__ */ new Map();
+		for (const serverDefinition of currentServerDefinitions) for (const resource of serverDefinition.resources) {
+			if (!resourceToServers.has(resource.uri)) resourceToServers.set(resource.uri, []);
+			resourceToServers.get(resource.uri)?.push(serverDefinition.serverName);
+		}
+		const resources = [];
+		for (const serverDefinition of currentServerDefinitions) for (const resource of serverDefinition.resources) {
+			const hasClash = (resourceToServers.get(resource.uri) || []).length > 1;
+			resources.push({
+				...resource,
+				uri: hasClash ? `${serverDefinition.serverName}__${resource.uri}` : resource.uri
+			});
+		}
+		return { resources };
+	});
+	server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+		const { uri } = request.params;
+		const { serverName, actualToolName: actualUri } = parseToolName(uri);
+		if (serverName) return await (await clientManager.ensureConnected(serverName)).readResource(actualUri);
+		const matchingServers = await definitionsCacheService.getServersForResource(actualUri);
+		if (matchingServers.length === 0) throw new Error(`Resource not found: ${uri}`);
+		if (matchingServers.length > 1) throw new Error(`Resource "${actualUri}" exists on multiple servers: ${matchingServers.join(", ")}. Use the prefixed format (e.g., "${matchingServers[0]}__${actualUri}") to specify which server to use.`);
+		return await (await clientManager.ensureConnected(matchingServers[0])).readResource(actualUri);
+	});
+	server.setRequestHandler(ListPromptsRequestSchema, async () => {
+		const currentServerDefinitions = await definitionsCacheService.getServerDefinitions();
+		const promptToServers = /* @__PURE__ */ new Map();
+		const serverPromptsMap = /* @__PURE__ */ new Map();
+		for (const serverDefinition of currentServerDefinitions) {
+			serverPromptsMap.set(serverDefinition.serverName, serverDefinition.prompts);
+			for (const prompt of serverDefinition.prompts) {
+				if (!promptToServers.has(prompt.name)) promptToServers.set(prompt.name, []);
+				promptToServers.get(prompt.name).push(serverDefinition.serverName);
+			}
+		}
+		const aggregatedPrompts = [];
+		for (const serverDefinition of currentServerDefinitions) {
+			const prompts = serverPromptsMap.get(serverDefinition.serverName) || [];
+			for (const prompt of prompts) {
+				const hasClash = (promptToServers.get(prompt.name) || []).length > 1;
+				aggregatedPrompts.push({
+					name: hasClash ? `${serverDefinition.serverName}__${prompt.name}` : prompt.name,
+					description: prompt.description,
+					arguments: prompt.arguments
+				});
+			}
+		}
+		return { prompts: aggregatedPrompts };
+	});
+	server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+		const { name, arguments: args } = request.params;
+		const currentServerDefinitions = await definitionsCacheService.getServerDefinitions();
+		const { serverName, actualToolName: actualPromptName } = parseToolName(name);
+		if (serverName) return await (await clientManager.ensureConnected(serverName)).getPrompt(actualPromptName, args);
+		const serversWithPrompt = [];
+		for (const serverDefinition of currentServerDefinitions) if (serverDefinition.prompts.some((prompt) => prompt.name === name)) serversWithPrompt.push(serverDefinition.serverName);
+		if (serversWithPrompt.length === 0) throw new Error(`Prompt not found: ${name}`);
+		if (serversWithPrompt.length > 1) throw new Error(`Prompt "${name}" exists on multiple servers: ${serversWithPrompt.join(", ")}. Use the prefixed format (e.g., "${serversWithPrompt[0]}__${name}") to specify which server to use.`);
+		const client = clientManager.getClient(serversWithPrompt[0]);
+		if (!client) return await (await clientManager.ensureConnected(serversWithPrompt[0])).getPrompt(name, args);
+		return await client.getPrompt(name, args);
+	});
+	return server;
+}
+/**
+* Create a single MCP server instance (backward-compatible wrapper).
+* For multi-session HTTP transport, use createProxyContainer() + createSessionServer() instead.
+*/
+async function createServer(options) {
+	return createSessionServer(await createProxyContainer(options));
+}
+
+//#endregion
+//#region src/types/index.ts
+/**
+* Transport mode constants
+*/
+const TRANSPORT_MODE = {
+	STDIO: "stdio",
+	HTTP: "http",
+	SSE: "sse"
+};
+
+//#endregion
+export { SearchListToolsTool as C, findConfigFile as D, generateServerId as E, UseToolTool as S, DefinitionsCacheService as T, StopServerService as _, createProxyContainer as a, createProxyLogger as b, createStdioHttpTransportHandler as c, version as d, StdioHttpTransportHandler as f, SkillService as g, HttpTransportHandler as h, createHttpTransportHandler as i, createStdioTransportHandler as l, SseTransportHandler as m, createServer as n, createProxyIoCContainer as o, StdioTransportHandler as p, createSessionServer as r, createSseTransportHandler as s, TRANSPORT_MODE as t, initializeSharedServices as u, RuntimeStateService as v, DescribeToolsTool as w, ConfigFetcherService as x, McpClientManagerService as y };