@agimon-ai/mcp-proxy 0.9.0 → 0.9.1

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { C as DefinitionsCacheService, D as version, T as findConfigFile, b as RuntimeStateService, d as StdioHttpTransportHandler, f as StdioTransportHandler, m as HttpTransportHandler, n as createServer, o as createProxyIoCContainer, p as SseTransportHandler, r as createSessionServer, t as TRANSPORT_MODE, u as initializeSharedServices, w as generateServerId, y as StopServerService } from "./src-DA5H3rpr.mjs";
+import { C as DefinitionsCacheService, D as version, T as findConfigFile, b as RuntimeStateService, d as StdioHttpTransportHandler, f as StdioTransportHandler, m as HttpTransportHandler, n as createServer, o as createProxyIoCContainer, p as SseTransportHandler, r as createSessionServer, t as TRANSPORT_MODE, u as initializeSharedServices, v as StopServerService, w as generateServerId } from "./src-Dv7rJN0P.mjs";
 import { constants, existsSync, readFileSync } from "node:fs";
 import { access, writeFile } from "node:fs/promises";
 import yaml from "js-yaml";
@@ -8,107 +8,9 @@ import path, { dirname, join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { Liquid } from "liquidjs";
 import { Command } from "commander";
-import { DEFAULT_PORT_RANGE, PortRegistryService } from "@agimon-ai/foundation-port-registry";
-import { ProcessRegistryService, createProcessLease, resolveSiblingRegistryPath } from "@agimon-ai/foundation-process-registry";
 import { fileURLToPath } from "node:url";
-//#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/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/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/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 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 = resolve(options.output);
-		const isYaml = !options.json && (outputPath.endsWith(".yaml") || outputPath.endsWith(".yml"));
-		let content;
-		if (isYaml) {
-			const liquid = new 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 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
+import { ProcessRegistryService, createProcessLease, resolveSiblingRegistryPath } from "@agimon-ai/foundation-process-registry";
+import { DEFAULT_PORT_RANGE, PortRegistryService } from "@agimon-ai/foundation-port-registry";
 //#region src/commands/prestart-http.ts
 /**
 * Prestart HTTP Command
@@ -316,1188 +218,1074 @@ const prestartHttpCommand = new Command("prestart-http").description("Start an m
 	}
 });
 //#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_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 PORT_REGISTRY_SERVICE_HTTP = "mcp-proxy-http";
-const PORT_REGISTRY_SERVICE_TYPE = "service";
-function getWorkspaceRoot() {
-	return resolveWorkspaceRoot();
-}
-const PROCESS_REGISTRY_SERVICE_HTTP = "mcp-proxy-http";
-const PROCESS_REGISTRY_SERVICE_TYPE = "service";
-function getRegistryRepositoryPath() {
-	return getWorkspaceRoot();
-}
+//#region src/commands/bootstrap.ts
 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";
-}
-async function pathExists(filePath) {
+async function checkHealth(host, port) {
 	try {
-		await access(filePath, constants.F_OK);
-		return true;
+		return (await fetch(`http://${host}:${port}/health`, { signal: AbortSignal.timeout(3e3) })).ok;
 	} catch {
 		return false;
 	}
 }
-async function findConfigFileAsync() {
+/**
+* Proxy mode: connect to a running HTTP server instead of downstream servers directly.
+* Auto-starts the server if not running.
+*/
+async function withProxiedContext(container, config, configFilePath, options, run) {
+	const host = config.proxy?.host ?? "localhost";
+	const port = config.proxy?.port;
+	const endpoint = `http://${host}:${port}/mcp`;
+	if (!await checkHealth(host, port)) {
+		if (!options.json) console.error("Starting HTTP proxy server in background...");
+		await prestartHttpRuntime({
+			host,
+			port,
+			config: configFilePath,
+			cache: options.useCache !== false,
+			clearDefinitionsCache: false,
+			proxyMode: "flat"
+		});
+	}
+	const clientManager = container.createClientManagerService();
 	try {
-		const projectPath = process.env.PROJECT_PATH;
-		if (projectPath) for (const fileName of CONFIG_FILE_NAMES) {
-			const configPath = resolve(projectPath, fileName);
-			if (await pathExists(configPath)) return configPath;
-		}
-		const MAX_PARENT_LEVELS = 3;
-		let searchDir = process.cwd();
-		for (let level = 0; level <= MAX_PARENT_LEVELS; level++) {
-			for (const fileName of CONFIG_FILE_NAMES) {
-				const configPath = join(searchDir, fileName);
-				if (await pathExists(configPath)) return configPath;
-			}
-			const parentDir = dirname(searchDir);
-			if (parentDir === searchDir) break;
-			searchDir = parentDir;
-		}
-		return null;
+		await clientManager.connectToServer("proxy", {
+			name: "proxy",
+			transport: "http",
+			config: { url: endpoint }
+		});
+		if (!options.json) console.error(`✓ Connected to proxy at ${endpoint}`);
 	} catch (error) {
-		throw new Error(`Failed to discover MCP config file: ${toErrorMessage$9(error)}`);
+		throw new Error(`Failed to connect to proxy server at ${endpoint}: ${toErrorMessage$9(error)}`);
 	}
-}
-function loadProxyDefaults(configPath) {
 	try {
-		const content = readFileSync(configPath, "utf-8");
-		const proxy = (configPath.endsWith(".yaml") || configPath.endsWith(".yml") ? yaml.load(content) : JSON.parse(content))?.proxy;
-		if (!proxy || typeof proxy !== "object") return {};
-		const p = proxy;
-		return {
-			type: typeof p.type === "string" ? p.type : void 0,
-			port: typeof p.port === "number" && Number.isInteger(p.port) && p.port > 0 ? p.port : void 0,
-			host: typeof p.host === "string" ? p.host : void 0,
-			keepAlive: typeof p.keepAlive === "boolean" ? p.keepAlive : void 0
-		};
-	} catch {
-		return {};
+		return await run({
+			container,
+			configFilePath,
+			config,
+			clientManager
+		});
+	} finally {
+		await clientManager.disconnectAll();
 	}
 }
-async function resolveServerId(options, resolvedConfigPath) {
-	const container = 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)}`);
+/**
+* Direct mode: connect to all downstream MCP servers individually.
+*/
+async function withDirectContext(container, config, configFilePath, options, run) {
+	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$9(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();
 	}
-	return 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, proxyDefaults) {
-	const envPort = process.env.MCP_PORT ? Number(process.env.MCP_PORT) : void 0;
-	return {
-		mode,
-		port: options.port ?? (Number.isFinite(envPort) ? envPort : void 0) ?? proxyDefaults?.port,
-		host: options.host ?? process.env.MCP_HOST ?? proxyDefaults?.host ?? DEFAULT_HOST
-	};
-}
-function createStdioSafeLogger() {
-	const logToStderr = (message, data) => {
-		if (data === void 0) {
-			console.error(message);
-			return;
-		}
-		console.error(message, data);
-	};
-	return {
-		trace: logToStderr,
-		debug: logToStderr,
-		info: logToStderr,
-		warn: logToStderr,
-		error: logToStderr
-	};
-}
-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 ${port === void 0 ? `${host} (dynamic port)` : `${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 PortRegistryService(process.env.PORT_REGISTRY_PATH);
-}
-function getRegistryEnvironment() {
-	return process.env.NODE_ENV ?? "development";
-}
-async function createPortRegistryLease(serviceName, host, preferredPort, serverId, transport, configPath, portRange = preferredPort !== void 0 ? {
-	min: preferredPort,
-	max: preferredPort
-} : DEFAULT_PORT_RANGE) {
-	const portRegistry = createPortRegistryService();
-	const result = await portRegistry.reservePort({
-		repositoryPath: getRegistryRepositoryPath(),
-		serviceName,
-		serviceType: PORT_REGISTRY_SERVICE_TYPE,
-		environment: getRegistryEnvironment(),
-		pid: process.pid,
-		host,
-		preferredPort,
-		portRange,
-		force: true,
-		metadata: {
-			transport,
-			serverId,
-			...configPath ? { configPath } : {}
-		}
-	});
-	if (!result.success || !result.record) {
-		const requestedPortLabel = preferredPort === void 0 ? "dynamic port" : `port ${preferredPort}`;
-		throw new Error(result.error || `Failed to reserve ${requestedPortLabel} in port registry`);
-	}
-	let released = false;
-	return {
-		port: result.record.port,
-		release: async () => {
-			if (released) return;
-			released = true;
-			const releaseResult = await portRegistry.releasePort({
-				repositoryPath: getRegistryRepositoryPath(),
-				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 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 });
-		await removeRuntimeRecord(runtimeStateService, serverId);
-	}
+async function withConnectedCommandContext(options, run) {
+	const container = createProxyIoCContainer();
+	const configFilePath = options.config || 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();
+	if (config.proxy?.port) return await withProxiedContext(container, config, configFilePath, options, run);
+	return await withDirectContext(container, config, configFilePath, options, run);
 }
+//#endregion
+//#region src/commands/describe-tools.ts
 /**
-* Run post-stop cleanup for an HTTP runtime (release port, dispose services, remove state).
-* This is the subset of stopOwnedHttpTransport that runs AFTER handler.stop() has already
-* been called by startServer()'s signal handler — avoids double-stopping the transport.
+* 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
 */
-async function cleanupHttpRuntime(runtimeStateService, serverId, processLease) {
-	await processLease?.release({ kill: 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 });
-		await removeRuntimeRecord(runtimeStateService, serverId);
-	}
+function toErrorMessage$8(error) {
+	return error instanceof Error ? error.message : String(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
+* Describe specific MCP tools
 */
-async function startServer(handler, onStopped) {
+const describeToolsCommand = new 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 handler.start();
+		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) {
-		throw new Error(`Failed to start transport handler: ${toErrorMessage$9(error)}`);
+		console.error(`Error executing describe-tools: ${toErrorMessage$8(error)}`);
+		process.exit(1);
 	}
-	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"));
+});
+//#endregion
+//#region src/commands/get-prompt.ts
+function toErrorMessage$7(error) {
+	return error instanceof Error ? error.message : String(error);
 }
-async function createAndStartHttpRuntime(serverOptions, config, resolvedConfigPath) {
-	const sharedServices = await initializeSharedServices(serverOptions);
-	const runtimeStateService = new RuntimeStateService();
-	const shutdownToken = randomUUID();
-	const runtimeServerId = serverOptions.serverId ?? generateServerId();
-	const requestedPort = config.port;
-	const portRange = requestedPort !== void 0 ? {
-		min: requestedPort,
-		max: requestedPort
-	} : DEFAULT_PORT_RANGE;
-	const portLease = await createPortRegistryLease(PORT_REGISTRY_SERVICE_HTTP, config.host ?? DEFAULT_HOST, requestedPort, runtimeServerId, TRANSPORT_TYPE_HTTP, resolvedConfigPath, portRange);
-	const runtimePort = portLease.port;
-	const runtimeConfig = {
-		...config,
-		port: runtimePort
-	};
-	const processLease = await createProcessLease({
-		repositoryPath: getRegistryRepositoryPath(),
-		serviceName: PROCESS_REGISTRY_SERVICE_HTTP,
-		serviceType: PROCESS_REGISTRY_SERVICE_TYPE,
-		environment: getRegistryEnvironment(),
-		host: runtimeConfig.host ?? DEFAULT_HOST,
-		port: runtimePort,
-		command: process.argv[1],
-		args: process.argv.slice(2),
-		metadata: {
-			transport: TRANSPORT_TYPE_HTTP,
-			serverId: runtimeServerId,
-			...resolvedConfigPath ? { configPath: resolvedConfigPath } : {}
-		}
-	});
-	let releasePort = async () => {
-		await releasePortLease(portLease ?? null);
-		releasePort = async () => void 0;
-	};
-	const runtimeRecord = createRuntimeRecord(runtimeServerId, runtimeConfig, runtimePort, shutdownToken, resolvedConfigPath);
-	let handler;
-	let isStopping = false;
-	const stopHandler = async () => {
-		if (isStopping) return;
-		isStopping = true;
+const getPromptCommand = new 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 {
-			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)}`);
+			promptArgs = JSON.parse(options.args);
+		} catch {
+			throw new Error("Invalid JSON in --args");
 		}
-	};
-	try {
-		handler = new HttpTransportHandler(() => createSessionServer(sharedServices), runtimeConfig, createHttpAdminOptions(runtimeRecord.serverId, shutdownToken, stopHandler));
-	} catch (error) {
-		await releasePort();
-		await processLease.release({ kill: 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 cleanupHttpRuntime(runtimeStateService, runtimeRecord.serverId, processLease);
+		await withConnectedCommandContext(options, async ({ clientManager }) => {
+			const clients = clientManager.getAllClients();
+			if (options.server) {
+				const client = clientManager.getClient(options.server);
+				if (!client) throw new Error(`Server "${options.server}" not found`);
+				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));
+				}
+				return;
+			}
+			const matchingServers = [];
+			await Promise.all(clients.map(async (client) => {
+				try {
+					if ((await client.listPrompts()).some((prompt) => prompt.name === promptName)) matchingServers.push(client.serverName);
+				} catch (error) {
+					if (!options.json) console.error(`Failed to list prompts from ${client.serverName}: ${toErrorMessage$7(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));
+			}
 		});
-		await writeRuntimeRecord(runtimeStateService, runtimeRecord);
 	} catch (error) {
-		await releasePort();
-		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(`Error executing get-prompt: ${toErrorMessage$7(error)}`);
+		process.exit(1);
 	}
