@agimon-ai/mcp-proxy 0.5.0 → 0.5.1

package/dist/cli.cjs

@@ -1,17 +1,27 @@
 #!/usr/bin/env node
-const require_src = require('./src-B2m53VQ1.cjs');
-let node_crypto = require("node:crypto");
+const require_src = require('./src-B5N-kt9Y.cjs');
+let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
+let js_yaml = require("js-yaml");
+js_yaml = require_src.__toESM(js_yaml);
+let node_crypto = require("node:crypto");
 let node_path = require("node:path");
 node_path = require_src.__toESM(node_path);
-let node_fs = require("node:fs");
-let liquidjs = require("liquidjs");
 let node_child_process = require("node:child_process");
+let liquidjs = require("liquidjs");
 let commander = require("commander");
 let __agimon_ai_foundation_port_registry = require("@agimon-ai/foundation-port-registry");
 let __agimon_ai_foundation_process_registry = require("@agimon-ai/foundation-process-registry");
 let node_url = require("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);
@@ -35,14 +45,6 @@ const print = {
 	indent: (message) => writeLine(`  ${message}`)
 };
 
-//#endregion
-//#region src/templates/mcp-config.yaml.liquid?raw
-var mcp_config_yaml_default = "# MCP Server Configuration\n# This file configures the MCP servers that mcp-proxy will connect to\n#\n# Environment Variable Interpolation:\n# Use ${VAR_NAME} syntax to reference environment variables\n# Example: ${HOME}, ${API_KEY}, ${DATABASE_URL}\n#\n# Instructions:\n# - config.instruction: Server's default instruction (from server documentation)\n# - instruction: User override (optional, takes precedence over config.instruction)\n# - config.toolBlacklist: Array of tool names to hide/block from this server\n# - config.omitToolDescription: Boolean to show only tool names without descriptions (saves tokens)\n\n# Remote Configuration Sources (OPTIONAL)\n# Fetch and merge configurations from remote URLs\n# Remote configs are merged with local configs based on merge strategy\n#\n# SECURITY: SSRF Protection is ENABLED by default\n# - Only HTTPS URLs are allowed (set security.enforceHttps: false to allow HTTP)\n# - Private IPs and localhost are blocked (set security.allowPrivateIPs: true for internal networks)\n# - Blocked ranges: 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16\nremoteConfigs:\n  # Example 1: Basic remote config with default security\n  # - url: ${AGIFLOW_URL}/api/v1/mcp-configs\n  #   headers:\n  #     Authorization: Bearer ${AGIFLOW_API_KEY}\n  #   mergeStrategy: local-priority  # Options: local-priority (default), remote-priority, merge-deep\n  #\n  # Example 2: Remote config with custom security settings (for internal networks)\n  # - url: ${INTERNAL_URL}/mcp-configs\n  #   headers:\n  #     Authorization: Bearer ${INTERNAL_TOKEN}\n  #   security:\n  #     allowPrivateIPs: true   # Allow internal IPs (default: false)\n  #     enforceHttps: false     # Allow HTTP (default: true, HTTPS only)\n  #   mergeStrategy: local-priority\n  #\n  # Example 3: Remote config with additional validation (OPTIONAL)\n  # - url: ${AGIFLOW_URL}/api/v1/mcp-configs\n  #   headers:\n  #     Authorization: Bearer ${AGIFLOW_API_KEY}\n  #     X-API-Key: ${AGIFLOW_API_KEY}\n  #   security:\n  #     enforceHttps: true      # Require HTTPS (default: true)\n  #     allowPrivateIPs: false  # Block private IPs (default: false)\n  #   validation:  # OPTIONAL: Additional regex validation on top of security checks\n  #     url: ^https://.*\\.agiflow\\.io/.*  # OPTIONAL: Regex pattern to validate URL format\n  #     headers:  # OPTIONAL: Regex patterns to validate header values\n  #       Authorization: ^Bearer [A-Za-z0-9_-]+$\n  #       X-API-Key: ^[A-Za-z0-9_-]{32,}$\n  #   mergeStrategy: local-priority\n\nmcpServers:\n{%- if mcpServers %}{% for server in mcpServers %}\n  {{ server.name }}:\n    command: {{ server.command }}\n    args:{% for arg in server.args %}\n      - '{{ arg }}'{% endfor %}\n    # env:\n    #   LOG_LEVEL: info\n    #   # API_KEY: ${MY_API_KEY}\n    # config:\n    #   instruction: Use this server for...\n    #   # toolBlacklist:\n    #   #   - tool_to_block\n    #   # omitToolDescription: true\n{% endfor %}\n  # Example MCP server using SSE transport\n  # remote-server:\n  #   url: https://example.com/mcp\n  #   type: sse\n  #   headers:\n  #     Authorization: Bearer ${API_KEY}\n  #   config:\n  #     instruction: This server provides tools for...\n{% else %}\n  # Example MCP server using stdio transport\n  example-server:\n    command: node\n    args:\n      - /path/to/mcp-server/build/index.js\n    env:\n      # Environment variables for the MCP server\n      LOG_LEVEL: info\n      # You can use environment variable interpolation:\n      # DATABASE_URL: ${DATABASE_URL}\n      # API_KEY: ${MY_API_KEY}\n    config:\n      # Server's default instruction (from server documentation)\n      instruction: Use this server for...\n      # Optional: Block specific tools from being listed or executed\n      # toolBlacklist:\n      #   - dangerous_tool_name\n      #   - another_blocked_tool\n      # Optional: Omit tool descriptions to save tokens (default: false)\n      # omitToolDescription: true\n    # instruction: Optional user override - takes precedence over config.instruction\n\n  # Example MCP server using SSE transport with environment variables\n  # remote-server:\n  #   url: https://example.com/mcp\n  #   type: sse\n  #   headers:\n  #     # Use ${VAR_NAME} to interpolate environment variables\n  #     Authorization: Bearer ${API_KEY}\n  #   config:\n  #     instruction: This server provides tools for...\n  #     # Optional: Block specific tools from being listed or executed\n  #     # toolBlacklist:\n  #     #   - tool_to_block\n  #     # Optional: Omit tool descriptions to save tokens (default: false)\n  #     # omitToolDescription: true\n  #   # instruction: Optional user override\n{% endif %}\n";
-
-//#endregion
-//#region src/templates/mcp-config.json?raw
-var mcp_config_default = "{\n  \"_comment\": \"MCP Server Configuration - Use ${VAR_NAME} syntax for environment variable interpolation\",\n  \"_instructions\": \"config.instruction: Server's default instruction | instruction: User override (takes precedence)\",\n  \"mcpServers\": {\n    \"example-server\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-server/build/index.js\"],\n      \"env\": {\n        \"LOG_LEVEL\": \"info\",\n        \"_comment\": \"You can use environment variable interpolation:\",\n        \"_example_DATABASE_URL\": \"${DATABASE_URL}\",\n        \"_example_API_KEY\": \"${MY_API_KEY}\"\n      },\n      \"config\": {\n        \"instruction\": \"Use this server for...\"\n      },\n      \"_instruction_override\": \"Optional user override - takes precedence over config.instruction\"\n    }\n  }\n}\n";
-
 //#endregion
 //#region src/commands/init.ts
 /**
@@ -138,11 +140,26 @@ function resolveWorkspaceRoot(startPath = process.env.PROJECT_PATH || process.cw
 		current = parent;
 	}
 }
-function resolveSiblingRegistryPath(registryPath, fileName) {
-	if (!registryPath) return;
-	const resolved = node_path.default.resolve(registryPath);
-	if (node_path.default.extname(resolved) === ".json") return node_path.default.join(node_path.default.dirname(resolved), fileName);
-	return node_path.default.join(resolved, fileName);
+const PROCESS_REGISTRY_SERVICE_HTTP$1 = "mcp-proxy-http";
+async function findExistingHealthyRuntime(workspaceRoot) {
+	const match = (await new __agimon_ai_foundation_process_registry.ProcessRegistryService(process.env.PROCESS_REGISTRY_PATH).listProcesses({
+		repositoryPath: workspaceRoot,
+		serviceName: PROCESS_REGISTRY_SERVICE_HTTP$1
+	}))[0];
+	if (!match?.host || !match?.port) return null;
+	try {
+		const healthUrl = `http://${match.host}:${match.port}/health`;
+		if ((await fetch(healthUrl)).ok) {
+			const metadata = match.metadata;
+			return {
+				host: match.host,
+				port: match.port,
+				serverId: metadata?.serverId ?? "unknown",
+				workspaceRoot
+			};
+		}
+	} catch {}
+	return null;
 }
 function buildCliCandidates() {
 	const __filename$1 = (0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href);
@@ -217,16 +234,38 @@ function spawnBackgroundRuntime(args, env, cwd) {
 	child.unref();
 	return child;
 }
+async function stopExistingRuntime(runtimeStateService, serverId, host, port) {
+	const runtimes = await runtimeStateService.list();
+	const targetHost = host || DEFAULT_HOST$1;
+	const match = runtimes.find((r) => {
+		if (serverId && r.serverId === serverId) return true;
+		if (port !== void 0 && r.host === targetHost && r.port === port) return true;
+		return false;
+	});
+	if (!match) return;
+	const stopService = new require_src.StopServerService(runtimeStateService);
+	try {
+		await stopService.stop({
+			serverId: match.serverId,
+			force: true
+		});
+	} catch {
+		await runtimeStateService.remove(match.serverId);
+	}
+}
 async function prestartHttpRuntime(options) {
 	const serverId = options.id || require_src.generateServerId();
 	const timeoutMs = parseTimeoutMs(options.timeoutMs);
 	const registryPath = options.registryPath || options.registryDir;
 	const workspaceRoot = resolveWorkspaceRoot();
+	const existing = await findExistingHealthyRuntime(workspaceRoot);
+	if (existing) return existing;
+	await stopExistingRuntime(new require_src.RuntimeStateService(), options.id, options.host, options.port);
 	const childEnv = {
 		...process.env,
 		...registryPath ? {
 			PORT_REGISTRY_PATH: registryPath,
-			PROCESS_REGISTRY_PATH: resolveSiblingRegistryPath(registryPath, "processes.json")
+			PROCESS_REGISTRY_PATH: (0, __agimon_ai_foundation_process_registry.resolveSiblingRegistryPath)(registryPath, "processes.json")
 		} : {}
 	};
 	const child = spawnBackgroundRuntime([
@@ -261,7 +300,7 @@ async function prestartHttpRuntime(options) {
 			workspaceRoot
 		};
 	} catch (error) {
-		throw new Error(`Failed to prestart HTTP runtime '${serverId}': ${error instanceof Error ? error.message : String(error)}`);
+		throw new Error(`Failed to prestart HTTP runtime '${serverId}': ${error instanceof Error ? error.message : String(error)}`, { cause: error });
 	}
 }
 const prestartHttpCommand = new commander.Command("prestart-http").description("Start an mcp-proxy HTTP runtime in the background and wait until it is healthy").option("--id <id>", "Server identifier to assign to the runtime").option("--host <host>", "Host to bind to", DEFAULT_HOST$1).option("-p, --port <port>", "Preferred HTTP port for the runtime", (value) => Number.parseInt(value, 10)).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("--registry-path <path>", "Custom registry path or directory for service discovery").option("--registry-dir <path>", "Custom registry directory for service discovery").option("--timeout-ms <ms>", "How long to wait for the runtime to become healthy", String(DEFAULT_TIMEOUT_MS)).action(async (options) => {
@@ -272,7 +311,7 @@ const prestartHttpCommand = new commander.Command("prestart-http").description("
 		process.stdout.write(`runtimeUrl=http://${host}:${port}\n`);
 		process.stdout.write(`workspaceRoot=${workspaceRoot}\n`);
 	} catch (error) {
-		throw new Error(`Failed to prestart HTTP runtime '${options.id || "generated-server-id"}': ${error instanceof Error ? error.message : String(error)}`);
+		throw new Error(`Failed to prestart HTTP runtime '${options.id || "generated-server-id"}': ${error instanceof Error ? error.message : String(error)}`, { cause: error });
 	}
 });
 
@@ -344,16 +383,37 @@ async function findConfigFileAsync() {
 			const configPath = (0, node_path.resolve)(projectPath, fileName);
 			if (await pathExists(configPath)) return configPath;
 		}
-		const cwd = process.cwd();
-		for (const fileName of CONFIG_FILE_NAMES) {
-			const configPath = (0, node_path.join)(cwd, fileName);
-			if (await pathExists(configPath)) return configPath;
+		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 = (0, node_path.join)(searchDir, fileName);
+				if (await pathExists(configPath)) return configPath;
+			}
+			const parentDir = (0, node_path.dirname)(searchDir);
+			if (parentDir === searchDir) break;
+			searchDir = parentDir;
 		}
 		return null;
 	} catch (error) {
 		throw new Error(`Failed to discover MCP config file: ${toErrorMessage$9(error)}`);
 	}
 }
+function loadProxyDefaults(configPath) {
+	try {
+		const content = (0, node_fs.readFileSync)(configPath, "utf-8");
+		const proxy = (configPath.endsWith(".yaml") || configPath.endsWith(".yml") ? js_yaml.default.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
+		};
+	} catch {
+		return {};
+	}
+}
 async function resolveServerId(options, resolvedConfigPath) {
 	const container = require_src.createProxyIoCContainer();
 	if (options.id) return options.id;
@@ -375,12 +435,12 @@ function validateTransportType(type) {
 function validateProxyMode(mode) {
 	if (!isValidProxyMode(mode)) throw new Error(`Unknown proxy mode: '${mode}'. Valid options: meta, flat, search`);
 }
-function createTransportConfig(options, mode) {
+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),
-		host: options.host || process.env.MCP_HOST || DEFAULT_HOST
+		port: options.port ?? (Number.isFinite(envPort) ? envPort : void 0) ?? proxyDefaults?.port,
+		host: options.host ?? process.env.MCP_HOST ?? proxyDefaults?.host ?? DEFAULT_HOST
 	};
 }
 function createStdioSafeLogger() {
@@ -429,9 +489,6 @@ function createRuntimeRecord(serverId, config, port, shutdownToken, configPath)
 function createPortRegistryService() {
 	return new __agimon_ai_foundation_port_registry.PortRegistryService(process.env.PORT_REGISTRY_PATH);
 }
-function createProcessRegistryService() {
-	return new __agimon_ai_foundation_process_registry.ProcessRegistryService(process.env.PROCESS_REGISTRY_PATH);
-}
 function getRegistryEnvironment() {
 	return process.env.NODE_ENV ?? "development";
 }
@@ -478,41 +535,6 @@ async function createPortRegistryLease(serviceName, host, preferredPort, serverI
 		}
 	};
 }
-async function createProcessRegistryLease(serviceName, host, port, serverId, transport, configPath) {
-	const processRegistry = createProcessRegistryService();
-	const result = await processRegistry.registerProcess({
-		repositoryPath: getRegistryRepositoryPath(),
-		serviceName,
-		serviceType: PROCESS_REGISTRY_SERVICE_TYPE,
-		environment: getRegistryEnvironment(),
-		pid: process.pid,
-		host,
-		port,
-		command: process.argv[1],
-		args: process.argv.slice(2),
-		metadata: {
-			transport,
-			serverId,
-			...configPath ? { configPath } : {}
-		}
-	});
-	if (!result.success || !result.record) throw new Error(result.error || `Failed to register process for ${serviceName}`);
-	let released = false;
-	return { release: async (options) => {
-		if (released) return;
-		released = true;
-		const releaseResult = await processRegistry.releaseProcess({
-			repositoryPath: getRegistryRepositoryPath(),
-			serviceName,
-			serviceType: PROCESS_REGISTRY_SERVICE_TYPE,
-			pid: process.pid,
-			environment: getRegistryEnvironment(),
-			kill: options?.kill ?? false,
-			releasePort: options?.releasePort ?? false
-		});
-		if (!releaseResult.success && releaseResult.error && !releaseResult.error.includes("No matching process entry")) throw new Error(releaseResult.error || `Failed to release process for ${serviceName}`);
-	} };
-}
 async function releasePortLease(lease) {
 	if (!lease) return;
 	await lease.release();
@@ -546,13 +568,19 @@ async function stopOwnedHttpTransport(handler, runtimeStateService, serverId, pr
 			throw new Error(`Failed to stop owned HTTP transport '${serverId}': ${toErrorMessage$9(error)}`);
 		}
 	} finally {
-		await processLease?.release({
-			kill: false,
-			releasePort: false
-		});
+		await processLease?.release({ kill: false });
 		await removeRuntimeRecord(runtimeStateService, serverId);
 	}
 }
+/**
+* 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.
+*/
+async function cleanupHttpRuntime(runtimeStateService, serverId, processLease) {
+	await processLease?.release({ kill: false });
+	await removeRuntimeRecord(runtimeStateService, serverId);
+}
 async function cleanupFailedRuntimeStartup(handler, runtimeStateService, serverId, processLease) {
 	try {
 		try {
@@ -561,10 +589,7 @@ async function cleanupFailedRuntimeStartup(handler, runtimeStateService, serverI
 			throw new Error(`Failed to stop HTTP transport during cleanup for '${serverId}': ${toErrorMessage$9(error)}`);
 		}
 	} finally {
-		await processLease?.release({
-			kill: false,
-			releasePort: false
-		});
+		await processLease?.release({ kill: false });
 		await removeRuntimeRecord(runtimeStateService, serverId);
 	}
 }
@@ -609,7 +634,21 @@ async function createAndStartHttpRuntime(serverOptions, config, resolvedConfigPa
 		...config,
 		port: runtimePort
 	};
-	const processLease = await createProcessRegistryLease(PROCESS_REGISTRY_SERVICE_HTTP, runtimeConfig.host ?? DEFAULT_HOST, runtimePort, runtimeServerId, TRANSPORT_TYPE_HTTP, resolvedConfigPath);
+	const processLease = await (0, __agimon_ai_foundation_process_registry.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;
@@ -633,10 +672,7 @@ async function createAndStartHttpRuntime(serverOptions, config, resolvedConfigPa
 		handler = new require_src.HttpTransportHandler(() => require_src.createSessionServer(sharedServices), runtimeConfig, createHttpAdminOptions(runtimeRecord.serverId, shutdownToken, stopHandler));
 	} catch (error) {
 		await releasePort();
-		await processLease.release({
-			kill: false,
-			releasePort: false
-		});
+		await processLease.release({ kill: false });
 		await sharedServices.dispose();
 		throw new Error(`Failed to create HTTP runtime server: ${toErrorMessage$9(error)}`);
 	}
@@ -644,19 +680,11 @@ async function createAndStartHttpRuntime(serverOptions, config, resolvedConfigPa
 		await startServer(handler, async () => {
 			await releasePort();
 			await sharedServices.dispose();
-			await processLease.release({
-				kill: false,
-				releasePort: false
-			});
-			await removeRuntimeRecord(runtimeStateService, runtimeRecord.serverId);
+			await cleanupHttpRuntime(runtimeStateService, runtimeRecord.serverId, processLease);
 		});
 		await writeRuntimeRecord(runtimeStateService, runtimeRecord);
 	} catch (error) {
 		await releasePort();
-		await processLease.release({
-			kill: false,
-			releasePort: false
-		});
 		await sharedServices.dispose();
 		await cleanupFailedRuntimeStartup(handler, runtimeStateService, runtimeRecord.serverId, processLease);
 		throw new Error(`Failed to start HTTP runtime '${runtimeRecord.serverId}': ${toErrorMessage$9(error)}`);
@@ -672,7 +700,24 @@ async function startStdioTransport(serverOptions) {
 }
 async function startSseTransport(serverOptions, config) {
 	try {
-		await startServer(new require_src.SseTransportHandler(await require_src.createServer(serverOptions), config));
+		const requestedPort = config.port;
+		const portRange = requestedPort !== void 0 ? {
+			min: requestedPort,
+			max: requestedPort
+		} : __agimon_ai_foundation_port_registry.DEFAULT_PORT_RANGE;
+		const portLease = await createPortRegistryLease("mcp-proxy-sse", config.host ?? DEFAULT_HOST, requestedPort, serverOptions.serverId ?? require_src.generateServerId(), TRANSPORT_TYPE_SSE, void 0, portRange);
+		const resolvedConfig = {
+			...config,
+			port: portLease.port
+		};
+		const handler = new require_src.SseTransportHandler(await require_src.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)}`);
 	}
@@ -680,13 +725,28 @@ async function startSseTransport(serverOptions, config) {
 async function resolveStdioHttpEndpoint(config, options, resolvedConfigPath) {
 	const repositoryPath = getRegistryRepositoryPath();
 	if (config.port !== void 0) return new URL(`http://${config.host ?? DEFAULT_HOST}:${config.port}${MCP_ENDPOINT_PATH}`);
-	const result = await createPortRegistryService().getPort({
+	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) return new URL(`http://${config.host ?? result.record.host}:${result.record.port}${MCP_ENDPOINT_PATH}`);
+	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
+		});
+	}
 	const runtime = await prestartHttpRuntime({
 		host: config.host ?? DEFAULT_HOST,
 		config: options.config || resolvedConfigPath,
@@ -704,21 +764,21 @@ async function startStdioHttpTransport(config, options, resolvedConfigPath) {
 		throw new Error(`Failed to start stdio-http transport: ${toErrorMessage$9(error)}`);
 	}
 }
-async function startTransport(transportType, options, resolvedConfigPath, serverOptions) {
+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, require_src.TRANSPORT_MODE.HTTP), resolvedConfigPath);
+			await createAndStartHttpRuntime(serverOptions, createTransportConfig(options, require_src.TRANSPORT_MODE.HTTP, proxyDefaults), resolvedConfigPath);
 			return;
 		}
 		if (transportType === TRANSPORT_TYPE_SSE) {
-			await startSseTransport(serverOptions, createTransportConfig(options, require_src.TRANSPORT_MODE.SSE));
+			await startSseTransport(serverOptions, createTransportConfig(options, require_src.TRANSPORT_MODE.SSE, proxyDefaults));
 			return;
 		}
-		await startStdioHttpTransport(createTransportConfig(options, require_src.TRANSPORT_MODE.HTTP), options, resolvedConfigPath);
+		await startStdioHttpTransport(createTransportConfig(options, require_src.TRANSPORT_MODE.HTTP, proxyDefaults), options, resolvedConfigPath);
 	} catch (error) {
 		throw new Error(`Failed to start transport '${transportType}': ${toErrorMessage$9(error)}`);
 	}
@@ -726,18 +786,19 @@ async function startTransport(transportType, options, resolvedConfigPath, server
 /**
 * MCP Serve command
 */
-const mcpServeCommand = new commander.Command("mcp-serve").description("Start MCP server with specified transport").option("-t, --type <type>", `Transport type: ${TRANSPORT_TYPE_STDIO}, ${TRANSPORT_TYPE_HTTP}, ${TRANSPORT_TYPE_SSE}, or ${TRANSPORT_TYPE_STDIO_HTTP}`, TRANSPORT_TYPE_STDIO).option("-p, --port <port>", "Port to listen on (http/sse) 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", DEFAULT_HOST).option("-c, --config <path>", "Path to MCP server configuration file").option("--no-cache", "Disable configuration caching, always reload from config file").option("--definitions-cache <path>", "Path to prefetched tool/prompt/skill definitions cache file").option("--clear-definitions-cache", "Delete definitions cache before startup", false).option("--proxy-mode <mode>", "How mcp-proxy exposes downstream tools: meta, flat, or search", "meta").option("--id <id>", "Unique server identifier (overrides config file id, auto-generated if not provided)").action(async (options) => {
+const mcpServeCommand = new commander.Command("mcp-serve").description("Start MCP server with specified transport").option("-t, --type <type>", `Transport type: ${TRANSPORT_TYPE_STDIO}, ${TRANSPORT_TYPE_HTTP}, ${TRANSPORT_TYPE_SSE}, or ${TRANSPORT_TYPE_STDIO_HTTP}`).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 transportType = validateTransportType(options.type.toLowerCase());
-		validateProxyMode(options.proxyMode);
 		const resolvedConfigPath = options.config || await findConfigFileAsync() || void 0;
-		await startTransport(transportType, options, resolvedConfigPath, createServerOptions(options, resolvedConfigPath, await resolveServerId(options, resolvedConfigPath)));
+		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) {
-		const rawTransportType = options.type.toLowerCase();
+		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, requestedPort, error));
+		console.error(formatStartError(transportType, options.host ?? DEFAULT_HOST, requestedPort, error));
 		process.exit(1);
 	}
 });
