@agimon-ai/mcp-proxy 0.9.0 → 0.9.1

package/dist/{src-DA5H3rpr.mjs → src-Dv7rJN0P.mjs}

@@ -1,10 +1,7 @@
-import { coerceArgs, formatZodError, jsonSchemaToZod } from "@agimon-ai/foundation-validator";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { CallToolRequestSchema, ElicitRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
-import { z } from "zod";
 import { existsSync } from "node:fs";
 import { access, mkdir, readFile, readdir, rm, stat, unlink, watch, writeFile } from "node:fs/promises";
 import yaml from "js-yaml";
+import { z } from "zod";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { homedir, tmpdir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
@@ -15,16 +12,19 @@ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { spawn } from "node:child_process";
 import { Liquid } from "liquidjs";
+import { coerceArgs, formatZodError, jsonSchemaToZod } from "@agimon-ai/foundation-validator";
 import { once } from "node:events";
 import { createServer } from "node:http";
 import { promisify } from "node:util";
 import { getRequestListener } from "@hono/node-server";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, ElicitRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { Hono } from "hono";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 //#region package.json
-var version = "0.8.0";
+var version = "0.9.0";
 //#endregion
 //#region src/utils/mcpConfigSchema.ts
 /**
@@ -943,25 +943,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 = 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
@@ -1097,68 +1140,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 = 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
@@ -1871,304 +1871,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 join(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 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 mkdir(this.runtimeDir, { recursive: true });
-		await 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 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 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 readFile(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 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 = 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 join(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 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 mkdir(this.runtimeDir, { recursive: true });
+		await 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 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 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 readFile(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 rm(this.getRecordPath(serverId), { force: true });
 	}
 };
 //#endregion
@@ -2527,339 +2663,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 = 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
@@ -2906,8 +2906,6 @@ var DescribeToolsTool = class DescribeToolsTool {
 	skillService;
 	definitionsCacheService;
 	liquid = new Liquid();
-	/** Cache for auto-detected skills from prompt front-matter */
-	autoDetectedSkillsCache = null;
 	/** Unique server identifier for this mcp-proxy instance */
 	serverId;
 	/**
@@ -2928,67 +2926,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.
 	*
@@ -3197,7 +3137,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);
@@ -4975,4 +4928,4 @@ const TRANSPORT_MODE = {
 	SSE: "sse"
 };
 //#endregion
-export { DefinitionsCacheService as C, version as D, ConfigFetcherService as E, createProxyLogger as S, findConfigFile as T, DescribeToolsTool as _, createProxyContainer as a, RuntimeStateService as b, createStdioHttpTransportHandler as c, StdioHttpTransportHandler as d, StdioTransportHandler as f, SearchListToolsTool as g, UseToolTool as h, createHttpTransportHandler as i, createStdioTransportHandler as l, HttpTransportHandler as m, createServer$1 as n, createProxyIoCContainer as o, SseTransportHandler as p, createSessionServer as r, createSseTransportHandler as s, TRANSPORT_MODE as t, initializeSharedServices as u, SkillService as v, generateServerId as w, McpClientManagerService as x, StopServerService as y };
+export { DefinitionsCacheService as C, version as D, ConfigFetcherService as E, createProxyLogger as S, findConfigFile as T, DescribeToolsTool as _, createProxyContainer as a, RuntimeStateService as b, createStdioHttpTransportHandler as c, StdioHttpTransportHandler as d, StdioTransportHandler as f, SearchListToolsTool as g, UseToolTool as h, createHttpTransportHandler as i, createStdioTransportHandler as l, HttpTransportHandler as m, createServer$1 as n, createProxyIoCContainer as o, SseTransportHandler as p, createSessionServer as r, createSseTransportHandler as s, TRANSPORT_MODE as t, initializeSharedServices as u, StopServerService as v, generateServerId as w, McpClientManagerService as x, SkillService as y };