-	console.error(`Runtime state: http://${runtimeRecord.host}:${runtimeRecord.port} (${runtimeRecord.serverId})`);
+});
+//#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/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/utils/output.ts
+function writeLine(message = "") {
+	console.log(message);
 }
-async function startStdioTransport(serverOptions) {
+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/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 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 {
-		await startServer(new StdioTransportHandler(await createServer(serverOptions), createStdioSafeLogger()));
+		const outputPath = resolve(options.output);
+		const isYaml = !options.json && (outputPath.endsWith(".yaml") || outputPath.endsWith(".yml"));
+		let content;
+		if (isYaml) {
+			const liquid = new 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 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) {
-		throw new Error(`Failed to start stdio transport: ${toErrorMessage$9(error)}`);
+		log.error("Error executing init:", error instanceof Error ? error.message : String(error));
+		process.exit(1);
 	}
+});
+//#endregion
+//#region src/commands/list-prompts.ts
+function toErrorMessage$6(error) {
+	return error instanceof Error ? error.message : String(error);
 }
-async function startSseTransport(serverOptions, config) {
+const listPromptsCommand = new 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 {
-		const requestedPort = config.port;
-		const portRange = requestedPort !== void 0 ? {
-			min: requestedPort,
-			max: requestedPort
-		} : DEFAULT_PORT_RANGE;
-		const portLease = await createPortRegistryLease("mcp-proxy-sse", config.host ?? DEFAULT_HOST, requestedPort, serverOptions.serverId ?? generateServerId(), TRANSPORT_TYPE_SSE, void 0, portRange);
-		const resolvedConfig = {
-			...config,
-			port: portLease.port
-		};
-		const handler = new SseTransportHandler(await createServer(serverOptions), resolvedConfig);
-		const shutdown = async () => {
-			await handler.stop();
-			await portLease.release();
-		};
-		process.on("SIGINT", shutdown);
-		process.on("SIGTERM", shutdown);
-		await startServer(handler);
-	} catch (error) {
-		throw new Error(`Failed to start SSE transport: ${toErrorMessage$9(error)}`);
-	}
-}
-async function resolveStdioHttpEndpoint(config, options, resolvedConfigPath) {
-	const repositoryPath = getRegistryRepositoryPath();
-	if (config.port !== void 0) return { endpoint: new URL(`http://${config.host ?? DEFAULT_HOST}:${config.port}${MCP_ENDPOINT_PATH}`) };
-	const portRegistry = createPortRegistryService();
-	const result = await portRegistry.getPort({
-		repositoryPath,
-		serviceName: PORT_REGISTRY_SERVICE_HTTP,
-		serviceType: PORT_REGISTRY_SERVICE_TYPE,
-		environment: getRegistryEnvironment()
-	});
-	if (result.success && result.record) {
-		const host = config.host ?? result.record.host;
-		const endpoint = new URL(`http://${host}:${result.record.port}${MCP_ENDPOINT_PATH}`);
-		try {
-			const healthUrl = `http://${host}:${result.record.port}/health`;
-			if ((await fetch(healthUrl)).ok) return { endpoint };
-		} catch {}
-		await portRegistry.releasePort({
-			repositoryPath,
-			serviceName: PORT_REGISTRY_SERVICE_HTTP,
-			serviceType: PORT_REGISTRY_SERVICE_TYPE,
-			environment: getRegistryEnvironment(),
-			force: true
+		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$6(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$6(error)}`);
+		process.exit(1);
 	}
-	const runtime = await prestartHttpRuntime({
-		host: config.host ?? DEFAULT_HOST,
-		config: options.config || resolvedConfigPath,
-		cache: options.cache,
-		definitionsCache: options.definitionsCache,
-		clearDefinitionsCache: options.clearDefinitionsCache,
-		proxyMode: options.proxyMode
-	});
-	return {
-		endpoint: new URL(`http://${runtime.host}:${runtime.port}${MCP_ENDPOINT_PATH}`),
-		ownedRuntimeServerId: runtime.reusedExistingRuntime ? void 0 : runtime.serverId
-	};
+});
+//#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$5(error) {
+	return error instanceof Error ? error.message : String(error);
 }