@@ -747,14 +808,58 @@ const mcpServeCommand = new commander.Command("mcp-serve").description("Start MC
 function toErrorMessage$8(error) {
 	return error instanceof Error ? error.message : String(error);
 }
-async function withConnectedCommandContext(options, run) {
-	const container = require_src.createProxyIoCContainer();
-	const configFilePath = options.config || require_src.findConfigFile();
-	if (!configFilePath) throw new Error("No config file found. Use --config or create mcp-config.yaml");
-	const config = await container.createConfigFetcherService({
-		configFilePath,
-		useCache: options.useCache
-	}).fetchConfiguration();
+async function checkHealth(host, port) {
+	try {
+		return (await fetch(`http://${host}:${port}/health`, { signal: AbortSignal.timeout(3e3) })).ok;
+	} 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();
+	try {
+		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 connect to proxy server at ${endpoint}: ${toErrorMessage$8(error)}`);
+	}
+	try {
+		return await run({
+			container,
+			configFilePath,
+			config,
+			clientManager
+		});
+	} finally {
+		await clientManager.disconnectAll();
+	}
+}
+/**
+* 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 {
@@ -776,6 +881,17 @@ async function withConnectedCommandContext(options, run) {
 		await clientManager.disconnectAll();
 	}
 }
+async function withConnectedCommandContext(options, run) {
+	const container = require_src.createProxyIoCContainer();
+	const configFilePath = options.config || require_src.findConfigFile();
+	if (!configFilePath) throw new Error("No config file found. Use --config or create mcp-config.yaml");
+	const config = await container.createConfigFetcherService({
+		configFilePath,
+		useCache: options.useCache
+	}).fetchConfiguration();
+	if (config.proxy?.port) return await withProxiedContext(container, config, configFilePath, options, run);
+	return await withDirectContext(container, config, configFilePath, options, run);
+}
 
 //#endregion
 //#region src/commands/list-tools.ts
@@ -1018,7 +1134,7 @@ function toErrorMessage$5(error) {
 /**
 * Execute an MCP tool with arguments
 */
-const useToolCommand = new commander.Command("use-tool").description("Execute an MCP tool with arguments").argument("<toolName>", "Tool name to execute").option("-c, --config <path>", "Path to MCP server configuration file").option("-s, --server <name>", "Server name (required if tool exists on multiple servers)").option("-a, --args <json>", "Tool arguments as JSON string", "{}").option("-t, --timeout <ms>", "Request timeout in milliseconds for tool execution (default: 60000)", parseInt).option("-j, --json", "Output as JSON", false).action(async (toolName, options) => {
+const useToolCommand = new commander.Command("use-tool").description("Execute an MCP tool with arguments").argument("<toolName>", "Tool name to execute").option("-c, --config <path>", "Path to MCP server configuration file").option("-s, --server <name>", "Server name (required if tool exists on multiple servers)").option("-a, --args <json>", "Tool arguments as JSON string", "{}").option("-t, --timeout <ms>", "Request timeout in milliseconds for tool execution (default: 60000)", Number.parseInt).option("-j, --json", "Output as JSON", false).action(async (toolName, options) => {
 	try {
 		let toolArgs = {};
 		try {