@agimon-ai/mcp-proxy 0.8.0 → 0.9.1

package/dist/{src-dZuRf3Wt.cjs → src-ElP1ds81.cjs}

@@ -20,14 +20,11 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-let _agimon_ai_foundation_validator = require("@agimon-ai/foundation-validator");
-let _modelcontextprotocol_sdk_server_index_js = require("@modelcontextprotocol/sdk/server/index.js");
-let _modelcontextprotocol_sdk_types_js = require("@modelcontextprotocol/sdk/types.js");
-let zod = require("zod");
 let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
 let js_yaml = require("js-yaml");
 js_yaml = __toESM(js_yaml);
+let zod = require("zod");
 let node_crypto = require("node:crypto");
 let node_os = require("node:os");
 let node_path = require("node:path");
@@ -38,16 +35,19 @@ let _modelcontextprotocol_sdk_client_stdio_js = require("@modelcontextprotocol/s
 let _modelcontextprotocol_sdk_client_streamableHttp_js = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
 let node_child_process = require("node:child_process");
 let liquidjs = require("liquidjs");
+let _agimon_ai_foundation_validator = require("@agimon-ai/foundation-validator");
 let node_events = require("node:events");
 let node_http = require("node:http");
 let node_util = require("node:util");
 let _hono_node_server = require("@hono/node-server");
 let _modelcontextprotocol_sdk_server_streamableHttp_js = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+let _modelcontextprotocol_sdk_types_js = require("@modelcontextprotocol/sdk/types.js");
 let hono = require("hono");
 let _modelcontextprotocol_sdk_server_sse_js = require("@modelcontextprotocol/sdk/server/sse.js");
 let _modelcontextprotocol_sdk_server_stdio_js = require("@modelcontextprotocol/sdk/server/stdio.js");
+let _modelcontextprotocol_sdk_server_index_js = require("@modelcontextprotocol/sdk/server/index.js");
 //#region package.json
-var version = "0.7.3";
+var version = "0.9.0";
 //#endregion
 //#region src/utils/mcpConfigSchema.ts
 /**
@@ -966,25 +966,68 @@ function findConfigFile() {
 	return null;
 }
 //#endregion
-//#region src/utils/parseToolName.ts
+//#region src/utils/generateServerId.ts
 /**
-* Parse tool name to extract server and actual tool name
-* Supports both plain tool names and prefixed format: {serverName}__{toolName}
+* generateServerId Utilities
 *
-* @param toolName - The tool name to parse (e.g., "my_tool" or "server__my_tool")
-* @returns Parsed result with optional serverName and actualToolName
+* DESIGN PATTERNS:
+* - Pure functions with no side effects
+* - Single responsibility per function
+* - Functional programming approach
+*
+* CODING STANDARDS:
+* - Export individual functions, not classes
+* - Use descriptive function names with verbs
+* - Add JSDoc comments for complex logic
+* - Keep functions small and focused
+*
+* AVOID:
+* - Side effects (mutating external state)
+* - Stateful logic (use services for state)
+* - Complex external dependencies
+*/
+/**
+* Character set for generating human-readable IDs.
+* Excludes confusing characters: 0, O, 1, l, I
+*/
+const CHARSET = "23456789abcdefghjkmnpqrstuvwxyz";
+/**
+* Default length for generated server IDs (6 characters)
+*/
+const DEFAULT_ID_LENGTH = 6;
+/**
+* Generate a short, human-readable server ID.
+*
+* Uses Node.js crypto.randomBytes for cryptographically secure randomness
+* with rejection sampling to avoid modulo bias.
+*
+* The generated ID:
+* - Is 6 characters long by default
+* - Uses only lowercase alphanumeric characters
+* - Excludes confusing characters (0, O, 1, l, I)
+*
+* @param length - Length of the ID to generate (default: 6)
+* @returns A random, human-readable ID
 *
 * @example
-* parseToolName("my_tool") // { actualToolName: "my_tool" }
-* parseToolName("server__my_tool") // { serverName: "server", actualToolName: "my_tool" }
+* generateServerId() // "abc234"
+* generateServerId(4) // "x7mn"
 */
-function parseToolName(toolName) {
-	const separatorIndex = toolName.indexOf("__");
-	if (separatorIndex > 0) return {
-		serverName: toolName.substring(0, separatorIndex),
-		actualToolName: toolName.substring(separatorIndex + 2)
-	};
-	return { actualToolName: toolName };
+function generateServerId(length = DEFAULT_ID_LENGTH) {
+	const charsetLength = 31;
+	const maxUnbiased = Math.floor(256 / charsetLength) * charsetLength - 1;
+	let result = "";
+	let remaining = length;
+	while (remaining > 0) {
+		const bytes = (0, node_crypto.randomBytes)(remaining);
+		for (let i = 0; i < bytes.length && remaining > 0; i++) {
+			const byte = bytes[i];
+			if (byte > maxUnbiased) continue;
+			result += CHARSET[byte % charsetLength];
+			remaining--;
+		}
+	}
+	return result;
 }
 //#endregion
 //#region src/utils/parseFrontMatter.ts
@@ -1120,68 +1163,25 @@ function extractSkillFrontMatter(content) {
 	return null;
 }
 //#endregion
-//#region src/utils/generateServerId.ts
-/**
-* generateServerId Utilities
-*
-* DESIGN PATTERNS:
-* - Pure functions with no side effects
-* - Single responsibility per function
-* - Functional programming approach
-*
-* CODING STANDARDS:
-* - Export individual functions, not classes
-* - Use descriptive function names with verbs
-* - Add JSDoc comments for complex logic
-* - Keep functions small and focused
-*
-* AVOID:
-* - Side effects (mutating external state)
-* - Stateful logic (use services for state)
-* - Complex external dependencies
-*/
-/**
-* Character set for generating human-readable IDs.
-* Excludes confusing characters: 0, O, 1, l, I
-*/
-const CHARSET = "23456789abcdefghjkmnpqrstuvwxyz";
-/**
-* Default length for generated server IDs (6 characters)
-*/
-const DEFAULT_ID_LENGTH = 6;
+//#region src/utils/parseToolName.ts
 /**
-* Generate a short, human-readable server ID.
-*
-* Uses Node.js crypto.randomBytes for cryptographically secure randomness
-* with rejection sampling to avoid modulo bias.
-*
-* The generated ID:
-* - Is 6 characters long by default
-* - Uses only lowercase alphanumeric characters
-* - Excludes confusing characters (0, O, 1, l, I)
+* Parse tool name to extract server and actual tool name
+* Supports both plain tool names and prefixed format: {serverName}__{toolName}
 *
-* @param length - Length of the ID to generate (default: 6)
-* @returns A random, human-readable ID
+* @param toolName - The tool name to parse (e.g., "my_tool" or "server__my_tool")
+* @returns Parsed result with optional serverName and actualToolName
 *
 * @example
-* generateServerId() // "abc234"
-* generateServerId(4) // "x7mn"
+* parseToolName("my_tool") // { actualToolName: "my_tool" }
+* parseToolName("server__my_tool") // { serverName: "server", actualToolName: "my_tool" }
 */
-function generateServerId(length = DEFAULT_ID_LENGTH) {
-	const charsetLength = 31;
-	const maxUnbiased = Math.floor(256 / charsetLength) * charsetLength - 1;
-	let result = "";
-	let remaining = length;
-	while (remaining > 0) {
-		const bytes = (0, node_crypto.randomBytes)(remaining);
-		for (let i = 0; i < bytes.length && remaining > 0; i++) {
-			const byte = bytes[i];
-			if (byte > maxUnbiased) continue;
-			result += CHARSET[byte % charsetLength];
-			remaining--;
-		}
-	}
-	return result;
+function parseToolName(toolName) {
+	const separatorIndex = toolName.indexOf("__");
+	if (separatorIndex > 0) return {
+		serverName: toolName.substring(0, separatorIndex),
+		actualToolName: toolName.substring(separatorIndex + 2)
+	};
+	return { actualToolName: toolName };
 }
 //#endregion
 //#region src/services/DefinitionsCacheService.ts
@@ -1894,304 +1894,440 @@ var McpClientManagerService = class {
 		return this.clients.has(serverName);
 	}
 };
+/** pnpx command name (pnpm's npx equivalent) */
+const COMMAND_PNPX = "pnpx";
+/** pnpm command name */
+const COMMAND_PNPM = "pnpm";
+/** Tool subcommand for uv */
+const ARG_TOOL = "tool";
+/** Install subcommand for uv tool and npm/pnpm */
+const ARG_INSTALL = "install";
+/**
+* Regex pattern for valid package names (npm, pnpm, uvx, uv)
+* Allows: @scope/package-name@version, package-name, package_name
+* Prevents shell metacharacters that could enable command injection
+* @example
+* // Valid: '@scope/package@1.0.0', 'my-package', 'my_package', '@org/pkg'
+* // Invalid: 'pkg; rm -rf /', 'pkg$(cmd)', 'pkg`whoami`', 'pkg|cat /etc/passwd'
+*/
+const VALID_PACKAGE_NAME_PATTERN = /^(@[a-zA-Z0-9_-]+\/)?[a-zA-Z0-9._-]+(@[a-zA-Z0-9._-]+)?$/;
+/** Windows platform identifier */
+const PLATFORM_WIN32 = "win32";
+/** Stdio option to ignore stream */
+const STDIO_IGNORE = "ignore";
+/** Stdio option to pipe stream */
+const STDIO_PIPE = "pipe";
 //#endregion
-//#region src/services/RuntimeStateService.ts
+//#region src/services/PrefetchService/PrefetchService.ts
 /**
-* RuntimeStateService
+* PrefetchService
 *
-* Persists runtime metadata for HTTP mcp-proxy instances so external commands
-* (for example `mcp-proxy stop`) can discover and target the correct server.
+* DESIGN PATTERNS:
+* - Service pattern for business logic encapsulation
+* - Single responsibility principle
+*
+* CODING STANDARDS:
+* - Use async/await for asynchronous operations
+* - Throw descriptive errors for error cases
+* - Keep methods focused and well-named
+* - Document complex logic with comments
+*
+* AVOID:
+* - Mixing concerns (keep focused on single domain)
+* - Direct tool implementation (services should be tool-agnostic)
 */
-const RUNTIME_DIR_NAME = "runtimes";
-const RUNTIME_FILE_SUFFIX = ".runtime.json";
-function isObject(value) {
-	return typeof value === "object" && value !== null;
-}
-function isRuntimeStateRecord(value) {
-	if (!isObject(value)) return false;
-	return typeof value.serverId === "string" && typeof value.host === "string" && typeof value.port === "number" && value.transport === "http" && typeof value.shutdownToken === "string" && typeof value.startedAt === "string" && typeof value.pid === "number" && (value.configPath === void 0 || typeof value.configPath === "string");
-}
-function toErrorMessage$2(error) {
-	return error instanceof Error ? error.message : String(error);
+/**
+* Type guard to check if a config object is an McpStdioConfig
+* @param config - Config object to check
+* @returns True if config has required McpStdioConfig properties
+*/
+function isMcpStdioConfig(config) {
+	return typeof config === "object" && config !== null && "command" in config;
 }
 /**
-* Runtime state persistence implementation.
+* PrefetchService handles pre-downloading packages used by MCP servers.
+* Supports npx (Node.js), uvx (Python/uv), and uv run commands.
+*
+* @example
+* ```typescript
+* const service = new PrefetchService({
+*   mcpConfig: await configFetcher.fetchConfiguration(),
+*   parallel: true,
+* });
+* const packages = service.extractPackages();
+* const summary = await service.prefetch();
+* ```
 */
-var RuntimeStateService = class RuntimeStateService {
-	runtimeDir;
-	logger;
-	constructor(runtimeDir, logger = console) {
-		this.runtimeDir = runtimeDir ?? RuntimeStateService.getDefaultRuntimeDir();
-		this.logger = logger;
-	}
-	/**
-	* Resolve default runtime directory under the user's home cache path.
-	* @returns Absolute runtime directory path
-	*/
-	static getDefaultRuntimeDir() {
-		return (0, node_path.join)((0, node_os.homedir)(), ".aicode-toolkit", "mcp-proxy", RUNTIME_DIR_NAME);
-	}
+var PrefetchService = class {
+	config;
 	/**
-	* Build runtime state file path for a given server ID.
-	* @param serverId - Target mcp-proxy server identifier
-	* @returns Absolute runtime file path
+	* Creates a new PrefetchService instance
+	* @param config - Service configuration options
 	*/
-	getRecordPath(serverId) {
-		return (0, node_path.join)(this.runtimeDir, `${serverId}${RUNTIME_FILE_SUFFIX}`);
+	constructor(config) {
+		this.config = config;
 	}
 	/**
-	* Persist a runtime state record.
-	* @param record - Runtime metadata to persist
-	* @returns Promise that resolves when write completes
+	* Extract all prefetchable packages from the MCP configuration
+	* @returns Array of package info objects
 	*/
-	async write(record) {
-		await (0, node_fs_promises.mkdir)(this.runtimeDir, { recursive: true });
-		await (0, node_fs_promises.writeFile)(this.getRecordPath(record.serverId), JSON.stringify(record, null, 2), "utf-8");
+	extractPackages() {
+		const packages = [];
+		const { mcpConfig, filter } = this.config;
+		for (const [serverName, serverConfig] of Object.entries(mcpConfig.mcpServers)) {
+			if (serverConfig.disabled) continue;
+			if (serverConfig.transport !== "stdio") continue;
+			if (!isMcpStdioConfig(serverConfig.config)) continue;
+			const packageInfo = this.extractPackageInfo(serverName, serverConfig.config);
+			if (packageInfo) {
+				if (filter && packageInfo.packageManager !== filter) continue;
+				packages.push(packageInfo);
+			}
+		}
+		return packages;
 	}
 	/**
-	* Read a runtime state record by server ID.
-	* @param serverId - Target mcp-proxy server identifier
-	* @returns Matching runtime record, or null when no record exists
+	* Prefetch all packages from the configuration
+	* @returns Summary of prefetch results
+	* @throws Error if prefetch operation fails unexpectedly
 	*/
-	async read(serverId) {
-		const filePath = this.getRecordPath(serverId);
+	async prefetch() {
 		try {
-			const content = await (0, node_fs_promises.readFile)(filePath, "utf-8");
-			const parsed = JSON.parse(content);
-			return isRuntimeStateRecord(parsed) ? parsed : null;
+			const packages = this.extractPackages();
+			const results = [];
+			if (packages.length === 0) return {
+				totalPackages: 0,
+				successful: 0,
+				failed: 0,
+				results: []
+			};
+			if (this.config.parallel) {
+				const promises = packages.map(async (pkg) => this.prefetchPackage(pkg));
+				results.push(...await Promise.all(promises));
+			} else for (const pkg of packages) {
+				const result = await this.prefetchPackage(pkg);
+				results.push(result);
+			}
+			const successful = results.filter((r) => r.success).length;
+			const failed = results.filter((r) => !r.success).length;
+			return {
+				totalPackages: packages.length,
+				successful,
+				failed,
+				results
+			};
 		} catch (error) {
-			if (isObject(error) && "code" in error && error.code === "ENOENT") return null;
-			throw new Error(`Failed to read runtime state for server '${serverId}' from '${filePath}': ${toErrorMessage$2(error)}`);
+			throw new Error(`Failed to prefetch packages: ${error instanceof Error ? error.message : String(error)}`);
 		}
 	}
 	/**
-	* List all persisted runtime records.
-	* @returns Array of runtime records
+	* Prefetch a single package
+	* @param pkg - Package info to prefetch
+	* @returns Result of the prefetch operation
 	*/
-	async list() {
+	async prefetchPackage(pkg) {
 		try {
-			const files = (await (0, node_fs_promises.readdir)(this.runtimeDir, { withFileTypes: true })).filter((entry) => entry.isFile() && entry.name.endsWith(RUNTIME_FILE_SUFFIX));
-			return (await Promise.all(files.map(async (file) => {
-				try {
-					const content = await (0, node_fs_promises.readFile)((0, node_path.join)(this.runtimeDir, file.name), "utf-8");
-					const parsed = JSON.parse(content);
-					return isRuntimeStateRecord(parsed) ? parsed : null;
-				} catch (error) {
-					this.logger.debug(`Skipping unreadable runtime state file ${file.name}`, error);
-					return null;
-				}
-			}))).filter((record) => record !== null);
+			const [command, ...args] = pkg.fullCommand;
+			const result = await this.runCommand(command, args);
+			return {
+				package: pkg,
+				success: result.success,
+				output: result.output
+			};
 		} catch (error) {
-			if (isObject(error) && "code" in error && error.code === "ENOENT") return [];
-			throw new Error(`Failed to list runtime states from '${this.runtimeDir}': ${toErrorMessage$2(error)}`);
+			return {
+				package: pkg,
+				success: false,
+				output: error instanceof Error ? error.message : String(error)
+			};
 		}
 	}
 	/**
-	* Remove a runtime state record by server ID.
-	* @param serverId - Target mcp-proxy server identifier
-	* @returns Promise that resolves when delete completes
+	* Validate package name to prevent command injection
+	* @param packageName - Package name to validate
+	* @returns True if package name is safe, false otherwise
+	* @remarks Rejects package names containing shell metacharacters
+	* @example
+	* isValidPackageName('@scope/package') // true
+	* isValidPackageName('my-package@1.0.0') // true
+	* isValidPackageName('pkg; rm -rf /') // false (shell injection)
+	* isValidPackageName('pkg$(whoami)') // false (command substitution)
 	*/
-	async remove(serverId) {
-		await (0, node_fs_promises.rm)(this.getRecordPath(serverId), { force: true });
+	isValidPackageName(packageName) {
+		return VALID_PACKAGE_NAME_PATTERN.test(packageName);
+	}
+	/**
+	* Extract package info from a server's stdio config
+	* @param serverName - Name of the MCP server
+	* @param config - Stdio configuration for the server
+	* @returns Package info if extractable, null otherwise
+	*/
+	extractPackageInfo(serverName, config) {
+		const command = config.command.toLowerCase();
+		const args = config.args || [];
+		if (command === "npx" || command.endsWith("/npx")) {
+			const packageName = this.extractNpxPackage(args);
+			if (packageName && this.isValidPackageName(packageName)) return {
+				serverName,
+				packageManager: "npx",
+				packageName,
+				fullCommand: [
+					"npm",
+					ARG_INSTALL,
+					"-g",
+					packageName
+				]
+			};
+		}
+		if (command === "pnpx" || command.endsWith("/pnpx")) {
+			const packageName = this.extractNpxPackage(args);
+			if (packageName && this.isValidPackageName(packageName)) return {
+				serverName,
+				packageManager: COMMAND_PNPX,
+				packageName,
+				fullCommand: [
+					COMMAND_PNPM,
+					"add",
+					"-g",
+					packageName
+				]
+			};
+		}
+		if (command === "uvx" || command.endsWith("/uvx")) {
+			const packageName = this.extractUvxPackage(args);
+			if (packageName && this.isValidPackageName(packageName)) return {
+				serverName,
+				packageManager: "uvx",
+				packageName,
+				fullCommand: ["uvx", packageName]
+			};
+		}
+		if ((command === "uv" || command.endsWith("/uv")) && args.includes("run")) {
+			const packageName = this.extractUvRunPackage(args);
+			if (packageName && this.isValidPackageName(packageName)) return {
+				serverName,
+				packageManager: "uv",
+				packageName,
+				fullCommand: [
+					"uv",
+					ARG_TOOL,
+					ARG_INSTALL,
+					packageName
+				]
+			};
+		}
+		return null;
+	}
+	/**
+	* Extract package name from npx command args
+	* @param args - Command arguments
+	* @returns Package name or null
+	* @remarks Handles --package=value, --package value, -p value patterns.
+	*          Falls back to first non-flag argument if no --package/-p flag found.
+	*          Returns null if flag has no value or is followed by another flag.
+	*          When multiple --package flags exist, returns the first valid one.
+	* @example
+	* extractNpxPackage(['--package=@scope/pkg']) // returns '@scope/pkg'
+	* extractNpxPackage(['--package', 'pkg-name']) // returns 'pkg-name'
+	* extractNpxPackage(['-p', 'pkg']) // returns 'pkg'
+	* extractNpxPackage(['-y', 'pkg-name', '--flag']) // returns 'pkg-name' (fallback)
+	* extractNpxPackage(['--package=']) // returns null (empty value)
+	*/
+	extractNpxPackage(args) {
+		for (let i = 0; i < args.length; i++) {
+			const arg = args[i];
+			if (arg.startsWith("--package=")) return arg.slice(10) || null;
+			if (arg === "--package" && i + 1 < args.length) {
+				const nextArg = args[i + 1];
+				if (!nextArg.startsWith("-")) return nextArg;
+			}
+			if (arg === "-p" && i + 1 < args.length) {
+				const nextArg = args[i + 1];
+				if (!nextArg.startsWith("-")) return nextArg;
+			}
+		}
+		for (const arg of args) {
+			if (arg.startsWith("-")) continue;
+			return arg;
+		}
+		return null;
+	}
+	/**
+	* Extract package name from uvx command args
+	* @param args - Command arguments
+	* @returns Package name or null
+	* @remarks Assumes the first non-flag argument is the package name.
+	*          Handles both single (-) and double (--) dash flags.
+	* @example
+	* extractUvxPackage(['mcp-server-fetch']) // returns 'mcp-server-fetch'
+	* extractUvxPackage(['--quiet', 'pkg-name']) // returns 'pkg-name'
+	*/
+	extractUvxPackage(args) {
+		for (const arg of args) {
+			if (arg.startsWith("-")) continue;
+			return arg;
+		}
+		return null;
+	}
+	/**
+	* Extract package name from uv run command args
+	* @param args - Command arguments
+	* @returns Package name or null
+	* @remarks Looks for the first non-flag argument after the 'run' subcommand.
+	*          Returns null if 'run' is not found in args.
+	* @example
+	* extractUvRunPackage(['run', 'mcp-server']) // returns 'mcp-server'
+	* extractUvRunPackage(['run', '--verbose', 'pkg']) // returns 'pkg'
+	* extractUvRunPackage(['install', 'pkg']) // returns null (no 'run')
+	*/
+	extractUvRunPackage(args) {
+		const runIndex = args.indexOf("run");
+		if (runIndex === -1) return null;
+		for (let i = runIndex + 1; i < args.length; i++) {
+			const arg = args[i];
+			if (arg.startsWith("-")) continue;
+			return arg;
+		}
+		return null;
+	}
+	/**
+	* Run a shell command and capture output
+	* @param command - Command to run
+	* @param args - Command arguments
+	* @returns Promise with success status and output
+	*/
+	runCommand(command, args) {
+		return new Promise((resolve) => {
+			const proc = (0, node_child_process.spawn)(command, args, {
+				stdio: [
+					STDIO_IGNORE,
+					STDIO_PIPE,
+					STDIO_PIPE
+				],
+				shell: process.platform === PLATFORM_WIN32
+			});
+			let stdout = "";
+			let stderr = "";
+			proc.stdout?.on("data", (data) => {
+				stdout += data.toString();
+			});
+			proc.stderr?.on("data", (data) => {
+				stderr += data.toString();
+			});
+			proc.on("close", (code) => {
+				resolve({
+					success: code === 0,
+					output: stdout || stderr
+				});
+			});
+			proc.on("error", (error) => {
+				resolve({
+					success: false,
+					output: error.message
+				});
+			});
+		});
 	}
 };
-/** Path for the runtime health check endpoint. */
-const HEALTH_CHECK_PATH = "/health";
-/** Path for the authenticated admin shutdown endpoint. */
-const ADMIN_SHUTDOWN_PATH = "/admin/shutdown";
-/** HTTP POST method identifier. */
-const HTTP_METHOD_POST = "POST";
-/** HTTP header name for bearer token authorization. */
-const AUTHORIZATION_HEADER_NAME = "Authorization";
-/** Prefix for bearer token values in the Authorization header. */
-const BEARER_TOKEN_PREFIX = "Bearer ";
-/** HTTP protocol scheme prefix for URL construction. */
-const HTTP_PROTOCOL = "http://";
-/** Hosts that are safe to send admin requests to (loopback only). */
-const ALLOWED_HOSTS = new Set([
-	"localhost",
-	"127.0.0.1",
-	"::1"
-]);
 //#endregion
-//#region src/services/StopServerService/types.ts
-/**
-* Safely cast a non-null object to a string-keyed record for property access.
-* @param value - Object value already verified as non-null
-* @returns The same value typed as a record
-*/
-function toRecord(value) {
-	return value;
-}
-/**
-* Type guard for health responses.
-* @param value - Candidate payload to validate
-* @returns True when payload matches health response shape
-*/
-function isHealthResponse(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const record = toRecord(value);
-	return "status" in record && record["status"] === "ok" && "transport" in record && record["transport"] === "http" && (!("serverId" in record) || record["serverId"] === void 0 || typeof record["serverId"] === "string");
-}
+//#region src/services/RuntimeStateService.ts
 /**
-* Type guard for shutdown responses.
-* @param value - Candidate payload to validate
-* @returns True when payload matches shutdown response shape
+* RuntimeStateService
+*
+* Persists runtime metadata for HTTP mcp-proxy instances so external commands
+* (for example `mcp-proxy stop`) can discover and target the correct server.
 */
-function isShutdownResponse(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const record = toRecord(value);
-	return "ok" in record && typeof record["ok"] === "boolean" && "message" in record && typeof record["message"] === "string" && (!("serverId" in record) || record["serverId"] === void 0 || typeof record["serverId"] === "string");
+const RUNTIME_DIR_NAME = "runtimes";
+const RUNTIME_FILE_SUFFIX = ".runtime.json";
+function isObject(value) {
+	return typeof value === "object" && value !== null;
 }
-//#endregion
-//#region src/services/StopServerService/StopServerService.ts
-/**
-* Format runtime endpoint URL after validating the host is a loopback address.
-* Rejects non-loopback hosts to prevent SSRF via tampered runtime state files.
-* @param runtime - Runtime record to format
-* @param path - Request path to append
-* @returns Full runtime URL
-*/
-function buildRuntimeUrl(runtime, path) {
-	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}:${runtime.port}${path}`;
+function isRuntimeStateRecord(value) {
+	if (!isObject(value)) return false;
+	return typeof value.serverId === "string" && typeof value.host === "string" && typeof value.port === "number" && value.transport === "http" && typeof value.shutdownToken === "string" && typeof value.startedAt === "string" && typeof value.pid === "number" && (value.configPath === void 0 || typeof value.configPath === "string");
 }
-function toErrorMessage$1(error) {
+function toErrorMessage$2(error) {
 	return error instanceof Error ? error.message : String(error);
 }
-function sleep(delayMs) {
-	return new Promise((resolve) => {
-		setTimeout(resolve, delayMs);
-	});
-}
 /**
-* Service for resolving runtime targets and stopping them safely.
+* Runtime state persistence implementation.
 */
-var StopServerService = class {
-	runtimeStateService;
+var RuntimeStateService = class RuntimeStateService {
+	runtimeDir;
 	logger;
-	constructor(runtimeStateService = new RuntimeStateService(), logger = console) {
-		this.runtimeStateService = runtimeStateService;
+	constructor(runtimeDir, logger = console) {
+		this.runtimeDir = runtimeDir ?? RuntimeStateService.getDefaultRuntimeDir();
 		this.logger = logger;
 	}
 	/**
-	* Resolve a target runtime and stop it cooperatively.
-	* @param request - Stop request options
-	* @returns Stop result payload
+	* Resolve default runtime directory under the user's home cache path.
+	* @returns Absolute runtime directory path
 	*/
-	async stop(request) {
-		const timeoutMs = request.timeoutMs ?? 5e3;
-		const runtime = await this.resolveRuntime(request);
-		const health = await this.fetchHealth(runtime, timeoutMs);
-		if (!health.reachable) {
-			await this.runtimeStateService.remove(runtime.serverId);
-			throw new Error(`Runtime '${runtime.serverId}' is not reachable at http://${runtime.host}:${runtime.port}. Removed stale runtime record.`);
-		}
-		if (!request.force && health.payload?.serverId && health.payload.serverId !== runtime.serverId) throw new Error(`Refusing to stop runtime at http://${runtime.host}:${runtime.port}: expected server ID '${runtime.serverId}' but health endpoint reported '${health.payload.serverId}'. Use --force to override.`);
-		const shutdownToken = request.token ?? runtime.shutdownToken;
-		if (!shutdownToken) throw new Error(`No shutdown token available for runtime '${runtime.serverId}'.`);
-		const shutdownResponse = await this.requestShutdown(runtime, shutdownToken, timeoutMs);
-		await this.waitForShutdown(runtime, timeoutMs);
-		await this.runtimeStateService.remove(runtime.serverId);
-		return {
-			ok: true,
-			serverId: runtime.serverId,
-			host: runtime.host,
-			port: runtime.port,
-			message: shutdownResponse.message
-		};
+	static getDefaultRuntimeDir() {
+		return (0, node_path.join)((0, node_os.homedir)(), ".aicode-toolkit", "mcp-proxy", RUNTIME_DIR_NAME);
 	}
 	/**
-	* Resolve a runtime record from explicit ID or a unique host/port pair.
-	* @param request - Stop request options
-	* @returns Matching runtime record
+	* Build runtime state file path for a given server ID.
+	* @param serverId - Target mcp-proxy server identifier
+	* @returns Absolute runtime file path
 	*/
-	async resolveRuntime(request) {
-		if (request.serverId) {
-			const runtime = await this.runtimeStateService.read(request.serverId);
-			if (!runtime) throw new Error(`No runtime record found for server ID '${request.serverId}'. Start the server with 'mcp-proxy mcp-serve --type http' first.`);
-			return runtime;
-		}
-		if (request.host === void 0 || request.port === void 0) throw new Error("Provide --id or both --host and --port to select a runtime.");
-		const matches = (await this.runtimeStateService.list()).filter((runtime) => runtime.host === request.host && runtime.port === request.port);
-		if (matches.length === 0) throw new Error(`No runtime record found for http://${request.host}:${request.port}. Start the server with 'mcp-proxy mcp-serve --type http' first.`);
-		if (matches.length > 1) throw new Error(`Multiple runtime records match http://${request.host}:${request.port}. Retry with --id to avoid stopping the wrong server.`);
-		return matches[0];
+	getRecordPath(serverId) {
+		return (0, node_path.join)(this.runtimeDir, `${serverId}${RUNTIME_FILE_SUFFIX}`);
 	}
 	/**
-	* Read the runtime health payload.
-	* @param runtime - Runtime to query
-	* @param timeoutMs - Request timeout in milliseconds
-	* @returns Reachability status and optional payload
+	* Persist a runtime state record.
+	* @param record - Runtime metadata to persist
+	* @returns Promise that resolves when write completes
 	*/
-	async fetchHealth(runtime, timeoutMs) {
-		try {
-			const response = await this.fetchWithTimeout(buildRuntimeUrl(runtime, HEALTH_CHECK_PATH), { method: "GET" }, timeoutMs);
-			if (!response.ok) return { reachable: false };
-			const payload = await response.json();
-			if (!isHealthResponse(payload)) throw new Error("Received invalid health response payload.");
-			return {
-				reachable: true,
-				payload
-			};
-		} catch (error) {
-			this.logger.debug(`Health check failed for ${runtime.serverId}`, error);
-			return { reachable: false };
-		}
+	async write(record) {
+		await (0, node_fs_promises.mkdir)(this.runtimeDir, { recursive: true });
+		await (0, node_fs_promises.writeFile)(this.getRecordPath(record.serverId), JSON.stringify(record, null, 2), "utf-8");
 	}
 	/**
-	* Send authenticated shutdown request to the admin endpoint.
-	* @param runtime - Runtime to stop
-	* @param shutdownToken - Bearer token for the admin endpoint
-	* @param timeoutMs - Request timeout in milliseconds
-	* @returns Parsed shutdown response payload
+	* Read a runtime state record by server ID.
+	* @param serverId - Target mcp-proxy server identifier
+	* @returns Matching runtime record, or null when no record exists
 	*/
-	async requestShutdown(runtime, shutdownToken, timeoutMs) {
-		const response = await this.fetchWithTimeout(buildRuntimeUrl(runtime, ADMIN_SHUTDOWN_PATH), {
-			method: HTTP_METHOD_POST,
-			headers: { [AUTHORIZATION_HEADER_NAME]: `${BEARER_TOKEN_PREFIX}${shutdownToken}` }
-		}, timeoutMs);
-		const payload = await response.json();
-		if (!isShutdownResponse(payload)) throw new Error("Received invalid shutdown response payload.");
-		if (!response.ok || !payload.ok) throw new Error(payload.message);
-		return payload;
+	async read(serverId) {
+		const filePath = this.getRecordPath(serverId);
+		try {
+			const content = await (0, node_fs_promises.readFile)(filePath, "utf-8");
+			const parsed = JSON.parse(content);
+			return isRuntimeStateRecord(parsed) ? parsed : null;
+		} catch (error) {
+			if (isObject(error) && "code" in error && error.code === "ENOENT") return null;
+			throw new Error(`Failed to read runtime state for server '${serverId}' from '${filePath}': ${toErrorMessage$2(error)}`);
+		}
 	}
 	/**
-	* Poll until the target runtime is no longer reachable.
-	* @param runtime - Runtime expected to stop
-	* @param timeoutMs - Maximum wait time in milliseconds
-	* @returns Promise that resolves when shutdown is observed
+	* List all persisted runtime records.
+	* @returns Array of runtime records
 	*/
-	async waitForShutdown(runtime, timeoutMs) {
-		const deadline = Date.now() + timeoutMs;
-		while (Date.now() < deadline) {
-			if (!(await this.fetchHealth(runtime, Math.max(250, deadline - Date.now()))).reachable) return;
-			await sleep(200);
+	async list() {
+		try {
+			const files = (await (0, node_fs_promises.readdir)(this.runtimeDir, { withFileTypes: true })).filter((entry) => entry.isFile() && entry.name.endsWith(RUNTIME_FILE_SUFFIX));
+			return (await Promise.all(files.map(async (file) => {
+				try {
+					const content = await (0, node_fs_promises.readFile)((0, node_path.join)(this.runtimeDir, file.name), "utf-8");
+					const parsed = JSON.parse(content);
+					return isRuntimeStateRecord(parsed) ? parsed : null;
+				} catch (error) {
+					this.logger.debug(`Skipping unreadable runtime state file ${file.name}`, error);
+					return null;
+				}
+			}))).filter((record) => record !== null);
+		} catch (error) {
+			if (isObject(error) && "code" in error && error.code === "ENOENT") return [];
+			throw new Error(`Failed to list runtime states from '${this.runtimeDir}': ${toErrorMessage$2(error)}`);
 		}
-		throw new Error(`Timed out waiting for runtime '${runtime.serverId}' to stop at http://${runtime.host}:${runtime.port}.`);
 	}
 	/**
-	* Perform a fetch with an abort timeout.
-	* @param url - Target URL
-	* @param init - Fetch options
-	* @param timeoutMs - Timeout in milliseconds
-	* @returns Fetch response
+	* Remove a runtime state record by server ID.
+	* @param serverId - Target mcp-proxy server identifier
+	* @returns Promise that resolves when delete completes
 	*/
-	async fetchWithTimeout(url, init, timeoutMs) {
-		const controller = new AbortController();
-		const timeoutId = setTimeout(() => {
-			controller.abort();
-		}, timeoutMs);
-		try {
-			return await fetch(url, {
-				...init,
-				signal: controller.signal
-			});
-		} catch (error) {
-			throw new Error(`Request to '${url}' failed: ${toErrorMessage$1(error)}`);
-		} finally {
-			clearTimeout(timeoutId);
-		}
+	async remove(serverId) {
+		await (0, node_fs_promises.rm)(this.getRecordPath(serverId), { force: true });
 	}
 };
 //#endregion
@@ -2550,339 +2686,203 @@ var SkillService = class {
 		};
 	}
 };
-/** pnpx command name (pnpm's npx equivalent) */
-const COMMAND_PNPX = "pnpx";
-/** pnpm command name */
-const COMMAND_PNPM = "pnpm";
-/** Tool subcommand for uv */
-const ARG_TOOL = "tool";
-/** Install subcommand for uv tool and npm/pnpm */
-const ARG_INSTALL = "install";
+/** Path for the runtime health check endpoint. */
+const HEALTH_CHECK_PATH = "/health";
+/** Path for the authenticated admin shutdown endpoint. */
+const ADMIN_SHUTDOWN_PATH = "/admin/shutdown";
+/** HTTP POST method identifier. */
+const HTTP_METHOD_POST = "POST";
+/** HTTP header name for bearer token authorization. */
+const AUTHORIZATION_HEADER_NAME = "Authorization";
+/** Prefix for bearer token values in the Authorization header. */
+const BEARER_TOKEN_PREFIX = "Bearer ";
+/** HTTP protocol scheme prefix for URL construction. */
+const HTTP_PROTOCOL = "http://";
+/** Hosts that are safe to send admin requests to (loopback only). */
+const ALLOWED_HOSTS = new Set([
+	"localhost",
+	"127.0.0.1",
+	"::1"
+]);
+//#endregion
+//#region src/services/StopServerService/types.ts
 /**
-* Regex pattern for valid package names (npm, pnpm, uvx, uv)
-* Allows: @scope/package-name@version, package-name, package_name
-* Prevents shell metacharacters that could enable command injection
-* @example
-* // Valid: '@scope/package@1.0.0', 'my-package', 'my_package', '@org/pkg'
-* // Invalid: 'pkg; rm -rf /', 'pkg$(cmd)', 'pkg`whoami`', 'pkg|cat /etc/passwd'
+* Safely cast a non-null object to a string-keyed record for property access.
+* @param value - Object value already verified as non-null
+* @returns The same value typed as a record
 */
-const VALID_PACKAGE_NAME_PATTERN = /^(@[a-zA-Z0-9_-]+\/)?[a-zA-Z0-9._-]+(@[a-zA-Z0-9._-]+)?$/;
-/** Windows platform identifier */
-const PLATFORM_WIN32 = "win32";
-/** Stdio option to ignore stream */
-const STDIO_IGNORE = "ignore";
-/** Stdio option to pipe stream */
-const STDIO_PIPE = "pipe";
-//#endregion
-//#region src/services/PrefetchService/PrefetchService.ts
+function toRecord(value) {
+	return value;
+}
 /**
-* PrefetchService
-*
-* DESIGN PATTERNS:
-* - Service pattern for business logic encapsulation
-* - Single responsibility principle
-*
-* CODING STANDARDS:
-* - Use async/await for asynchronous operations
-* - Throw descriptive errors for error cases
-* - Keep methods focused and well-named
-* - Document complex logic with comments
-*
-* AVOID:
-* - Mixing concerns (keep focused on single domain)
-* - Direct tool implementation (services should be tool-agnostic)
+* Type guard for health responses.
+* @param value - Candidate payload to validate
+* @returns True when payload matches health response shape
 */
+function isHealthResponse(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const record = toRecord(value);
+	return "status" in record && record["status"] === "ok" && "transport" in record && record["transport"] === "http" && (!("serverId" in record) || record["serverId"] === void 0 || typeof record["serverId"] === "string");
+}
 /**
-* Type guard to check if a config object is an McpStdioConfig
-* @param config - Config object to check
-* @returns True if config has required McpStdioConfig properties
+* Type guard for shutdown responses.
+* @param value - Candidate payload to validate
+* @returns True when payload matches shutdown response shape
 */
-function isMcpStdioConfig(config) {
-	return typeof config === "object" && config !== null && "command" in config;
+function isShutdownResponse(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const record = toRecord(value);
+	return "ok" in record && typeof record["ok"] === "boolean" && "message" in record && typeof record["message"] === "string" && (!("serverId" in record) || record["serverId"] === void 0 || typeof record["serverId"] === "string");
 }
+//#endregion
+//#region src/services/StopServerService/StopServerService.ts
 /**
-* PrefetchService handles pre-downloading packages used by MCP servers.
-* Supports npx (Node.js), uvx (Python/uv), and uv run commands.
-*
-* @example
-* ```typescript
-* const service = new PrefetchService({
-*   mcpConfig: await configFetcher.fetchConfiguration(),
-*   parallel: true,
-* });
-* const packages = service.extractPackages();
-* const summary = await service.prefetch();
-* ```
+* Format runtime endpoint URL after validating the host is a loopback address.
+* Rejects non-loopback hosts to prevent SSRF via tampered runtime state files.
+* @param runtime - Runtime record to format
+* @param path - Request path to append
+* @returns Full runtime URL
 */
-var PrefetchService = class {
-	config;
-	/**
-	* Creates a new PrefetchService instance
-	* @param config - Service configuration options
-	*/
-	constructor(config) {
-		this.config = config;
-	}
-	/**
-	* Extract all prefetchable packages from the MCP configuration
-	* @returns Array of package info objects
-	*/
-	extractPackages() {
-		const packages = [];
-		const { mcpConfig, filter } = this.config;
-		for (const [serverName, serverConfig] of Object.entries(mcpConfig.mcpServers)) {
-			if (serverConfig.disabled) continue;
-			if (serverConfig.transport !== "stdio") continue;
-			if (!isMcpStdioConfig(serverConfig.config)) continue;
-			const packageInfo = this.extractPackageInfo(serverName, serverConfig.config);
-			if (packageInfo) {
-				if (filter && packageInfo.packageManager !== filter) continue;
-				packages.push(packageInfo);
-			}
-		}
-		return packages;
-	}
-	/**
-	* Prefetch all packages from the configuration
-	* @returns Summary of prefetch results
-	* @throws Error if prefetch operation fails unexpectedly
-	*/
-	async prefetch() {
-		try {
-			const packages = this.extractPackages();
-			const results = [];
-			if (packages.length === 0) return {
-				totalPackages: 0,
-				successful: 0,
-				failed: 0,
-				results: []
-			};
-			if (this.config.parallel) {
-				const promises = packages.map(async (pkg) => this.prefetchPackage(pkg));
-				results.push(...await Promise.all(promises));
-			} else for (const pkg of packages) {
-				const result = await this.prefetchPackage(pkg);
-				results.push(result);
-			}
-			const successful = results.filter((r) => r.success).length;
-			const failed = results.filter((r) => !r.success).length;
-			return {
-				totalPackages: packages.length,
-				successful,
-				failed,
-				results
-			};
-		} catch (error) {
-			throw new Error(`Failed to prefetch packages: ${error instanceof Error ? error.message : String(error)}`);
-		}
+function buildRuntimeUrl(runtime, path) {
+	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}:${runtime.port}${path}`;
+}
+function toErrorMessage$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function sleep(delayMs) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, delayMs);
+	});
+}
+/**
+* Service for resolving runtime targets and stopping them safely.
+*/
+var StopServerService = class {
+	runtimeStateService;
+	logger;
+	constructor(runtimeStateService = new RuntimeStateService(), logger = console) {
+		this.runtimeStateService = runtimeStateService;
+		this.logger = logger;
 	}
 	/**
-	* Prefetch a single package
-	* @param pkg - Package info to prefetch
-	* @returns Result of the prefetch operation
+	* Resolve a target runtime and stop it cooperatively.
+	* @param request - Stop request options
+	* @returns Stop result payload
 	*/
-	async prefetchPackage(pkg) {
-		try {
-			const [command, ...args] = pkg.fullCommand;
-			const result = await this.runCommand(command, args);
-			return {
-				package: pkg,
-				success: result.success,
-				output: result.output
-			};
-		} catch (error) {
-			return {
-				package: pkg,
-				success: false,
-				output: error instanceof Error ? error.message : String(error)
-			};
+	async stop(request) {
+		const timeoutMs = request.timeoutMs ?? 5e3;
+		const runtime = await this.resolveRuntime(request);
+		const health = await this.fetchHealth(runtime, timeoutMs);
+		if (!health.reachable) {
+			await this.runtimeStateService.remove(runtime.serverId);
+			throw new Error(`Runtime '${runtime.serverId}' is not reachable at http://${runtime.host}:${runtime.port}. Removed stale runtime record.`);
 		}
+		if (!request.force && health.payload?.serverId && health.payload.serverId !== runtime.serverId) throw new Error(`Refusing to stop runtime at http://${runtime.host}:${runtime.port}: expected server ID '${runtime.serverId}' but health endpoint reported '${health.payload.serverId}'. Use --force to override.`);
+		const shutdownToken = request.token ?? runtime.shutdownToken;
+		if (!shutdownToken) throw new Error(`No shutdown token available for runtime '${runtime.serverId}'.`);
+		const shutdownResponse = await this.requestShutdown(runtime, shutdownToken, timeoutMs);
+		await this.waitForShutdown(runtime, timeoutMs);
+		await this.runtimeStateService.remove(runtime.serverId);
+		return {
+			ok: true,
+			serverId: runtime.serverId,
+			host: runtime.host,
+			port: runtime.port,
+			message: shutdownResponse.message
+		};
 	}
 	/**
-	* Validate package name to prevent command injection
-	* @param packageName - Package name to validate
-	* @returns True if package name is safe, false otherwise
-	* @remarks Rejects package names containing shell metacharacters
-	* @example
-	* isValidPackageName('@scope/package') // true
-	* isValidPackageName('my-package@1.0.0') // true
-	* isValidPackageName('pkg; rm -rf /') // false (shell injection)
-	* isValidPackageName('pkg$(whoami)') // false (command substitution)
-	*/
-	isValidPackageName(packageName) {
-		return VALID_PACKAGE_NAME_PATTERN.test(packageName);
-	}
-	/**
-	* Extract package info from a server's stdio config
-	* @param serverName - Name of the MCP server
-	* @param config - Stdio configuration for the server
-	* @returns Package info if extractable, null otherwise
+	* Resolve a runtime record from explicit ID or a unique host/port pair.
+	* @param request - Stop request options
+	* @returns Matching runtime record
 	*/
-	extractPackageInfo(serverName, config) {
-		const command = config.command.toLowerCase();
-		const args = config.args || [];
-		if (command === "npx" || command.endsWith("/npx")) {
-			const packageName = this.extractNpxPackage(args);
-			if (packageName && this.isValidPackageName(packageName)) return {
-				serverName,
-				packageManager: "npx",
-				packageName,
-				fullCommand: [
-					"npm",
-					ARG_INSTALL,
-					"-g",
-					packageName
-				]
-			};
-		}
-		if (command === "pnpx" || command.endsWith("/pnpx")) {
-			const packageName = this.extractNpxPackage(args);
-			if (packageName && this.isValidPackageName(packageName)) return {
-				serverName,
-				packageManager: COMMAND_PNPX,
-				packageName,
-				fullCommand: [
-					COMMAND_PNPM,
-					"add",
-					"-g",
-					packageName
-				]
-			};
-		}
-		if (command === "uvx" || command.endsWith("/uvx")) {
-			const packageName = this.extractUvxPackage(args);
-			if (packageName && this.isValidPackageName(packageName)) return {
-				serverName,
-				packageManager: "uvx",
-				packageName,
-				fullCommand: ["uvx", packageName]
-			};
-		}
-		if ((command === "uv" || command.endsWith("/uv")) && args.includes("run")) {
-			const packageName = this.extractUvRunPackage(args);
-			if (packageName && this.isValidPackageName(packageName)) return {
-				serverName,
-				packageManager: "uv",
-				packageName,
-				fullCommand: [
-					"uv",
-					ARG_TOOL,
-					ARG_INSTALL,
-					packageName
-				]
-			};
+	async resolveRuntime(request) {
+		if (request.serverId) {
+			const runtime = await this.runtimeStateService.read(request.serverId);
+			if (!runtime) throw new Error(`No runtime record found for server ID '${request.serverId}'. Start the server with 'mcp-proxy mcp-serve --type http' first.`);
+			return runtime;
 		}
-		return null;
+		if (request.host === void 0 || request.port === void 0) throw new Error("Provide --id or both --host and --port to select a runtime.");
+		const matches = (await this.runtimeStateService.list()).filter((runtime) => runtime.host === request.host && runtime.port === request.port);
+		if (matches.length === 0) throw new Error(`No runtime record found for http://${request.host}:${request.port}. Start the server with 'mcp-proxy mcp-serve --type http' first.`);
+		if (matches.length > 1) throw new Error(`Multiple runtime records match http://${request.host}:${request.port}. Retry with --id to avoid stopping the wrong server.`);
+		return matches[0];
 	}
 	/**
-	* Extract package name from npx command args
-	* @param args - Command arguments
-	* @returns Package name or null
-	* @remarks Handles --package=value, --package value, -p value patterns.
-	*          Falls back to first non-flag argument if no --package/-p flag found.
-	*          Returns null if flag has no value or is followed by another flag.
-	*          When multiple --package flags exist, returns the first valid one.
-	* @example
-	* extractNpxPackage(['--package=@scope/pkg']) // returns '@scope/pkg'
-	* extractNpxPackage(['--package', 'pkg-name']) // returns 'pkg-name'
-	* extractNpxPackage(['-p', 'pkg']) // returns 'pkg'
-	* extractNpxPackage(['-y', 'pkg-name', '--flag']) // returns 'pkg-name' (fallback)
-	* extractNpxPackage(['--package=']) // returns null (empty value)
+	* Read the runtime health payload.
+	* @param runtime - Runtime to query
+	* @param timeoutMs - Request timeout in milliseconds
+	* @returns Reachability status and optional payload
 	*/
-	extractNpxPackage(args) {
-		for (let i = 0; i < args.length; i++) {
-			const arg = args[i];
-			if (arg.startsWith("--package=")) return arg.slice(10) || null;
-			if (arg === "--package" && i + 1 < args.length) {
-				const nextArg = args[i + 1];
-				if (!nextArg.startsWith("-")) return nextArg;
-			}
-			if (arg === "-p" && i + 1 < args.length) {
-				const nextArg = args[i + 1];
-				if (!nextArg.startsWith("-")) return nextArg;
-			}
-		}
-		for (const arg of args) {
-			if (arg.startsWith("-")) continue;
-			return arg;
+	async fetchHealth(runtime, timeoutMs) {
+		try {
+			const response = await this.fetchWithTimeout(buildRuntimeUrl(runtime, HEALTH_CHECK_PATH), { method: "GET" }, timeoutMs);
+			if (!response.ok) return { reachable: false };
+			const payload = await response.json();
+			if (!isHealthResponse(payload)) throw new Error("Received invalid health response payload.");
+			return {
+				reachable: true,
+				payload
+			};
+		} catch (error) {
+			this.logger.debug(`Health check failed for ${runtime.serverId}`, error);
+			return { reachable: false };
 		}
-		return null;
 	}
 	/**
-	* Extract package name from uvx command args
-	* @param args - Command arguments
-	* @returns Package name or null
-	* @remarks Assumes the first non-flag argument is the package name.
-	*          Handles both single (-) and double (--) dash flags.
-	* @example
-	* extractUvxPackage(['mcp-server-fetch']) // returns 'mcp-server-fetch'
-	* extractUvxPackage(['--quiet', 'pkg-name']) // returns 'pkg-name'
+	* Send authenticated shutdown request to the admin endpoint.
+	* @param runtime - Runtime to stop
+	* @param shutdownToken - Bearer token for the admin endpoint
+	* @param timeoutMs - Request timeout in milliseconds
+	* @returns Parsed shutdown response payload
 	*/
-	extractUvxPackage(args) {
-		for (const arg of args) {
-			if (arg.startsWith("-")) continue;
-			return arg;
-		}
-		return null;
+	async requestShutdown(runtime, shutdownToken, timeoutMs) {
+		const response = await this.fetchWithTimeout(buildRuntimeUrl(runtime, ADMIN_SHUTDOWN_PATH), {
+			method: HTTP_METHOD_POST,
+			headers: { [AUTHORIZATION_HEADER_NAME]: `${BEARER_TOKEN_PREFIX}${shutdownToken}` }
+		}, timeoutMs);
+		const payload = await response.json();
+		if (!isShutdownResponse(payload)) throw new Error("Received invalid shutdown response payload.");
+		if (!response.ok || !payload.ok) throw new Error(payload.message);
+		return payload;
 	}
 	/**
-	* Extract package name from uv run command args
-	* @param args - Command arguments
-	* @returns Package name or null
-	* @remarks Looks for the first non-flag argument after the 'run' subcommand.
-	*          Returns null if 'run' is not found in args.
-	* @example
-	* extractUvRunPackage(['run', 'mcp-server']) // returns 'mcp-server'
-	* extractUvRunPackage(['run', '--verbose', 'pkg']) // returns 'pkg'
-	* extractUvRunPackage(['install', 'pkg']) // returns null (no 'run')
+	* Poll until the target runtime is no longer reachable.
+	* @param runtime - Runtime expected to stop
+	* @param timeoutMs - Maximum wait time in milliseconds
+	* @returns Promise that resolves when shutdown is observed
 	*/
-	extractUvRunPackage(args) {
-		const runIndex = args.indexOf("run");
-		if (runIndex === -1) return null;
-		for (let i = runIndex + 1; i < args.length; i++) {
-			const arg = args[i];
-			if (arg.startsWith("-")) continue;
-			return arg;
+	async waitForShutdown(runtime, timeoutMs) {
+		const deadline = Date.now() + timeoutMs;
+		while (Date.now() < deadline) {
+			if (!(await this.fetchHealth(runtime, Math.max(250, deadline - Date.now()))).reachable) return;
+			await sleep(200);
 		}
-		return null;
+		throw new Error(`Timed out waiting for runtime '${runtime.serverId}' to stop at http://${runtime.host}:${runtime.port}.`);
 	}
 	/**
-	* Run a shell command and capture output
-	* @param command - Command to run
-	* @param args - Command arguments
-	* @returns Promise with success status and output
+	* Perform a fetch with an abort timeout.
+	* @param url - Target URL
+	* @param init - Fetch options
+	* @param timeoutMs - Timeout in milliseconds
+	* @returns Fetch response
 	*/
-	runCommand(command, args) {
-		return new Promise((resolve) => {
-			const proc = (0, node_child_process.spawn)(command, args, {
-				stdio: [
-					STDIO_IGNORE,
-					STDIO_PIPE,
-					STDIO_PIPE
-				],
-				shell: process.platform === PLATFORM_WIN32
-			});
-			let stdout = "";
-			let stderr = "";
-			proc.stdout?.on("data", (data) => {
-				stdout += data.toString();
-			});
-			proc.stderr?.on("data", (data) => {
-				stderr += data.toString();
-			});
-			proc.on("close", (code) => {
-				resolve({
-					success: code === 0,
-					output: stdout || stderr
-				});
-			});
-			proc.on("error", (error) => {
-				resolve({
-					success: false,
-					output: error.message
-				});
+	async fetchWithTimeout(url, init, timeoutMs) {
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => {
+			controller.abort();
+		}, timeoutMs);
+		try {
+			return await fetch(url, {
+				...init,
+				signal: controller.signal
 			});
-		});
+		} catch (error) {
+			throw new Error(`Request to '${url}' failed: ${toErrorMessage$1(error)}`);
+		} finally {
+			clearTimeout(timeoutId);
+		}
 	}
 };
 //#endregion
@@ -2929,8 +2929,6 @@ var DescribeToolsTool = class DescribeToolsTool {
 	skillService;
 	definitionsCacheService;
 	liquid = new liquidjs.Liquid();
-	/** Cache for auto-detected skills from prompt front-matter */
-	autoDetectedSkillsCache = null;
 	/** Unique server identifier for this mcp-proxy instance */
 	serverId;
 	/**
@@ -2951,67 +2949,9 @@ var DescribeToolsTool = class DescribeToolsTool {
 	* the skill service cache is invalidated.
 	*/
 	clearAutoDetectedSkillsCache() {
-		this.autoDetectedSkillsCache = null;
 		this.definitionsCacheService.clearLiveCache();
 	}
 	/**
-	* Detects and caches skills from prompt front-matter across all connected MCP servers.
-	* Fetches all prompts and checks their content for YAML front-matter with name/description.
-	* Results are cached to avoid repeated fetches.
-	*
-	* Error Handling Strategy:
-	* - Errors are logged to stderr but do not fail the overall detection process
-	* - This ensures partial results are returned even if some servers/prompts fail
-	* - Common failure reasons: server temporarily unavailable, prompt requires arguments,
-	*   network timeout, or server doesn't support listPrompts
-	* - Errors are prefixed with [skill-detection] for easy filtering in logs
-	*
-	* @returns Array of auto-detected skills from prompt front-matter
-	*/
-	async detectSkillsFromPromptFrontMatter() {
-		if (this.autoDetectedSkillsCache !== null) return this.autoDetectedSkillsCache;
-		const clients = this.clientManager.getAllClients();
-		let listPromptsFailures = 0;
-		let fetchPromptFailures = 0;
-		const autoDetectedSkills = (await Promise.all(clients.map(async (client) => {
-			const detectedSkills = [];
-			const configuredPromptNames = new Set(client.prompts ? Object.keys(client.prompts) : []);
-			try {
-				const prompts = await client.listPrompts();
-				if (!prompts || prompts.length === 0) return detectedSkills;
-				const promptResults = await Promise.all(prompts.map(async (promptInfo) => {
-					if (configuredPromptNames.has(promptInfo.name)) return null;
-					try {
-						const skillExtraction = extractSkillFrontMatter(((await client.getPrompt(promptInfo.name)).messages || []).map((m) => {
-							const content = m.content;
-							if (typeof content === "string") return content;
-							if (content && typeof content === "object" && "text" in content) return String(content.text);
-							return "";
-						}).join("\n"));
-						if (skillExtraction) return {
-							serverName: client.serverName,
-							promptName: promptInfo.name,
-							skill: skillExtraction.skill
-						};
-						return null;
-					} catch (error) {
-						fetchPromptFailures++;
-						console.error(`${LOG_PREFIX_SKILL_DETECTION} Failed to fetch prompt '${promptInfo.name}' from ${client.serverName}: ${error instanceof Error ? error.message : "Unknown error"}`);
-						return null;
-					}
-				}));
-				for (const result of promptResults) if (result) detectedSkills.push(result);
-			} catch (error) {
-				listPromptsFailures++;
-				console.error(`${LOG_PREFIX_SKILL_DETECTION} Failed to list prompts from ${client.serverName}: ${error instanceof Error ? error.message : "Unknown error"}`);
-			}
-			return detectedSkills;
-		}))).flat();
-		if (listPromptsFailures > 0 || fetchPromptFailures > 0) console.error(`${LOG_PREFIX_SKILL_DETECTION} Completed with ${listPromptsFailures} server failure(s) and ${fetchPromptFailures} prompt failure(s). Detected ${autoDetectedSkills.length} skill(s).`);
-		this.autoDetectedSkillsCache = autoDetectedSkills;
-		return autoDetectedSkills;
-	}
-	/**
 	* Collects skills derived from prompt configurations across all connected MCP servers.
 	* Includes both explicitly configured prompts and auto-detected skills from front-matter.
 	*
@@ -3220,7 +3160,20 @@ var DescribeToolsTool = class DescribeToolsTool {
 			if (serverName) {
 				const serverTools = serverToolsMap.get(serverName);
 				if (!serverTools) {
-					result.notFound = requestedName;
+					try {
+						const tool = (await (await this.clientManager.ensureConnected(serverName)).listTools()).find((t) => t.name === actualToolName);
+						if (tool) result.tools.push({
+							server: serverName,
+							tool: {
+								name: tool.name,
+								description: tool.description,
+								inputSchema: tool.inputSchema
+							}
+						});
+						else result.notFound = requestedName;
+					} catch {
+						result.notFound = requestedName;
+					}
 					return result;
 				}
 				const tool = serverTools.find((t) => t.name === actualToolName);