-async function startStdioHttpTransport(config, options, resolvedConfigPath, proxyDefaults) {
-	let ownedRuntimeServerId;
-	const keepAlive = proxyDefaults?.keepAlive ?? false;
+/**
+* List all available resources from connected MCP servers
+*/
+const listResourcesCommand = new 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 {
-		const resolvedEndpoint = await resolveStdioHttpEndpoint(config, options, resolvedConfigPath);
-		ownedRuntimeServerId = resolvedEndpoint.ownedRuntimeServerId;
-		const { endpoint } = resolvedEndpoint;
-		await startServer(new StdioHttpTransportHandler({ endpoint }, createStdioSafeLogger()), async () => {
-			if (keepAlive || !ownedRuntimeServerId) return;
-			await new StopServerService().stop({
-				serverId: ownedRuntimeServerId,
-				force: true
-			});
+		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$5(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) {
-		if (!keepAlive && ownedRuntimeServerId) {
-			const stopServerService = new StopServerService();
-			try {
-				await stopServerService.stop({
-					serverId: ownedRuntimeServerId,
-					force: true
-				});
-			} catch (cleanupError) {
-				throw new Error(`Failed to start stdio-http transport: ${toErrorMessage$9(error)}; also failed to stop owned HTTP runtime '${ownedRuntimeServerId}': ${toErrorMessage$9(cleanupError)}`);
-			}
-		}
-		throw new Error(`Failed to start stdio-http transport: ${toErrorMessage$9(error)}`);
+		console.error(`Error executing list-resources: ${toErrorMessage$5(error)}`);
+		process.exit(1);
 	}
+});
+//#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$4(error) {
+	return error instanceof Error ? error.message : String(error);
 }
-async function startTransport(transportType, options, resolvedConfigPath, serverOptions, proxyDefaults) {
-	try {
-		if (transportType === TRANSPORT_TYPE_STDIO) {
-			await startStdioTransport(serverOptions);
-			return;
-		}
-		if (transportType === TRANSPORT_TYPE_HTTP) {
-			await createAndStartHttpRuntime(serverOptions, createTransportConfig(options, TRANSPORT_MODE.HTTP, proxyDefaults), resolvedConfigPath);
-			return;
+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;
 		}
-		if (transportType === TRANSPORT_TYPE_SSE) {
-			await startSseTransport(serverOptions, createTransportConfig(options, TRANSPORT_MODE.SSE, proxyDefaults));
-			return;
+		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}`);
 		}
-		await startStdioHttpTransport(createTransportConfig(options, TRANSPORT_MODE.HTTP, proxyDefaults), options, resolvedConfigPath, proxyDefaults);
-	} catch (error) {
-		throw new Error(`Failed to start transport '${transportType}': ${toErrorMessage$9(error)}`);
 	}
 }
-/**
-* MCP Serve command
-*/
-const mcpServeCommand = new 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}`).option("-p, --port <port>", "Port to listen on (http/sse) or backend port for stdio-http", (val) => Number.parseInt(val, 10)).option("--host <host>", "Host to bind to (http/sse) or backend host for stdio-http").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) => {
+const searchToolsCommand = new 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 {
-		const resolvedConfigPath = options.config || await findConfigFileAsync() || void 0;
-		const proxyDefaults = resolvedConfigPath ? loadProxyDefaults(resolvedConfigPath) : {};
-		const transportType = validateTransportType((options.type ?? proxyDefaults.type ?? TRANSPORT_TYPE_STDIO).toLowerCase());
-		validateProxyMode(options.proxyMode);
-		await startTransport(transportType, options, resolvedConfigPath, createServerOptions(options, resolvedConfigPath, await resolveServerId(options, resolvedConfigPath)), proxyDefaults);
+		await withConnectedCommandContext(options, async ({ container, config, clientManager, configFilePath }) => {
+			clientManager.registerServerConfigs(config.mcpServers);
+			const cachePath = options.definitionsCache || DefinitionsCacheService.getDefaultCachePath(configFilePath);
+			let cacheData;
+			try {
+				cacheData = await 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) {
-		const rawTransportType = (options.type ?? TRANSPORT_TYPE_STDIO).toLowerCase();
-		const transportType = isValidTransportType(rawTransportType) ? rawTransportType : TRANSPORT_TYPE_STDIO;
-		const envPort = process.env.MCP_PORT ? Number(process.env.MCP_PORT) : void 0;
-		const requestedPort = options.port ?? (Number.isFinite(envPort) ? envPort : void 0);
-		console.error(formatStartError(transportType, options.host ?? DEFAULT_HOST, requestedPort, error));
+		console.error(`Error executing search-tools: ${toErrorMessage$4(error)}`);
 		process.exit(1);
 	}
 });
 //#endregion
-//#region src/commands/bootstrap.ts
-function toErrorMessage$8(error) {
+//#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_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 PORT_REGISTRY_SERVICE_HTTP = "mcp-proxy-http";
+const PORT_REGISTRY_SERVICE_TYPE = "service";
+function getWorkspaceRoot() {
+	return resolveWorkspaceRoot();
+}
+const PROCESS_REGISTRY_SERVICE_HTTP = "mcp-proxy-http";
+const PROCESS_REGISTRY_SERVICE_TYPE = "service";
+function getRegistryRepositoryPath() {
+	return getWorkspaceRoot();
+}
+function toErrorMessage$3(error) {
 	return error instanceof Error ? error.message : String(error);
 }
-async function checkHealth(host, port) {
+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";
+}
+async function pathExists(filePath) {
 	try {
-		return (await fetch(`http://${host}:${port}/health`, { signal: AbortSignal.timeout(3e3) })).ok;
+		await access(filePath, constants.F_OK);
+		return true;
 	} catch {
 		return false;
 	}
 }
-/**
-* Proxy mode: connect to a running HTTP server instead of downstream servers directly.
-* Auto-starts the server if not running.
-*/
-async function withProxiedContext(container, config, configFilePath, options, run) {
-	const host = config.proxy?.host ?? "localhost";
-	const port = config.proxy?.port;
-	const endpoint = `http://${host}:${port}/mcp`;
-	if (!await checkHealth(host, port)) {
-		if (!options.json) console.error("Starting HTTP proxy server in background...");
-		await prestartHttpRuntime({
-			host,
-			port,
-			config: configFilePath,
-			cache: options.useCache !== false,
-			clearDefinitionsCache: false,
-			proxyMode: "flat"
-		});
-	}
-	const clientManager = container.createClientManagerService();
+async function findConfigFileAsync() {
 	try {
-		await clientManager.connectToServer("proxy", {
-			name: "proxy",
-			transport: "http",
-			config: { url: endpoint }
-		});
-		if (!options.json) console.error(`✓ Connected to proxy at ${endpoint}`);
+		const projectPath = process.env.PROJECT_PATH;
+		if (projectPath) for (const fileName of CONFIG_FILE_NAMES) {
+			const configPath = resolve(projectPath, fileName);
+			if (await pathExists(configPath)) return configPath;
+		}
+		const MAX_PARENT_LEVELS = 3;
+		let searchDir = process.cwd();
+		for (let level = 0; level <= MAX_PARENT_LEVELS; level++) {
+			for (const fileName of CONFIG_FILE_NAMES) {
+				const configPath = join(searchDir, fileName);
+				if (await pathExists(configPath)) return configPath;
+			}
+			const parentDir = dirname(searchDir);
+			if (parentDir === searchDir) break;
+			searchDir = parentDir;
+		}
+		return null;
 	} catch (error) {
-		throw new Error(`Failed to connect to proxy server at ${endpoint}: ${toErrorMessage$8(error)}`);
+		throw new Error(`Failed to discover MCP config file: ${toErrorMessage$3(error)}`);
 	}
+}
+function loadProxyDefaults(configPath) {
 	try {
-		return await run({
-			container,
-			configFilePath,
-			config,
-			clientManager
-		});
-	} finally {
-		await clientManager.disconnectAll();
+		const content = readFileSync(configPath, "utf-8");
+		const proxy = (configPath.endsWith(".yaml") || configPath.endsWith(".yml") ? yaml.load(content) : JSON.parse(content))?.proxy;
+		if (!proxy || typeof proxy !== "object") return {};
+		const p = proxy;
+		return {
+			type: typeof p.type === "string" ? p.type : void 0,
+			port: typeof p.port === "number" && Number.isInteger(p.port) && p.port > 0 ? p.port : void 0,
+			host: typeof p.host === "string" ? p.host : void 0,
+			keepAlive: typeof p.keepAlive === "boolean" ? p.keepAlive : void 0
+		};
+	} catch {
+		return {};
 	}
 }
-/**
-* Direct mode: connect to all downstream MCP servers individually.
-*/
-async function withDirectContext(container, config, configFilePath, options, run) {
-	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)}`);
+async function resolveServerId(options, resolvedConfigPath) {
+	const container = 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$3(error)}`);
+	}
+	return 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, proxyDefaults) {
+	const envPort = process.env.MCP_PORT ? Number(process.env.MCP_PORT) : void 0;
+	return {
+		mode,
+		port: options.port ?? (Number.isFinite(envPort) ? envPort : void 0) ?? proxyDefaults?.port,
+		host: options.host ?? process.env.MCP_HOST ?? proxyDefaults?.host ?? DEFAULT_HOST
+	};
+}
+function createStdioSafeLogger() {
+	const logToStderr = (message, data) => {
+		if (data === void 0) {
+			console.error(message);
+			return;
 		}
-	}));
-	if (clientManager.getAllClients().length === 0) throw new Error("No MCP servers connected");
-	try {
-		return await run({
-			container,
-			configFilePath,
-			config,
-			clientManager
-		});
-	} finally {
-		await clientManager.disconnectAll();
+		console.error(message, data);
+	};
+	return {
+		trace: logToStderr,
+		debug: logToStderr,
+		info: logToStderr,
+		warn: logToStderr,
+		error: logToStderr
+	};
+}
+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$3(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 ${port === void 0 ? `${host} (dynamic port)` : `${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 PortRegistryService(process.env.PORT_REGISTRY_PATH);
+}
+function getRegistryEnvironment() {
+	return process.env.NODE_ENV ?? "development";
+}
+async function createPortRegistryLease(serviceName, host, preferredPort, serverId, transport, configPath, portRange = preferredPort !== void 0 ? {
+	min: preferredPort,
+	max: preferredPort
+} : DEFAULT_PORT_RANGE) {
+	const portRegistry = createPortRegistryService();
+	const result = await portRegistry.reservePort({
+		repositoryPath: getRegistryRepositoryPath(),
+		serviceName,
+		serviceType: PORT_REGISTRY_SERVICE_TYPE,
+		environment: getRegistryEnvironment(),
+		pid: process.pid,
+		host,
+		preferredPort,
+		portRange,
+		force: true,
+		metadata: {
+			transport,
+			serverId,
+			...configPath ? { configPath } : {}
+		}
+	});
+	if (!result.success || !result.record) {
+		const requestedPortLabel = preferredPort === void 0 ? "dynamic port" : `port ${preferredPort}`;
+		throw new Error(result.error || `Failed to reserve ${requestedPortLabel} in port registry`);
 	}
+	let released = false;
+	return {
+		port: result.record.port,
+		release: async () => {
+			if (released) return;
+			released = true;
+			const releaseResult = await portRegistry.releasePort({
+				repositoryPath: getRegistryRepositoryPath(),
+				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 withConnectedCommandContext(options, run) {
-	const container = createProxyIoCContainer();
-	const configFilePath = options.config || 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();
-	if (config.proxy?.port) return await withProxiedContext(container, config, configFilePath, options, run);
-	return await withDirectContext(container, config, configFilePath, options, run);
+async function releasePortLease(lease) {
+	if (!lease) return;
+	await lease.release();
 }
-//#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 createHttpAdminOptions(serverId, shutdownToken, onShutdownRequested) {
+	return {
+		serverId,
+		shutdownToken,
+		onShutdownRequested
+	};
 }
-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}`);
-		}
+async function removeRuntimeRecord(runtimeStateService, serverId) {
+	try {
+		await runtimeStateService.remove(serverId);
+	} catch (error) {
+		throw new Error(`Failed to remove runtime state for '${serverId}': ${toErrorMessage$3(error)}`);
 	}
 }
