@agimon-ai/mcp-proxy 0.4.11 → 0.5.1

package/dist/cli.mjs

@@ -1,16 +1,25 @@
 #!/usr/bin/env node
-import { D as findConfigFile, E as generateServerId, T as DefinitionsCacheService, _ as StopServerService, d as version, f as StdioHttpTransportHandler, h as HttpTransportHandler, m as SseTransportHandler, n as createServer, o as createProxyIoCContainer, p as StdioTransportHandler, r as createSessionServer, t as TRANSPORT_MODE, u as initializeSharedServices, v as RuntimeStateService } from "./src-Cp1GdSlN.mjs";
-import { randomUUID } from "node:crypto";
+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-DQSfFKFP.mjs";
+import { constants, existsSync, readFileSync } from "node:fs";
 import { access, writeFile } from "node:fs/promises";
-import path, { join, resolve } from "node:path";
-import { constants, existsSync } from "node:fs";
-import { Liquid } from "liquidjs";
+import yaml from "js-yaml";
+import { randomUUID } from "node:crypto";
+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 } from "@agimon-ai/foundation-process-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);
@@ -34,14 +43,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
 /**
@@ -158,12 +159,6 @@ async function findExistingHealthyRuntime(workspaceRoot) {
 	} catch {}
 	return null;
 }
-function resolveSiblingRegistryPath(registryPath, fileName) {
-	if (!registryPath) return;
-	const resolved = path.resolve(registryPath);
-	if (path.extname(resolved) === ".json") return path.join(path.dirname(resolved), fileName);
-	return path.join(resolved, fileName);
-}
 function buildCliCandidates() {
 	const __filename = fileURLToPath(import.meta.url);
 	const __dirname = path.dirname(__filename);
@@ -386,16 +381,37 @@ async function findConfigFileAsync() {
 			const configPath = resolve(projectPath, fileName);
 			if (await pathExists(configPath)) return configPath;
 		}
-		const cwd = process.cwd();
-		for (const fileName of CONFIG_FILE_NAMES) {
-			const configPath = 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 = 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 discover MCP config file: ${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
+		};
+	} catch {
+		return {};
+	}
+}
 async function resolveServerId(options, resolvedConfigPath) {
 	const container = createProxyIoCContainer();
 	if (options.id) return options.id;
@@ -417,12 +433,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() {
@@ -471,9 +487,6 @@ function createRuntimeRecord(serverId, config, port, shutdownToken, configPath)
 function createPortRegistryService() {
 	return new PortRegistryService(process.env.PORT_REGISTRY_PATH);
 }
-function createProcessRegistryService() {
-	return new ProcessRegistryService(process.env.PROCESS_REGISTRY_PATH);
-}
 function getRegistryEnvironment() {
 	return process.env.NODE_ENV ?? "development";
 }
@@ -520,41 +533,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();
@@ -588,13 +566,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 {
@@ -603,10 +587,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);
 	}
 }
@@ -651,7 +632,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 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;
@@ -675,10 +670,7 @@ async function createAndStartHttpRuntime(serverOptions, config, resolvedConfigPa
 		handler = new HttpTransportHandler(() => 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)}`);
 	}
@@ -686,19 +678,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)}`);
@@ -778,21 +762,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, TRANSPORT_MODE.HTTP), resolvedConfigPath);
+			await createAndStartHttpRuntime(serverOptions, createTransportConfig(options, TRANSPORT_MODE.HTTP, proxyDefaults), resolvedConfigPath);
 			return;
 		}
 		if (transportType === TRANSPORT_TYPE_SSE) {
-			await startSseTransport(serverOptions, createTransportConfig(options, TRANSPORT_MODE.SSE));
+			await startSseTransport(serverOptions, createTransportConfig(options, TRANSPORT_MODE.SSE, proxyDefaults));
 			return;
 		}
-		await startStdioHttpTransport(createTransportConfig(options, TRANSPORT_MODE.HTTP), options, resolvedConfigPath);
+		await startStdioHttpTransport(createTransportConfig(options, TRANSPORT_MODE.HTTP, proxyDefaults), options, resolvedConfigPath);
 	} catch (error) {
 		throw new Error(`Failed to start transport '${transportType}': ${toErrorMessage$9(error)}`);
 	}
@@ -800,18 +784,19 @@ async function startTransport(transportType, options, resolvedConfigPath, server
 /**
 * 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}`, 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 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);
 	}
 });
@@ -821,14 +806,58 @@ const mcpServeCommand = new Command("mcp-serve").description("Start MCP server w
 function toErrorMessage$8(error) {
 	return error instanceof Error ? error.message : String(error);
 }
-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();
+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 {
@@ -850,6 +879,17 @@ async function withConnectedCommandContext(options, run) {
 		await clientManager.disconnectAll();
 	}
 }
+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/list-tools.ts
@@ -1092,7 +1132,7 @@ function toErrorMessage$5(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)", parseInt).option("-j, --json", "Output as JSON", false).action(async (toolName, options) => {
+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 {

package/dist/index.cjs

@@ -1,4 +1,4 @@
-const require_src = require('./src-DwErnAUn.cjs');
+const require_src = require('./src-B5N-kt9Y.cjs');
 
 exports.ConfigFetcherService = require_src.ConfigFetcherService;
 exports.DefinitionsCacheService = require_src.DefinitionsCacheService;

package/dist/index.d.cts

@@ -260,6 +260,11 @@ interface PromptConfig {
  */
 interface RemoteMcpConfiguration {
   id?: string;
+  proxy?: {
+    type?: string;
+    port?: number;
+    host?: string;
+  };
   mcpServers: Record<string, McpServerConfig>;
   skills?: SkillsConfig;
 }
