@agimon-ai/mcp-proxy 0.4.0

package/dist/cli.cjs

@@ -0,0 +1,1513 @@
+#!/usr/bin/env node
+const require_src = require('./src-6KF7hZTe.cjs');
+let node_crypto = require("node:crypto");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+let node_fs = require("node:fs");
+let liquidjs = require("liquidjs");
+let commander = require("commander");
+let __agimon_ai_foundation_process_registry = require("@agimon-ai/foundation-process-registry");
+let __agimon_ai_foundation_port_registry = require("@agimon-ai/foundation-port-registry");
+
+//#region src/utils/output.ts
+function writeLine(message = "") {
+	console.log(message);
+}
+function writeError(message, detail) {
+	if (detail) console.error(`${message} ${detail}`);
+	else console.error(message);
+}
+const log = {
+	info: (message) => writeLine(message),
+	error: (message, detail) => writeError(message, detail)
+};
+const print = {
+	info: (message) => writeLine(message),
+	warning: (message) => writeLine(`Warning: ${message}`),
+	error: (message) => writeError(message),
+	success: (message) => writeLine(message),
+	newline: () => writeLine(),
+	header: (message) => writeLine(message),
+	item: (message) => writeLine(`- ${message}`),
+	indent: (message) => writeLine(`  ${message}`)
+};
+
+//#endregion
+//#region src/templates/mcp-config.yaml.liquid?raw
+var mcp_config_yaml_default = "# MCP Server Configuration\n# This file configures the MCP servers that mcp-proxy will connect to\n#\n# Environment Variable Interpolation:\n# Use ${VAR_NAME} syntax to reference environment variables\n# Example: ${HOME}, ${API_KEY}, ${DATABASE_URL}\n#\n# Instructions:\n# - config.instruction: Server's default instruction (from server documentation)\n# - instruction: User override (optional, takes precedence over config.instruction)\n# - config.toolBlacklist: Array of tool names to hide/block from this server\n# - config.omitToolDescription: Boolean to show only tool names without descriptions (saves tokens)\n\n# Remote Configuration Sources (OPTIONAL)\n# Fetch and merge configurations from remote URLs\n# Remote configs are merged with local configs based on merge strategy\n#\n# SECURITY: SSRF Protection is ENABLED by default\n# - Only HTTPS URLs are allowed (set security.enforceHttps: false to allow HTTP)\n# - Private IPs and localhost are blocked (set security.allowPrivateIPs: true for internal networks)\n# - Blocked ranges: 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16\nremoteConfigs:\n  # Example 1: Basic remote config with default security\n  # - url: ${AGIFLOW_URL}/api/v1/mcp-configs\n  #   headers:\n  #     Authorization: Bearer ${AGIFLOW_API_KEY}\n  #   mergeStrategy: local-priority  # Options: local-priority (default), remote-priority, merge-deep\n  #\n  # Example 2: Remote config with custom security settings (for internal networks)\n  # - url: ${INTERNAL_URL}/mcp-configs\n  #   headers:\n  #     Authorization: Bearer ${INTERNAL_TOKEN}\n  #   security:\n  #     allowPrivateIPs: true   # Allow internal IPs (default: false)\n  #     enforceHttps: false     # Allow HTTP (default: true, HTTPS only)\n  #   mergeStrategy: local-priority\n  #\n  # Example 3: Remote config with additional validation (OPTIONAL)\n  # - url: ${AGIFLOW_URL}/api/v1/mcp-configs\n  #   headers:\n  #     Authorization: Bearer ${AGIFLOW_API_KEY}\n  #     X-API-Key: ${AGIFLOW_API_KEY}\n  #   security:\n  #     enforceHttps: true      # Require HTTPS (default: true)\n  #     allowPrivateIPs: false  # Block private IPs (default: false)\n  #   validation:  # OPTIONAL: Additional regex validation on top of security checks\n  #     url: ^https://.*\\.agiflow\\.io/.*  # OPTIONAL: Regex pattern to validate URL format\n  #     headers:  # OPTIONAL: Regex patterns to validate header values\n  #       Authorization: ^Bearer [A-Za-z0-9_-]+$\n  #       X-API-Key: ^[A-Za-z0-9_-]{32,}$\n  #   mergeStrategy: local-priority\n\nmcpServers:\n{%- if mcpServers %}{% for server in mcpServers %}\n  {{ server.name }}:\n    command: {{ server.command }}\n    args:{% for arg in server.args %}\n      - '{{ arg }}'{% endfor %}\n    # env:\n    #   LOG_LEVEL: info\n    #   # API_KEY: ${MY_API_KEY}\n    # config:\n    #   instruction: Use this server for...\n    #   # toolBlacklist:\n    #   #   - tool_to_block\n    #   # omitToolDescription: true\n{% endfor %}\n  # Example MCP server using SSE transport\n  # remote-server:\n  #   url: https://example.com/mcp\n  #   type: sse\n  #   headers:\n  #     Authorization: Bearer ${API_KEY}\n  #   config:\n  #     instruction: This server provides tools for...\n{% else %}\n  # Example MCP server using stdio transport\n  example-server:\n    command: node\n    args:\n      - /path/to/mcp-server/build/index.js\n    env:\n      # Environment variables for the MCP server\n      LOG_LEVEL: info\n      # You can use environment variable interpolation:\n      # DATABASE_URL: ${DATABASE_URL}\n      # API_KEY: ${MY_API_KEY}\n    config:\n      # Server's default instruction (from server documentation)\n      instruction: Use this server for...\n      # Optional: Block specific tools from being listed or executed\n      # toolBlacklist:\n      #   - dangerous_tool_name\n      #   - another_blocked_tool\n      # Optional: Omit tool descriptions to save tokens (default: false)\n      # omitToolDescription: true\n    # instruction: Optional user override - takes precedence over config.instruction\n\n  # Example MCP server using SSE transport with environment variables\n  # remote-server:\n  #   url: https://example.com/mcp\n  #   type: sse\n  #   headers:\n  #     # Use ${VAR_NAME} to interpolate environment variables\n  #     Authorization: Bearer ${API_KEY}\n  #   config:\n  #     instruction: This server provides tools for...\n  #     # Optional: Block specific tools from being listed or executed\n  #     # toolBlacklist:\n  #     #   - tool_to_block\n  #     # Optional: Omit tool descriptions to save tokens (default: false)\n  #     # omitToolDescription: true\n  #   # instruction: Optional user override\n{% endif %}\n";
+
+//#endregion
+//#region src/templates/mcp-config.json?raw
+var mcp_config_default = "{\n  \"_comment\": \"MCP Server Configuration - Use ${VAR_NAME} syntax for environment variable interpolation\",\n  \"_instructions\": \"config.instruction: Server's default instruction | instruction: User override (takes precedence)\",\n  \"mcpServers\": {\n    \"example-server\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-server/build/index.js\"],\n      \"env\": {\n        \"LOG_LEVEL\": \"info\",\n        \"_comment\": \"You can use environment variable interpolation:\",\n        \"_example_DATABASE_URL\": \"${DATABASE_URL}\",\n        \"_example_API_KEY\": \"${MY_API_KEY}\"\n      },\n      \"config\": {\n        \"instruction\": \"Use this server for...\"\n      },\n      \"_instruction_override\": \"Optional user override - takes precedence over config.instruction\"\n    }\n  }\n}\n";
+
+//#endregion
+//#region src/commands/init.ts
+/**
+* Init Command
+*
+* DESIGN PATTERNS:
+* - Command pattern with Commander for CLI argument parsing
+* - Async/await pattern for asynchronous operations
+* - Error handling pattern with try-catch and proper exit codes
+*
+* CODING STANDARDS:
+* - Use async action handlers for asynchronous operations
+* - Provide clear option descriptions and default values
+* - Handle errors gracefully with process.exit()
+* - Log progress and errors to console
+* - Use Commander's .option() and .argument() for inputs
+*
+* AVOID:
+* - Synchronous blocking operations in action handlers
+* - Missing error handling (always use try-catch)
+* - Hardcoded values (use options or environment variables)
+* - Not exiting with appropriate exit codes on errors
+*/
+/**
+* Initialize MCP configuration file
+*/
+const initCommand = new commander.Command("init").description("Initialize MCP configuration file").option("-o, --output <path>", "Output file path", "mcp-config.yaml").option("--json", "Generate JSON config instead of YAML", false).option("-f, --force", "Overwrite existing config file", false).option("--mcp-servers <json>", "JSON string of MCP servers to add to config (optional)").action(async (options) => {
+	try {
+		const outputPath = (0, node_path.resolve)(options.output);
+		const isYaml = !options.json && (outputPath.endsWith(".yaml") || outputPath.endsWith(".yml"));
+		let content;
+		if (isYaml) {
+			const liquid = new liquidjs.Liquid();
+			let mcpServersData = null;
+			if (options.mcpServers) try {
+				const serversObj = JSON.parse(options.mcpServers);
+				mcpServersData = Object.entries(serversObj).map(([name, config]) => ({
+					name,
+					command: config.command,
+					args: config.args
+				}));
+			} catch (parseError) {
+				log.error("Failed to parse --mcp-servers JSON:", parseError instanceof Error ? parseError.message : String(parseError));
+				process.exit(1);
+			}
+			content = await liquid.parseAndRender(mcp_config_yaml_default, { mcpServers: mcpServersData });
+		} else content = mcp_config_default;
+		try {
+			await (0, node_fs_promises.writeFile)(outputPath, content, {
+				encoding: "utf-8",
+				flag: options.force ? "w" : "wx"
+			});
+		} catch (error) {
+			if (error && typeof error === "object" && "code" in error && error.code === "EEXIST") {
+				log.error(`Config file already exists: ${outputPath}`);
+				log.info("Use --force to overwrite");
+				process.exit(1);
+			}
+			throw error;
+		}
+		log.info(`MCP configuration file created: ${outputPath}`);
+		log.info("Next steps:");
+		log.info("1. Edit the configuration file to add your MCP servers");
+		log.info(`2. Run: mcp-proxy mcp-serve --config ${outputPath}`);
+	} catch (error) {
+		log.error("Error executing init:", error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	}
+});
+
+//#endregion
+//#region src/commands/mcp-serve.ts
+/**
+* MCP Serve Command
+*
+* DESIGN PATTERNS:
+* - Command pattern with Commander for CLI argument parsing
+* - Transport abstraction pattern for flexible deployment (stdio, HTTP, SSE)
+* - Factory pattern for creating transport handlers
+* - Graceful shutdown pattern with signal handling
+*
+* CODING STANDARDS:
+* - Use async/await for asynchronous operations
+* - Implement proper error handling with try-catch blocks
+* - Handle process signals for graceful shutdown
+* - Provide clear CLI options and help messages
+*
+* AVOID:
+* - Hardcoded configuration values (use CLI options or environment variables)
+* - Missing error handling for transport startup
+* - Not cleaning up resources on shutdown
+*/
+const CONFIG_FILE_NAMES = [
+	"mcp-config.yaml",
+	"mcp-config.yml",
+	"mcp-config.json"
+];
+const MCP_ENDPOINT_PATH = "/mcp";
+const DEFAULT_PORT = 3e3;
+const DEFAULT_HOST = "localhost";
+const TRANSPORT_TYPE_STDIO = "stdio";
+const TRANSPORT_TYPE_HTTP = "http";
+const TRANSPORT_TYPE_SSE = "sse";
+const TRANSPORT_TYPE_STDIO_HTTP = "stdio-http";
+const RUNTIME_TRANSPORT = TRANSPORT_TYPE_HTTP;
+const STDIO_HTTP_PROXY_STOP_LABEL = "Failed stopping stdio-http proxy";
+const INTERNAL_HTTP_STOP_LABEL = "Failed stopping internal HTTP transport";
+const PORT_REGISTRY_SERVICE_HTTP = "mcp-proxy-http";
+const PORT_REGISTRY_SERVICE_STDIO_HTTP = "mcp-proxy-stdio-http";
+const PORT_REGISTRY_SERVICE_TYPE = "service";
+const PORT_REGISTRY_REPOSITORY_PATH = process.cwd();
+const PROCESS_REGISTRY_SERVICE_HTTP = "mcp-proxy-http";
+const PROCESS_REGISTRY_SERVICE_STDIO_HTTP = "mcp-proxy-stdio-http";
+const PROCESS_REGISTRY_SERVICE_TYPE = "service";
+const PROCESS_REGISTRY_REPOSITORY_PATH = process.cwd();
+function toErrorMessage$9(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function isValidTransportType(type) {
+	return type === TRANSPORT_TYPE_STDIO || type === TRANSPORT_TYPE_HTTP || type === TRANSPORT_TYPE_SSE || type === TRANSPORT_TYPE_STDIO_HTTP;
+}
+function isValidProxyMode(mode) {
+	return mode === "meta" || mode === "flat" || mode === "search";
+}
+function isAddressInUseError(error) {
+	if (error instanceof Error && error.message.includes("EADDRINUSE")) return true;
+	if (typeof error !== "object" || error === null) return false;
+	if ("code" in error && error.code === "EADDRINUSE") return true;
+	if ("message" in error && typeof error.message === "string" && error.message.includes("EADDRINUSE")) return true;
+	return false;
+}
+async function pathExists(filePath) {
+	try {
+		await (0, node_fs_promises.access)(filePath, node_fs.constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function findConfigFileAsync() {
+	try {
+		const projectPath = process.env.PROJECT_PATH;
+		if (projectPath) for (const fileName of CONFIG_FILE_NAMES) {
+			const configPath = (0, node_path.resolve)(projectPath, fileName);
+			if (await pathExists(configPath)) return configPath;
+		}
+		const cwd = process.cwd();
+		for (const fileName of CONFIG_FILE_NAMES) {
+			const configPath = (0, node_path.join)(cwd, fileName);
+			if (await pathExists(configPath)) return configPath;
+		}
+		return null;
+	} catch (error) {
+		throw new Error(`Failed to discover MCP config file: ${toErrorMessage$9(error)}`);
+	}
+}
+async function resolveServerId(options, resolvedConfigPath) {
+	const container = require_src.createProxyIoCContainer();
+	if (options.id) return options.id;
+	if (resolvedConfigPath) try {
+		const config = await container.createConfigFetcherService({
+			configFilePath: resolvedConfigPath,
+			useCache: options.cache !== false
+		}).fetchConfiguration(options.cache === false);
+		if (config.id) return config.id;
+	} catch (error) {
+		throw new Error(`Failed to resolve server ID from config '${resolvedConfigPath}': ${toErrorMessage$9(error)}`);
+	}
+	return require_src.generateServerId();
+}
+function validateTransportType(type) {
+	if (!isValidTransportType(type)) throw new Error(`Unknown transport type: '${type}'. Valid options: ${TRANSPORT_TYPE_STDIO}, ${TRANSPORT_TYPE_HTTP}, ${TRANSPORT_TYPE_SSE}, ${TRANSPORT_TYPE_STDIO_HTTP}`);
+	return type;
+}
+function validateProxyMode(mode) {
+	if (!isValidProxyMode(mode)) throw new Error(`Unknown proxy mode: '${mode}'. Valid options: meta, flat, search`);
+}
+function createTransportConfig(options, mode) {
+	return {
+		mode,
+		port: options.port || Number(process.env.MCP_PORT) || DEFAULT_PORT,
+		host: options.host || process.env.MCP_HOST || DEFAULT_HOST
+	};
+}
+function createServerOptions(options, resolvedConfigPath, serverId) {
+	return {
+		configFilePath: resolvedConfigPath,
+		noCache: options.cache === false,
+		serverId,
+		definitionsCachePath: options.definitionsCache,
+		clearDefinitionsCache: options.clearDefinitionsCache,
+		proxyMode: options.proxyMode
+	};
+}
+function formatStartError(type, host, port, error) {
+	const startErrorMessage = toErrorMessage$9(error);
+	if (type === TRANSPORT_TYPE_STDIO) return `Failed to start MCP server with transport '${type}': ${startErrorMessage}`;
+	return `Failed to start MCP server with transport '${type}' on ${host}:${port}: ${startErrorMessage}`;
+}
+function createRuntimeRecord(serverId, config, port, shutdownToken, configPath) {
+	return {
+		serverId,
+		host: config.host ?? DEFAULT_HOST,
+		port,
+		transport: RUNTIME_TRANSPORT,
+		shutdownToken,
+		startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		pid: process.pid,
+		configPath
+	};
+}
+function createPortRegistryService() {
+	return new __agimon_ai_foundation_port_registry.PortRegistryService(process.env.PORT_REGISTRY_PATH);
+}
+function createProcessRegistryService() {
+	return new __agimon_ai_foundation_process_registry.ProcessRegistryService(process.env.PROCESS_REGISTRY_PATH);
+}
+function getRegistryEnvironment() {
+	return process.env.NODE_ENV ?? "development";
+}
+async function createPortRegistryLease(serviceName, host, preferredPort, serverId, transport, configPath) {
+	const portRegistry = createPortRegistryService();
+	const result = await portRegistry.reservePort({
+		repositoryPath: PORT_REGISTRY_REPOSITORY_PATH,
+		serviceName,
+		serviceType: PORT_REGISTRY_SERVICE_TYPE,
+		environment: getRegistryEnvironment(),
+		pid: process.pid,
+		host,
+		preferredPort,
+		portRange: {
+			min: preferredPort,
+			max: preferredPort
+		},
+		force: true,
+		metadata: {
+			transport,
+			serverId,
+			...configPath ? { configPath } : {}
+		}
+	});
+	if (!result.success || !result.record) throw new Error(result.error || `Failed to reserve port ${preferredPort} in port registry`);
+	let released = false;
+	return { release: async () => {
+		if (released) return;
+		released = true;
+		const releaseResult = await portRegistry.releasePort({
+			repositoryPath: PORT_REGISTRY_REPOSITORY_PATH,
+			serviceName,
+			serviceType: PORT_REGISTRY_SERVICE_TYPE,
+			pid: process.pid,
+			environment: getRegistryEnvironment(),
+			force: true
+		});
+		if (!releaseResult.success && releaseResult.error && !releaseResult.error.includes("No matching registry entry")) throw new Error(releaseResult.error || `Failed to release port for ${serviceName}`);
+	} };
+}
+async function createProcessRegistryLease(serviceName, host, port, serverId, transport, configPath) {
+	const processRegistry = createProcessRegistryService();
+	const result = await processRegistry.registerProcess({
+		repositoryPath: PROCESS_REGISTRY_REPOSITORY_PATH,
+		serviceName,
+		serviceType: PROCESS_REGISTRY_SERVICE_TYPE,
+		environment: getRegistryEnvironment(),
+		pid: process.pid,
+		host,
+		port,
+		command: process.argv[1],
+		args: process.argv.slice(2),
+		metadata: {
+			transport,
+			serverId,
+			...configPath ? { configPath } : {}
+		}
+	});
+	if (!result.success || !result.record) throw new Error(result.error || `Failed to register process for ${serviceName}`);
+	let released = false;
+	return { release: async (options) => {
+		if (released) return;
+		released = true;
+		const releaseResult = await processRegistry.releaseProcess({
+			repositoryPath: PROCESS_REGISTRY_REPOSITORY_PATH,
+			serviceName,
+			serviceType: PROCESS_REGISTRY_SERVICE_TYPE,
+			pid: process.pid,
+			environment: getRegistryEnvironment(),
+			kill: options?.kill ?? false,
+			releasePort: options?.releasePort ?? false
+		});
+		if (!releaseResult.success && releaseResult.error && !releaseResult.error.includes("No matching process entry")) throw new Error(releaseResult.error || `Failed to release process for ${serviceName}`);
+	} };
+}
+async function releasePortLease(lease) {
+	if (!lease) return;
+	await lease.release();
+}
+function createHttpAdminOptions(serverId, shutdownToken, onShutdownRequested) {
+	return {
+		serverId,
+		shutdownToken,
+		onShutdownRequested
+	};
+}
+async function removeRuntimeRecord(runtimeStateService, serverId) {
+	try {
+		await runtimeStateService.remove(serverId);
+	} catch (error) {
+		throw new Error(`Failed to remove runtime state for '${serverId}': ${toErrorMessage$9(error)}`);
+	}
+}
+async function writeRuntimeRecord(runtimeStateService, record) {
+	try {
+		await runtimeStateService.write(record);
+	} catch (error) {
+		throw new Error(`Failed to persist runtime state for '${record.serverId}': ${toErrorMessage$9(error)}`);
+	}
+}
+async function stopOwnedHttpTransport(handler, runtimeStateService, serverId, processLease) {
+	try {
+		try {
+			await handler.stop();
+		} catch (error) {
+			throw new Error(`Failed to stop owned HTTP transport '${serverId}': ${toErrorMessage$9(error)}`);
+		}
+	} finally {
+		await processLease?.release({
+			kill: false,
+			releasePort: false
+		});
+		await removeRuntimeRecord(runtimeStateService, serverId);
+	}
+}
+async function cleanupFailedRuntimeStartup(handler, runtimeStateService, serverId, processLease) {
+	try {
+		try {
+			await handler.stop();
+		} catch (error) {
+			throw new Error(`Failed to stop HTTP transport during cleanup for '${serverId}': ${toErrorMessage$9(error)}`);
+		}
+	} finally {
+		await processLease?.release({
+			kill: false,
+			releasePort: false
+		});
+		await removeRuntimeRecord(runtimeStateService, serverId);
+	}
+}
+async function stopTransportWithContext(label, stopOperation) {
+	try {
+		await stopOperation();
+	} catch (error) {
+		throw new Error(`${label}: ${toErrorMessage$9(error)}`);
+	}
+}
+async function removeRuntimeRecordDuringStop(runtimeStateService, serverId) {
+	try {
+		await removeRuntimeRecord(runtimeStateService, serverId);
+	} catch (error) {
+		throw new Error(`Failed to remove runtime state during HTTP stop callback for '${serverId}': ${toErrorMessage$9(error)}`);
+	}
+}
+function createStdioHttpInternalTransport(sharedServices, config, adminOptions) {
+	try {
+		return new require_src.HttpTransportHandler(() => require_src.createSessionServer(sharedServices), config, adminOptions);
+	} catch (error) {
+		throw new Error(`Failed to create internal HTTP transport for stdio-http proxy: ${toErrorMessage$9(error)}`);
+	}
+}
+/**
+* Start MCP server with given transport handler
+* @param handler - The transport handler to start
+* @param onStopped - Optional cleanup callback run after signal-based shutdown
+*/
+async function startServer(handler, onStopped) {
+	try {
+		await handler.start();
+	} catch (error) {
+		throw new Error(`Failed to start transport handler: ${toErrorMessage$9(error)}`);
+	}
+	const shutdown = async (signal) => {
+		console.error(`\nReceived ${signal}, shutting down gracefully...`);
+		try {
+			await handler.stop();
+			if (onStopped) await onStopped();
+			process.exit(0);
+		} catch (error) {
+			console.error(`Failed to gracefully stop transport during ${signal}: ${toErrorMessage$9(error)}`);
+			process.exit(1);
+		}
+	};
+	process.on("SIGINT", async () => await shutdown("SIGINT"));
+	process.on("SIGTERM", async () => await shutdown("SIGTERM"));
+}
+async function createAndStartHttpRuntime(serverOptions, config, resolvedConfigPath) {
+	const sharedServices = await require_src.initializeSharedServices(serverOptions);
+	const runtimeStateService = new require_src.RuntimeStateService();
+	const shutdownToken = (0, node_crypto.randomUUID)();
+	const runtimeServerId = serverOptions.serverId ?? require_src.generateServerId();
+	const processLease = await createProcessRegistryLease(PROCESS_REGISTRY_SERVICE_HTTP, config.host ?? DEFAULT_HOST, config.port ?? DEFAULT_PORT, runtimeServerId, TRANSPORT_TYPE_HTTP, resolvedConfigPath);
+	const portLease = await createPortRegistryLease(PORT_REGISTRY_SERVICE_HTTP, config.host ?? DEFAULT_HOST, config.port ?? DEFAULT_PORT, runtimeServerId, TRANSPORT_TYPE_HTTP, resolvedConfigPath);
+	let releasePort = async () => {
+		await releasePortLease(portLease);
+		releasePort = async () => void 0;
+	};
+	const runtimeRecord = createRuntimeRecord(runtimeServerId, config, config.port ?? DEFAULT_PORT, shutdownToken, resolvedConfigPath);
+	let handler;
+	let isStopping = false;
+	const stopHandler = async () => {
+		if (isStopping) return;
+		isStopping = true;
+		try {
+			await stopOwnedHttpTransport(handler, runtimeStateService, runtimeRecord.serverId, processLease);
+			await releasePort();
+			await sharedServices.dispose();
+			process.exit(0);
+		} catch (error) {
+			throw new Error(`Failed to stop HTTP runtime '${runtimeRecord.serverId}' from admin shutdown: ${toErrorMessage$9(error)}`);
+		}
+	};
+	try {
+		handler = new require_src.HttpTransportHandler(() => require_src.createSessionServer(sharedServices), config, createHttpAdminOptions(runtimeRecord.serverId, shutdownToken, stopHandler));
+	} catch (error) {
+		await releasePort();
+		await processLease.release({
+			kill: false,
+			releasePort: false
+		});
+		await sharedServices.dispose();
+		throw new Error(`Failed to create HTTP runtime server: ${toErrorMessage$9(error)}`);
+	}
+	try {
+		await startServer(handler, async () => {
+			await releasePort();
+			await sharedServices.dispose();
+			await processLease.release({
+				kill: false,
+				releasePort: false
+			});
+			await removeRuntimeRecordDuringStop(runtimeStateService, runtimeRecord.serverId);
+		});
+		await writeRuntimeRecord(runtimeStateService, runtimeRecord);
+	} catch (error) {
+		await releasePort();
+		await processLease.release({
+			kill: false,
+			releasePort: false
+		});
+		await sharedServices.dispose();
+		await cleanupFailedRuntimeStartup(handler, runtimeStateService, runtimeRecord.serverId, processLease);
+		throw new Error(`Failed to start HTTP runtime '${runtimeRecord.serverId}': ${toErrorMessage$9(error)}`);
+	}
+	console.error(`Runtime state: http://${runtimeRecord.host}:${runtimeRecord.port} (${runtimeRecord.serverId})`);
+}
+async function stopInternalHttpTransport(stdioHttpHandler, httpHandler, ownsInternalHttpTransport) {
+	try {
+		const stopOperations = [stopTransportWithContext(STDIO_HTTP_PROXY_STOP_LABEL, async () => {
+			await stdioHttpHandler.stop();
+		})];
+		if (ownsInternalHttpTransport && httpHandler) stopOperations.push(stopTransportWithContext(INTERNAL_HTTP_STOP_LABEL, async () => {
+			await httpHandler.stop();
+		}));
+		await Promise.all(stopOperations);
+	} catch (error) {
+		throw new Error(`Failed to stop stdio-http transport: ${toErrorMessage$9(error)}`);
+	}
+}
+async function startStdioTransport(serverOptions) {
+	try {
+		await startServer(new require_src.StdioTransportHandler(await require_src.createServer(serverOptions)));
+	} catch (error) {
+		throw new Error(`Failed to start stdio transport: ${toErrorMessage$9(error)}`);
+	}
+}
+async function startSseTransport(serverOptions, config) {
+	try {
+		await startServer(new require_src.SseTransportHandler(await require_src.createServer(serverOptions), config));
+	} catch (error) {
+		throw new Error(`Failed to start SSE transport: ${toErrorMessage$9(error)}`);
+	}
+}
+async function startStdioHttpTransport(serverOptions, config, resolvedConfigPath) {
+	const shared = { services: null };
+	let processLease;
+	let internalPortLease = null;
+	try {
+		const stdioHttpHandler = new require_src.StdioHttpTransportHandler({ endpoint: new URL(`http://${config.host}:${config.port}${MCP_ENDPOINT_PATH}`) });
+		const runtimeStateService = new require_src.RuntimeStateService();
+		const serverId = serverOptions.serverId ?? require_src.generateServerId();
+		const shutdownToken = (0, node_crypto.randomUUID)();
+		processLease = await createProcessRegistryLease(PROCESS_REGISTRY_SERVICE_STDIO_HTTP, config.host ?? DEFAULT_HOST, config.port ?? DEFAULT_PORT, serverId, TRANSPORT_TYPE_STDIO_HTTP, resolvedConfigPath);
+		let httpHandler = null;
+		let ownsInternalHttpTransport = false;
+		let isStopping = false;
+		let releaseInternalPort = async () => {
+			await releasePortLease(internalPortLease);
+			internalPortLease = null;
+			releaseInternalPort = async () => void 0;
+		};
+		const stopOwnedRuntime = async () => {
+			if (isStopping) return;
+			isStopping = true;
+			try {
+				await Promise.all([stopInternalHttpTransport(stdioHttpHandler, httpHandler, ownsInternalHttpTransport), removeRuntimeRecord(runtimeStateService, serverId)]);
+				await releaseInternalPort();
+				if (shared.services) await shared.services.dispose();
+				ownsInternalHttpTransport = false;
+				process.exit(0);
+			} catch (error) {
+				console.error(`Unexpected error during admin shutdown: ${toErrorMessage$9(error)}`);
+				process.exit(1);
+			}
+		};
+		const adminOptions = createHttpAdminOptions(serverId, shutdownToken, stopOwnedRuntime);
+		await startServer({
+			async start() {
+				let initialProxyConnectError;
+				try {
+					await stdioHttpHandler.start();
+					return;
+				} catch (error) {
+					initialProxyConnectError = error;
+				}
+				if (!shared.services) shared.services = await require_src.initializeSharedServices(serverOptions);
+				try {
+					internalPortLease = await createPortRegistryLease(PORT_REGISTRY_SERVICE_STDIO_HTTP, config.host ?? DEFAULT_HOST, config.port ?? DEFAULT_PORT, serverId, TRANSPORT_TYPE_STDIO_HTTP, resolvedConfigPath);
+					httpHandler = createStdioHttpInternalTransport(shared.services, config, adminOptions);
+					await httpHandler.start();
+					ownsInternalHttpTransport = true;
+				} catch (error) {
+					if (!isAddressInUseError(error)) {
+						await releaseInternalPort();
+						throw new Error(`Failed to start internal HTTP transport for stdio-http proxy: ${toErrorMessage$9(error)}`);
+					}
+				}
+				try {
+					await stdioHttpHandler.start();
+				} catch (error) {
+					let rollbackStopErrorMessage = "";
+					if (ownsInternalHttpTransport && httpHandler) {
+						try {
+							await httpHandler.stop();
+						} catch (stopError) {
+							rollbackStopErrorMessage = toErrorMessage$9(stopError);
+						}
+						ownsInternalHttpTransport = false;
+					}
+					await releaseInternalPort();
+					const retryErrorMessage = toErrorMessage$9(error);
+					const initialErrorMessage = toErrorMessage$9(initialProxyConnectError);
+					const rollbackMessage = rollbackStopErrorMessage ? `; rollback stop failed: ${rollbackStopErrorMessage}` : "";
+					throw new Error(`Failed to start stdio-http proxy bridge: initial connect failed (${initialErrorMessage}); retry failed (${retryErrorMessage})${rollbackMessage}`);
+				}
+				if (ownsInternalHttpTransport) try {
+					await writeRuntimeRecord(runtimeStateService, createRuntimeRecord(serverId, config, config.port ?? DEFAULT_PORT, shutdownToken, resolvedConfigPath));
+				} catch (error) {
+					throw new Error(`Failed to persist runtime state for stdio-http server '${serverId}': ${toErrorMessage$9(error)}`);
+				}
+			},
+			async stop() {
+				try {
+					await Promise.all([stopInternalHttpTransport(stdioHttpHandler, httpHandler, ownsInternalHttpTransport), removeRuntimeRecord(runtimeStateService, serverId)]);
+					await releaseInternalPort();
+					await processLease?.release({
+						kill: false,
+						releasePort: false
+					});
+					ownsInternalHttpTransport = false;
+					if (shared.services) await shared.services.dispose();
+				} catch (error) {
+					ownsInternalHttpTransport = false;
+					throw new Error(`Failed during stdio-http shutdown for '${serverId}': ${toErrorMessage$9(error)}`);
+				}
+			}
+		});
+	} catch (error) {
+		try {
+			await releasePortLease(internalPortLease);
+			await processLease?.release({
+				kill: false,
+				releasePort: false
+			});
+		} catch {}
+		if (shared.services) await shared.services.dispose();
+		throw new Error(`Failed to start stdio-http transport: ${toErrorMessage$9(error)}`);
+	}
+}
+async function startTransport(transportType, options, resolvedConfigPath, serverOptions) {
+	try {
+		if (transportType === TRANSPORT_TYPE_STDIO) {
+			await startStdioTransport(serverOptions);
+			return;
+		}
+		if (transportType === TRANSPORT_TYPE_HTTP) {
+			await createAndStartHttpRuntime(serverOptions, createTransportConfig(options, require_src.TRANSPORT_MODE.HTTP), resolvedConfigPath);
+			return;
+		}
+		if (transportType === TRANSPORT_TYPE_SSE) {
+			await startSseTransport(serverOptions, createTransportConfig(options, require_src.TRANSPORT_MODE.SSE));
+			return;
+		}
+		await startStdioHttpTransport(serverOptions, createTransportConfig(options, require_src.TRANSPORT_MODE.HTTP), resolvedConfigPath);
+	} catch (error) {
+		throw new Error(`Failed to start transport '${transportType}': ${toErrorMessage$9(error)}`);
+	}
+}
+/**
+* MCP Serve command
+*/
+const mcpServeCommand = new commander.Command("mcp-serve").description("Start MCP server with specified transport").option("-t, --type <type>", `Transport type: ${TRANSPORT_TYPE_STDIO}, ${TRANSPORT_TYPE_HTTP}, ${TRANSPORT_TYPE_SSE}, or ${TRANSPORT_TYPE_STDIO_HTTP}`, TRANSPORT_TYPE_STDIO).option("-p, --port <port>", "Port to listen on (http/sse/stdio-http internal HTTP)", (val) => parseInt(val, 10), DEFAULT_PORT).option("--host <host>", "Host to bind to (http/sse/stdio-http internal HTTP)", DEFAULT_HOST).option("-c, --config <path>", "Path to MCP server configuration file").option("--no-cache", "Disable configuration caching, always reload from config file").option("--definitions-cache <path>", "Path to prefetched tool/prompt/skill definitions cache file").option("--clear-definitions-cache", "Delete definitions cache before startup", false).option("--proxy-mode <mode>", "How mcp-proxy exposes downstream tools: meta, flat, or search", "meta").option("--id <id>", "Unique server identifier (overrides config file id, auto-generated if not provided)").action(async (options) => {
+	try {
+		const transportType = validateTransportType(options.type.toLowerCase());
+		validateProxyMode(options.proxyMode);
+		const resolvedConfigPath = options.config || await findConfigFileAsync() || void 0;
+		await startTransport(transportType, options, resolvedConfigPath, createServerOptions(options, resolvedConfigPath, await resolveServerId(options, resolvedConfigPath)));
+	} catch (error) {
+		const rawTransportType = options.type.toLowerCase();
+		const transportType = isValidTransportType(rawTransportType) ? rawTransportType : TRANSPORT_TYPE_STDIO;
+		console.error(formatStartError(transportType, options.host, options.port, error));
+		process.exit(1);
+	}
+});
+
+//#endregion
+//#region src/commands/bootstrap.ts
+function toErrorMessage$8(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+async function withConnectedCommandContext(options, run) {
+	const container = require_src.createProxyIoCContainer();
+	const configFilePath = options.config || require_src.findConfigFile();
+	if (!configFilePath) throw new Error("No config file found. Use --config or create mcp-config.yaml");
+	const config = await container.createConfigFetcherService({
+		configFilePath,
+		useCache: options.useCache
+	}).fetchConfiguration();
+	const clientManager = container.createClientManagerService();
+	await Promise.all(Object.entries(config.mcpServers).map(async ([serverName, serverConfig]) => {
+		try {
+			await clientManager.connectToServer(serverName, serverConfig);
+			if (!options.json) console.error(`✓ Connected to ${serverName}`);
+		} catch (error) {
+			if (!options.json) console.error(`✗ Failed to connect to ${serverName}: ${toErrorMessage$8(error)}`);
+		}
+	}));
+	if (clientManager.getAllClients().length === 0) throw new Error("No MCP servers connected");
+	try {
+		return await run({
+			container,
+			configFilePath,
+			config,
+			clientManager
+		});
+	} finally {
+		await clientManager.disconnectAll();
+	}
+}
+
+//#endregion
+//#region src/commands/list-tools.ts
+/**
+* List Tools Command
+*
+* DESIGN PATTERNS:
+* - Command pattern with Commander for CLI argument parsing
+* - Async/await pattern for asynchronous operations
+* - Error handling pattern with try-catch and proper exit codes
+*
+* CODING STANDARDS:
+* - Use async action handlers for asynchronous operations
+* - Provide clear option descriptions and default values
+* - Handle errors gracefully with process.exit()
+* - Log progress and errors to console
+* - Use Commander's .option() and .argument() for inputs
+*
+* AVOID:
+* - Synchronous blocking operations in action handlers
+* - Missing error handling (always use try-catch)
+* - Hardcoded values (use options or environment variables)
+* - Not exiting with appropriate exit codes on errors
+*/
+function toErrorMessage$7(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function printSearchResults(result) {
+	for (const server of result.servers) {
+		console.log(`\n${server.server}:`);
+		if (server.capabilities && server.capabilities.length > 0) console.log(`  capabilities: ${server.capabilities.join(", ")}`);
+		if (server.summary) console.log(`  summary: ${server.summary}`);
+		if (server.tools.length === 0) {
+			console.log("  no tools");
+			continue;
+		}
+		for (const tool of server.tools) {
+			const capabilitySummary = tool.capabilities && tool.capabilities.length > 0 ? ` [${tool.capabilities.join(", ")}]` : "";
+			console.log(`  - ${tool.name}${capabilitySummary}`);
+			if (tool.description) console.log(`    ${tool.description}`);
+		}
+	}
+}
+const searchToolsCommand = new commander.Command("search-tools").description("Search proxied MCP tools by capability or server").option("-c, --config <path>", "Path to MCP server configuration file").option("-s, --server <name>", "Filter by server name").option("--capability <name>", "Filter by capability tag, summary, tool name, or description").option("--definitions-cache <path>", "Path to definitions cache file").option("-j, --json", "Output as JSON", false).action(async (options) => {
+	try {
+		await withConnectedCommandContext(options, async ({ container, config, clientManager, configFilePath }) => {
+			clientManager.registerServerConfigs(config.mcpServers);
+			const cachePath = options.definitionsCache || require_src.DefinitionsCacheService.getDefaultCachePath(configFilePath);
+			let cacheData;
+			try {
+				cacheData = await require_src.DefinitionsCacheService.readFromFile(cachePath);
+			} catch {
+				cacheData = void 0;
+			}
+			const definitionsCacheService = container.createDefinitionsCacheService(clientManager, void 0, { cacheData });
+			const textBlock = (await container.createSearchListToolsTool(clientManager, definitionsCacheService).execute({
+				capability: options.capability,
+				serverName: options.server
+			})).content.find((content) => content.type === "text");
+			const parsed = textBlock?.type === "text" ? JSON.parse(textBlock.text) : { servers: [] };
+			if (options.json) console.log(JSON.stringify(parsed, null, 2));
+			else {
+				if (!parsed.servers || parsed.servers.length === 0) throw new Error("No tools matched the requested filters");
+				printSearchResults(parsed);
+			}
+		});
+	} catch (error) {
+		console.error(`Error executing search-tools: ${toErrorMessage$7(error)}`);
+		process.exit(1);
+	}
+});
+
+//#endregion
+//#region src/commands/describe-tools.ts
+/**
+* Describe Tools Command
+*
+* DESIGN PATTERNS:
+* - Command pattern with Commander for CLI argument parsing
+* - Async/await pattern for asynchronous operations
+* - Error handling pattern with try-catch and proper exit codes
+*
+* CODING STANDARDS:
+* - Use async action handlers for asynchronous operations
+* - Provide clear option descriptions and default values
+* - Handle errors gracefully with process.exit()
+* - Log progress and errors to console
+* - Use Commander's .option() and .argument() for inputs
+*
+* AVOID:
+* - Synchronous blocking operations in action handlers
+* - Missing error handling (always use try-catch)
+* - Hardcoded values (use options or environment variables)
+* - Not exiting with appropriate exit codes on errors
+*/
+function toErrorMessage$6(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Describe specific MCP tools
+*/
+const describeToolsCommand = new commander.Command("describe-tools").description("Describe specific MCP tools").argument("<toolNames...>", "Tool names to describe").option("-c, --config <path>", "Path to MCP server configuration file").option("-s, --server <name>", "Filter by server name").option("-j, --json", "Output as JSON", false).action(async (toolNames, options) => {
+	try {
+		await withConnectedCommandContext(options, async ({ container, config, clientManager }) => {
+			const clients = options.server ? [clientManager.getClient(options.server)].filter((client) => client !== void 0) : clientManager.getAllClients();
+			if (options.server && clients.length === 0) throw new Error(`Server "${options.server}" not found`);
+			const cwd = process.env.PROJECT_PATH || process.cwd();
+			const skillPaths = config.skills?.paths || [];
+			const skillService = skillPaths.length > 0 ? container.createSkillService(cwd, skillPaths) : void 0;
+			const foundTools = [];
+			const foundSkills = [];
+			const notFoundTools = [...toolNames];
+			const toolResults = await Promise.all(clients.map(async (client) => {
+				try {
+					return {
+						client,
+						tools: await client.listTools(),
+						error: null
+					};
+				} catch (error) {
+					return {
+						client,
+						tools: [],
+						error
+					};
+				}
+			}));
+			for (const { client, tools, error } of toolResults) {
+				if (error) {
+					if (!options.json) console.error(`Failed to list tools from ${client.serverName}:`, error);
+					continue;
+				}
+				for (const toolName of toolNames) {
+					const tool = tools.find((entry) => entry.name === toolName);
+					if (tool) {
+						foundTools.push({
+							server: client.serverName,
+							name: tool.name,
+							description: tool.description,
+							inputSchema: tool.inputSchema
+						});
+						const idx = notFoundTools.indexOf(toolName);
+						if (idx > -1) notFoundTools.splice(idx, 1);
+					}
+				}
+			}
+			if (skillService && notFoundTools.length > 0) {
+				const skillResults = await Promise.all([...notFoundTools].map(async (toolName) => {
+					const skillName = toolName.startsWith("skill__") ? toolName.slice(7) : toolName;
+					return {
+						toolName,
+						skill: await skillService.getSkill(skillName)
+					};
+				}));
+				for (const { toolName, skill } of skillResults) if (skill) {
+					foundSkills.push({
+						name: skill.name,
+						location: skill.basePath,
+						instructions: skill.content
+					});
+					const idx = notFoundTools.indexOf(toolName);
+					if (idx > -1) notFoundTools.splice(idx, 1);
+				}
+			}
+			const nextSteps = [];
+			if (foundTools.length > 0) nextSteps.push("For MCP tools: Use the use_tool function with toolName and toolArgs based on the inputSchema above.");
+			if (foundSkills.length > 0) nextSteps.push(`For skill, just follow skill's description to continue.`);
+			if (options.json) {
+				const result = {};
+				if (foundTools.length > 0) result.tools = foundTools;
+				if (foundSkills.length > 0) result.skills = foundSkills;
+				if (nextSteps.length > 0) result.nextSteps = nextSteps;
+				if (notFoundTools.length > 0) result.notFound = notFoundTools;
+				console.log(JSON.stringify(result, null, 2));
+			} else {
+				if (foundTools.length > 0) {
+					console.log("\nFound tools:\n");
+					for (const tool of foundTools) {
+						console.log(`Server: ${tool.server}`);
+						console.log(`Tool: ${tool.name}`);
+						console.log(`Description: ${tool.description || "No description"}`);
+						console.log("Input Schema:");
+						console.log(JSON.stringify(tool.inputSchema, null, 2));
+						console.log("");
+					}
+				}
+				if (foundSkills.length > 0) {
+					console.log("\nFound skills:\n");
+					for (const skill of foundSkills) {
+						console.log(`Skill: ${skill.name}`);
+						console.log(`Location: ${skill.location}`);
+						console.log(`Instructions:\n${skill.instructions}`);
+						console.log("");
+					}
+				}
+				if (nextSteps.length > 0) {
+					console.log("\nNext steps:");
+					for (const step of nextSteps) console.log(`  • ${step}`);
+					console.log("");
+				}
+				if (notFoundTools.length > 0) console.error(`\nTools/skills not found: ${notFoundTools.join(", ")}`);
+				if (foundTools.length === 0 && foundSkills.length === 0) {
+					console.error("No tools or skills found");
+					process.exit(1);
+				}
+			}
+		});
+	} catch (error) {
+		console.error(`Error executing describe-tools: ${toErrorMessage$6(error)}`);
+		process.exit(1);
+	}
+});
+
+//#endregion
+//#region src/commands/use-tool.ts
+/**
+* Use Tool Command
+*
+* DESIGN PATTERNS:
+* - Command pattern with Commander for CLI argument parsing
+* - Async/await pattern for asynchronous operations
+* - Error handling pattern with try-catch and proper exit codes
+*
+* CODING STANDARDS:
+* - Use async action handlers for asynchronous operations
+* - Provide clear option descriptions and default values
+* - Handle errors gracefully with process.exit()
+* - Log progress and errors to console
+* - Use Commander'"'"'s .option() and .argument() for inputs
+*
+* AVOID:
+* - Synchronous blocking operations in action handlers
+* - Missing error handling (always use try-catch)
+* - Hardcoded values (use options or environment variables)
+* - Not exiting with appropriate exit codes on errors
+*/
+function toErrorMessage$5(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Execute an MCP tool with arguments
+*/
+const useToolCommand = new commander.Command("use-tool").description("Execute an MCP tool with arguments").argument("<toolName>", "Tool name to execute").option("-c, --config <path>", "Path to MCP server configuration file").option("-s, --server <name>", "Server name (required if tool exists on multiple servers)").option("-a, --args <json>", "Tool arguments as JSON string", "{}").option("-t, --timeout <ms>", "Request timeout in milliseconds for tool execution (default: 60000)", parseInt).option("-j, --json", "Output as JSON", false).action(async (toolName, options) => {
+	try {
+		let toolArgs = {};
+		try {
+			toolArgs = JSON.parse(options.args);
+		} catch {
+			console.error("Error: Invalid JSON in --args");
+			process.exit(1);
+		}
+		await withConnectedCommandContext(options, async ({ container, config, clientManager }) => {
+			const clients = clientManager.getAllClients();
+			if (options.server) {
+				const client$1 = clientManager.getClient(options.server);
+				if (!client$1) throw new Error(`Server "${options.server}" not found`);
+				if (!options.json) console.error(`Executing ${toolName} on ${options.server}...`);
+				const requestOptions$1 = options.timeout ? { timeout: options.timeout } : void 0;
+				const result$1 = await client$1.callTool(toolName, toolArgs, requestOptions$1);
+				if (options.json) console.log(JSON.stringify(result$1, null, 2));
+				else {
+					console.log("\nResult:");
+					if (result$1.content) for (const content of result$1.content) if (content.type === "text") console.log(content.text);
+					else console.log(JSON.stringify(content, null, 2));
+					if (result$1.isError) {
+						console.error("\n⚠️  Tool execution returned an error");
+						process.exit(1);
+					}
+				}
+				return;
+			}
+			const searchResults = await Promise.all(clients.map(async (client$1) => {
+				try {
+					const hasTool = (await client$1.listTools()).some((t) => t.name === toolName);
+					return {
+						serverName: client$1.serverName,
+						hasTool,
+						error: null
+					};
+				} catch (error) {
+					return {
+						serverName: client$1.serverName,
+						hasTool: false,
+						error
+					};
+				}
+			}));
+			const matchingServers = [];
+			for (const { serverName, hasTool, error } of searchResults) {
+				if (error) {
+					if (!options.json) console.error(`Failed to list tools from ${serverName}:`, error);
+					continue;
+				}
+				if (hasTool) matchingServers.push(serverName);
+			}
+			if (matchingServers.length === 0) {
+				const skillPaths = config.skills?.paths || [];
+				if (skillPaths.length > 0) try {
+					const cwd = process.env.PROJECT_PATH || process.cwd();
+					const skillService = container.createSkillService(cwd, skillPaths);
+					const skillName = toolName.startsWith("skill__") ? toolName.slice(7) : toolName;
+					const skill = await skillService.getSkill(skillName);
+					if (skill) {
+						const result$1 = { content: [{
+							type: "text",
+							text: skill.content
+						}] };
+						if (options.json) console.log(JSON.stringify(result$1, null, 2));
+						else {
+							console.log("\nSkill content:");
+							console.log(skill.content);
+						}
+						return;
+					}
+				} catch (error) {
+					if (!options.json) console.error(`Failed to lookup skill "${toolName}":`, error);
+				}
+				throw new Error(`Tool or skill "${toolName}" not found on any connected server or configured skill paths`);
+			}
+			if (matchingServers.length > 1) throw new Error(`Tool "${toolName}" found on multiple servers: ${matchingServers.join(", ")}`);
+			const targetServer = matchingServers[0];
+			const client = clientManager.getClient(targetServer);
+			if (!client) throw new Error(`Internal error: Server "${targetServer}" not connected`);
+			if (!options.json) console.error(`Executing ${toolName} on ${targetServer}...`);
+			const requestOptions = options.timeout ? { timeout: options.timeout } : void 0;
+			const result = await client.callTool(toolName, toolArgs, requestOptions);
+			if (options.json) console.log(JSON.stringify(result, null, 2));
+			else {
+				console.log("\nResult:");
+				if (result.content) for (const content of result.content) if (content.type === "text") console.log(content.text);
+				else console.log(JSON.stringify(content, null, 2));
+				if (result.isError) {
+					console.error("\n⚠️  Tool execution returned an error");
+					process.exit(1);
+				}
+			}
+		});
+	} catch (error) {
+		console.error(`Error executing use-tool: ${toErrorMessage$5(error)}`);
+		process.exit(1);
+	}
+});
+
+//#endregion
+//#region src/commands/list-resources.ts
+/**
+* ListResources Command
+*
+* DESIGN PATTERNS:
+* - Command pattern with Commander for CLI argument parsing
+* - Async/await pattern for asynchronous operations
+* - Error handling pattern with try-catch and proper exit codes
+*
+* CODING STANDARDS:
+* - Use async action handlers for asynchronous operations
+* - Provide clear option descriptions and default values
+* - Handle errors gracefully with process.exit()
+* - Log progress and errors to console
+* - Use Commander's .option() and .argument() for inputs
+*
+* AVOID:
+* - Synchronous blocking operations in action handlers
+* - Missing error handling (always use try-catch)
+* - Hardcoded values (use options or environment variables)
+* - Not exiting with appropriate exit codes on errors
+*/
+function toErrorMessage$4(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* List all available resources from connected MCP servers
+*/
+const listResourcesCommand = new commander.Command("list-resources").description("List all available resources from connected MCP servers").option("-c, --config <path>", "Path to MCP server configuration file").option("-s, --server <name>", "Filter by server name").option("-j, --json", "Output as JSON", false).action(async (options) => {
+	try {
+		await withConnectedCommandContext(options, async ({ clientManager }) => {
+			const clients = options.server ? [clientManager.getClient(options.server)].filter((c) => c !== void 0) : clientManager.getAllClients();
+			if (options.server && clients.length === 0) throw new Error(`Server "${options.server}" not found`);
+			const resourcesByServer = {};
+			const resourceResults = await Promise.all(clients.map(async (client) => {
+				try {
+					const resources = await client.listResources();
+					return {
+						serverName: client.serverName,
+						resources,
+						error: null
+					};
+				} catch (error) {
+					return {
+						serverName: client.serverName,
+						resources: [],
+						error
+					};
+				}
+			}));
+			for (const { serverName, resources, error } of resourceResults) {
+				if (error && !options.json) console.error(`Failed to list resources from ${serverName}: ${toErrorMessage$4(error)}`);
+				resourcesByServer[serverName] = resources;
+			}
+			if (options.json) console.log(JSON.stringify(resourcesByServer, null, 2));
+			else for (const [serverName, resources] of Object.entries(resourcesByServer)) {
+				console.log(`\n${serverName}:`);
+				if (resources.length === 0) console.log("  No resources available");
+				else for (const resource of resources) {
+					const label = resource.name ? `${resource.name} (${resource.uri})` : resource.uri;
+					console.log(`  - ${label}${resource.description ? `: ${resource.description}` : ""}`);
+				}
+			}
+		});
+	} catch (error) {
+		console.error(`Error executing list-resources: ${toErrorMessage$4(error)}`);
+		process.exit(1);
+	}
+});
+
+//#endregion
+//#region src/commands/read-resource.ts
+/**
+* ReadResource Command
+*
+* DESIGN PATTERNS:
+* - Command pattern with Commander for CLI argument parsing
+* - Async/await pattern for asynchronous operations
+* - Error handling pattern with try-catch and proper exit codes
+*
+* CODING STANDARDS:
+* - Use async action handlers for asynchronous operations
+* - Provide clear option descriptions and default values
+* - Handle errors gracefully with process.exit()
+* - Log progress and errors to console
+* - Use Commander's .option() and .argument() for inputs
+*
+* AVOID:
+* - Synchronous blocking operations in action handlers
+* - Missing error handling (always use try-catch)
+* - Hardcoded values (use options or environment variables)
+* - Not exiting with appropriate exit codes on errors
+*/
+function toErrorMessage$3(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Read a resource by URI from a connected MCP server
+*/
+const readResourceCommand = new commander.Command("read-resource").description("Read a resource by URI from a connected MCP server").argument("<uri>", "Resource URI to read").option("-c, --config <path>", "Path to MCP server configuration file").option("-s, --server <name>", "Server name (required if resource exists on multiple servers)").option("-j, --json", "Output as JSON", false).action(async (uri, options) => {
+	try {
+		await withConnectedCommandContext(options, async ({ clientManager }) => {
+			const clients = clientManager.getAllClients();
+			if (options.server) {
+				const client$1 = clientManager.getClient(options.server);
+				if (!client$1) throw new Error(`Server "${options.server}" not found`);
+				if (!options.json) console.error(`Reading ${uri} from ${options.server}...`);
+				const result$1 = await client$1.readResource(uri);
+				if (options.json) console.log(JSON.stringify(result$1, null, 2));
+				else for (const content of result$1.contents) if ("text" in content) console.log(content.text);
+				else console.log(JSON.stringify(content, null, 2));
+				return;
+			}
+			const searchResults = await Promise.all(clients.map(async (client$1) => {
+				try {
+					const hasResource = (await client$1.listResources()).some((r) => r.uri === uri);
+					return {
+						serverName: client$1.serverName,
+						hasResource,
+						error: null
+					};
+				} catch (error) {
+					return {
+						serverName: client$1.serverName,
+						hasResource: false,
+						error
+					};
+				}
+			}));
+			const matchingServers = [];
+			for (const { serverName, hasResource, error } of searchResults) {
+				if (error) {
+					console.error(`Failed to list resources from ${serverName}: ${toErrorMessage$3(error)}`);
+					continue;
+				}
+				if (hasResource) matchingServers.push(serverName);
+			}
+			if (matchingServers.length === 0) throw new Error(`Resource "${uri}" not found on any connected server`);
+			if (matchingServers.length > 1) throw new Error(`Resource "${uri}" found on multiple servers: ${matchingServers.join(", ")}. Use --server to disambiguate`);
+			const targetServer = matchingServers[0];
+			const client = clientManager.getClient(targetServer);
+			if (!client) throw new Error(`Internal error: Server "${targetServer}" not connected`);
+			if (!options.json) console.error(`Reading ${uri} from ${targetServer}...`);
+			const result = await client.readResource(uri);
+			if (options.json) console.log(JSON.stringify(result, null, 2));
+			else for (const content of result.contents) if ("text" in content) console.log(content.text);
+			else console.log(JSON.stringify(content, null, 2));
+		});
+	} catch (error) {
+		console.error(`Error executing read-resource: ${toErrorMessage$3(error)}`);
+		process.exit(1);
+	}
+});
+
+//#endregion
+//#region src/commands/list-prompts.ts
+function toErrorMessage$2(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+const listPromptsCommand = new commander.Command("list-prompts").description("List all available prompts from connected MCP servers").option("-c, --config <path>", "Path to MCP server configuration file").option("-s, --server <name>", "Filter by server name").option("-j, --json", "Output as JSON", false).action(async (options) => {
+	try {
+		await withConnectedCommandContext(options, async ({ clientManager }) => {
+			const clients = options.server ? [clientManager.getClient(options.server)].filter((client) => client !== void 0) : clientManager.getAllClients();
+			if (options.server && clients.length === 0) throw new Error(`Server "${options.server}" not found`);
+			const promptsByServer = {};
+			await Promise.all(clients.map(async (client) => {
+				try {
+					promptsByServer[client.serverName] = await client.listPrompts();
+				} catch (error) {
+					promptsByServer[client.serverName] = [];
+					if (!options.json) console.error(`Failed to list prompts from ${client.serverName}: ${toErrorMessage$2(error)}`);
+				}
+			}));
+			if (options.json) console.log(JSON.stringify(promptsByServer, null, 2));
+			else for (const [serverName, prompts] of Object.entries(promptsByServer)) {
+				console.log(`\n${serverName}:`);
+				if (prompts.length === 0) {
+					console.log("  No prompts available");
+					continue;
+				}
+				for (const prompt of prompts) {
+					console.log(`  - ${prompt.name}: ${prompt.description || "No description"}`);
+					if (prompt.arguments && prompt.arguments.length > 0) {
+						const args = prompt.arguments.map((arg) => `${arg.name}${arg.required ? " (required)" : ""}`).join(", ");
+						console.log(`    args: ${args}`);
+					}
+				}
+			}
+		});
+	} catch (error) {
+		console.error(`Error executing list-prompts: ${toErrorMessage$2(error)}`);
+		process.exit(1);
+	}
+});
+
+//#endregion
+//#region src/commands/get-prompt.ts
+function toErrorMessage$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+const getPromptCommand = new commander.Command("get-prompt").description("Get a prompt by name from a connected MCP server").argument("<promptName>", "Prompt name to fetch").option("-c, --config <path>", "Path to MCP server configuration file").option("-s, --server <name>", "Server name (required if prompt exists on multiple servers)").option("-a, --args <json>", "Prompt arguments as JSON string", "{}").option("-j, --json", "Output as JSON", false).action(async (promptName, options) => {
+	try {
+		let promptArgs = {};
+		try {
+			promptArgs = JSON.parse(options.args);
+		} catch {
+			throw new Error("Invalid JSON in --args");
+		}
+		await withConnectedCommandContext(options, async ({ clientManager }) => {
+			const clients = clientManager.getAllClients();
+			if (options.server) {
+				const client$1 = clientManager.getClient(options.server);
+				if (!client$1) throw new Error(`Server "${options.server}" not found`);
+				const prompt$1 = await client$1.getPrompt(promptName, promptArgs);
+				if (options.json) console.log(JSON.stringify(prompt$1, null, 2));
+				else for (const message of prompt$1.messages) {
+					const content = message.content;
+					if (typeof content === "object" && content && "text" in content) console.log(content.text);
+					else console.log(JSON.stringify(message, null, 2));
+				}
+				return;
+			}
+			const matchingServers = [];
+			await Promise.all(clients.map(async (client$1) => {
+				try {
+					if ((await client$1.listPrompts()).some((prompt$1) => prompt$1.name === promptName)) matchingServers.push(client$1.serverName);
+				} catch (error) {
+					if (!options.json) console.error(`Failed to list prompts from ${client$1.serverName}: ${toErrorMessage$1(error)}`);
+				}
+			}));
+			if (matchingServers.length === 0) throw new Error(`Prompt "${promptName}" not found on any connected server`);
+			if (matchingServers.length > 1) throw new Error(`Prompt "${promptName}" found on multiple servers: ${matchingServers.join(", ")}. Use --server to disambiguate`);
+			const client = clientManager.getClient(matchingServers[0]);
+			if (!client) throw new Error(`Internal error: Server "${matchingServers[0]}" not connected`);
+			const prompt = await client.getPrompt(promptName, promptArgs);
+			if (options.json) console.log(JSON.stringify(prompt, null, 2));
+			else for (const message of prompt.messages) {
+				const content = message.content;
+				if (typeof content === "object" && content && "text" in content) console.log(content.text);
+				else console.log(JSON.stringify(message, null, 2));
+			}
+		});
+	} catch (error) {
+		console.error(`Error executing get-prompt: ${toErrorMessage$1(error)}`);
+		process.exit(1);
+	}
+});
+
+//#endregion
+//#region src/commands/prefetch.ts
+/**
+* Prefetch Command
+*
+* DESIGN PATTERNS:
+* - Command pattern with Commander for CLI argument parsing
+* - Async/await pattern for asynchronous operations
+* - Error handling pattern with try-catch and proper exit codes
+*
+* CODING STANDARDS:
+* - Use async action handlers for asynchronous operations
+* - Provide clear option descriptions and default values
+* - Handle errors gracefully with process.exit()
+* - Log progress and errors to console
+* - Use Commander's .option() and .argument() for inputs
+*
+* AVOID:
+* - Synchronous blocking operations in action handlers
+* - Missing error handling (always use try-catch)
+* - Hardcoded values (use options or environment variables)
+* - Not exiting with appropriate exit codes on errors
+*/
+/**
+* Pre-download packages used by MCP servers (npx, pnpx, uvx, uv)
+*/
+const prefetchCommand = new commander.Command("prefetch").description("Pre-download packages used by MCP servers (npx, pnpx, uvx, uv)").option("-c, --config <path>", "Path to MCP server configuration file").option("-p, --parallel", "Run prefetch commands in parallel", false).option("-d, --dry-run", "Show what would be prefetched without executing", false).option("-f, --filter <type>", "Filter by package manager type: npx, pnpx, uvx, or uv").option("--definitions-out <path>", "Write discovered definitions to a JSON or YAML cache file").option("--skip-packages", "Skip package prefetch and only build definitions cache", false).option("--clear-definitions-cache", "Delete the definitions cache file before continuing", false).action(async (options) => {
+	try {
+		const container = require_src.createProxyIoCContainer();
+		const configFilePath = options.config || require_src.findConfigFile();
+		if (!configFilePath) {
+			print.error("No MCP configuration file found.");
+			print.info("Use --config <path> to specify a config file, or run \"mcp-proxy init\" to create one.");
+			process.exit(1);
+		}
+		print.info(`Loading configuration from: ${configFilePath}`);
+		const mcpConfig = await container.createConfigFetcherService({
+			configFilePath,
+			useCache: false
+		}).fetchConfiguration(true);
+		const serverId = mcpConfig.id || require_src.generateServerId();
+		const configHash = require_src.DefinitionsCacheService.generateConfigHash(mcpConfig);
+		const effectiveDefinitionsPath = options.definitionsOut || require_src.DefinitionsCacheService.getDefaultCachePath(configFilePath);
+		const prefetchService = container.createPrefetchService({
+			mcpConfig,
+			filter: options.filter,
+			parallel: options.parallel
+		});
+		const packages = prefetchService.extractPackages();
+		const shouldPrefetchPackages = !options.skipPackages;
+		const shouldWriteDefinitions = Boolean(options.definitionsOut);
+		if (options.clearDefinitionsCache) if (options.dryRun) print.info(`Would clear definitions cache: ${effectiveDefinitionsPath}`);
+		else {
+			await require_src.DefinitionsCacheService.clearFile(effectiveDefinitionsPath);
+			print.success(`Cleared definitions cache: ${effectiveDefinitionsPath}`);
+		}
+		if (shouldPrefetchPackages) if (packages.length === 0) {
+			print.warning("No packages found to prefetch.");
+			print.info("Prefetch supports: npx, pnpx, uvx, and uv run commands");
+		} else {
+			print.info(`Found ${packages.length} package(s) to prefetch:`);
+			for (const pkg of packages) print.item(`${pkg.serverName}: ${pkg.packageManager} ${pkg.packageName}`);
+		}
+		if (!shouldPrefetchPackages && !shouldWriteDefinitions) {
+			print.warning("Nothing to do. Use package prefetch or provide --definitions-out.");
+			return;
+		}
+		if (options.dryRun) {
+			if (shouldPrefetchPackages && packages.length > 0) {
+				print.newline();
+				print.header("Dry run mode - commands that would be executed:");
+				for (const pkg of packages) print.indent(pkg.fullCommand.join(" "));
+			}
+			if (shouldWriteDefinitions) {
+				print.newline();
+				print.info(`Would write definitions cache to: ${effectiveDefinitionsPath}`);
+			}
+			return;
+		}
+		let packagePrefetchFailed = false;
+		if (shouldPrefetchPackages && packages.length > 0) {
+			print.newline();
+			print.info("Prefetching packages...");
+			const summary = await prefetchService.prefetch();
+			print.newline();
+			if (summary.failed === 0) print.success(`Package prefetch complete: ${summary.successful} succeeded, ${summary.failed} failed`);
+			else print.warning(`Package prefetch complete: ${summary.successful} succeeded, ${summary.failed} failed`);
+			if (summary.failed > 0) {
+				packagePrefetchFailed = true;
+				print.newline();
+				print.error("Failed packages:");
+				for (const result of summary.results.filter((r) => !r.success)) print.item(`${result.package.serverName} (${result.package.packageName}): ${result.output.trim()}`);
+			}
+		}
+		if (shouldWriteDefinitions) {
+			print.newline();
+			print.info("Collecting definitions cache...");
+			const clientManager = container.createClientManagerService();
+			const skillPaths = mcpConfig.skills?.paths || [];
+			const skillService = skillPaths.length > 0 ? container.createSkillService(process.cwd(), skillPaths) : void 0;
+			const definitionsCacheService = container.createDefinitionsCacheService(clientManager, skillService);
+			await Promise.all(Object.entries(mcpConfig.mcpServers).map(async ([serverName, serverConfig]) => {
+				try {
+					await clientManager.connectToServer(serverName, serverConfig);
+					print.item(`Connected for definitions: ${serverName}`);
+				} catch (error) {
+					print.warning(`Failed to connect for definitions: ${serverName} (${error instanceof Error ? error.message : String(error)})`);
+				}
+			}));
+			const definitionsCache = await definitionsCacheService.collectForCache({
+				configPath: configFilePath,
+				configHash,
+				oneMcpVersion: require_src.version,
+				serverId
+			});
+			await require_src.DefinitionsCacheService.writeToFile(effectiveDefinitionsPath, definitionsCache);
+			print.success(`Definitions cache written: ${effectiveDefinitionsPath} (${Object.keys(definitionsCache.servers).length} servers, ${definitionsCache.skills.length} skills)`);
+			if (definitionsCache.failures.length > 0) print.warning(`Definitions cache completed with ${definitionsCache.failures.length} server failure(s)`);
+			await clientManager.disconnectAll();
+		}
+		if (packagePrefetchFailed) process.exit(1);
+	} catch (error) {
+		print.error(`Error executing prefetch: ${error instanceof Error ? error.message : String(error)}`);
+		process.exit(1);
+	}
+});
+
+//#endregion
+//#region src/commands/stop.ts
+/**
+* Stop Command
+*
+* Stops a running HTTP mcp-proxy server using the authenticated admin endpoint
+* and the persisted runtime registry.
+*/
+function toErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function printStopResult(result) {
+	console.log(`Stopped mcp-proxy server '${result.serverId}'.`);
+	console.log(`Endpoint: http://${result.host}:${result.port}`);
+	console.log(`Result: ${result.message}`);
+}
+/**
+* Stop a running HTTP mcp-proxy server.
+*/
+const stopCommand = new commander.Command("stop").description("Stop a running HTTP mcp-proxy server").option("--id <id>", "Target server ID from the runtime registry").option("--host <host>", "Target runtime host").option("--port <port>", "Target runtime port", (value) => Number.parseInt(value, 10)).option("-c, --config <path>", "Reserved for future config-based targeting support").option("--token <token>", "Override the persisted shutdown token").option("--force", "Skip server ID verification against the /health response", false).option("-j, --json", "Output as JSON", false).option("--timeout <ms>", "Maximum time to wait for shutdown completion", (value) => Number.parseInt(value, 10), 5e3).action(async (options) => {
+	try {
+		if (options.config) console.error("Warning: --config is not used yet; runtime resolution uses the persisted registry.");
+		const result = await require_src.createProxyIoCContainer().createStopServerService().stop({
+			serverId: options.id,
+			host: options.host,
+			port: options.port,
+			token: options.token,
+			force: options.force,
+			timeoutMs: options.timeout
+		});
+		if (options.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+		printStopResult(result);
+	} catch (error) {
+		const errorMessage = `Error executing stop: ${toErrorMessage(error)}`;
+		if (options.json) console.log(JSON.stringify({
+			ok: false,
+			error: errorMessage
+		}, null, 2));
+		else console.error(errorMessage);
+		process.exit(1);
+	}
+});
+
+//#endregion
+//#region src/cli.ts
+/**
+* MCP Server Entry Point
+*
+* DESIGN PATTERNS:
+* - CLI pattern with Commander for argument parsing
+* - Command pattern for organizing CLI commands
+* - Transport abstraction for multiple communication methods
+*
+* CODING STANDARDS:
+* - Use async/await for asynchronous operations
+* - Handle errors gracefully with try-catch
+* - Log important events for debugging
+* - Register all commands in main entry point
+*
+* AVOID:
+* - Hardcoding command logic in index.ts (use separate command files)
+* - Missing error handling for command execution
+*/
+/**
+* Main entry point
+*/
+async function main() {
+	try {
+		const program = new commander.Command();
+		program.name("mcp-proxy").description("MCP proxy server package").version(require_src.version);
+		program.addCommand(initCommand);
+		program.addCommand(mcpServeCommand);
+		program.addCommand(searchToolsCommand);
+		program.addCommand(describeToolsCommand);
+		program.addCommand(useToolCommand);
+		program.addCommand(listResourcesCommand);
+		program.addCommand(readResourceCommand);
+		program.addCommand(listPromptsCommand);
+		program.addCommand(getPromptCommand);
+		program.addCommand(prefetchCommand);
+		program.addCommand(stopCommand);
+		await program.parseAsync(process.argv);
+	} catch (error) {
+		console.error(`CLI execution failed: ${error instanceof Error ? error.message : error}`);
+		process.exit(1);
+	}
+}
+main().catch((error) => {
+	console.error(`Fatal error: ${error instanceof Error ? error.message : error}`);
+	process.exit(1);
+});
+
+//#endregion