-const searchToolsCommand = new 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) => {
+async function writeRuntimeRecord(runtimeStateService, record) {
 	try {
-		await withConnectedCommandContext(options, async ({ container, config, clientManager, configFilePath }) => {
-			clientManager.registerServerConfigs(config.mcpServers);
-			const cachePath = options.definitionsCache || DefinitionsCacheService.getDefaultCachePath(configFilePath);
-			let cacheData;
-			try {
-				cacheData = await 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);
-			}
-		});
+		await runtimeStateService.write(record);
 	} catch (error) {
-		console.error(`Error executing search-tools: ${toErrorMessage$7(error)}`);
-		process.exit(1);
+		throw new Error(`Failed to persist runtime state for '${record.serverId}': ${toErrorMessage$3(error)}`);
 	}
-});
-//#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 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) => {
+async function stopOwnedHttpTransport(handler, runtimeStateService, serverId, processLease) {
 	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);
+		try {
+			await handler.stop();
+		} catch (error) {
+			throw new Error(`Failed to stop owned HTTP transport '${serverId}': ${toErrorMessage$3(error)}`);
+		}
+	} finally {
+		await processLease?.release({ kill: false });
+		await removeRuntimeRecord(runtimeStateService, serverId);
 	}
-});
-//#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
+* Run post-stop cleanup for an HTTP runtime (release port, dispose services, remove state).
+* This is the subset of stopOwnedHttpTransport that runs AFTER handler.stop() has already
+* been called by startServer()'s signal handler — avoids double-stopping the transport.
 */