@@ -515,6 +520,62 @@ declare class ConfigFetcherService {
   isCacheValid(): boolean;
 }
 //#endregion
+//#region src/services/McpClientManagerService.d.ts
+/**
+ * Service for managing MCP client connections to remote servers
+ */
+declare class McpClientManagerService {
+  private clients;
+  private serverConfigs;
+  private connectionPromises;
+  private logger;
+  constructor(logger?: LoggerLike);
+  /**
+   * Kill all stdio MCP server child processes.
+   * Sends SIGTERM first, then SIGKILL after 1s if the process hasn't exited.
+   * Must be called by the owner (e.g. transport/command layer) during shutdown.
+   * Awaiting the returned promise ensures force-kill timers complete before process.exit().
+   */
+  cleanupChildProcesses(): Promise<void>;
+  /**
+   * Connect to an MCP server based on its configuration with timeout
+   * Uses the timeout from server config, falling back to default (30s)
+   */
+  connectToServer(serverName: string, config: McpServerConfig): Promise<void>;
+  registerServerConfigs(configs: Record<string, McpServerConfig>): void;
+  getKnownServerNames(): string[];
+  getServerRequestTimeout(serverName: string): number | undefined;
+  ensureConnected(serverName: string): Promise<McpClientConnection>;
+  private createConnection;
+  /**
+   * Perform the actual connection to MCP server
+   */
+  private performConnection;
+  private connectStdioClient;
+  private connectHttpClient;
+  private connectSseClient;
+  /**
+   * Get a connected client by server name
+   */
+  getClient(serverName: string): McpClientConnection | undefined;
+  /**
+   * Get all connected clients
+   */
+  getAllClients(): McpClientConnection[];
+  /**
+   * Disconnect from a specific server
+   */
+  disconnectServer(serverName: string): Promise<void>;
+  /**
+   * Disconnect from all servers
+   */
+  disconnectAll(): Promise<void>;
+  /**
+   * Check if a server is connected
+   */
+  isConnected(serverName: string): boolean;
+}
+//#endregion
 //#region src/services/SkillService.d.ts
 /**
  * Service for loading and managing skills from configured skill directories.
@@ -643,60 +704,6 @@ declare class SkillService {
   private loadSkillFile;
 }
 //#endregion
-//#region src/services/McpClientManagerService.d.ts
-/**
- * Service for managing MCP client connections to remote servers
- */
-declare class McpClientManagerService {
-  private clients;
-  private serverConfigs;
-  private connectionPromises;
-  private logger;
-  constructor(logger?: LoggerLike);
-  /**
-   * Synchronously kill all stdio MCP server child processes.
-   * Must be called by the owner (e.g. transport/command layer) during shutdown.
-   */
-  cleanupChildProcesses(): void;
-  /**
-   * Connect to an MCP server based on its configuration with timeout
-   * Uses the timeout from server config, falling back to default (30s)
-   */
-  connectToServer(serverName: string, config: McpServerConfig): Promise<void>;
-  registerServerConfigs(configs: Record<string, McpServerConfig>): void;
-  getKnownServerNames(): string[];
-  getServerRequestTimeout(serverName: string): number | undefined;
-  ensureConnected(serverName: string): Promise<McpClientConnection>;
-  private createConnection;
-  /**
-   * Perform the actual connection to MCP server
-   */
-  private performConnection;
-  private connectStdioClient;
-  private connectHttpClient;
-  private connectSseClient;
-  /**
-   * Get a connected client by server name
-   */
-  getClient(serverName: string): McpClientConnection | undefined;
-  /**
-   * Get all connected clients
-   */
-  getAllClients(): McpClientConnection[];
-  /**
-   * Disconnect from a specific server
-   */
-  disconnectServer(serverName: string): Promise<void>;
-  /**
-   * Disconnect from all servers
-   */
-  disconnectAll(): Promise<void>;
-  /**
-   * Check if a server is connected
-   */
-  isConnected(serverName: string): boolean;
-}
-//#endregion
 //#region src/services/DefinitionsCacheService.d.ts
 interface DefinitionsCacheServiceOptions {
   cacheData?: DefinitionsCacheFile;
@@ -1115,10 +1122,14 @@ declare class UseToolTool implements Tool<UseToolToolInput> {
 /**
  * HTTP transport handler using Streamable HTTP (protocol version 2025-03-26)
  * Provides stateful session management with resumability support
+ *
+ * Uses a hybrid server architecture:
+ * - Raw Node.js createServer for /mcp routes (MCP SDK needs native req/res)
+ * - Hono for REST routes (/health, /admin/shutdown)
  */
 declare class HttpTransportHandler implements HttpTransportHandler$1 {
   private serverFactory;
-  private app;
+  private honoApp;
   private server;
   private sessionManager;
   private config;
@@ -1126,10 +1137,14 @@ declare class HttpTransportHandler implements HttpTransportHandler$1 {
   private adminRateLimiter;
   private logger;
   constructor(serverFactory: () => Server | Promise<Server>, config: TransportConfig, adminOptions?: HttpTransportAdminOptions, logger?: LoggerLike);
-  private setupMiddleware;
-  private setupRoutes;
+  private setupHonoRoutes;
   private isAuthorizedShutdownRequest;
   private handleAdminShutdownRequest;
+  /**
+   * Handle MCP protocol requests (POST/GET/DELETE /mcp)
+   * Uses raw Node.js req/res as required by MCP SDK
+   */
+  private handleMcpRequest;
   private handlePostRequest;
   private handleGetRequest;
   private handleDeleteRequest;
@@ -1147,14 +1162,13 @@ declare class HttpTransportHandler implements HttpTransportHandler$1 {
  */
 declare class SseTransportHandler implements HttpTransportHandler$1 {
   private serverFactory;
-  private app;
+  private honoApp;
   private server;
   private sessionManager;
   private config;
   private logger;
   constructor(serverFactory: Server | (() => Server), config: TransportConfig, logger?: LoggerLike);
-  private setupMiddleware;
-  private setupRoutes;
+  private setupHonoRoutes;
   private handleSseConnection;
   private handlePostMessage;
   start(): Promise<void>;