@agimon-ai/mcp-proxy 0.4.1 → 0.4.3

package/dist/cli.cjs

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
-const require_src = require('./src-6KF7hZTe.cjs');
+const require_src = require('./src-G1hs2GLZ.cjs');
 let node_crypto = require("node:crypto");
 let node_fs_promises = require("node:fs/promises");
 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 commander = require("commander");
 let __agimon_ai_foundation_process_registry = require("@agimon-ai/foundation-process-registry");
 let __agimon_ai_foundation_port_registry = require("@agimon-ai/foundation-port-registry");
+let node_url = require("node:url");
 
 //#region src/utils/output.ts
 function writeLine(message = "") {
@@ -138,21 +141,16 @@ const CONFIG_FILE_NAMES = [
 	"mcp-config.json"
 ];
 const MCP_ENDPOINT_PATH = "/mcp";
-const DEFAULT_PORT = 3e3;
-const DEFAULT_HOST = "localhost";
+const DEFAULT_HOST$1 = "localhost";
 const TRANSPORT_TYPE_STDIO = "stdio";
 const TRANSPORT_TYPE_HTTP = "http";
 const TRANSPORT_TYPE_SSE = "sse";
 const TRANSPORT_TYPE_STDIO_HTTP = "stdio-http";
 const RUNTIME_TRANSPORT = TRANSPORT_TYPE_HTTP;
-const STDIO_HTTP_PROXY_STOP_LABEL = "Failed stopping stdio-http proxy";
-const INTERNAL_HTTP_STOP_LABEL = "Failed stopping internal HTTP transport";
 const PORT_REGISTRY_SERVICE_HTTP = "mcp-proxy-http";
-const PORT_REGISTRY_SERVICE_STDIO_HTTP = "mcp-proxy-stdio-http";
 const PORT_REGISTRY_SERVICE_TYPE = "service";
 const PORT_REGISTRY_REPOSITORY_PATH = process.cwd();
 const PROCESS_REGISTRY_SERVICE_HTTP = "mcp-proxy-http";
-const PROCESS_REGISTRY_SERVICE_STDIO_HTTP = "mcp-proxy-stdio-http";
 const PROCESS_REGISTRY_SERVICE_TYPE = "service";
 const PROCESS_REGISTRY_REPOSITORY_PATH = process.cwd();
 function toErrorMessage$9(error) {
@@ -164,13 +162,6 @@ function isValidTransportType(type) {
 function isValidProxyMode(mode) {
 	return mode === "meta" || mode === "flat" || mode === "search";
 }
-function isAddressInUseError(error) {
-	if (error instanceof Error && error.message.includes("EADDRINUSE")) return true;
-	if (typeof error !== "object" || error === null) return false;
-	if ("code" in error && error.code === "EADDRINUSE") return true;
-	if ("message" in error && typeof error.message === "string" && error.message.includes("EADDRINUSE")) return true;
-	return false;
-}
 async function pathExists(filePath) {
 	try {
 		await (0, node_fs_promises.access)(filePath, node_fs.constants.F_OK);
@@ -218,10 +209,11 @@ function validateProxyMode(mode) {
 	if (!isValidProxyMode(mode)) throw new Error(`Unknown proxy mode: '${mode}'. Valid options: meta, flat, search`);
 }
 function createTransportConfig(options, mode) {
+	const envPort = process.env.MCP_PORT ? Number(process.env.MCP_PORT) : void 0;
 	return {
 		mode,
-		port: options.port || Number(process.env.MCP_PORT) || DEFAULT_PORT,
-		host: options.host || process.env.MCP_HOST || DEFAULT_HOST
+		port: options.port ?? (Number.isFinite(envPort) ? envPort : void 0),
+		host: options.host || process.env.MCP_HOST || DEFAULT_HOST$1
 	};
 }
 function createServerOptions(options, resolvedConfigPath, serverId) {
@@ -237,12 +229,12 @@ function createServerOptions(options, resolvedConfigPath, serverId) {
 function formatStartError(type, host, port, error) {
 	const startErrorMessage = toErrorMessage$9(error);
 	if (type === TRANSPORT_TYPE_STDIO) return `Failed to start MCP server with transport '${type}': ${startErrorMessage}`;
-	return `Failed to start MCP server with transport '${type}' on ${host}:${port}: ${startErrorMessage}`;
+	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,
+		host: config.host ?? DEFAULT_HOST$1,
 		port,
 		transport: RUNTIME_TRANSPORT,
 		shutdownToken,
@@ -260,7 +252,10 @@ function createProcessRegistryService() {
 function getRegistryEnvironment() {
 	return process.env.NODE_ENV ?? "development";
 }
-async function createPortRegistryLease(serviceName, host, preferredPort, serverId, transport, configPath) {
+async function createPortRegistryLease(serviceName, host, preferredPort, serverId, transport, configPath, portRange = preferredPort !== void 0 ? {
+	min: preferredPort,
+	max: preferredPort
+} : __agimon_ai_foundation_port_registry.DEFAULT_PORT_RANGE) {
 	const portRegistry = createPortRegistryService();
 	const result = await portRegistry.reservePort({
 		repositoryPath: PORT_REGISTRY_REPOSITORY_PATH,
@@ -270,10 +265,7 @@ async function createPortRegistryLease(serviceName, host, preferredPort, serverI
 		pid: process.pid,
 		host,
 		preferredPort,
-		portRange: {
-			min: preferredPort,
-			max: preferredPort
-		},
+		portRange,
 		force: true,
 		metadata: {
 			transport,
@@ -281,21 +273,27 @@ async function createPortRegistryLease(serviceName, host, preferredPort, serverI
 			...configPath ? { configPath } : {}
 		}
 	});
-	if (!result.success || !result.record) throw new Error(result.error || `Failed to reserve port ${preferredPort} in port registry`);
+	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 { release: async () => {
-		if (released) return;
-		released = true;
-		const releaseResult = await portRegistry.releasePort({
-			repositoryPath: PORT_REGISTRY_REPOSITORY_PATH,
-			serviceName,
-			serviceType: PORT_REGISTRY_SERVICE_TYPE,
-			pid: process.pid,
-			environment: getRegistryEnvironment(),
-			force: true
-		});
-		if (!releaseResult.success && releaseResult.error && !releaseResult.error.includes("No matching registry entry")) throw new Error(releaseResult.error || `Failed to release port for ${serviceName}`);
-	} };
+	return {
+		port: result.record.port,
+		release: async () => {
+			if (released) return;
+			released = true;
+			const releaseResult = await portRegistry.releasePort({
+				repositoryPath: PORT_REGISTRY_REPOSITORY_PATH,
+				serviceName,
+				serviceType: PORT_REGISTRY_SERVICE_TYPE,
+				pid: process.pid,
+				environment: getRegistryEnvironment(),
+				force: true
+			});
+			if (!releaseResult.success && releaseResult.error && !releaseResult.error.includes("No matching registry entry")) throw new Error(releaseResult.error || `Failed to release port for ${serviceName}`);
+		}
+	};
 }
 async function createProcessRegistryLease(serviceName, host, port, serverId, transport, configPath) {
 	const processRegistry = createProcessRegistryService();
@@ -387,27 +385,6 @@ async function cleanupFailedRuntimeStartup(handler, runtimeStateService, serverI
 		await removeRuntimeRecord(runtimeStateService, serverId);
 	}
 }
-async function stopTransportWithContext(label, stopOperation) {
-	try {
-		await stopOperation();
-	} catch (error) {
-		throw new Error(`${label}: ${toErrorMessage$9(error)}`);
-	}
-}
-async function removeRuntimeRecordDuringStop(runtimeStateService, serverId) {
-	try {
-		await removeRuntimeRecord(runtimeStateService, serverId);
-	} catch (error) {
-		throw new Error(`Failed to remove runtime state during HTTP stop callback for '${serverId}': ${toErrorMessage$9(error)}`);
-	}
-}
-function createStdioHttpInternalTransport(sharedServices, config, adminOptions) {
-	try {
-		return new require_src.HttpTransportHandler(() => require_src.createSessionServer(sharedServices), config, adminOptions);
-	} catch (error) {
-		throw new Error(`Failed to create internal HTTP transport for stdio-http proxy: ${toErrorMessage$9(error)}`);
-	}
-}
 /**
 * Start MCP server with given transport handler
 * @param handler - The transport handler to start
@@ -438,13 +415,23 @@ async function createAndStartHttpRuntime(serverOptions, config, resolvedConfigPa
 	const runtimeStateService = new require_src.RuntimeStateService();
 	const shutdownToken = (0, node_crypto.randomUUID)();
 	const runtimeServerId = serverOptions.serverId ?? require_src.generateServerId();
-	const processLease = await createProcessRegistryLease(PROCESS_REGISTRY_SERVICE_HTTP, config.host ?? DEFAULT_HOST, config.port ?? DEFAULT_PORT, runtimeServerId, TRANSPORT_TYPE_HTTP, resolvedConfigPath);
-	const portLease = await createPortRegistryLease(PORT_REGISTRY_SERVICE_HTTP, config.host ?? DEFAULT_HOST, config.port ?? DEFAULT_PORT, runtimeServerId, TRANSPORT_TYPE_HTTP, resolvedConfigPath);
+	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(PORT_REGISTRY_SERVICE_HTTP, config.host ?? DEFAULT_HOST$1, requestedPort, runtimeServerId, TRANSPORT_TYPE_HTTP, resolvedConfigPath, portRange);
+	const runtimePort = portLease.port;
+	const runtimeConfig = {
+		...config,
+		port: runtimePort
+	};
+	const processLease = await createProcessRegistryLease(PROCESS_REGISTRY_SERVICE_HTTP, runtimeConfig.host ?? DEFAULT_HOST$1, runtimePort, runtimeServerId, TRANSPORT_TYPE_HTTP, resolvedConfigPath);
 	let releasePort = async () => {
-		await releasePortLease(portLease);
+		await releasePortLease(portLease ?? null);
 		releasePort = async () => void 0;
 	};
-	const runtimeRecord = createRuntimeRecord(runtimeServerId, config, config.port ?? DEFAULT_PORT, shutdownToken, resolvedConfigPath);
+	const runtimeRecord = createRuntimeRecord(runtimeServerId, runtimeConfig, runtimePort, shutdownToken, resolvedConfigPath);
 	let handler;
 	let isStopping = false;
 	const stopHandler = async () => {
@@ -460,7 +447,7 @@ async function createAndStartHttpRuntime(serverOptions, config, resolvedConfigPa
 		}
 	};
 	try {
-		handler = new require_src.HttpTransportHandler(() => require_src.createSessionServer(sharedServices), config, createHttpAdminOptions(runtimeRecord.serverId, shutdownToken, stopHandler));
+		handler = new require_src.HttpTransportHandler(() => require_src.createSessionServer(sharedServices), runtimeConfig, createHttpAdminOptions(runtimeRecord.serverId, shutdownToken, stopHandler));
 	} catch (error) {
 		await releasePort();
 		await processLease.release({
@@ -478,7 +465,7 @@ async function createAndStartHttpRuntime(serverOptions, config, resolvedConfigPa
 				kill: false,
 				releasePort: false
 			});
-			await removeRuntimeRecordDuringStop(runtimeStateService, runtimeRecord.serverId);
+			await removeRuntimeRecord(runtimeStateService, runtimeRecord.serverId);
 		});
 		await writeRuntimeRecord(runtimeStateService, runtimeRecord);
 	} catch (error) {
@@ -493,19 +480,6 @@ async function createAndStartHttpRuntime(serverOptions, config, resolvedConfigPa
 	}
 	console.error(`Runtime state: http://${runtimeRecord.host}:${runtimeRecord.port} (${runtimeRecord.serverId})`);
 }
-async function stopInternalHttpTransport(stdioHttpHandler, httpHandler, ownsInternalHttpTransport) {
-	try {
-		const stopOperations = [stopTransportWithContext(STDIO_HTTP_PROXY_STOP_LABEL, async () => {
-			await stdioHttpHandler.stop();
-		})];
-		if (ownsInternalHttpTransport && httpHandler) stopOperations.push(stopTransportWithContext(INTERNAL_HTTP_STOP_LABEL, async () => {
-			await httpHandler.stop();
-		}));
-		await Promise.all(stopOperations);
-	} catch (error) {
-		throw new Error(`Failed to stop stdio-http transport: ${toErrorMessage$9(error)}`);
-	}
-}
 async function startStdioTransport(serverOptions) {
 	try {
 		await startServer(new require_src.StdioTransportHandler(await require_src.createServer(serverOptions)));
@@ -520,109 +494,21 @@ async function startSseTransport(serverOptions, config) {
 		throw new Error(`Failed to start SSE transport: ${toErrorMessage$9(error)}`);
 	}
 }
-async function startStdioHttpTransport(serverOptions, config, resolvedConfigPath) {
-	const shared = { services: null };
-	let processLease;
-	let internalPortLease = null;
+async function resolveStdioHttpEndpoint(config) {
+	if (config.port !== void 0) return new URL(`http://${config.host ?? DEFAULT_HOST$1}:${config.port}${MCP_ENDPOINT_PATH}`);
+	const result = await createPortRegistryService().getPort({
+		repositoryPath: PORT_REGISTRY_REPOSITORY_PATH,
+		serviceName: PORT_REGISTRY_SERVICE_HTTP,
+		serviceType: PORT_REGISTRY_SERVICE_TYPE,
+		environment: getRegistryEnvironment()
+	});
+	if (!result.success || !result.record) throw new Error(result.error || "No prestarted HTTP backend found for stdio-http transport");
+	return new URL(`http://${config.host ?? result.record.host}:${result.record.port}${MCP_ENDPOINT_PATH}`);
+}
+async function startStdioHttpTransport(config) {
 	try {
-		const stdioHttpHandler = new require_src.StdioHttpTransportHandler({ endpoint: new URL(`http://${config.host}:${config.port}${MCP_ENDPOINT_PATH}`) });
-		const runtimeStateService = new require_src.RuntimeStateService();
-		const serverId = serverOptions.serverId ?? require_src.generateServerId();
-		const shutdownToken = (0, node_crypto.randomUUID)();
-		processLease = await createProcessRegistryLease(PROCESS_REGISTRY_SERVICE_STDIO_HTTP, config.host ?? DEFAULT_HOST, config.port ?? DEFAULT_PORT, serverId, TRANSPORT_TYPE_STDIO_HTTP, resolvedConfigPath);
-		let httpHandler = null;
-		let ownsInternalHttpTransport = false;
-		let isStopping = false;
-		let releaseInternalPort = async () => {
-			await releasePortLease(internalPortLease);
-			internalPortLease = null;
-			releaseInternalPort = async () => void 0;
-		};
-		const stopOwnedRuntime = async () => {
-			if (isStopping) return;
-			isStopping = true;
-			try {
-				await Promise.all([stopInternalHttpTransport(stdioHttpHandler, httpHandler, ownsInternalHttpTransport), removeRuntimeRecord(runtimeStateService, serverId)]);
-				await releaseInternalPort();
-				if (shared.services) await shared.services.dispose();
-				ownsInternalHttpTransport = false;
-				process.exit(0);
-			} catch (error) {
-				console.error(`Unexpected error during admin shutdown: ${toErrorMessage$9(error)}`);
-				process.exit(1);
-			}
-		};
-		const adminOptions = createHttpAdminOptions(serverId, shutdownToken, stopOwnedRuntime);
-		await startServer({
-			async start() {
-				let initialProxyConnectError;
-				try {
-					await stdioHttpHandler.start();
-					return;
-				} catch (error) {
-					initialProxyConnectError = error;
-				}
-				if (!shared.services) shared.services = await require_src.initializeSharedServices(serverOptions);
-				try {
-					internalPortLease = await createPortRegistryLease(PORT_REGISTRY_SERVICE_STDIO_HTTP, config.host ?? DEFAULT_HOST, config.port ?? DEFAULT_PORT, serverId, TRANSPORT_TYPE_STDIO_HTTP, resolvedConfigPath);
-					httpHandler = createStdioHttpInternalTransport(shared.services, config, adminOptions);
-					await httpHandler.start();
-					ownsInternalHttpTransport = true;
-				} catch (error) {
-					if (!isAddressInUseError(error)) {
-						await releaseInternalPort();
-						throw new Error(`Failed to start internal HTTP transport for stdio-http proxy: ${toErrorMessage$9(error)}`);
-					}
-				}
-				try {
-					await stdioHttpHandler.start();
-				} catch (error) {
-					let rollbackStopErrorMessage = "";
-					if (ownsInternalHttpTransport && httpHandler) {
-						try {
-							await httpHandler.stop();
-						} catch (stopError) {
-							rollbackStopErrorMessage = toErrorMessage$9(stopError);
-						}
-						ownsInternalHttpTransport = false;
-					}
-					await releaseInternalPort();
-					const retryErrorMessage = toErrorMessage$9(error);
-					const initialErrorMessage = toErrorMessage$9(initialProxyConnectError);
-					const rollbackMessage = rollbackStopErrorMessage ? `; rollback stop failed: ${rollbackStopErrorMessage}` : "";
-					throw new Error(`Failed to start stdio-http proxy bridge: initial connect failed (${initialErrorMessage}); retry failed (${retryErrorMessage})${rollbackMessage}`);
-				}
-				if (ownsInternalHttpTransport) try {
-					await writeRuntimeRecord(runtimeStateService, createRuntimeRecord(serverId, config, config.port ?? DEFAULT_PORT, shutdownToken, resolvedConfigPath));
-				} catch (error) {
-					throw new Error(`Failed to persist runtime state for stdio-http server '${serverId}': ${toErrorMessage$9(error)}`);
-				}
-			},
-			async stop() {
-				try {
-					await Promise.all([stopInternalHttpTransport(stdioHttpHandler, httpHandler, ownsInternalHttpTransport), removeRuntimeRecord(runtimeStateService, serverId)]);
-					await releaseInternalPort();
-					await processLease?.release({
-						kill: false,
-						releasePort: false
-					});
-					ownsInternalHttpTransport = false;
-					if (shared.services) await shared.services.dispose();
-				} catch (error) {
-					ownsInternalHttpTransport = false;
-					throw new Error(`Failed during stdio-http shutdown for '${serverId}': ${toErrorMessage$9(error)}`);
-				}
-			}
-		});
+		await startServer(new require_src.StdioHttpTransportHandler({ endpoint: await resolveStdioHttpEndpoint(config) }));
 	} catch (error) {
-		try {
-			await releasePortLease(internalPortLease);
-			await processLease?.release({
-				kill: false,
-				releasePort: false
-			});
-		} catch {}
-		if (shared.services) await shared.services.dispose();
 		throw new Error(`Failed to start stdio-http transport: ${toErrorMessage$9(error)}`);
 	}
 }
@@ -640,7 +526,7 @@ async function startTransport(transportType, options, resolvedConfigPath, server
 			await startSseTransport(serverOptions, createTransportConfig(options, require_src.TRANSPORT_MODE.SSE));
 			return;
 		}
-		await startStdioHttpTransport(serverOptions, createTransportConfig(options, require_src.TRANSPORT_MODE.HTTP), resolvedConfigPath);
+		await startStdioHttpTransport(createTransportConfig(options, require_src.TRANSPORT_MODE.HTTP));
 	} catch (error) {
 		throw new Error(`Failed to start transport '${transportType}': ${toErrorMessage$9(error)}`);
 	}
@@ -648,7 +534,7 @@ 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/stdio-http internal HTTP)", (val) => parseInt(val, 10), DEFAULT_PORT).option("--host <host>", "Host to bind to (http/sse/stdio-http internal HTTP)", DEFAULT_HOST).option("-c, --config <path>", "Path to MCP server configuration file").option("--no-cache", "Disable configuration caching, always reload from config file").option("--definitions-cache <path>", "Path to prefetched tool/prompt/skill definitions cache file").option("--clear-definitions-cache", "Delete definitions cache before startup", false).option("--proxy-mode <mode>", "How mcp-proxy exposes downstream tools: meta, flat, or search", "meta").option("--id <id>", "Unique server identifier (overrides config file id, auto-generated if not provided)").action(async (options) => {
+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) => parseInt(val, 10)).option("--host <host>", "Host to bind to (http/sse) or backend host for stdio-http", DEFAULT_HOST$1).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);
@@ -657,11 +543,163 @@ const mcpServeCommand = new commander.Command("mcp-serve").description("Start MC
 	} catch (error) {
 		const rawTransportType = options.type.toLowerCase();
 		const transportType = isValidTransportType(rawTransportType) ? rawTransportType : TRANSPORT_TYPE_STDIO;
-		console.error(formatStartError(transportType, options.host, options.port, error));
+		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));
 		process.exit(1);
 	}
 });
 
+//#endregion
+//#region src/commands/prestart-http.ts
+/**
+* Prestart HTTP Command
+*
+* Starts an mcp-proxy HTTP runtime in the background, waits until it is healthy,
+* and then exits so the runtime can be reused by other commands.
+*/
+const WORKSPACE_MARKERS = [
+	"pnpm-workspace.yaml",
+	"nx.json",
+	".git"
+];
+const DEFAULT_HOST = "localhost";
+const DEFAULT_TIMEOUT_MS = 12e4;
+const POLL_INTERVAL_MS = 250;
+function resolveWorkspaceRoot(startPath = process.cwd()) {
+	let current = node_path.default.resolve(startPath);
+	while (true) {
+		for (const marker of WORKSPACE_MARKERS) if ((0, node_fs.existsSync)(node_path.default.join(current, marker))) return current;
+		const parent = node_path.default.dirname(current);
+		if (parent === current) return process.cwd();
+		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);
+}
+function buildCliCandidates() {
+	const __filename$1 = (0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href);
+	const __dirname$1 = node_path.default.dirname(__filename$1);
+	const distCandidates = [
+		node_path.default.resolve(__dirname$1, "cli.mjs"),
+		node_path.default.resolve(__dirname$1, "..", "dist", "cli.mjs"),
+		node_path.default.resolve(__dirname$1, "..", "..", "dist", "cli.mjs")
+	];
+	const srcCandidates = [node_path.default.resolve(__dirname$1, "..", "cli.ts"), node_path.default.resolve(__dirname$1, "..", "..", "src", "cli.ts")];
+	for (const candidate of distCandidates) if ((0, node_fs.existsSync)(candidate)) return {
+		command: process.execPath,
+		args: [candidate]
+	};
+	for (const candidate of srcCandidates) if ((0, node_fs.existsSync)(candidate)) return {
+		command: process.execPath,
+		args: [
+			"--import",
+			"tsx",
+			candidate
+		]
+	};
+	throw new Error("Unable to locate mcp-proxy CLI entrypoint");
+}
+function parseTimeoutMs(value) {
+	if (!value) return DEFAULT_TIMEOUT_MS;
+	const parsed = Number.parseInt(value, 10);
+	if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`Invalid timeout value: ${value}`);
+	return parsed;
+}
+async function waitForFile(filePath, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		try {
+			await (0, node_fs_promises.access)(filePath);
+			return;
+		} catch {}
+		await new Promise((resolve$2) => setTimeout(resolve$2, POLL_INTERVAL_MS));
+	}
+	throw new Error(`Timed out waiting for runtime state file: ${filePath}`);
+}
+async function waitForHealthyRuntime(serverId, timeoutMs) {
+	const runtimeStateService = new require_src.RuntimeStateService();
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		const record = await runtimeStateService.read(serverId);
+		if (record) {
+			const healthUrl = `http://${record.host}:${record.port}/health`;
+			try {
+				const response = await fetch(healthUrl);
+				if (response.ok) {
+					const payload = await response.json().catch(() => null);
+					if (!payload || payload.transport === "http") return {
+						host: record.host,
+						port: record.port
+					};
+				}
+			} catch {}
+		}
+		await new Promise((resolve$2) => setTimeout(resolve$2, POLL_INTERVAL_MS));
+	}
+	throw new Error(`Timed out waiting for HTTP runtime '${serverId}' to become healthy`);
+}
+function spawnBackgroundRuntime(args, env) {
+	const { command, args: baseArgs } = buildCliCandidates();
+	const child = (0, node_child_process.spawn)(command, [...baseArgs, ...args], {
+		detached: true,
+		stdio: "ignore",
+		env
+	});
+	child.unref();
+	return child;
+}
+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).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) => {
+	const serverId = options.id || require_src.generateServerId();
+	const timeoutMs = parseTimeoutMs(options.timeoutMs);
+	const registryPath = options.registryPath || options.registryDir;
+	new require_src.RuntimeStateService();
+	const workspaceRoot = resolveWorkspaceRoot(process.cwd());
+	const childEnv = {
+		...process.env,
+		...registryPath ? {
+			PORT_REGISTRY_PATH: registryPath,
+			PROCESS_REGISTRY_PATH: resolveSiblingRegistryPath(registryPath, "processes.json")
+		} : {}
+	};
+	const child = spawnBackgroundRuntime([
+		"mcp-serve",
+		"--type",
+		"http",
+		"--id",
+		serverId,
+		"--host",
+		options.host || DEFAULT_HOST,
+		...options.port !== void 0 ? ["--port", String(options.port)] : [],
+		...options.config ? ["--config", options.config] : [],
+		...options.cache === false ? ["--no-cache"] : [],
+		...options.definitionsCache ? ["--definitions-cache", options.definitionsCache] : [],
+		...options.clearDefinitionsCache ? ["--clear-definitions-cache"] : [],
+		"--proxy-mode",
+		options.proxyMode
+	], childEnv);
+	const childExit = new Promise((_, reject) => {
+		child.once("exit", (code, signal) => {
+			reject(/* @__PURE__ */ new Error(`Background runtime exited before becoming healthy (code=${code ?? "null"}, signal=${signal ?? "null"})`));
+		});
+	});
+	const runtimeFile = node_path.default.join(require_src.RuntimeStateService.getDefaultRuntimeDir(), `${serverId}.runtime.json`);
+	try {
+		await Promise.race([waitForFile(runtimeFile, timeoutMs), childExit]);
+		const { host, port } = await Promise.race([waitForHealthyRuntime(serverId, timeoutMs), childExit]);
+		process.stdout.write(`mcp-proxy HTTP runtime ready at http://${host}:${port} (${serverId})\n`);
+		process.stdout.write(`runtimeId=${serverId}\n`);
+		process.stdout.write(`runtimeUrl=http://${host}:${port}\n`);
+		process.stdout.write(`workspaceRoot=${workspaceRoot}\n`);
+	} catch (error) {
+		throw new Error(`Failed to prestart HTTP runtime '${serverId}': ${error instanceof Error ? error.message : String(error)}`);
+	}
+});
+
 //#endregion
 //#region src/commands/bootstrap.ts
 function toErrorMessage$8(error) {
@@ -1490,6 +1528,7 @@ async function main() {
 		program.name("mcp-proxy").description("MCP proxy server package").version(require_src.version);
 		program.addCommand(initCommand);
 		program.addCommand(mcpServeCommand);
+		program.addCommand(prestartHttpCommand);
 		program.addCommand(searchToolsCommand);
 		program.addCommand(describeToolsCommand);
 		program.addCommand(useToolCommand);

package/dist/cli.mjs

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
-import { D as findConfigFile, E as generateServerId, T as DefinitionsCacheService, 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-DQ_MagA0.mjs";
+import { D as findConfigFile, E as generateServerId, T as DefinitionsCacheService, 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-0OJqEpGA.mjs";
 import { randomUUID } from "node:crypto";
 import { access, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
-import { constants } from "node:fs";
+import path, { join, resolve } from "node:path";
+import { constants, existsSync } from "node:fs";
 import { Liquid } from "liquidjs";
+import { spawn } from "node:child_process";
 import { Command } from "commander";
 import { ProcessRegistryService } from "@agimon-ai/foundation-process-registry";
-import { PortRegistryService } from "@agimon-ai/foundation-port-registry";
+import { DEFAULT_PORT_RANGE, PortRegistryService } from "@agimon-ai/foundation-port-registry";
+import { fileURLToPath } from "node:url";
 
 //#region src/utils/output.ts
 function writeLine(message = "") {
@@ -138,21 +140,16 @@ const CONFIG_FILE_NAMES = [
 	"mcp-config.json"
 ];
 const MCP_ENDPOINT_PATH = "/mcp";
-const DEFAULT_PORT = 3e3;
-const DEFAULT_HOST = "localhost";
+const DEFAULT_HOST$1 = "localhost";
 const TRANSPORT_TYPE_STDIO = "stdio";
 const TRANSPORT_TYPE_HTTP = "http";
 const TRANSPORT_TYPE_SSE = "sse";
 const TRANSPORT_TYPE_STDIO_HTTP = "stdio-http";
 const RUNTIME_TRANSPORT = TRANSPORT_TYPE_HTTP;
-const STDIO_HTTP_PROXY_STOP_LABEL = "Failed stopping stdio-http proxy";
-const INTERNAL_HTTP_STOP_LABEL = "Failed stopping internal HTTP transport";
 const PORT_REGISTRY_SERVICE_HTTP = "mcp-proxy-http";
-const PORT_REGISTRY_SERVICE_STDIO_HTTP = "mcp-proxy-stdio-http";
 const PORT_REGISTRY_SERVICE_TYPE = "service";
 const PORT_REGISTRY_REPOSITORY_PATH = process.cwd();
 const PROCESS_REGISTRY_SERVICE_HTTP = "mcp-proxy-http";
-const PROCESS_REGISTRY_SERVICE_STDIO_HTTP = "mcp-proxy-stdio-http";
 const PROCESS_REGISTRY_SERVICE_TYPE = "service";
 const PROCESS_REGISTRY_REPOSITORY_PATH = process.cwd();
 function toErrorMessage$9(error) {
@@ -164,13 +161,6 @@ function isValidTransportType(type) {
 function isValidProxyMode(mode) {
 	return mode === "meta" || mode === "flat" || mode === "search";
 }
-function isAddressInUseError(error) {
-	if (error instanceof Error && error.message.includes("EADDRINUSE")) return true;
-	if (typeof error !== "object" || error === null) return false;
-	if ("code" in error && error.code === "EADDRINUSE") return true;
-	if ("message" in error && typeof error.message === "string" && error.message.includes("EADDRINUSE")) return true;
-	return false;
-}
 async function pathExists(filePath) {
 	try {
 		await access(filePath, constants.F_OK);
@@ -218,10 +208,11 @@ function validateProxyMode(mode) {
 	if (!isValidProxyMode(mode)) throw new Error(`Unknown proxy mode: '${mode}'. Valid options: meta, flat, search`);
 }
 function createTransportConfig(options, mode) {
+	const envPort = process.env.MCP_PORT ? Number(process.env.MCP_PORT) : void 0;
 	return {
 		mode,
-		port: options.port || Number(process.env.MCP_PORT) || DEFAULT_PORT,
-		host: options.host || process.env.MCP_HOST || DEFAULT_HOST
+		port: options.port ?? (Number.isFinite(envPort) ? envPort : void 0),
+		host: options.host || process.env.MCP_HOST || DEFAULT_HOST$1
 	};
 }
 function createServerOptions(options, resolvedConfigPath, serverId) {
@@ -237,12 +228,12 @@ function createServerOptions(options, resolvedConfigPath, serverId) {
 function formatStartError(type, host, port, error) {
 	const startErrorMessage = toErrorMessage$9(error);
 	if (type === TRANSPORT_TYPE_STDIO) return `Failed to start MCP server with transport '${type}': ${startErrorMessage}`;
-	return `Failed to start MCP server with transport '${type}' on ${host}:${port}: ${startErrorMessage}`;
+	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,
+		host: config.host ?? DEFAULT_HOST$1,
 		port,
 		transport: RUNTIME_TRANSPORT,
 		shutdownToken,
@@ -260,7 +251,10 @@ function createProcessRegistryService() {
 function getRegistryEnvironment() {
 	return process.env.NODE_ENV ?? "development";
 }
-async function createPortRegistryLease(serviceName, host, preferredPort, serverId, transport, configPath) {
+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: PORT_REGISTRY_REPOSITORY_PATH,
@@ -270,10 +264,7 @@ async function createPortRegistryLease(serviceName, host, preferredPort, serverI
 		pid: process.pid,
 		host,
 		preferredPort,
-		portRange: {
-			min: preferredPort,
-			max: preferredPort
-		},
+		portRange,
 		force: true,
 		metadata: {
 			transport,
@@ -281,21 +272,27 @@ async function createPortRegistryLease(serviceName, host, preferredPort, serverI
 			...configPath ? { configPath } : {}
 		}
 	});
-	if (!result.success || !result.record) throw new Error(result.error || `Failed to reserve port ${preferredPort} in port registry`);
+	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 { release: async () => {
-		if (released) return;
-		released = true;
-		const releaseResult = await portRegistry.releasePort({
-			repositoryPath: PORT_REGISTRY_REPOSITORY_PATH,
-			serviceName,
-			serviceType: PORT_REGISTRY_SERVICE_TYPE,
-			pid: process.pid,
-			environment: getRegistryEnvironment(),
-			force: true
-		});
-		if (!releaseResult.success && releaseResult.error && !releaseResult.error.includes("No matching registry entry")) throw new Error(releaseResult.error || `Failed to release port for ${serviceName}`);
-	} };
+	return {
+		port: result.record.port,
+		release: async () => {
+			if (released) return;
+			released = true;
+			const releaseResult = await portRegistry.releasePort({
+				repositoryPath: PORT_REGISTRY_REPOSITORY_PATH,
+				serviceName,
+				serviceType: PORT_REGISTRY_SERVICE_TYPE,
+				pid: process.pid,
+				environment: getRegistryEnvironment(),
+				force: true
+			});
+			if (!releaseResult.success && releaseResult.error && !releaseResult.error.includes("No matching registry entry")) throw new Error(releaseResult.error || `Failed to release port for ${serviceName}`);
+		}
+	};
 }
 async function createProcessRegistryLease(serviceName, host, port, serverId, transport, configPath) {
 	const processRegistry = createProcessRegistryService();
@@ -387,27 +384,6 @@ async function cleanupFailedRuntimeStartup(handler, runtimeStateService, serverI
 		await removeRuntimeRecord(runtimeStateService, serverId);
 	}
 }
-async function stopTransportWithContext(label, stopOperation) {
-	try {
-		await stopOperation();
-	} catch (error) {
-		throw new Error(`${label}: ${toErrorMessage$9(error)}`);
-	}
-}
-async function removeRuntimeRecordDuringStop(runtimeStateService, serverId) {
-	try {
-		await removeRuntimeRecord(runtimeStateService, serverId);
-	} catch (error) {
-		throw new Error(`Failed to remove runtime state during HTTP stop callback for '${serverId}': ${toErrorMessage$9(error)}`);
-	}
-}
-function createStdioHttpInternalTransport(sharedServices, config, adminOptions) {
-	try {
-		return new HttpTransportHandler(() => createSessionServer(sharedServices), config, adminOptions);
-	} catch (error) {
-		throw new Error(`Failed to create internal HTTP transport for stdio-http proxy: ${toErrorMessage$9(error)}`);
-	}
-}
 /**
 * Start MCP server with given transport handler
 * @param handler - The transport handler to start
@@ -438,13 +414,23 @@ async function createAndStartHttpRuntime(serverOptions, config, resolvedConfigPa
 	const runtimeStateService = new RuntimeStateService();
 	const shutdownToken = randomUUID();
 	const runtimeServerId = serverOptions.serverId ?? generateServerId();
-	const processLease = await createProcessRegistryLease(PROCESS_REGISTRY_SERVICE_HTTP, config.host ?? DEFAULT_HOST, config.port ?? DEFAULT_PORT, runtimeServerId, TRANSPORT_TYPE_HTTP, resolvedConfigPath);
-	const portLease = await createPortRegistryLease(PORT_REGISTRY_SERVICE_HTTP, config.host ?? DEFAULT_HOST, config.port ?? DEFAULT_PORT, runtimeServerId, TRANSPORT_TYPE_HTTP, resolvedConfigPath);
+	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$1, requestedPort, runtimeServerId, TRANSPORT_TYPE_HTTP, resolvedConfigPath, portRange);
+	const runtimePort = portLease.port;
+	const runtimeConfig = {
+		...config,
+		port: runtimePort
+	};
+	const processLease = await createProcessRegistryLease(PROCESS_REGISTRY_SERVICE_HTTP, runtimeConfig.host ?? DEFAULT_HOST$1, runtimePort, runtimeServerId, TRANSPORT_TYPE_HTTP, resolvedConfigPath);
 	let releasePort = async () => {
-		await releasePortLease(portLease);
+		await releasePortLease(portLease ?? null);
 		releasePort = async () => void 0;
 	};
-	const runtimeRecord = createRuntimeRecord(runtimeServerId, config, config.port ?? DEFAULT_PORT, shutdownToken, resolvedConfigPath);
+	const runtimeRecord = createRuntimeRecord(runtimeServerId, runtimeConfig, runtimePort, shutdownToken, resolvedConfigPath);
 	let handler;
 	let isStopping = false;
 	const stopHandler = async () => {
@@ -460,7 +446,7 @@ async function createAndStartHttpRuntime(serverOptions, config, resolvedConfigPa
 		}
 	};
 	try {
-		handler = new HttpTransportHandler(() => createSessionServer(sharedServices), config, createHttpAdminOptions(runtimeRecord.serverId, shutdownToken, stopHandler));
+		handler = new HttpTransportHandler(() => createSessionServer(sharedServices), runtimeConfig, createHttpAdminOptions(runtimeRecord.serverId, shutdownToken, stopHandler));
 	} catch (error) {
 		await releasePort();
 		await processLease.release({
@@ -478,7 +464,7 @@ async function createAndStartHttpRuntime(serverOptions, config, resolvedConfigPa
 				kill: false,
 				releasePort: false
 			});
-			await removeRuntimeRecordDuringStop(runtimeStateService, runtimeRecord.serverId);
+			await removeRuntimeRecord(runtimeStateService, runtimeRecord.serverId);
 		});
 		await writeRuntimeRecord(runtimeStateService, runtimeRecord);
 	} catch (error) {
@@ -493,19 +479,6 @@ async function createAndStartHttpRuntime(serverOptions, config, resolvedConfigPa
 	}
 	console.error(`Runtime state: http://${runtimeRecord.host}:${runtimeRecord.port} (${runtimeRecord.serverId})`);
 }
-async function stopInternalHttpTransport(stdioHttpHandler, httpHandler, ownsInternalHttpTransport) {
-	try {
-		const stopOperations = [stopTransportWithContext(STDIO_HTTP_PROXY_STOP_LABEL, async () => {
-			await stdioHttpHandler.stop();
-		})];
-		if (ownsInternalHttpTransport && httpHandler) stopOperations.push(stopTransportWithContext(INTERNAL_HTTP_STOP_LABEL, async () => {
-			await httpHandler.stop();
-		}));
-		await Promise.all(stopOperations);
-	} catch (error) {
-		throw new Error(`Failed to stop stdio-http transport: ${toErrorMessage$9(error)}`);
-	}
-}
 async function startStdioTransport(serverOptions) {
 	try {
 		await startServer(new StdioTransportHandler(await createServer(serverOptions)));
@@ -520,109 +493,21 @@ async function startSseTransport(serverOptions, config) {
 		throw new Error(`Failed to start SSE transport: ${toErrorMessage$9(error)}`);
 	}
 }
-async function startStdioHttpTransport(serverOptions, config, resolvedConfigPath) {
-	const shared = { services: null };
-	let processLease;
-	let internalPortLease = null;
+async function resolveStdioHttpEndpoint(config) {
+	if (config.port !== void 0) return new URL(`http://${config.host ?? DEFAULT_HOST$1}:${config.port}${MCP_ENDPOINT_PATH}`);
+	const result = await createPortRegistryService().getPort({
+		repositoryPath: PORT_REGISTRY_REPOSITORY_PATH,
+		serviceName: PORT_REGISTRY_SERVICE_HTTP,
+		serviceType: PORT_REGISTRY_SERVICE_TYPE,
+		environment: getRegistryEnvironment()
+	});
+	if (!result.success || !result.record) throw new Error(result.error || "No prestarted HTTP backend found for stdio-http transport");
+	return new URL(`http://${config.host ?? result.record.host}:${result.record.port}${MCP_ENDPOINT_PATH}`);
+}
+async function startStdioHttpTransport(config) {
 	try {
-		const stdioHttpHandler = new StdioHttpTransportHandler({ endpoint: new URL(`http://${config.host}:${config.port}${MCP_ENDPOINT_PATH}`) });
-		const runtimeStateService = new RuntimeStateService();
-		const serverId = serverOptions.serverId ?? generateServerId();
-		const shutdownToken = randomUUID();
-		processLease = await createProcessRegistryLease(PROCESS_REGISTRY_SERVICE_STDIO_HTTP, config.host ?? DEFAULT_HOST, config.port ?? DEFAULT_PORT, serverId, TRANSPORT_TYPE_STDIO_HTTP, resolvedConfigPath);
-		let httpHandler = null;
-		let ownsInternalHttpTransport = false;
-		let isStopping = false;
-		let releaseInternalPort = async () => {
-			await releasePortLease(internalPortLease);
-			internalPortLease = null;
-			releaseInternalPort = async () => void 0;
-		};
-		const stopOwnedRuntime = async () => {
-			if (isStopping) return;
-			isStopping = true;
-			try {
-				await Promise.all([stopInternalHttpTransport(stdioHttpHandler, httpHandler, ownsInternalHttpTransport), removeRuntimeRecord(runtimeStateService, serverId)]);
-				await releaseInternalPort();
-				if (shared.services) await shared.services.dispose();
-				ownsInternalHttpTransport = false;
-				process.exit(0);
-			} catch (error) {
-				console.error(`Unexpected error during admin shutdown: ${toErrorMessage$9(error)}`);
-				process.exit(1);
-			}
-		};
-		const adminOptions = createHttpAdminOptions(serverId, shutdownToken, stopOwnedRuntime);
-		await startServer({
-			async start() {
-				let initialProxyConnectError;
-				try {
-					await stdioHttpHandler.start();
-					return;
-				} catch (error) {
-					initialProxyConnectError = error;
-				}
-				if (!shared.services) shared.services = await initializeSharedServices(serverOptions);
-				try {
-					internalPortLease = await createPortRegistryLease(PORT_REGISTRY_SERVICE_STDIO_HTTP, config.host ?? DEFAULT_HOST, config.port ?? DEFAULT_PORT, serverId, TRANSPORT_TYPE_STDIO_HTTP, resolvedConfigPath);
-					httpHandler = createStdioHttpInternalTransport(shared.services, config, adminOptions);
-					await httpHandler.start();
-					ownsInternalHttpTransport = true;
-				} catch (error) {
-					if (!isAddressInUseError(error)) {
-						await releaseInternalPort();
-						throw new Error(`Failed to start internal HTTP transport for stdio-http proxy: ${toErrorMessage$9(error)}`);
-					}
-				}
-				try {
-					await stdioHttpHandler.start();
-				} catch (error) {
-					let rollbackStopErrorMessage = "";
-					if (ownsInternalHttpTransport && httpHandler) {
-						try {
-							await httpHandler.stop();
-						} catch (stopError) {
-							rollbackStopErrorMessage = toErrorMessage$9(stopError);
-						}
-						ownsInternalHttpTransport = false;
-					}
-					await releaseInternalPort();
-					const retryErrorMessage = toErrorMessage$9(error);
-					const initialErrorMessage = toErrorMessage$9(initialProxyConnectError);
-					const rollbackMessage = rollbackStopErrorMessage ? `; rollback stop failed: ${rollbackStopErrorMessage}` : "";
-					throw new Error(`Failed to start stdio-http proxy bridge: initial connect failed (${initialErrorMessage}); retry failed (${retryErrorMessage})${rollbackMessage}`);
-				}
-				if (ownsInternalHttpTransport) try {
-					await writeRuntimeRecord(runtimeStateService, createRuntimeRecord(serverId, config, config.port ?? DEFAULT_PORT, shutdownToken, resolvedConfigPath));
-				} catch (error) {
-					throw new Error(`Failed to persist runtime state for stdio-http server '${serverId}': ${toErrorMessage$9(error)}`);
-				}
-			},
-			async stop() {
-				try {
-					await Promise.all([stopInternalHttpTransport(stdioHttpHandler, httpHandler, ownsInternalHttpTransport), removeRuntimeRecord(runtimeStateService, serverId)]);
-					await releaseInternalPort();
-					await processLease?.release({
-						kill: false,
-						releasePort: false
-					});
-					ownsInternalHttpTransport = false;
-					if (shared.services) await shared.services.dispose();
-				} catch (error) {
-					ownsInternalHttpTransport = false;
-					throw new Error(`Failed during stdio-http shutdown for '${serverId}': ${toErrorMessage$9(error)}`);
-				}
-			}
-		});
+		await startServer(new StdioHttpTransportHandler({ endpoint: await resolveStdioHttpEndpoint(config) }));
 	} catch (error) {
-		try {
-			await releasePortLease(internalPortLease);
-			await processLease?.release({
-				kill: false,
-				releasePort: false
-			});
-		} catch {}
-		if (shared.services) await shared.services.dispose();
 		throw new Error(`Failed to start stdio-http transport: ${toErrorMessage$9(error)}`);
 	}
 }
@@ -640,7 +525,7 @@ async function startTransport(transportType, options, resolvedConfigPath, server
 			await startSseTransport(serverOptions, createTransportConfig(options, TRANSPORT_MODE.SSE));
 			return;
 		}
-		await startStdioHttpTransport(serverOptions, createTransportConfig(options, TRANSPORT_MODE.HTTP), resolvedConfigPath);
+		await startStdioHttpTransport(createTransportConfig(options, TRANSPORT_MODE.HTTP));
 	} catch (error) {
 		throw new Error(`Failed to start transport '${transportType}': ${toErrorMessage$9(error)}`);
 	}
@@ -648,7 +533,7 @@ 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/stdio-http internal HTTP)", (val) => parseInt(val, 10), DEFAULT_PORT).option("--host <host>", "Host to bind to (http/sse/stdio-http internal HTTP)", DEFAULT_HOST).option("-c, --config <path>", "Path to MCP server configuration file").option("--no-cache", "Disable configuration caching, always reload from config file").option("--definitions-cache <path>", "Path to prefetched tool/prompt/skill definitions cache file").option("--clear-definitions-cache", "Delete definitions cache before startup", false).option("--proxy-mode <mode>", "How mcp-proxy exposes downstream tools: meta, flat, or search", "meta").option("--id <id>", "Unique server identifier (overrides config file id, auto-generated if not provided)").action(async (options) => {
+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) => parseInt(val, 10)).option("--host <host>", "Host to bind to (http/sse) or backend host for stdio-http", DEFAULT_HOST$1).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);
@@ -657,11 +542,163 @@ const mcpServeCommand = new Command("mcp-serve").description("Start MCP server w
 	} catch (error) {
 		const rawTransportType = options.type.toLowerCase();
 		const transportType = isValidTransportType(rawTransportType) ? rawTransportType : TRANSPORT_TYPE_STDIO;
-		console.error(formatStartError(transportType, options.host, options.port, error));
+		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));
 		process.exit(1);
 	}
 });
 
+//#endregion
+//#region src/commands/prestart-http.ts
+/**
+* Prestart HTTP Command
+*
+* Starts an mcp-proxy HTTP runtime in the background, waits until it is healthy,
+* and then exits so the runtime can be reused by other commands.
+*/
+const WORKSPACE_MARKERS = [
+	"pnpm-workspace.yaml",
+	"nx.json",
+	".git"
+];
+const DEFAULT_HOST = "localhost";
+const DEFAULT_TIMEOUT_MS = 12e4;
+const POLL_INTERVAL_MS = 250;
+function resolveWorkspaceRoot(startPath = process.cwd()) {
+	let current = path.resolve(startPath);
+	while (true) {
+		for (const marker of WORKSPACE_MARKERS) if (existsSync(path.join(current, marker))) return current;
+		const parent = path.dirname(current);
+		if (parent === current) return process.cwd();
+		current = parent;
+	}
+}
+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);
+	const distCandidates = [
+		path.resolve(__dirname, "cli.mjs"),
+		path.resolve(__dirname, "..", "dist", "cli.mjs"),
+		path.resolve(__dirname, "..", "..", "dist", "cli.mjs")
+	];
+	const srcCandidates = [path.resolve(__dirname, "..", "cli.ts"), path.resolve(__dirname, "..", "..", "src", "cli.ts")];
+	for (const candidate of distCandidates) if (existsSync(candidate)) return {
+		command: process.execPath,
+		args: [candidate]
+	};
+	for (const candidate of srcCandidates) if (existsSync(candidate)) return {
+		command: process.execPath,
+		args: [
+			"--import",
+			"tsx",
+			candidate
+		]
+	};
+	throw new Error("Unable to locate mcp-proxy CLI entrypoint");
+}
+function parseTimeoutMs(value) {
+	if (!value) return DEFAULT_TIMEOUT_MS;
+	const parsed = Number.parseInt(value, 10);
+	if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`Invalid timeout value: ${value}`);
+	return parsed;
+}
+async function waitForFile(filePath, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		try {
+			await access(filePath);
+			return;
+		} catch {}
+		await new Promise((resolve$1) => setTimeout(resolve$1, POLL_INTERVAL_MS));
+	}
+	throw new Error(`Timed out waiting for runtime state file: ${filePath}`);
+}
+async function waitForHealthyRuntime(serverId, timeoutMs) {
+	const runtimeStateService = new RuntimeStateService();
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		const record = await runtimeStateService.read(serverId);
+		if (record) {
+			const healthUrl = `http://${record.host}:${record.port}/health`;
+			try {
+				const response = await fetch(healthUrl);
+				if (response.ok) {
+					const payload = await response.json().catch(() => null);
+					if (!payload || payload.transport === "http") return {
+						host: record.host,
+						port: record.port
+					};
+				}
+			} catch {}
+		}
+		await new Promise((resolve$1) => setTimeout(resolve$1, POLL_INTERVAL_MS));
+	}
+	throw new Error(`Timed out waiting for HTTP runtime '${serverId}' to become healthy`);
+}
+function spawnBackgroundRuntime(args, env) {
+	const { command, args: baseArgs } = buildCliCandidates();
+	const child = spawn(command, [...baseArgs, ...args], {
+		detached: true,
+		stdio: "ignore",
+		env
+	});
+	child.unref();
+	return child;
+}
+const prestartHttpCommand = new 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).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) => {
+	const serverId = options.id || generateServerId();
+	const timeoutMs = parseTimeoutMs(options.timeoutMs);
+	const registryPath = options.registryPath || options.registryDir;
+	new RuntimeStateService();
+	const workspaceRoot = resolveWorkspaceRoot(process.cwd());
+	const childEnv = {
+		...process.env,
+		...registryPath ? {
+			PORT_REGISTRY_PATH: registryPath,
+			PROCESS_REGISTRY_PATH: resolveSiblingRegistryPath(registryPath, "processes.json")
+		} : {}
+	};
+	const child = spawnBackgroundRuntime([
+		"mcp-serve",
+		"--type",
+		"http",
+		"--id",
+		serverId,
+		"--host",
+		options.host || DEFAULT_HOST,
+		...options.port !== void 0 ? ["--port", String(options.port)] : [],
+		...options.config ? ["--config", options.config] : [],
+		...options.cache === false ? ["--no-cache"] : [],
+		...options.definitionsCache ? ["--definitions-cache", options.definitionsCache] : [],
+		...options.clearDefinitionsCache ? ["--clear-definitions-cache"] : [],
+		"--proxy-mode",
+		options.proxyMode
+	], childEnv);
+	const childExit = new Promise((_, reject) => {
+		child.once("exit", (code, signal) => {
+			reject(/* @__PURE__ */ new Error(`Background runtime exited before becoming healthy (code=${code ?? "null"}, signal=${signal ?? "null"})`));
+		});
+	});
+	const runtimeFile = path.join(RuntimeStateService.getDefaultRuntimeDir(), `${serverId}.runtime.json`);
+	try {
+		await Promise.race([waitForFile(runtimeFile, timeoutMs), childExit]);
+		const { host, port } = await Promise.race([waitForHealthyRuntime(serverId, timeoutMs), childExit]);
+		process.stdout.write(`mcp-proxy HTTP runtime ready at http://${host}:${port} (${serverId})\n`);
+		process.stdout.write(`runtimeId=${serverId}\n`);
+		process.stdout.write(`runtimeUrl=http://${host}:${port}\n`);
+		process.stdout.write(`workspaceRoot=${workspaceRoot}\n`);
+	} catch (error) {
+		throw new Error(`Failed to prestart HTTP runtime '${serverId}': ${error instanceof Error ? error.message : String(error)}`);
+	}
+});
+
 //#endregion
 //#region src/commands/bootstrap.ts
 function toErrorMessage$8(error) {
@@ -1490,6 +1527,7 @@ async function main() {
 		program.name("mcp-proxy").description("MCP proxy server package").version(version);
 		program.addCommand(initCommand);
 		program.addCommand(mcpServeCommand);
+		program.addCommand(prestartHttpCommand);
 		program.addCommand(searchToolsCommand);
 		program.addCommand(describeToolsCommand);
 		program.addCommand(useToolCommand);

package/dist/index.cjs

@@ -1,4 +1,4 @@
-const require_src = require('./src-6KF7hZTe.cjs');
+const require_src = require('./src-G1hs2GLZ.cjs');
 
 exports.ConfigFetcherService = require_src.ConfigFetcherService;
 exports.DefinitionsCacheService = require_src.DefinitionsCacheService;

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { C as SearchListToolsTool, D as findConfigFile, E as generateServerId, S as UseToolTool, T as DefinitionsCacheService, _ as StopServerService, a as createProxyContainer, b as createProxyLogger, c as createStdioHttpTransportHandler, f as StdioHttpTransportHandler, g as SkillService, h as HttpTransportHandler, i as createHttpTransportHandler, l as createStdioTransportHandler, m as SseTransportHandler, n as createServer, p as StdioTransportHandler, r as createSessionServer, s as createSseTransportHandler, t as TRANSPORT_MODE, u as initializeSharedServices, v as RuntimeStateService, w as DescribeToolsTool, x as ConfigFetcherService, y as McpClientManagerService } from "./src-DQ_MagA0.mjs";
+import { C as SearchListToolsTool, D as findConfigFile, E as generateServerId, S as UseToolTool, T as DefinitionsCacheService, _ as StopServerService, a as createProxyContainer, b as createProxyLogger, c as createStdioHttpTransportHandler, f as StdioHttpTransportHandler, g as SkillService, h as HttpTransportHandler, i as createHttpTransportHandler, l as createStdioTransportHandler, m as SseTransportHandler, n as createServer, p as StdioTransportHandler, r as createSessionServer, s as createSseTransportHandler, t as TRANSPORT_MODE, u as initializeSharedServices, v as RuntimeStateService, w as DescribeToolsTool, x as ConfigFetcherService, y as McpClientManagerService } from "./src-0OJqEpGA.mjs";
 
 export { ConfigFetcherService, DefinitionsCacheService, DescribeToolsTool, HttpTransportHandler, McpClientManagerService, RuntimeStateService, SearchListToolsTool, SkillService, SseTransportHandler, StdioHttpTransportHandler, StdioTransportHandler, StopServerService, TRANSPORT_MODE, UseToolTool, createHttpTransportHandler, createProxyContainer, createProxyLogger, createServer, createSessionServer, createSseTransportHandler, createStdioHttpTransportHandler, createStdioTransportHandler, findConfigFile, generateServerId, initializeSharedServices };

package/dist/{src-DQ_MagA0.mjs → src-0OJqEpGA.mjs}

@@ -2758,9 +2758,9 @@ function isShutdownResponse(value) {
 * @param path - Request path to append
 * @returns Full runtime URL
 */
-function buildRuntimeUrl(runtime, path) {
+function buildRuntimeUrl(runtime, path$1) {
 	if (!ALLOWED_HOSTS.has(runtime.host)) throw new Error(`Refusing to connect to non-loopback host '${runtime.host}'. Only ${Array.from(ALLOWED_HOSTS).join(", ")} are allowed.`);
-	return `${HTTP_PROTOCOL}${runtime.host}${URL_PORT_SEPARATOR}${runtime.port}${path}`;
+	return `${HTTP_PROTOCOL}${runtime.host}${URL_PORT_SEPARATOR}${runtime.port}${path$1}`;
 }
 function toErrorMessage$1(error) {
 	return error instanceof Error ? error.message : String(error);
@@ -2938,13 +2938,13 @@ var SkillLoadError = class extends Error {
 * @returns true if path exists, false otherwise
 * @throws Error for unexpected filesystem errors (permission denied, etc.)
 */
-async function pathExists(path) {
+async function pathExists(path$1) {
 	try {
-		await access(path);
+		await access(path$1);
 		return true;
 	} catch (error) {
 		if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
-		throw new Error(`Failed to check path existence for "${path}": ${error instanceof Error ? error.message : "Unknown error"}`);
+		throw new Error(`Failed to check path existence for "${path$1}": ${error instanceof Error ? error.message : "Unknown error"}`);
 	}
 }
 /**
@@ -4313,7 +4313,7 @@ var StdioHttpTransportHandler = class {
 
 //#endregion
 //#region package.json
-var version = "0.3.19";
+var version = "0.4.2";
 
 //#endregion
 //#region src/container/index.ts

package/dist/{src-6KF7hZTe.cjs → src-G1hs2GLZ.cjs}

@@ -4342,7 +4342,7 @@ var StdioHttpTransportHandler = class {
 
 //#endregion
 //#region package.json
-var version = "0.3.19";
+var version = "0.4.2";
 
 //#endregion
 //#region src/container/index.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agimon-ai/mcp-proxy",
   "description": "MCP proxy server package",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "license": "AGPL-3.0",
   "keywords": [
     "mcp",
@@ -27,9 +27,9 @@
     "js-yaml": "^4.1.0",
     "liquidjs": "^10.21.0",
     "zod": "^3.24.1",
-    "@agimon-ai/foundation-process-registry": "0.2.1",
-    "@agimon-ai/foundation-port-registry": "0.2.5",
-    "@agimon-ai/log-sink-mcp": "0.2.5"
+    "@agimon-ai/foundation-process-registry": "0.2.3",
+    "@agimon-ai/foundation-port-registry": "0.2.7",
+    "@agimon-ai/log-sink-mcp": "0.2.7"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",