-const useToolCommand = new 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)", Number.parseInt).option("-j, --json", "Output as JSON", false).action(async (toolName, options) => {
+async function cleanupHttpRuntime(runtimeStateService, serverId, processLease) {
+	await processLease?.release({ kill: false });
+	await removeRuntimeRecord(runtimeStateService, serverId);
+}
+async function cleanupFailedRuntimeStartup(handler, runtimeStateService, serverId, processLease) {
 	try {
-		let toolArgs = {};
 		try {
-			toolArgs = JSON.parse(options.args);
-		} catch {
-			console.error("Error: Invalid JSON in --args");
-			process.exit(1);
+			await handler.stop();
+		} catch (error) {
+			throw new Error(`Failed to stop HTTP transport during cleanup for '${serverId}': ${toErrorMessage$3(error)}`);
 		}
-		await withConnectedCommandContext(options, async ({ container, config, clientManager }) => {
-			const clients = clientManager.getAllClients();
-			if (options.server) {
-				const client = clientManager.getClient(options.server);
-				if (!client) throw new Error(`Server "${options.server}" not found`);
-				if (!options.json) console.error(`Executing ${toolName} on ${options.server}...`);
-				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);
-					}
-				}
-				return;
-			}
-			const searchResults = await Promise.all(clients.map(async (client) => {
-				try {
-					const hasTool = (await client.listTools()).some((t) => t.name === toolName);
-					return {
-						serverName: client.serverName,
-						hasTool,
-						error: null
-					};
-				} catch (error) {
-					return {
-						serverName: client.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 = { content: [{
-							type: "text",
-							text: skill.content
-						}] };
-						if (options.json) console.log(JSON.stringify(result, 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);
+	} finally {
+		await processLease?.release({ kill: false });
+		await removeRuntimeRecord(runtimeStateService, serverId);
 	}
-});
-//#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
+* Start MCP server with given transport handler
+* @param handler - The transport handler to start
+* @param onStopped - Optional cleanup callback run after signal-based shutdown
 */
-const listResourcesCommand = new 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) => {
+async function startServer(handler, onStopped) {
 	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}` : ""}`);
-				}
-			}
-		});
+		await handler.start();
+	} catch (error) {
+		throw new Error(`Failed to start transport handler: ${toErrorMessage$3(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$3(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 initializeSharedServices(serverOptions);
+	const runtimeStateService = new RuntimeStateService();
+	const shutdownToken = randomUUID();
+	const runtimeServerId = serverOptions.serverId ?? generateServerId();
+	const requestedPort = config.port;
+	const portRange = requestedPort !== void 0 ? {
+		min: requestedPort,
+		max: requestedPort
+	} : DEFAULT_PORT_RANGE;
+	const portLease = await createPortRegistryLease(PORT_REGISTRY_SERVICE_HTTP, config.host ?? DEFAULT_HOST, requestedPort, runtimeServerId, TRANSPORT_TYPE_HTTP, resolvedConfigPath, portRange);
+	const runtimePort = portLease.port;
+	const runtimeConfig = {
+		...config,
+		port: runtimePort
+	};
+	const processLease = await createProcessLease({
+		repositoryPath: getRegistryRepositoryPath(),
+		serviceName: PROCESS_REGISTRY_SERVICE_HTTP,
+		serviceType: PROCESS_REGISTRY_SERVICE_TYPE,
+		environment: getRegistryEnvironment(),
+		host: runtimeConfig.host ?? DEFAULT_HOST,
+		port: runtimePort,
+		command: process.argv[1],
+		args: process.argv.slice(2),
+		metadata: {
+			transport: TRANSPORT_TYPE_HTTP,
+			serverId: runtimeServerId,
+			...resolvedConfigPath ? { configPath: resolvedConfigPath } : {}
+		}
+	});
+	let releasePort = async () => {
+		await releasePortLease(portLease ?? null);
+		releasePort = async () => void 0;
+	};
+	const runtimeRecord = createRuntimeRecord(runtimeServerId, runtimeConfig, runtimePort, 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$3(error)}`);
+		}
+	};
+	try {
+		handler = new HttpTransportHandler(() => createSessionServer(sharedServices), runtimeConfig, createHttpAdminOptions(runtimeRecord.serverId, shutdownToken, stopHandler));
 	} catch (error) {
-		console.error(`Error executing list-resources: ${toErrorMessage$4(error)}`);
-		process.exit(1);
+		await releasePort();
+		await processLease.release({ kill: false });
+		await sharedServices.dispose();
+		throw new Error(`Failed to create HTTP runtime server: ${toErrorMessage$3(error)}`);
 	}
