@agimon-ai/mcp-proxy 0.4.0 → 0.4.2

package/dist/cli.cjs

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
-const require_src = require('./src-6KF7hZTe.cjs');
+const require_src = require('./src-Cm2AVRBA.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 = "") {
@@ -139,7 +142,7 @@ const CONFIG_FILE_NAMES = [
 ];
 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";
@@ -218,10 +221,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) ?? DEFAULT_PORT,
+		host: options.host || process.env.MCP_HOST || DEFAULT_HOST$1
 	};
 }
 function createServerOptions(options, resolvedConfigPath, serverId) {
@@ -242,7 +246,7 @@ function formatStartError(type, host, port, error) {
 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 +264,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 = {
+	min: preferredPort,
+	max: preferredPort
+}) {
 	const portRegistry = createPortRegistryService();
 	const result = await portRegistry.reservePort({
 		repositoryPath: PORT_REGISTRY_REPOSITORY_PATH,
@@ -270,10 +277,7 @@ async function createPortRegistryLease(serviceName, host, preferredPort, serverI
 		pid: process.pid,
 		host,
 		preferredPort,
-		portRange: {
-			min: preferredPort,
-			max: preferredPort
-		},
+		portRange,
 		force: true,
 		metadata: {
 			transport,
@@ -283,19 +287,22 @@ async function createPortRegistryLease(serviceName, host, preferredPort, serverI
 	});
 	if (!result.success || !result.record) throw new Error(result.error || `Failed to reserve port ${preferredPort} in port registry`);
 	let released = false;
-	return { release: async () => {
-		if (released) return;
-		released = true;
-		const releaseResult = await portRegistry.releasePort({
-			repositoryPath: PORT_REGISTRY_REPOSITORY_PATH,
-			serviceName,
-			serviceType: PORT_REGISTRY_SERVICE_TYPE,
-			pid: process.pid,
-			environment: getRegistryEnvironment(),
-			force: true
-		});
-		if (!releaseResult.success && releaseResult.error && !releaseResult.error.includes("No matching registry entry")) throw new Error(releaseResult.error || `Failed to release port for ${serviceName}`);
-	} };
+	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();
@@ -438,13 +445,14 @@ 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 runtimePort = config.port ?? DEFAULT_PORT;
+	const processLease = await createProcessRegistryLease(PROCESS_REGISTRY_SERVICE_HTTP, config.host ?? DEFAULT_HOST$1, runtimePort, runtimeServerId, TRANSPORT_TYPE_HTTP, resolvedConfigPath);
+	const portLease = await createPortRegistryLease(PORT_REGISTRY_SERVICE_HTTP, config.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, config, runtimePort, shutdownToken, resolvedConfigPath);
 	let handler;
 	let isStopping = false;
 	const stopHandler = async () => {
@@ -520,30 +528,37 @@ async function startSseTransport(serverOptions, config) {
 		throw new Error(`Failed to start SSE transport: ${toErrorMessage$9(error)}`);
 	}
 }
-async function startStdioHttpTransport(serverOptions, config, resolvedConfigPath) {
+async function startStdioHttpTransport(serverOptions, config, resolvedConfigPath, options) {
 	const shared = { services: null };
 	let processLease;
-	let internalPortLease = null;
+	let portLease;
 	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 envPort = process.env.MCP_PORT ? Number(process.env.MCP_PORT) : void 0;
+		const requestedPort = options.port ?? (Number.isFinite(envPort) ? envPort : void 0) ?? DEFAULT_PORT;
+		const portRange = options.port !== void 0 || Number.isFinite(envPort) ? {
+			min: requestedPort,
+			max: requestedPort
+		} : __agimon_ai_foundation_port_registry.DEFAULT_PORT_RANGE;
+		portLease = await createPortRegistryLease(PORT_REGISTRY_SERVICE_STDIO_HTTP, config.host ?? DEFAULT_HOST$1, requestedPort, serverId, TRANSPORT_TYPE_STDIO_HTTP, resolvedConfigPath, portRange);
+		const internalPort = portLease.port;
+		const transportConfig = {
+			...config,
+			port: internalPort
+		};
+		const stdioHttpHandler = new require_src.StdioHttpTransportHandler({ endpoint: new URL(`http://${transportConfig.host}:${transportConfig.port}${MCP_ENDPOINT_PATH}`) });
+		const runtimeStateService = new require_src.RuntimeStateService();
 		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);
+		processLease = await createProcessRegistryLease(PROCESS_REGISTRY_SERVICE_STDIO_HTTP, transportConfig.host ?? DEFAULT_HOST$1, internalPort, 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();
+				await releasePortLease(portLease ?? null);
 				if (shared.services) await shared.services.dispose();
 				ownsInternalHttpTransport = false;
 				process.exit(0);
@@ -564,15 +579,11 @@ async function startStdioHttpTransport(serverOptions, config, resolvedConfigPath
 				}
 				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);
+					httpHandler = createStdioHttpInternalTransport(shared.services, transportConfig, 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)}`);
-					}
+					if (!isAddressInUseError(error)) throw new Error(`Failed to start internal HTTP transport for stdio-http proxy: ${toErrorMessage$9(error)}`);
 				}
 				try {
 					await stdioHttpHandler.start();
@@ -586,14 +597,13 @@ async function startStdioHttpTransport(serverOptions, config, resolvedConfigPath
 						}
 						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));
+					await writeRuntimeRecord(runtimeStateService, createRuntimeRecord(serverId, transportConfig, internalPort, shutdownToken, resolvedConfigPath));
 				} catch (error) {
 					throw new Error(`Failed to persist runtime state for stdio-http server '${serverId}': ${toErrorMessage$9(error)}`);
 				}
@@ -601,7 +611,7 @@ async function startStdioHttpTransport(serverOptions, config, resolvedConfigPath
 			async stop() {
 				try {
 					await Promise.all([stopInternalHttpTransport(stdioHttpHandler, httpHandler, ownsInternalHttpTransport), removeRuntimeRecord(runtimeStateService, serverId)]);
-					await releaseInternalPort();
+					await releasePortLease(portLease ?? null);
 					await processLease?.release({
 						kill: false,
 						releasePort: false
@@ -616,7 +626,7 @@ async function startStdioHttpTransport(serverOptions, config, resolvedConfigPath
 		});
 	} catch (error) {
 		try {
-			await releasePortLease(internalPortLease);
+			await portLease?.release();
 			await processLease?.release({
 				kill: false,
 				releasePort: false
@@ -640,7 +650,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(serverOptions, createTransportConfig(options, require_src.TRANSPORT_MODE.HTTP), resolvedConfigPath, options);
 	} catch (error) {
 		throw new Error(`Failed to start transport '${transportType}': ${toErrorMessage$9(error)}`);
 	}
@@ -648,7 +658,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/stdio-http internal HTTP)", (val) => parseInt(val, 10)).option("--host <host>", "Host to bind to (http/sse/stdio-http internal 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 +667,161 @@ 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));
+		console.error(formatStartError(transportType, options.host, options.port ?? DEFAULT_PORT, 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 +1650,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-CNXwWpA2.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 = "") {
@@ -139,7 +141,7 @@ const CONFIG_FILE_NAMES = [
 ];
 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";
@@ -218,10 +220,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) ?? DEFAULT_PORT,
+		host: options.host || process.env.MCP_HOST || DEFAULT_HOST$1
 	};
 }
 function createServerOptions(options, resolvedConfigPath, serverId) {
@@ -242,7 +245,7 @@ function formatStartError(type, host, port, error) {
 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 +263,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 = {
+	min: preferredPort,
+	max: preferredPort
+}) {
 	const portRegistry = createPortRegistryService();
 	const result = await portRegistry.reservePort({
 		repositoryPath: PORT_REGISTRY_REPOSITORY_PATH,
@@ -270,10 +276,7 @@ async function createPortRegistryLease(serviceName, host, preferredPort, serverI
 		pid: process.pid,
 		host,
 		preferredPort,
-		portRange: {
-			min: preferredPort,
-			max: preferredPort
-		},
+		portRange,
 		force: true,
 		metadata: {
 			transport,
@@ -283,19 +286,22 @@ async function createPortRegistryLease(serviceName, host, preferredPort, serverI
 	});
 	if (!result.success || !result.record) throw new Error(result.error || `Failed to reserve port ${preferredPort} in port registry`);
 	let released = false;
-	return { release: async () => {
-		if (released) return;
-		released = true;
-		const releaseResult = await portRegistry.releasePort({
-			repositoryPath: PORT_REGISTRY_REPOSITORY_PATH,
-			serviceName,
-			serviceType: PORT_REGISTRY_SERVICE_TYPE,
-			pid: process.pid,
-			environment: getRegistryEnvironment(),
-			force: true
-		});
-		if (!releaseResult.success && releaseResult.error && !releaseResult.error.includes("No matching registry entry")) throw new Error(releaseResult.error || `Failed to release port for ${serviceName}`);
-	} };
+	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();
@@ -438,13 +444,14 @@ 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 runtimePort = config.port ?? DEFAULT_PORT;
+	const processLease = await createProcessRegistryLease(PROCESS_REGISTRY_SERVICE_HTTP, config.host ?? DEFAULT_HOST$1, runtimePort, runtimeServerId, TRANSPORT_TYPE_HTTP, resolvedConfigPath);
+	const portLease = await createPortRegistryLease(PORT_REGISTRY_SERVICE_HTTP, config.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, config, runtimePort, shutdownToken, resolvedConfigPath);
 	let handler;
 	let isStopping = false;
 	const stopHandler = async () => {
@@ -520,30 +527,37 @@ async function startSseTransport(serverOptions, config) {
 		throw new Error(`Failed to start SSE transport: ${toErrorMessage$9(error)}`);
 	}
 }
-async function startStdioHttpTransport(serverOptions, config, resolvedConfigPath) {
+async function startStdioHttpTransport(serverOptions, config, resolvedConfigPath, options) {
 	const shared = { services: null };
 	let processLease;
-	let internalPortLease = null;
+	let portLease;
 	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 envPort = process.env.MCP_PORT ? Number(process.env.MCP_PORT) : void 0;
+		const requestedPort = options.port ?? (Number.isFinite(envPort) ? envPort : void 0) ?? DEFAULT_PORT;
+		const portRange = options.port !== void 0 || Number.isFinite(envPort) ? {
+			min: requestedPort,
+			max: requestedPort
+		} : DEFAULT_PORT_RANGE;
+		portLease = await createPortRegistryLease(PORT_REGISTRY_SERVICE_STDIO_HTTP, config.host ?? DEFAULT_HOST$1, requestedPort, serverId, TRANSPORT_TYPE_STDIO_HTTP, resolvedConfigPath, portRange);
+		const internalPort = portLease.port;
+		const transportConfig = {
+			...config,
+			port: internalPort
+		};
+		const stdioHttpHandler = new StdioHttpTransportHandler({ endpoint: new URL(`http://${transportConfig.host}:${transportConfig.port}${MCP_ENDPOINT_PATH}`) });
+		const runtimeStateService = new RuntimeStateService();
 		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);
+		processLease = await createProcessRegistryLease(PROCESS_REGISTRY_SERVICE_STDIO_HTTP, transportConfig.host ?? DEFAULT_HOST$1, internalPort, 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();
+				await releasePortLease(portLease ?? null);
 				if (shared.services) await shared.services.dispose();
 				ownsInternalHttpTransport = false;
 				process.exit(0);
@@ -564,15 +578,11 @@ async function startStdioHttpTransport(serverOptions, config, resolvedConfigPath
 				}
 				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);
+					httpHandler = createStdioHttpInternalTransport(shared.services, transportConfig, 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)}`);
-					}
+					if (!isAddressInUseError(error)) throw new Error(`Failed to start internal HTTP transport for stdio-http proxy: ${toErrorMessage$9(error)}`);
 				}
 				try {
 					await stdioHttpHandler.start();
@@ -586,14 +596,13 @@ async function startStdioHttpTransport(serverOptions, config, resolvedConfigPath
 						}
 						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));
+					await writeRuntimeRecord(runtimeStateService, createRuntimeRecord(serverId, transportConfig, internalPort, shutdownToken, resolvedConfigPath));
 				} catch (error) {
 					throw new Error(`Failed to persist runtime state for stdio-http server '${serverId}': ${toErrorMessage$9(error)}`);
 				}
@@ -601,7 +610,7 @@ async function startStdioHttpTransport(serverOptions, config, resolvedConfigPath
 			async stop() {
 				try {
 					await Promise.all([stopInternalHttpTransport(stdioHttpHandler, httpHandler, ownsInternalHttpTransport), removeRuntimeRecord(runtimeStateService, serverId)]);
-					await releaseInternalPort();
+					await releasePortLease(portLease ?? null);
 					await processLease?.release({
 						kill: false,
 						releasePort: false
@@ -616,7 +625,7 @@ async function startStdioHttpTransport(serverOptions, config, resolvedConfigPath
 		});
 	} catch (error) {
 		try {
-			await releasePortLease(internalPortLease);
+			await portLease?.release();
 			await processLease?.release({
 				kill: false,
 				releasePort: false
@@ -640,7 +649,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(serverOptions, createTransportConfig(options, TRANSPORT_MODE.HTTP), resolvedConfigPath, options);
 	} catch (error) {
 		throw new Error(`Failed to start transport '${transportType}': ${toErrorMessage$9(error)}`);
 	}
@@ -648,7 +657,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/stdio-http internal HTTP)", (val) => parseInt(val, 10)).option("--host <host>", "Host to bind to (http/sse/stdio-http internal 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 +666,161 @@ 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));
+		console.error(formatStartError(transportType, options.host, options.port ?? DEFAULT_PORT, 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 +1649,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-Cm2AVRBA.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-CNXwWpA2.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-CNXwWpA2.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.1";
 
 //#endregion
 //#region src/container/index.ts

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

@@ -4342,7 +4342,7 @@ var StdioHttpTransportHandler = class {
 
 //#endregion
 //#region package.json
-var version = "0.3.19";
+var version = "0.4.1";
 
 //#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.0",
+  "version": "0.4.2",
   "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.0",
-    "@agimon-ai/foundation-port-registry": "0.2.4",
-    "@agimon-ai/log-sink-mcp": "0.2.5"
+    "@agimon-ai/foundation-port-registry": "0.2.6",
+    "@agimon-ai/log-sink-mcp": "0.2.6",
+    "@agimon-ai/foundation-process-registry": "0.2.2"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",