@agiflowai/one-mcp 0.2.6 → 0.2.8

package/dist/{http-xSfxBa8A.cjs → http-BzrxGEr-.cjs}

@@ -38,6 +38,7 @@ let node_os = require("node:os");
 let __modelcontextprotocol_sdk_client_index_js = require("@modelcontextprotocol/sdk/client/index.js");
 let __modelcontextprotocol_sdk_client_stdio_js = require("@modelcontextprotocol/sdk/client/stdio.js");
 let __modelcontextprotocol_sdk_client_sse_js = require("@modelcontextprotocol/sdk/client/sse.js");
+let __modelcontextprotocol_sdk_client_streamableHttp_js = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
 let liquidjs = require("liquidjs");
 let __modelcontextprotocol_sdk_server_stdio_js = require("@modelcontextprotocol/sdk/server/stdio.js");
 let __modelcontextprotocol_sdk_server_sse_js = require("@modelcontextprotocol/sdk/server/sse.js");
@@ -230,6 +231,7 @@ const ClaudeCodeStdioServerSchema = zod.z.object({
 	env: zod.z.record(zod.z.string(), zod.z.string()).optional(),
 	disabled: zod.z.boolean().optional(),
 	instruction: zod.z.string().optional(),
+	timeout: zod.z.number().positive().optional(),
 	config: AdditionalConfigSchema
 });
 const ClaudeCodeHttpServerSchema = zod.z.object({
@@ -238,6 +240,7 @@ const ClaudeCodeHttpServerSchema = zod.z.object({
 	type: zod.z.enum(["http", "sse"]).optional(),
 	disabled: zod.z.boolean().optional(),
 	instruction: zod.z.string().optional(),
+	timeout: zod.z.number().positive().optional(),
 	config: AdditionalConfigSchema
 });
 const ClaudeCodeServerConfigSchema = zod.z.union([ClaudeCodeStdioServerSchema, ClaudeCodeHttpServerSchema]);
@@ -268,6 +271,7 @@ const SkillsConfigSchema = zod.z.object({ paths: zod.z.array(zod.z.string()) });
 * Full Claude Code MCP configuration schema
 */
 const ClaudeCodeMcpConfigSchema = zod.z.object({
+	id: zod.z.string().optional(),
 	mcpServers: zod.z.record(zod.z.string(), ClaudeCodeServerConfigSchema),
 	remoteConfigs: zod.z.array(RemoteConfigSourceSchema).optional(),
 	skills: SkillsConfigSchema.optional()
@@ -308,6 +312,7 @@ const McpServerConfigSchema = zod.z.discriminatedUnion("transport", [
 		toolBlacklist: zod.z.array(zod.z.string()).optional(),
 		omitToolDescription: zod.z.boolean().optional(),
 		prompts: zod.z.record(zod.z.string(), InternalPromptConfigSchema).optional(),
+		timeout: zod.z.number().positive().optional(),
 		transport: zod.z.literal("stdio"),
 		config: McpStdioConfigSchema
 	}),
@@ -317,6 +322,7 @@ const McpServerConfigSchema = zod.z.discriminatedUnion("transport", [
 		toolBlacklist: zod.z.array(zod.z.string()).optional(),
 		omitToolDescription: zod.z.boolean().optional(),
 		prompts: zod.z.record(zod.z.string(), InternalPromptConfigSchema).optional(),
+		timeout: zod.z.number().positive().optional(),
 		transport: zod.z.literal("http"),
 		config: McpHttpConfigSchema
 	}),
@@ -326,6 +332,7 @@ const McpServerConfigSchema = zod.z.discriminatedUnion("transport", [
 		toolBlacklist: zod.z.array(zod.z.string()).optional(),
 		omitToolDescription: zod.z.boolean().optional(),
 		prompts: zod.z.record(zod.z.string(), InternalPromptConfigSchema).optional(),
+		timeout: zod.z.number().positive().optional(),
 		transport: zod.z.literal("sse"),
 		config: McpSseConfigSchema
 	})
@@ -334,6 +341,7 @@ const McpServerConfigSchema = zod.z.discriminatedUnion("transport", [
 * Full internal MCP configuration schema
 */
 const InternalMcpConfigSchema = zod.z.object({
+	id: zod.z.string().optional(),
 	mcpServers: zod.z.record(zod.z.string(), McpServerConfigSchema),
 	skills: SkillsConfigSchema.optional()
 });
@@ -359,6 +367,7 @@ function transformClaudeCodeConfig(claudeConfig) {
 				toolBlacklist: stdioConfig.config?.toolBlacklist,
 				omitToolDescription: stdioConfig.config?.omitToolDescription,
 				prompts: stdioConfig.config?.prompts,
+				timeout: stdioConfig.timeout,
 				transport: "stdio",
 				config: {
 					command: interpolatedCommand,
@@ -377,6 +386,7 @@ function transformClaudeCodeConfig(claudeConfig) {
 				toolBlacklist: httpConfig.config?.toolBlacklist,
 				omitToolDescription: httpConfig.config?.omitToolDescription,
 				prompts: httpConfig.config?.prompts,
+				timeout: httpConfig.timeout,
 				transport,
 				config: {
 					url: interpolatedUrl,
@@ -386,6 +396,7 @@ function transformClaudeCodeConfig(claudeConfig) {
 		}
 	}
 	return {
+		id: claudeConfig.id,
 		mcpServers: transformedServers,
 		skills: claudeConfig.skills
 	};
@@ -546,22 +557,21 @@ var RemoteConfigCacheService = class {
 		try {
 			if (!(0, node_fs.existsSync)(this.cacheDir)) return;
 			const now = Date.now();
-			const files = await (0, node_fs_promises.readdir)(this.cacheDir);
-			let expiredCount = 0;
-			for (const file of files) {
-				if (!file.endsWith(".json")) continue;
+			const jsonFiles = (await (0, node_fs_promises.readdir)(this.cacheDir)).filter((file) => file.endsWith(".json"));
+			const expiredCount = (await Promise.all(jsonFiles.map(async (file) => {
 				const filePath = (0, node_path.join)(this.cacheDir, file);
 				try {
 					const content = await (0, node_fs_promises.readFile)(filePath, "utf-8");
 					if (now > JSON.parse(content).expiresAt) {
 						await (0, node_fs_promises.unlink)(filePath);
-						expiredCount++;
+						return true;
 					}
+					return false;
 				} catch (error) {
 					await (0, node_fs_promises.unlink)(filePath).catch(() => {});
-					expiredCount++;
+					return true;
 				}
-			}
+			}))).filter(Boolean).length;
 			if (expiredCount > 0) console.error(`Cleaned up ${expiredCount} expired remote config cache entries`);
 		} catch (error) {
 			console.error("Failed to clean expired remote config cache:", error);
@@ -577,14 +587,15 @@ var RemoteConfigCacheService = class {
 				totalSize: 0
 			};
 			const jsonFiles = (await (0, node_fs_promises.readdir)(this.cacheDir)).filter((file) => file.endsWith(".json"));
-			let totalSize = 0;
-			for (const file of jsonFiles) {
+			const totalSize = (await Promise.all(jsonFiles.map(async (file) => {
 				const filePath = (0, node_path.join)(this.cacheDir, file);
 				try {
 					const content = await (0, node_fs_promises.readFile)(filePath, "utf-8");
-					totalSize += Buffer.byteLength(content, "utf-8");
-				} catch {}
-			}
+					return Buffer.byteLength(content, "utf-8");
+				} catch {
+					return 0;
+				}
+			}))).reduce((sum, size) => sum + size, 0);
 			return {
 				totalEntries: jsonFiles.length,
 				totalSize
@@ -835,6 +846,8 @@ var ConfigFetcherService = class {
 
 //#endregion
 //#region src/services/McpClientManagerService.ts
+/** Default connection timeout in milliseconds (30 seconds) */
+const DEFAULT_CONNECTION_TIMEOUT_MS = 3e4;
 /**
 * MCP Client wrapper for managing individual server connections
 * This is an internal class used by McpClientManagerService
@@ -940,8 +953,10 @@ var McpClientManagerService = class {
 	}
 	/**
 	* Connect to an MCP server based on its configuration with timeout
+	* Uses the timeout from server config, falling back to default (30s)
 	*/
-	async connectToServer(serverName, config, timeoutMs = 1e4) {
+	async connectToServer(serverName, config) {
+		const timeoutMs = config.timeout ?? DEFAULT_CONNECTION_TIMEOUT_MS;
 		if (this.clients.has(serverName)) throw new Error(`Client for ${serverName} is already connected`);
 		const client = new __modelcontextprotocol_sdk_client_index_js.Client({
 			name: `@agiflowai/one-mcp-client`,
@@ -973,6 +988,7 @@ var McpClientManagerService = class {
 	*/
 	async performConnection(mcpClient, config) {
 		if (config.transport === "stdio") await this.connectStdioClient(mcpClient, config.config);
+		else if (config.transport === "http") await this.connectHttpClient(mcpClient, config.config);
 		else if (config.transport === "sse") await this.connectSseClient(mcpClient, config.config);
 		else throw new Error(`Unsupported transport type: ${config.transport}`);
 	}
@@ -986,6 +1002,10 @@ var McpClientManagerService = class {
 		const childProcess = transport["_process"];
 		if (childProcess) mcpClient.setChildProcess(childProcess);
 	}
+	async connectHttpClient(mcpClient, config) {
+		const transport = new __modelcontextprotocol_sdk_client_streamableHttp_js.StreamableHTTPClientTransport(new URL(config.url), { requestInit: config.headers ? { headers: config.headers } : void 0 });
+		await mcpClient["client"].connect(transport);
+	}
 	async connectSseClient(mcpClient, config) {
 		const transport = new __modelcontextprotocol_sdk_client_sse_js.SSEClientTransport(new URL(config.url));
 		await mcpClient["client"].connect(transport);
@@ -1028,6 +1048,274 @@ var McpClientManagerService = class {
 	}
 };
 
+//#endregion
+//#region src/utils/findConfigFile.ts
+/**
+* Config File Finder Utility
+*
+* DESIGN PATTERNS:
+* - Utility function pattern for reusable logic
+* - Fail-fast pattern with early returns
+* - Environment variable configuration pattern
+*
+* CODING STANDARDS:
+* - Use sync filesystem operations for config discovery (performance)
+* - Check PROJECT_PATH environment variable first
+* - Fall back to current working directory
+* - Support both .yaml and .json extensions
+* - Return null if no config file is found
+*
+* AVOID:
+* - Throwing errors (return null instead for optional config)
+* - Hardcoded file names without extension variants
+* - Ignoring environment variables
+*/
+/**
+* Find MCP configuration file by checking PROJECT_PATH first, then cwd
+* Looks for both mcp-config.yaml and mcp-config.json
+*
+* @returns Absolute path to config file, or null if not found
+*/
+function findConfigFile() {
+	const configFileNames = [
+		"mcp-config.yaml",
+		"mcp-config.yml",
+		"mcp-config.json"
+	];
+	const projectPath = process.env.PROJECT_PATH;
+	if (projectPath) for (const fileName of configFileNames) {
+		const configPath = (0, node_path.resolve)(projectPath, fileName);
+		if ((0, node_fs.existsSync)(configPath)) return configPath;
+	}
+	const cwd = process.cwd();
+	for (const fileName of configFileNames) {
+		const configPath = (0, node_path.join)(cwd, fileName);
+		if ((0, node_fs.existsSync)(configPath)) return configPath;
+	}
+	return null;
+}
+
+//#endregion
+//#region src/utils/parseToolName.ts
+/**
+* Parse tool name to extract server and actual tool name
+* Supports both plain tool names and prefixed format: {serverName}__{toolName}
+*
+* @param toolName - The tool name to parse (e.g., "my_tool" or "server__my_tool")
+* @returns Parsed result with optional serverName and actualToolName
+*
+* @example
+* parseToolName("my_tool") // { actualToolName: "my_tool" }
+* parseToolName("server__my_tool") // { serverName: "server", actualToolName: "my_tool" }
+*/
+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/utils/parseFrontMatter.ts
+/**
+* Parses YAML front matter from a string content.
+* Front matter must be at the start of the content, delimited by `---`.
+*
+* Supports:
+* - Simple key: value pairs
+* - Literal block scalar (|) for multi-line preserving newlines
+* - Folded block scalar (>) for multi-line folding to single line
+*
+* @param content - The content string that may contain front matter
+* @returns Object with parsed front matter (or null) and remaining content
+*
+* @example
+* const result = parseFrontMatter(`---
+* name: my-skill
+* description: A skill description
+* ---
+* The actual content here`);
+* // result.frontMatter = { name: 'my-skill', description: 'A skill description' }
+* // result.content = 'The actual content here'
+*
+* @example
+* // Multi-line with literal block scalar
+* const result = parseFrontMatter(`---
+* name: my-skill
+* description: |
+*   Line 1
+*   Line 2
+* ---
+* Content`);
+* // result.frontMatter.description = 'Line 1\nLine 2'
+*/
+function parseFrontMatter(content) {
+	const trimmedContent = content.trimStart();
+	if (!trimmedContent.startsWith("---")) return {
+		frontMatter: null,
+		content
+	};
+	const endDelimiterIndex = trimmedContent.indexOf("\n---", 3);
+	if (endDelimiterIndex === -1) return {
+		frontMatter: null,
+		content
+	};
+	const yamlContent = trimmedContent.slice(4, endDelimiterIndex).trim();
+	if (!yamlContent) return {
+		frontMatter: null,
+		content
+	};
+	const frontMatter = {};
+	const lines = yamlContent.split("\n");
+	let currentKey = null;
+	let currentValue = [];
+	let multiLineMode = null;
+	let baseIndent = 0;
+	const saveCurrentKey = () => {
+		if (currentKey && currentValue.length > 0) if (multiLineMode === "literal") frontMatter[currentKey] = currentValue.join("\n").trimEnd();
+		else if (multiLineMode === "folded") frontMatter[currentKey] = currentValue.join(" ").trim();
+		else frontMatter[currentKey] = currentValue.join("").trim();
+		currentKey = null;
+		currentValue = [];
+		multiLineMode = null;
+		baseIndent = 0;
+	};
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		const trimmedLine = line.trim();
+		const colonIndex = line.indexOf(":");
+		if (colonIndex !== -1 && !line.startsWith(" ") && !line.startsWith("	")) {
+			saveCurrentKey();
+			const key = line.slice(0, colonIndex).trim();
+			let value = line.slice(colonIndex + 1).trim();
+			if (value === "|" || value === "|-") {
+				currentKey = key;
+				multiLineMode = "literal";
+				if (i + 1 < lines.length) {
+					const match = lines[i + 1].match(/^(\s+)/);
+					baseIndent = match ? match[1].length : 2;
+				}
+			} else if (value === ">" || value === ">-") {
+				currentKey = key;
+				multiLineMode = "folded";
+				if (i + 1 < lines.length) {
+					const match = lines[i + 1].match(/^(\s+)/);
+					baseIndent = match ? match[1].length : 2;
+				}
+			} else {
+				if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
+				if (key && value) frontMatter[key] = value;
+			}
+		} else if (multiLineMode && currentKey) {
+			const lineIndent = line.match(/^(\s*)/)?.[1].length || 0;
+			if (trimmedLine === "") currentValue.push("");
+			else if (lineIndent >= baseIndent) {
+				const unindentedLine = line.slice(baseIndent);
+				currentValue.push(unindentedLine);
+			} else saveCurrentKey();
+		}
+	}
+	saveCurrentKey();
+	return {
+		frontMatter,
+		content: trimmedContent.slice(endDelimiterIndex + 4).trimStart()
+	};
+}
+/**
+* Checks if parsed front matter contains valid skill metadata.
+* A valid skill front matter must have both `name` and `description` fields.
+*
+* @param frontMatter - The parsed front matter object
+* @returns True if front matter contains valid skill metadata
+*/
+function isValidSkillFrontMatter(frontMatter) {
+	return frontMatter !== null && typeof frontMatter.name === "string" && frontMatter.name.length > 0 && typeof frontMatter.description === "string" && frontMatter.description.length > 0;
+}
+/**
+* Extracts skill front matter from content if present and valid.
+*
+* @param content - The content string that may contain skill front matter
+* @returns Object with skill metadata and content, or null if no valid skill front matter
+*/
+function extractSkillFrontMatter(content) {
+	const { frontMatter, content: remainingContent } = parseFrontMatter(content);
+	if (frontMatter && isValidSkillFrontMatter(frontMatter)) return {
+		skill: {
+			name: frontMatter.name,
+			description: frontMatter.description
+		},
+		content: remainingContent
+	};
+	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;
+/**
+* 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
+* generateServerId() // "abc234"
+* generateServerId(4) // "x7mn"
+*/
+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/services/SkillService.ts
 /**
@@ -1098,14 +1386,21 @@ var SkillService = class {
 	skillPaths;
 	cachedSkills = null;
 	skillsByName = null;
+	/** Active file watchers for skill directories */
+	watchers = [];
+	/** Callback invoked when cache is invalidated due to file changes */
+	onCacheInvalidated;
 	/**
 	* Creates a new SkillService instance
 	* @param cwd - Current working directory for resolving relative paths
 	* @param skillPaths - Array of paths to skills directories
+	* @param options - Optional configuration
+	* @param options.onCacheInvalidated - Callback invoked when cache is invalidated due to file changes
 	*/
-	constructor(cwd, skillPaths) {
+	constructor(cwd, skillPaths, options) {
 		this.cwd = cwd;
 		this.skillPaths = skillPaths;
+		this.onCacheInvalidated = options?.onCacheInvalidated;
 	}
 	/**
 	* Get all available skills from configured directories.
@@ -1121,13 +1416,13 @@ var SkillService = class {
 		if (this.cachedSkills !== null) return this.cachedSkills;
 		const skills = [];
 		const loadedSkillNames = /* @__PURE__ */ new Set();
-		for (const skillPath of this.skillPaths) {
+		const allDirSkills = await Promise.all(this.skillPaths.map(async (skillPath) => {
 			const skillsDir = (0, node_path.isAbsolute)(skillPath) ? skillPath : (0, node_path.join)(this.cwd, skillPath);
-			const dirSkills = await this.loadSkillsFromDirectory(skillsDir, "project");
-			for (const skill of dirSkills) if (!loadedSkillNames.has(skill.name)) {
-				skills.push(skill);
-				loadedSkillNames.add(skill.name);
-			}
+			return this.loadSkillsFromDirectory(skillsDir, "project");
+		}));
+		for (const dirSkills of allDirSkills) for (const skill of dirSkills) if (!loadedSkillNames.has(skill.name)) {
+			skills.push(skill);
+			loadedSkillNames.add(skill.name);
 		}
 		this.cachedSkills = skills;
 		this.skillsByName = new Map(skills.map((skill) => [skill.name, skill]));
@@ -1151,6 +1446,60 @@ var SkillService = class {
 		this.skillsByName = null;
 	}
 	/**
+	* Starts watching skill directories for changes to SKILL.md files.
+	* When changes are detected, the cache is automatically invalidated.
+	*
+	* Uses Node.js fs.watch with recursive option for efficient directory monitoring.
+	* Only invalidates cache when SKILL.md files are modified.
+	*
+	* @example
+	* const skillService = new SkillService(cwd, skillPaths, {
+	*   onCacheInvalidated: () => console.log('Skills cache invalidated')
+	* });
+	* await skillService.startWatching();
+	*/
+	async startWatching() {
+		this.stopWatching();
+		const existenceChecks = await Promise.all(this.skillPaths.map(async (skillPath) => {
+			const skillsDir = (0, node_path.isAbsolute)(skillPath) ? skillPath : (0, node_path.join)(this.cwd, skillPath);
+			return {
+				skillsDir,
+				exists: await pathExists(skillsDir)
+			};
+		}));
+		for (const { skillsDir, exists } of existenceChecks) {
+			if (!exists) continue;
+			const abortController = new AbortController();
+			this.watchers.push(abortController);
+			this.watchDirectory(skillsDir, abortController.signal).catch((error) => {
+				if (error?.name !== "AbortError") console.error(`[skill-watcher] Error watching ${skillsDir}: ${error instanceof Error ? error.message : "Unknown error"}`);
+			});
+		}
+	}
+	/**
+	* Stops all active file watchers.
+	* Should be called when the service is being disposed.
+	*/
+	stopWatching() {
+		for (const controller of this.watchers) controller.abort();
+		this.watchers = [];
+	}
+	/**
+	* Watches a directory for changes to SKILL.md files.
+	* @param dirPath - Directory path to watch
+	* @param signal - AbortSignal to stop watching
+	*/
+	async watchDirectory(dirPath, signal) {
+		const watcher = (0, node_fs_promises.watch)(dirPath, {
+			recursive: true,
+			signal
+		});
+		for await (const event of watcher) if (event.filename && event.filename.endsWith("SKILL.md")) {
+			this.clearCache();
+			this.onCacheInvalidated?.();
+		}
+	}
+	/**
 	* Load skills from a directory.
 	* Supports both flat structure (SKILL.md) and nested structure (name/SKILL.md).
 	*
@@ -1177,38 +1526,54 @@ var SkillService = class {
 		} catch (error) {
 			throw new SkillLoadError(`Failed to read skills directory: ${error instanceof Error ? error.message : "Unknown error"}`, dirPath, error instanceof Error ? error : void 0);
 		}
-		for (const entry of entries) {
+		const entryStats = await Promise.all(entries.map(async (entry) => {
 			const entryPath = (0, node_path.join)(dirPath, entry);
-			let entryStat;
 			try {
-				entryStat = await (0, node_fs_promises.stat)(entryPath);
+				return {
+					entry,
+					entryPath,
+					stat: await (0, node_fs_promises.stat)(entryPath),
+					error: null
+				};
 			} catch (error) {
 				console.warn(`Skipping entry ${entryPath}: ${error instanceof Error ? error.message : "Unknown error"}`);
-				continue;
+				return {
+					entry,
+					entryPath,
+					stat: null,
+					error
+				};
 			}
+		}));
+		const skillFilesToLoad = [];
+		for (const { entry, entryPath, stat: entryStat } of entryStats) {
+			if (!entryStat) continue;
 			if (entryStat.isDirectory()) {
 				const skillFilePath = (0, node_path.join)(entryPath, "SKILL.md");
-				try {
-					if (await pathExists(skillFilePath)) {
-						const skill = await this.loadSkillFile(skillFilePath, location);
-						if (skill) skills.push(skill);
-					}
-				} catch (error) {
-					console.warn(`Skipping skill at ${skillFilePath}: ${error instanceof Error ? error.message : "Unknown error"}`);
-					continue;
-				}
-			} else if (entry === "SKILL.md") try {
-				const skill = await this.loadSkillFile(entryPath, location);
-				if (skill) skills.push(skill);
+				skillFilesToLoad.push({
+					filePath: skillFilePath,
+					isRootLevel: false
+				});
+			} else if (entry === "SKILL.md") skillFilesToLoad.push({
+				filePath: entryPath,
+				isRootLevel: true
+			});
+		}
+		const loadResults = await Promise.all(skillFilesToLoad.map(async ({ filePath, isRootLevel }) => {
+			try {
+				if (!isRootLevel && !await pathExists(filePath)) return null;
+				return await this.loadSkillFile(filePath, location);
 			} catch (error) {
-				console.warn(`Skipping skill at ${entryPath}: ${error instanceof Error ? error.message : "Unknown error"}`);
-				continue;
+				console.warn(`Skipping skill at ${filePath}: ${error instanceof Error ? error.message : "Unknown error"}`);
+				return null;
 			}
-		}
+		}));
+		for (const skill of loadResults) if (skill) skills.push(skill);
 		return skills;
 	}
 	/**
 	* Load a single skill file and parse its frontmatter.
+	* Supports multi-line YAML values using literal (|) and folded (>) block scalars.
 	*
 	* @param filePath - Path to the SKILL.md file
 	* @param location - Whether this is a 'project' or 'user' skill
@@ -1222,150 +1587,67 @@ var SkillService = class {
 	* // Returns null if frontmatter is missing name or description
 	*/
 	async loadSkillFile(filePath, location) {
-		let content;
+		let fileContent;
 		try {
-			content = await (0, node_fs_promises.readFile)(filePath, "utf-8");
+			fileContent = await (0, node_fs_promises.readFile)(filePath, "utf-8");
 		} catch (error) {
 			throw new SkillLoadError(`Failed to read skill file: ${error instanceof Error ? error.message : "Unknown error"}`, filePath, error instanceof Error ? error : void 0);
 		}
-		const { metadata, body } = this.parseFrontmatter(content);
-		if (!metadata.name || !metadata.description) return null;
+		const { frontMatter, content } = parseFrontMatter(fileContent);
+		if (!frontMatter || !frontMatter.name || !frontMatter.description) return null;
 		return {
-			name: metadata.name,
-			description: metadata.description,
+			name: frontMatter.name,
+			description: frontMatter.description,
 			location,
-			content: body,
+			content,
 			basePath: (0, node_path.dirname)(filePath)
 		};
 	}
-	/**
-	* Parse YAML frontmatter from markdown content.
-	* Frontmatter is delimited by --- at start and end.
-	*
-	* @param content - Full markdown content with frontmatter
-	* @returns Parsed metadata and body content
-	*
-	* @example
-	* // Input content:
-	* // ---
-	* // name: my-skill
-	* // description: A sample skill
-	* // ---
-	* // # Skill Content
-	* // This is the skill body.
-	*
-	* const result = parseFrontmatter(content);
-	* // result.metadata = { name: 'my-skill', description: 'A sample skill' }
-	* // result.body = '# Skill Content\nThis is the skill body.'
-	*/
-	parseFrontmatter(content) {
-		const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
-		if (!match) return {
-			metadata: {},
-			body: content
-		};
-		const [, frontmatter, body] = match;
-		const metadata = {};
-		const lines = frontmatter.split("\n");
-		for (const line of lines) {
-			const colonIndex = line.indexOf(":");
-			if (colonIndex > 0) {
-				const key = line.slice(0, colonIndex).trim();
-				let value = line.slice(colonIndex + 1).trim();
-				if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
-				if (key === "name" || key === "description" || key === "license") metadata[key] = value;
-			}
-		}
-		return {
-			metadata,
-			body: body.trim()
-		};
-	}
 };
 
 //#endregion
-//#region src/utils/findConfigFile.ts
+//#region src/constants/index.ts
 /**
-* Config File Finder Utility
-*
-* DESIGN PATTERNS:
-* - Utility function pattern for reusable logic
-* - Fail-fast pattern with early returns
-* - Environment variable configuration pattern
-*
-* CODING STANDARDS:
-* - Use sync filesystem operations for config discovery (performance)
-* - Check PROJECT_PATH environment variable first
-* - Fall back to current working directory
-* - Support both .yaml and .json extensions
-* - Return null if no config file is found
-*
-* AVOID:
-* - Throwing errors (return null instead for optional config)
-* - Hardcoded file names without extension variants
-* - Ignoring environment variables
+* Shared constants for one-mcp package
 */
 /**
-* Find MCP configuration file by checking PROJECT_PATH first, then cwd
-* Looks for both mcp-config.yaml and mcp-config.json
-*
-* @returns Absolute path to config file, or null if not found
+* Prefix added to skill names when they clash with MCP tool names.
+* This ensures skills can be uniquely identified even when a tool has the same name.
 */
-function findConfigFile() {
-	const configFileNames = [
-		"mcp-config.yaml",
-		"mcp-config.yml",
-		"mcp-config.json"
-	];
-	const projectPath = process.env.PROJECT_PATH;
-	if (projectPath) for (const fileName of configFileNames) {
-		const configPath = (0, node_path.resolve)(projectPath, fileName);
-		if ((0, node_fs.existsSync)(configPath)) return configPath;
-	}
-	const cwd = process.cwd();
-	for (const fileName of configFileNames) {
-		const configPath = (0, node_path.join)(cwd, fileName);
-		if ((0, node_fs.existsSync)(configPath)) return configPath;
-	}
-	return null;
-}
-
-//#endregion
-//#region src/utils/parseToolName.ts
+const SKILL_PREFIX = "skill__";
 /**
-* Parse tool name to extract server and actual tool name
-* Supports both plain tool names and prefixed format: {serverName}__{toolName}
-*
-* @param toolName - The tool name to parse (e.g., "my_tool" or "server__my_tool")
-* @returns Parsed result with optional serverName and actualToolName
-*
-* @example
-* parseToolName("my_tool") // { actualToolName: "my_tool" }
-* parseToolName("server__my_tool") // { serverName: "server", actualToolName: "my_tool" }
+* Log prefix for skill detection messages.
+* Used to easily filter skill detection logs in stderr output.
 */
-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/templates/skills-description.liquid?raw
-var skills_description_default = "{% if skills.size > 0 %}\n<skills>\n<instructions>\nWhen users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.\n\nHow to use skills:\n- Invoke skills using this tool with the skill name only (no arguments)\n- When you invoke a skill, you will see <command-message>The \"{name}\" skill is loading</command-message>\n- The skill's prompt will expand and provide detailed instructions on how to complete the task\n- Examples:\n  - `skill: \"pdf\"` - invoke the pdf skill\n  - `skill: \"xlsx\"` - invoke the xlsx skill\n  - `skill: \"ms-office-suite:pdf\"` - invoke using fully qualified name\n\nImportant:\n- Only use skills listed in <available_skills> below\n- Do not invoke a skill that is already running\n- Do not use this tool for built-in CLI commands (like /help, /clear, etc.)\n</instructions>\n\n<available_skills>\n{% for skill in skills -%}\n<item><name>{{ skill.displayName }}</name><description>{{ skill.description }}</description></item>\n{% endfor -%}\n</available_skills>\n</skills>\n{% endif %}\n";
+const LOG_PREFIX_SKILL_DETECTION = "[skill-detection]";
+/**
+* Prefix for prompt-based skill locations.
+* Format: "prompt:{serverName}:{promptName}"
+*/
+const PROMPT_LOCATION_PREFIX = "prompt:";
+/**
+* Default server ID used when no ID is provided via CLI or config.
+* This fallback is used when auto-generation also fails.
+*/
+const DEFAULT_SERVER_ID = "unknown";
 
 //#endregion
-//#region src/templates/mcp-servers-description.liquid?raw
-var mcp_servers_description_default = "<mcp_servers>\n<instructions>\nBefore you use any tools above, you MUST call this tool with a list of tool names to learn how to use them properly before use_tool; this includes:\n- Arguments schema needed to pass to the tool use\n- Description about each tool\n\nThis tool is optimized for batch queries - you can request multiple tools at once for better performance.\n</instructions>\n\n{% for server in servers -%}\n<server name=\"{{ server.name }}\">\n{% if server.instruction -%}\n<instruction>{{ server.instruction }}</instruction>\n{% endif -%}\n<tools>\n{% if server.omitToolDescription -%}\n{{ server.toolNames | join: \", \" }}\n{% else -%}\n{% for tool in server.tools -%}\n<item><name>{{ tool.displayName }}</name><description>{{ tool.description | default: \"No description\" }}</description></item>\n{% endfor -%}\n{% endif -%}\n</tools>\n</server>\n{% endfor -%}\n</mcp_servers>\n";
+//#region src/templates/toolkit-description.liquid?raw
+var toolkit_description_default = "<toolkit id=\"{{ serverId }}\">\n<instruction>\nBefore you use any capabilities below, you MUST call this tool with a list of names to learn how to use them properly; this includes:\n- For tools: Arguments schema needed to pass to use_tool\n- For skills: Detailed instructions that will expand when invoked (Prefer to be explored first when relevant)\n\nThis tool is optimized for batch queries - you can request multiple capabilities at once for better performance.\n\nHow to invoke:\n- For MCP tools: Use use_tool with toolName and toolArgs based on the schema\n- For skills: Use this tool with the skill name to get expanded instructions\n</instruction>\n\n<available_capabilities>\n{% for server in servers -%}\n<group name=\"{{ server.name }}\">\n{% if server.instruction -%}\n<group_instruction>{{ server.instruction }}</group_instruction>\n{% endif -%}\n{% if server.omitToolDescription -%}\n{% for toolName in server.toolNames -%}\n<item name=\"{{ toolName }}\"></item>\n{% endfor -%}\n{% else -%}\n{% for tool in server.tools -%}\n<item name=\"{{ tool.displayName }}\"><description>{{ tool.description | default: \"No description\" }}</description></item>\n{% endfor -%}\n{% endif -%}\n</group>\n{% endfor -%}\n{% if skills.size > 0 -%}\n<group name=\"skills\">\n{% for skill in skills -%}\n<item name=\"{{ skill.displayName }}\"><description>{{ skill.description }}</description></item>\n{% endfor -%}\n</group>\n{% endif -%}\n</available_capabilities>\n</toolkit>\n";
 
 //#endregion
 //#region src/tools/DescribeToolsTool.ts
 /**
-* Prefix used to identify skill invocations
+* Formats skill instructions with the loading command message prefix.
+* This message is used by Claude Code to indicate that a skill is being loaded.
+*
+* @param name - The skill name
+* @param instructions - The raw skill instructions/content
+* @returns Formatted instructions with command message prefix
 */
-const SKILL_PREFIX$1 = "skill__";
+function formatSkillInstructions(name, instructions) {
+	return `<command-message>The "${name}" skill is loading</command-message>\n${instructions}`;
+}
 /**
 * DescribeToolsTool provides progressive disclosure of MCP tools and skills.
 *
@@ -1388,22 +1670,93 @@ var DescribeToolsTool = class DescribeToolsTool {
 	clientManager;
 	skillService;
 	liquid = new liquidjs.Liquid();
+	/** Cache for auto-detected skills from prompt front-matter */
+	autoDetectedSkillsCache = null;
+	/** Unique server identifier for this one-mcp instance */
+	serverId;
 	/**
 	* Creates a new DescribeToolsTool instance
 	* @param clientManager - The MCP client manager for accessing remote servers
 	* @param skillService - Optional skill service for loading skills
+	* @param serverId - Unique server identifier for this one-mcp instance
 	*/
-	constructor(clientManager, skillService) {
+	constructor(clientManager, skillService, serverId) {
 		this.clientManager = clientManager;
 		this.skillService = skillService;
+		this.serverId = serverId || DEFAULT_SERVER_ID;
+	}
+	/**
+	* Clears the cached auto-detected skills from prompt front-matter.
+	* Use this when prompt configurations may have changed or when
+	* the skill service cache is invalidated.
+	*/
+	clearAutoDetectedSkillsCache() {
+		this.autoDetectedSkillsCache = null;
+	}
+	/**
+	* 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.
-	* Prompts with a skill configuration are converted to skill format for display.
+	* Includes both explicitly configured prompts and auto-detected skills from front-matter.
 	*
 	* @returns Array of skill template data derived from prompts
 	*/
-	collectPromptSkills() {
+	async collectPromptSkills() {
 		const clients = this.clientManager.getAllClients();
 		const promptSkills = [];
 		for (const client of clients) {
@@ -1414,16 +1767,22 @@ var DescribeToolsTool = class DescribeToolsTool {
 				description: promptConfig.skill.description
 			});
 		}
+		const autoDetectedSkills = await this.detectSkillsFromPromptFrontMatter();
+		for (const autoSkill of autoDetectedSkills) promptSkills.push({
+			name: autoSkill.skill.name,
+			displayName: autoSkill.skill.name,
+			description: autoSkill.skill.description
+		});
 		return promptSkills;
 	}
 	/**
 	* Finds a prompt-based skill by name from all connected MCP servers.
-	* Returns the prompt name and skill config for fetching the prompt content.
+	* Searches both explicitly configured prompts and auto-detected skills from front-matter.
 	*
 	* @param skillName - The skill name to search for
 	* @returns Object with serverName, promptName, and skill config, or undefined if not found
 	*/
-	findPromptSkill(skillName) {
+	async findPromptSkill(skillName) {
 		if (!skillName) return void 0;
 		const clients = this.clientManager.getAllClients();
 		for (const client of clients) {
@@ -1434,16 +1793,24 @@ var DescribeToolsTool = class DescribeToolsTool {
 				skill: promptConfig.skill
 			};
 		}
+		const autoDetectedSkills = await this.detectSkillsFromPromptFrontMatter();
+		for (const autoSkill of autoDetectedSkills) if (autoSkill.skill.name === skillName) return {
+			serverName: autoSkill.serverName,
+			promptName: autoSkill.promptName,
+			skill: autoSkill.skill,
+			autoDetected: true
+		};
 	}
 	/**
 	* Retrieves skill content from a prompt-based skill configuration.
 	* Fetches the prompt from the MCP server and extracts text content.
+	* Handles both explicitly configured prompts and auto-detected skills from front-matter.
 	*
 	* @param skillName - The skill name being requested
 	* @returns SkillDescription if found and successfully fetched, undefined otherwise
 	*/
 	async getPromptSkillContent(skillName) {
-		const promptSkill = this.findPromptSkill(skillName);
+		const promptSkill = await this.findPromptSkill(skillName);
 		if (!promptSkill) return void 0;
 		const client = this.clientManager.getClient(promptSkill.serverName);
 		if (!client) {
@@ -1451,7 +1818,7 @@ var DescribeToolsTool = class DescribeToolsTool {
 			return;
 		}
 		try {
-			const instructions = (await client.getPrompt(promptSkill.promptName)).messages?.map((m) => {
+			const rawInstructions = (await client.getPrompt(promptSkill.promptName)).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);
@@ -1459,8 +1826,8 @@ var DescribeToolsTool = class DescribeToolsTool {
 			}).join("\n") || "";
 			return {
 				name: promptSkill.skill.name,
-				location: promptSkill.skill.folder || `prompt:${promptSkill.serverName}/${promptSkill.promptName}`,
-				instructions
+				location: promptSkill.skill.folder || `${PROMPT_LOCATION_PREFIX}${promptSkill.serverName}/${promptSkill.promptName}`,
+				instructions: formatSkillInstructions(promptSkill.skill.name, rawInstructions)
 			};
 		} catch (error) {
 			console.error(`Failed to get prompt-based skill '${skillName}': ${error instanceof Error ? error.message : "Unknown error"}`);
@@ -1468,49 +1835,18 @@ var DescribeToolsTool = class DescribeToolsTool {
 		}
 	}
 	/**
-	* Builds the skills section of the tool description using a Liquid template.
+	* Builds the combined toolkit description using a single Liquid template.
 	*
-	* Retrieves all available skills from the SkillService and prompt-based skills,
-	* then renders them using the skills-description.liquid template. Skills are only
-	* prefixed with skill__ when their name clashes with an MCP tool or another skill.
-	*
-	* @param mcpToolNames - Set of MCP tool names to check for clashes
-	* @returns Rendered skills section string with available skills list
-	*/
-	async buildSkillsSection(mcpToolNames) {
-		const rawSkills = this.skillService ? await this.skillService.getSkills() : [];
-		const promptSkills = this.collectPromptSkills();
-		const allSkillsData = [...rawSkills.map((skill) => ({
-			name: skill.name,
-			displayName: skill.name,
-			description: skill.description
-		})), ...promptSkills];
-		const skillNameCounts = /* @__PURE__ */ new Map();
-		for (const skill of allSkillsData) skillNameCounts.set(skill.name, (skillNameCounts.get(skill.name) || 0) + 1);
-		const skills = allSkillsData.map((skill) => {
-			const clashesWithMcpTool = mcpToolNames.has(skill.name);
-			const clashesWithOtherSkill = (skillNameCounts.get(skill.name) || 0) > 1;
-			const needsPrefix = clashesWithMcpTool || clashesWithOtherSkill;
-			return {
-				name: skill.name,
-				displayName: needsPrefix ? `${SKILL_PREFIX$1}${skill.name}` : skill.name,
-				description: skill.description
-			};
-		});
-		return this.liquid.parseAndRender(skills_description_default, { skills });
-	}
-	/**
-	* Builds the MCP servers section of the tool description using a Liquid template.
-	*
-	* Collects all tools from connected MCP servers, detects name clashes,
-	* and renders them using the mcp-servers-description.liquid template.
+	* Collects all tools from connected MCP servers and all skills, then renders
+	* them together using the toolkit-description.liquid template.
 	*
 	* Tool names are prefixed with serverName__ when the same tool exists
-	* on multiple servers to avoid ambiguity.
+	* on multiple servers. Skill names are prefixed with skill__ when they
+	* clash with MCP tools or other skills.
 	*
-	* @returns Object with rendered servers section and set of all tool names for skill clash detection
+	* @returns Object with rendered description and set of all tool names
 	*/
-	async buildServersSection() {
+	async buildToolkitDescription() {
 		const clients = this.clientManager.getAllClients();
 		const toolToServers = /* @__PURE__ */ new Map();
 		const serverToolsMap = /* @__PURE__ */ new Map();
@@ -1531,9 +1867,6 @@ var DescribeToolsTool = class DescribeToolsTool {
 		}));
 		/**
 		* Formats tool name with server prefix if the tool exists on multiple servers
-		* @param toolName - The original tool name
-		* @param serverName - The server providing this tool
-		* @returns Tool name prefixed with serverName__ if clashing, otherwise plain name
 		*/
 		const formatToolName = (toolName, serverName) => {
 			return (toolToServers.get(toolName) || []).length > 1 ? `${serverName}__${toolName}` : toolName;
@@ -1553,31 +1886,57 @@ var DescribeToolsTool = class DescribeToolsTool {
 				toolNames: formattedTools.map((t) => t.displayName)
 			};
 		});
+		const rawSkills = this.skillService ? await this.skillService.getSkills() : [];
+		const promptSkills = await this.collectPromptSkills();
+		const seenSkillNames = /* @__PURE__ */ new Set();
+		const allSkillsData = [];
+		for (const skill of rawSkills) if (!seenSkillNames.has(skill.name)) {
+			seenSkillNames.add(skill.name);
+			allSkillsData.push({
+				name: skill.name,
+				displayName: skill.name,
+				description: skill.description
+			});
+		}
+		for (const skill of promptSkills) if (!seenSkillNames.has(skill.name)) {
+			seenSkillNames.add(skill.name);
+			allSkillsData.push(skill);
+		}
+		const skills = allSkillsData.map((skill) => {
+			const clashesWithMcpTool = allToolNames.has(skill.name);
+			return {
+				name: skill.name,
+				displayName: clashesWithMcpTool ? `${SKILL_PREFIX}${skill.name}` : skill.name,
+				description: skill.description
+			};
+		});
 		return {
-			content: await this.liquid.parseAndRender(mcp_servers_description_default, { servers }),
+			content: await this.liquid.parseAndRender(toolkit_description_default, {
+				servers,
+				skills,
+				serverId: this.serverId
+			}),
 			toolNames: allToolNames
 		};
 	}
 	/**
-	* Gets the tool definition including available servers, tools, and skills.
+	* Gets the tool definition including available tools and skills in a unified format.
 	*
 	* The definition includes:
-	* - List of all connected MCP servers with their available tools
-	* - List of available skills with skill__ prefix
-	* - Usage instructions for querying tool/skill details
+	* - All MCP tools from connected servers
+	* - All available skills (file-based and prompt-based)
+	* - Unified instructions for querying capability details
 	*
-	* Tool names are prefixed with serverName__ when the same tool name
-	* exists on multiple servers to avoid ambiguity.
+	* Tool names are prefixed with serverName__ when clashing.
+	* Skill names are prefixed with skill__ when clashing.
 	*
 	* @returns Tool definition with description and input schema
 	*/
 	async getDefinition() {
-		const serversResult = await this.buildServersSection();
-		const skillsSection = await this.buildSkillsSection(serversResult.toolNames);
+		const { content } = await this.buildToolkitDescription();
 		return {
 			name: DescribeToolsTool.TOOL_NAME,
-			description: `${serversResult.content}
-${skillsSection}`,
+			description: content,
 			inputSchema: {
 				type: "object",
 				properties: { toolNames: {
@@ -1637,40 +1996,42 @@ ${skillsSection}`,
 					serverToolsMap.set(client.serverName, []);
 				}
 			}));
-			const foundTools = [];
-			const foundSkills = [];
-			const notFoundItems = [];
-			for (const requestedName of toolNames) {
-				if (requestedName.startsWith(SKILL_PREFIX$1)) {
-					const skillName = requestedName.slice(7);
+			const lookupResults = await Promise.all(toolNames.map(async (requestedName) => {
+				const result$1 = {
+					tools: [],
+					skills: [],
+					notFound: null
+				};
+				if (requestedName.startsWith(SKILL_PREFIX)) {
+					const skillName = requestedName.slice(SKILL_PREFIX.length);
 					if (this.skillService) {
 						const skill = await this.skillService.getSkill(skillName);
 						if (skill) {
-							foundSkills.push({
+							result$1.skills.push({
 								name: skill.name,
 								location: skill.basePath,
-								instructions: skill.content
+								instructions: formatSkillInstructions(skill.name, skill.content)
 							});
-							continue;
+							return result$1;
 						}
 					}
 					const promptSkillContent = await this.getPromptSkillContent(skillName);
 					if (promptSkillContent) {
-						foundSkills.push(promptSkillContent);
-						continue;
+						result$1.skills.push(promptSkillContent);
+						return result$1;
 					}
-					notFoundItems.push(requestedName);
-					continue;
+					result$1.notFound = requestedName;
+					return result$1;
 				}
 				const { serverName, actualToolName } = parseToolName(requestedName);
 				if (serverName) {
 					const serverTools = serverToolsMap.get(serverName);
 					if (!serverTools) {
-						notFoundItems.push(requestedName);
-						continue;
+						result$1.notFound = requestedName;
+						return result$1;
 					}
 					const tool = serverTools.find((t) => t.name === actualToolName);
-					if (tool) foundTools.push({
+					if (tool) result$1.tools.push({
 						server: serverName,
 						tool: {
 							name: tool.name,
@@ -1678,52 +2039,61 @@ ${skillsSection}`,
 							inputSchema: tool.inputSchema
 						}
 					});
-					else notFoundItems.push(requestedName);
-				} else {
-					const servers = toolToServers.get(actualToolName);
-					if (!servers || servers.length === 0) {
-						if (this.skillService) {
-							const skill = await this.skillService.getSkill(actualToolName);
-							if (skill) {
-								foundSkills.push({
-									name: skill.name,
-									location: skill.basePath,
-									instructions: skill.content
-								});
-								continue;
-							}
-						}
-						const promptSkillContent = await this.getPromptSkillContent(actualToolName);
-						if (promptSkillContent) {
-							foundSkills.push(promptSkillContent);
-							continue;
+					else result$1.notFound = requestedName;
+					return result$1;
+				}
+				const servers = toolToServers.get(actualToolName);
+				if (!servers || servers.length === 0) {
+					if (this.skillService) {
+						const skill = await this.skillService.getSkill(actualToolName);
+						if (skill) {
+							result$1.skills.push({
+								name: skill.name,
+								location: skill.basePath,
+								instructions: formatSkillInstructions(skill.name, skill.content)
+							});
+							return result$1;
 						}
-						notFoundItems.push(requestedName);
-						continue;
 					}
-					if (servers.length === 1) {
-						const server = servers[0];
-						const tool = serverToolsMap.get(server).find((t) => t.name === actualToolName);
-						foundTools.push({
-							server,
-							tool: {
-								name: tool.name,
-								description: tool.description,
-								inputSchema: tool.inputSchema
-							}
-						});
-					} else for (const server of servers) {
-						const tool = serverToolsMap.get(server).find((t) => t.name === actualToolName);
-						foundTools.push({
-							server,
-							tool: {
-								name: tool.name,
-								description: tool.description,
-								inputSchema: tool.inputSchema
-							}
-						});
+					const promptSkillContent = await this.getPromptSkillContent(actualToolName);
+					if (promptSkillContent) {
+						result$1.skills.push(promptSkillContent);
+						return result$1;
 					}
+					result$1.notFound = requestedName;
+					return result$1;
 				}
+				if (servers.length === 1) {
+					const server = servers[0];
+					const tool = serverToolsMap.get(server).find((t) => t.name === actualToolName);
+					result$1.tools.push({
+						server,
+						tool: {
+							name: tool.name,
+							description: tool.description,
+							inputSchema: tool.inputSchema
+						}
+					});
+				} else for (const server of servers) {
+					const tool = serverToolsMap.get(server).find((t) => t.name === actualToolName);
+					result$1.tools.push({
+						server,
+						tool: {
+							name: tool.name,
+							description: tool.description,
+							inputSchema: tool.inputSchema
+						}
+					});
+				}
+				return result$1;
+			}));
+			const foundTools = [];
+			const foundSkills = [];
+			const notFoundItems = [];
+			for (const result$1 of lookupResults) {
+				foundTools.push(...result$1.tools);
+				foundSkills.push(...result$1.skills);
+				if (result$1.notFound) notFoundItems.push(result$1.notFound);
 			}
 			if (foundTools.length === 0 && foundSkills.length === 0) return {
 				content: [{
@@ -1766,10 +2136,6 @@ ${skillsSection}`,
 //#endregion
 //#region src/tools/UseToolTool.ts
 /**
-* Prefix used to identify skill invocations (e.g., skill__pdf)
-*/
-const SKILL_PREFIX = "skill__";
-/**
 * UseToolTool executes MCP tools and skills with proper error handling.
 *
 * This tool supports three invocation patterns:
@@ -1786,14 +2152,18 @@ var UseToolTool = class UseToolTool {
 	static TOOL_NAME = "use_tool";
 	clientManager;
 	skillService;
+	/** Unique server identifier for this one-mcp instance */
+	serverId;
 	/**
 	* Creates a new UseToolTool instance
 	* @param clientManager - The MCP client manager for accessing remote servers
 	* @param skillService - Optional skill service for loading and executing skills
+	* @param serverId - Unique server identifier for this one-mcp instance
 	*/
-	constructor(clientManager, skillService) {
+	constructor(clientManager, skillService, serverId) {
 		this.clientManager = clientManager;
 		this.skillService = skillService;
+		this.serverId = serverId || DEFAULT_SERVER_ID;
 	}
 	/**
 	* Returns the MCP tool definition with name, description, and input schema.
@@ -1809,6 +2179,8 @@ var UseToolTool = class UseToolTool {
 			description: `Execute an MCP tool (NOT Skill) with provided arguments. You MUST call describe_tools first to discover the tool's correct arguments. Then to use tool:
 - Provide toolName and toolArgs based on the schema
 - If multiple servers provide the same tool, specify serverName
+
+IMPORTANT: Only use tools discovered from describe_tools with id="${this.serverId}".
 `,
 			inputSchema: {
 				type: "object",
@@ -1895,7 +2267,7 @@ var UseToolTool = class UseToolTool {
 		try {
 			const { toolName: inputToolName, toolArgs = {} } = input;
 			if (inputToolName.startsWith(SKILL_PREFIX)) {
-				const skillName = inputToolName.slice(7);
+				const skillName = inputToolName.slice(SKILL_PREFIX.length);
 				if (this.skillService) {
 					const skill = await this.skillService.getSkill(skillName);
 					if (skill) return this.executeSkill(skill);
@@ -2030,6 +2402,7 @@ async function createServer(options) {
 	} });
 	const clientManager = new McpClientManagerService();
 	let configSkills;
+	let configId;
 	if (options?.configFilePath) {
 		let config;
 		try {
@@ -2041,6 +2414,7 @@ async function createServer(options) {
 			throw new Error(`Failed to load MCP configuration from '${options.configFilePath}': ${error instanceof Error ? error.message : String(error)}`);
 		}
 		configSkills = config.skills;
+		configId = config.id;
 		const failedConnections = [];
 		const connectionPromises = Object.entries(config.mcpServers).map(async ([serverName, serverConfig]) => {
 			try {
@@ -2059,10 +2433,19 @@ async function createServer(options) {
 		if (failedConnections.length > 0 && failedConnections.length < Object.keys(config.mcpServers).length) console.error(`Warning: Some MCP server connections failed: ${failedConnections.map((f) => f.serverName).join(", ")}`);
 		if (failedConnections.length > 0 && failedConnections.length === Object.keys(config.mcpServers).length) throw new Error(`All MCP server connections failed: ${failedConnections.map((f) => `${f.serverName}: ${f.error.message}`).join(", ")}`);
 	}
+	const serverId = options?.serverId || configId || generateServerId();
+	console.error(`[one-mcp] Server ID: ${serverId}`);
 	const skillsConfig = options?.skills || configSkills;
-	const skillService = skillsConfig && skillsConfig.paths.length > 0 ? new SkillService(process.cwd(), skillsConfig.paths) : void 0;
-	const describeTools = new DescribeToolsTool(clientManager, skillService);
-	const useTool = new UseToolTool(clientManager, skillService);
+	const toolsRef = { describeTools: null };
+	const skillService = skillsConfig && skillsConfig.paths.length > 0 ? new SkillService(process.cwd(), skillsConfig.paths, { onCacheInvalidated: () => {
+		toolsRef.describeTools?.clearAutoDetectedSkillsCache();
+	} }) : void 0;
+	const describeTools = new DescribeToolsTool(clientManager, skillService, serverId);
+	const useTool = new UseToolTool(clientManager, skillService, serverId);
+	toolsRef.describeTools = describeTools;
+	if (skillService) skillService.startWatching().catch((error) => {
+		console.error(`[skill-watcher] File watcher failed (non-critical): ${error instanceof Error ? error.message : "Unknown error"}`);
+	});
 	server.setRequestHandler(__modelcontextprotocol_sdk_types_js.ListToolsRequestSchema, async () => ({ tools: [await describeTools.getDefinition(), useTool.getDefinition()] }));
 	server.setRequestHandler(__modelcontextprotocol_sdk_types_js.CallToolRequestSchema, async (request) => {
 		const { name, arguments: args } = request.params;