-});
-//#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 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 = clientManager.getClient(options.server);
-				if (!client) throw new Error(`Server "${options.server}" not found`);
-				if (!options.json) console.error(`Reading ${uri} from ${options.server}...`);
-				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));
-				return;
-			}
-			const searchResults = await Promise.all(clients.map(async (client) => {
-				try {
-					const hasResource = (await client.listResources()).some((r) => r.uri === uri);
-					return {
-						serverName: client.serverName,
-						hasResource,
-						error: null
-					};
-				} catch (error) {
-					return {
-						serverName: client.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));
+		await startServer(handler, async () => {
+			await releasePort();
+			await sharedServices.dispose();
+			await cleanupHttpRuntime(runtimeStateService, runtimeRecord.serverId, processLease);
 		});
+		await writeRuntimeRecord(runtimeStateService, runtimeRecord);
 	} catch (error) {
-		console.error(`Error executing read-resource: ${toErrorMessage$3(error)}`);
-		process.exit(1);
+		await releasePort();
+		await sharedServices.dispose();
+		await cleanupFailedRuntimeStartup(handler, runtimeStateService, runtimeRecord.serverId, processLease);
+		throw new Error(`Failed to start HTTP runtime '${runtimeRecord.serverId}': ${toErrorMessage$3(error)}`);
 	}
-});
-//#endregion
-//#region src/commands/list-prompts.ts
-function toErrorMessage$2(error) {
-	return error instanceof Error ? error.message : String(error);
+	console.error(`Runtime state: http://${runtimeRecord.host}:${runtimeRecord.port} (${runtimeRecord.serverId})`);
 }
-const listPromptsCommand = new 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) => {
+async function startStdioTransport(serverOptions) {
 	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}`);
-					}
-				}
-			}
-		});
+		await startServer(new StdioTransportHandler(await createServer(serverOptions), createStdioSafeLogger()));
 	} catch (error) {
-		console.error(`Error executing list-prompts: ${toErrorMessage$2(error)}`);
-		process.exit(1);
+		throw new Error(`Failed to start stdio transport: ${toErrorMessage$3(error)}`);
 	}
-});
-//#endregion
-//#region src/commands/get-prompt.ts
-function toErrorMessage$1(error) {
-	return error instanceof Error ? error.message : String(error);
 }
-const getPromptCommand = new 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) => {
+async function startSseTransport(serverOptions, config) {
 	try {
-		let promptArgs = {};
+		const requestedPort = config.port;
+		const portRange = requestedPort !== void 0 ? {
+			min: requestedPort,
+			max: requestedPort
+		} : DEFAULT_PORT_RANGE;
+		const portLease = await createPortRegistryLease("mcp-proxy-sse", config.host ?? DEFAULT_HOST, requestedPort, serverOptions.serverId ?? generateServerId(), TRANSPORT_TYPE_SSE, void 0, portRange);
+		const resolvedConfig = {
+			...config,
+			port: portLease.port
+		};
+		const handler = new SseTransportHandler(await createServer(serverOptions), resolvedConfig);
+		const shutdown = async () => {
+			await handler.stop();
+			await portLease.release();
+		};
+		process.on("SIGINT", shutdown);
+		process.on("SIGTERM", shutdown);
+		await startServer(handler);
+	} catch (error) {
+		throw new Error(`Failed to start SSE transport: ${toErrorMessage$3(error)}`);
+	}
+}
+async function resolveStdioHttpEndpoint(config, options, resolvedConfigPath) {
+	const repositoryPath = getRegistryRepositoryPath();
+	if (config.port !== void 0) return { endpoint: new URL(`http://${config.host ?? DEFAULT_HOST}:${config.port}${MCP_ENDPOINT_PATH}`) };
+	const portRegistry = createPortRegistryService();
+	const result = await portRegistry.getPort({
+		repositoryPath,
+		serviceName: PORT_REGISTRY_SERVICE_HTTP,
+		serviceType: PORT_REGISTRY_SERVICE_TYPE,
+		environment: getRegistryEnvironment()
+	});
+	if (result.success && result.record) {
+		const host = config.host ?? result.record.host;
+		const endpoint = new URL(`http://${host}:${result.record.port}${MCP_ENDPOINT_PATH}`);
 		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 = clientManager.getClient(options.server);
-				if (!client) throw new Error(`Server "${options.server}" not found`);
-				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));
-				}
-				return;
-			}
-			const matchingServers = [];
-			await Promise.all(clients.map(async (client) => {
-				try {
-					if ((await client.listPrompts()).some((prompt) => prompt.name === promptName)) matchingServers.push(client.serverName);
-				} catch (error) {
-					if (!options.json) console.error(`Failed to list prompts from ${client.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));
+			const healthUrl = `http://${host}:${result.record.port}/health`;
+			if ((await fetch(healthUrl)).ok) return { endpoint };
+		} catch {}
+		await portRegistry.releasePort({
+			repositoryPath,
+			serviceName: PORT_REGISTRY_SERVICE_HTTP,
+			serviceType: PORT_REGISTRY_SERVICE_TYPE,
+			environment: getRegistryEnvironment(),
+			force: true
+		});
+	}
+	const runtime = await prestartHttpRuntime({
+		host: config.host ?? DEFAULT_HOST,
+		config: options.config || resolvedConfigPath,
+		cache: options.cache,
+		definitionsCache: options.definitionsCache,
+		clearDefinitionsCache: options.clearDefinitionsCache,
+		proxyMode: options.proxyMode
+	});
+	return {
+		endpoint: new URL(`http://${runtime.host}:${runtime.port}${MCP_ENDPOINT_PATH}`),
+		ownedRuntimeServerId: runtime.reusedExistingRuntime ? void 0 : runtime.serverId
+	};
+}
+async function startStdioHttpTransport(config, options, resolvedConfigPath, proxyDefaults) {
+	let ownedRuntimeServerId;
+	const keepAlive = proxyDefaults?.keepAlive ?? false;
+	try {
+		const resolvedEndpoint = await resolveStdioHttpEndpoint(config, options, resolvedConfigPath);
+		ownedRuntimeServerId = resolvedEndpoint.ownedRuntimeServerId;
+		const { endpoint } = resolvedEndpoint;
+		await startServer(new StdioHttpTransportHandler({ endpoint }, createStdioSafeLogger()), async () => {
+			if (keepAlive || !ownedRuntimeServerId) return;
+			await new StopServerService().stop({
+				serverId: ownedRuntimeServerId,
+				force: true
+			});
+		});
+	} catch (error) {
+		if (!keepAlive && ownedRuntimeServerId) {
+			const stopServerService = new StopServerService();
+			try {
+				await stopServerService.stop({
+					serverId: ownedRuntimeServerId,
+					force: true
+				});
+			} catch (cleanupError) {
+				throw new Error(`Failed to start stdio-http transport: ${toErrorMessage$3(error)}; also failed to stop owned HTTP runtime '${ownedRuntimeServerId}': ${toErrorMessage$3(cleanupError)}`);
 			}
-		});
+		}
+		throw new Error(`Failed to start stdio-http transport: ${toErrorMessage$3(error)}`);
+	}
+}
+async function startTransport(transportType, options, resolvedConfigPath, serverOptions, proxyDefaults) {
+	try {
+		if (transportType === TRANSPORT_TYPE_STDIO) {
+			await startStdioTransport(serverOptions);
+			return;
+		}
+		if (transportType === TRANSPORT_TYPE_HTTP) {
+			await createAndStartHttpRuntime(serverOptions, createTransportConfig(options, TRANSPORT_MODE.HTTP, proxyDefaults), resolvedConfigPath);
+			return;
+		}
+		if (transportType === TRANSPORT_TYPE_SSE) {
+			await startSseTransport(serverOptions, createTransportConfig(options, TRANSPORT_MODE.SSE, proxyDefaults));
+			return;
+		}
+		await startStdioHttpTransport(createTransportConfig(options, TRANSPORT_MODE.HTTP, proxyDefaults), options, resolvedConfigPath, proxyDefaults);
+	} catch (error) {
+		throw new Error(`Failed to start transport '${transportType}': ${toErrorMessage$3(error)}`);
+	}
+}
+/**
+* MCP Serve command
+*/
+const mcpServeCommand = new 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}`).option("-p, --port <port>", "Port to listen on (http/sse) or backend port for stdio-http", (val) => Number.parseInt(val, 10)).option("--host <host>", "Host to bind to (http/sse) or backend host for stdio-http").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 resolvedConfigPath = options.config || await findConfigFileAsync() || void 0;
+		const proxyDefaults = resolvedConfigPath ? loadProxyDefaults(resolvedConfigPath) : {};
+		const transportType = validateTransportType((options.type ?? proxyDefaults.type ?? TRANSPORT_TYPE_STDIO).toLowerCase());
+		validateProxyMode(options.proxyMode);
+		await startTransport(transportType, options, resolvedConfigPath, createServerOptions(options, resolvedConfigPath, await resolveServerId(options, resolvedConfigPath)), proxyDefaults);
 	} catch (error) {
-		console.error(`Error executing get-prompt: ${toErrorMessage$1(error)}`);
+		const rawTransportType = (options.type ?? TRANSPORT_TYPE_STDIO).toLowerCase();
+		const transportType = isValidTransportType(rawTransportType) ? rawTransportType : TRANSPORT_TYPE_STDIO;
+		const envPort = process.env.MCP_PORT ? Number(process.env.MCP_PORT) : void 0;
+		const requestedPort = options.port ?? (Number.isFinite(envPort) ? envPort : void 0);
+		console.error(formatStartError(transportType, options.host ?? DEFAULT_HOST, requestedPort, error));
 		process.exit(1);
 	}
 });
@@ -1628,6 +1416,89 @@ const prefetchCommand = new Command("prefetch").description("Pre-download packag
 	}
 });
 //#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$2(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Read a resource by URI from a connected MCP server
+*/
+const readResourceCommand = new 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 = clientManager.getClient(options.server);
+				if (!client) throw new Error(`Server "${options.server}" not found`);
+				if (!options.json) console.error(`Reading ${uri} from ${options.server}...`);
+				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));
+				return;
+			}
+			const searchResults = await Promise.all(clients.map(async (client) => {
+				try {
+					const hasResource = (await client.listResources()).some((r) => r.uri === uri);
+					return {
+						serverName: client.serverName,
+						hasResource,
+						error: null
+					};
+				} catch (error) {
+					return {
+						serverName: client.serverName,
+						hasResource: false,
+						error
+					};
+				}
+			}));
+			const matchingServers = [];
+			for (const { serverName, hasResource, error } of searchResults) {
+				if (error) {
+					console.error(`Failed to list resources from ${serverName}: ${toErrorMessage$2(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$2(error)}`);
+		process.exit(1);
+	}
+});
+//#endregion
 //#region src/commands/stop.ts
 /**
 * Stop Command
@@ -1635,7 +1506,7 @@ const prefetchCommand = new Command("prefetch").description("Pre-download packag
 * Stops a running HTTP mcp-proxy server using the authenticated admin endpoint
 * and the persisted runtime registry.
 */
-function toErrorMessage(error) {
+function toErrorMessage$1(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 function printStopResult(result) {
@@ -1663,7 +1534,7 @@ const stopCommand = new Command("stop").description("Stop a running HTTP mcp-pro
 		}
 		printStopResult(result);
 	} catch (error) {
-		const errorMessage = `Error executing stop: ${toErrorMessage(error)}`;
+		const errorMessage = `Error executing stop: ${toErrorMessage$1(error)}`;
 		if (options.json) console.log(JSON.stringify({
 			ok: false,
 			error: errorMessage
@@ -1673,6 +1544,135 @@ const stopCommand = new Command("stop").description("Stop a running HTTP mcp-pro
 	}
 });
 //#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(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Execute an MCP tool with arguments
+*/
+const useToolCommand = new 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)", Number.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 = clientManager.getClient(options.server);
+				if (!client) throw new Error(`Server "${options.server}" not found`);
+				if (!options.json) console.error(`Executing ${toolName} on ${options.server}...`);
+				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);
+					}
+				}
+				return;
+			}
+			const searchResults = await Promise.all(clients.map(async (client) => {
+				try {
+					const hasTool = (await client.listTools()).some((t) => t.name === toolName);
+					return {
+						serverName: client.serverName,
+						hasTool,
+						error: null
+					};
+				} catch (error) {
+					return {
+						serverName: client.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 = { content: [{
+							type: "text",
+							text: skill.content
+						}] };
+						if (options.json) console.log(JSON.stringify(result, 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(error)}`);
+		process.exit(1);
+	}
+});
+//#endregion
 //#region src/cli.ts
 /**
 * MCP Server Entry Point