@agiflowai/one-mcp 0.2.4 → 0.2.5

package/dist/{http-CzQfsUEI.mjs → http-BKDyW8YB.mjs}

@@ -1,15 +1,16 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
-import { mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, readdir, stat, unlink, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import yaml from "js-yaml";
 import { z } from "zod";
 import { createHash, randomUUID } from "node:crypto";
-import { join, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { Liquid } from "liquidjs";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import express from "express";
@@ -216,11 +217,16 @@ const RemoteConfigSourceSchema = z.object({
 	]).optional()
 });
 /**
+* Skills configuration schema
+*/
+const SkillsConfigSchema = z.object({ paths: z.array(z.string()) });
+/**
 * Full Claude Code MCP configuration schema
 */
 const ClaudeCodeMcpConfigSchema = z.object({
 	mcpServers: z.record(z.string(), ClaudeCodeServerConfigSchema),
-	remoteConfigs: z.array(RemoteConfigSourceSchema).optional()
+	remoteConfigs: z.array(RemoteConfigSourceSchema).optional(),
+	skills: SkillsConfigSchema.optional()
 });
 /**
 * Internal MCP config format
@@ -268,7 +274,10 @@ const McpServerConfigSchema = z.discriminatedUnion("transport", [
 /**
 * Full internal MCP configuration schema
 */
-const InternalMcpConfigSchema = z.object({ mcpServers: z.record(z.string(), McpServerConfigSchema) });
+const InternalMcpConfigSchema = z.object({
+	mcpServers: z.record(z.string(), McpServerConfigSchema),
+	skills: SkillsConfigSchema.optional()
+});
 /**
 * Transform Claude Code config to internal format
 * Converts standard Claude Code MCP configuration to normalized internal format
@@ -315,7 +324,10 @@ function transformClaudeCodeConfig(claudeConfig) {
 			};
 		}
 	}
-	return { mcpServers: transformedServers };
+	return {
+		mcpServers: transformedServers,
+		skills: claudeConfig.skills
+	};
 }
 /**
 * Parse and validate MCP config from raw JSON
@@ -951,6 +963,261 @@ var McpClientManagerService = class {
 	}
 };
 
+//#endregion
+//#region src/services/SkillService.ts
+/**
+* SkillService
+*
+* DESIGN PATTERNS:
+* - Service pattern for business logic encapsulation
+* - Single responsibility principle
+* - Lazy loading pattern for skill discovery
+*
+* 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)
+*/
+/**
+* Error thrown when skill loading fails
+*/
+var SkillLoadError = class extends Error {
+	constructor(message, filePath, cause) {
+		super(message);
+		this.filePath = filePath;
+		this.cause = cause;
+		this.name = "SkillLoadError";
+	}
+};
+/**
+* Check if a path exists asynchronously
+* @param path - Path to check
+* @returns true if path exists, false otherwise
+* @throws Error for unexpected filesystem errors (permission denied, etc.)
+*/
+async function pathExists(path) {
+	try {
+		await access(path);
+		return true;
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+		throw new Error(`Failed to check path existence for "${path}": ${error instanceof Error ? error.message : "Unknown error"}`);
+	}
+}
+/**
+* Service for loading and managing skills from configured skill directories.
+*
+* Skills are markdown files with YAML frontmatter that can be invoked via
+* the skill__ prefix in describe_tools and use_tool.
+*
+* Skills are only enabled when explicitly configured via the `skills.paths` array
+* in the MCP config.
+*
+* @example
+* // Config with skills enabled:
+* // skills:
+* //   paths:
+* //     - ".claude/skills"
+* //     - "/absolute/path/to/skills"
+*
+* const skillService = new SkillService('/project/root', ['.claude/skills']);
+* const skills = await skillService.getSkills();
+*/
+var SkillService = class {
+	cwd;
+	skillPaths;
+	cachedSkills = null;
+	skillsByName = null;
+	/**
+	* Creates a new SkillService instance
+	* @param cwd - Current working directory for resolving relative paths
+	* @param skillPaths - Array of paths to skills directories
+	*/
+	constructor(cwd, skillPaths) {
+		this.cwd = cwd;
+		this.skillPaths = skillPaths;
+	}
+	/**
+	* Get all available skills from configured directories.
+	* Results are cached after first load.
+	*
+	* Skills from earlier entries in the config take precedence over
+	* skills with the same name from later entries.
+	*
+	* @returns Array of loaded skills
+	* @throws SkillLoadError if a critical error occurs during loading
+	*/
+	async getSkills() {
+		if (this.cachedSkills !== null) return this.cachedSkills;
+		const skills = [];
+		const loadedSkillNames = /* @__PURE__ */ new Set();
+		for (const skillPath of this.skillPaths) {
+			const skillsDir = isAbsolute(skillPath) ? skillPath : 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);
+			}
+		}
+		this.cachedSkills = skills;
+		this.skillsByName = new Map(skills.map((skill) => [skill.name, skill]));
+		return skills;
+	}
+	/**
+	* Get a specific skill by name with O(1) lookup from cache.
+	* @param name - The skill name (without skill__ prefix)
+	* @returns The skill if found, undefined otherwise
+	*/
+	async getSkill(name) {
+		if (this.skillsByName === null) await this.getSkills();
+		return this.skillsByName?.get(name);
+	}
+	/**
+	* Clears the cached skills to force a fresh reload on the next getSkills() or getSkill() call.
+	* Use this when skill files have been modified on disk.
+	*/
+	clearCache() {
+		this.cachedSkills = null;
+		this.skillsByName = null;
+	}
+	/**
+	* Load skills from a directory.
+	* Supports both flat structure (SKILL.md) and nested structure (name/SKILL.md).
+	*
+	* @param dirPath - Path to the skills directory
+	* @param location - Whether this is a 'project' or 'user' skill directory
+	* @returns Array of successfully loaded skills (skips invalid skills)
+	* @throws SkillLoadError if there's a critical I/O error
+	*
+	* @example
+	* // Load skills from project directory
+	* const skills = await this.loadSkillsFromDirectory('/path/to/.claude/skills', 'project');
+	* // Returns: [{ name: 'pdf', description: '...', location: 'project', ... }]
+	*/
+	async loadSkillsFromDirectory(dirPath, location) {
+		const skills = [];
+		try {
+			if (!await pathExists(dirPath)) return skills;
+		} catch (error) {
+			throw new SkillLoadError(`Cannot access skills directory: ${error instanceof Error ? error.message : "Unknown error"}`, dirPath, error instanceof Error ? error : void 0);
+		}
+		let entries;
+		try {
+			entries = await readdir(dirPath);
+		} 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 entryPath = join(dirPath, entry);
+			let entryStat;
+			try {
+				entryStat = await stat(entryPath);
+			} catch (error) {
+				console.warn(`Skipping entry ${entryPath}: ${error instanceof Error ? error.message : "Unknown error"}`);
+				continue;
+			}
+			if (entryStat.isDirectory()) {
+				const skillFilePath = 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);
+			} catch (error) {
+				console.warn(`Skipping skill at ${entryPath}: ${error instanceof Error ? error.message : "Unknown error"}`);
+				continue;
+			}
+		}
+		return skills;
+	}
+	/**
+	* Load a single skill file and parse its frontmatter.
+	*
+	* @param filePath - Path to the SKILL.md file
+	* @param location - Whether this is a 'project' or 'user' skill
+	* @returns The loaded skill, or null if the file is invalid (missing required frontmatter)
+	* @throws SkillLoadError if there's an I/O error reading the file
+	*
+	* @example
+	* // Load a skill from a file
+	* const skill = await this.loadSkillFile('/path/to/pdf/SKILL.md', 'project');
+	* // Returns: { name: 'pdf', description: 'PDF skill', location: 'project', content: '...', basePath: '/path/to/pdf' }
+	* // Returns null if frontmatter is missing name or description
+	*/
+	async loadSkillFile(filePath, location) {
+		let content;
+		try {
+			content = await 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;
+		return {
+			name: metadata.name,
+			description: metadata.description,
+			location,
+			content: body,
+			basePath: 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
 /**
@@ -1020,15 +1287,89 @@ function parseToolName(toolName) {
 	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<skill-item><name>{{ skill.displayName }}</name><description>{{ skill.description }}</description></skill-item>\n{% endfor -%}\n</available_skills>\n</skills>\n{% endif %}\n\n<usage_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</usage_instructions>\n";
+
+//#endregion
+//#region src/templates/mcp-servers-description.liquid?raw
+var mcp_servers_description_default = "<mcp_servers>\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<tool-item><name>{{ tool.displayName }}</name><description>{{ tool.description | default: \"No description\" }}</description></tool-item>\n{% endfor -%}\n{% endif -%}\n</tools>\n</server>\n{% endfor -%}\n</mcp_servers>\n";
+
 //#endregion
 //#region src/tools/DescribeToolsTool.ts
+/**
+* Prefix used to identify skill invocations
+*/
+const SKILL_PREFIX$1 = "skill__";
+/**
+* DescribeToolsTool provides progressive disclosure of MCP tools and skills.
+*
+* This tool lists available tools from all connected MCP servers and skills
+* from the configured skills directories. Users can query for specific tools
+* or skills to get detailed input schemas and descriptions.
+*
+* Tool naming conventions:
+* - Unique tools: use plain name (e.g., "browser_click")
+* - Clashing tools: use serverName__toolName format (e.g., "playwright__click")
+* - Skills: use skill__skillName format (e.g., "skill__pdf")
+*
+* @example
+* const tool = new DescribeToolsTool(clientManager, skillService);
+* const definition = await tool.getDefinition();
+* const result = await tool.execute({ toolNames: ['browser_click', 'skill__pdf'] });
+*/
 var DescribeToolsTool = class DescribeToolsTool {
 	static TOOL_NAME = "describe_tools";
 	clientManager;
-	constructor(clientManager) {
+	skillService;
+	liquid = new Liquid();
+	/**
+	* Creates a new DescribeToolsTool instance
+	* @param clientManager - The MCP client manager for accessing remote servers
+	* @param skillService - Optional skill service for loading skills
+	*/
+	constructor(clientManager, skillService) {
 		this.clientManager = clientManager;
+		this.skillService = skillService;
 	}
-	async getDefinition() {
+	/**
+	* Builds the skills section of the tool description using a Liquid template.
+	*
+	* Retrieves all available skills from the SkillService and 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 skillNameCounts = /* @__PURE__ */ new Map();
+		for (const skill of rawSkills) skillNameCounts.set(skill.name, (skillNameCounts.get(skill.name) || 0) + 1);
+		const skills = rawSkills.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.
+	*
+	* Tool names are prefixed with serverName__ when the same tool exists
+	* on multiple servers to avoid ambiguity.
+	*
+	* @returns Object with rendered servers section and set of all tool names for skill clash detection
+	*/
+	async buildServersSection() {
 		const clients = this.clientManager.getAllClients();
 		const toolToServers = /* @__PURE__ */ new Map();
 		const serverToolsMap = /* @__PURE__ */ new Map();
@@ -1047,30 +1388,63 @@ var DescribeToolsTool = class DescribeToolsTool {
 				serverToolsMap.set(client.serverName, []);
 			}
 		}));
-		const serverDescriptions = clients.map((client) => {
-			const tools = serverToolsMap.get(client.serverName) || [];
-			const formatToolName = (toolName) => {
-				return (toolToServers.get(toolName) || []).length > 1 ? `${client.serverName}__${toolName}` : toolName;
+		/**
+		* 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;
+		};
+		const allToolNames = /* @__PURE__ */ new Set();
+		const servers = clients.map((client) => {
+			const formattedTools = (serverToolsMap.get(client.serverName) || []).map((t) => ({
+				displayName: formatToolName(t.name, client.serverName),
+				description: t.description
+			}));
+			for (const tool of formattedTools) allToolNames.add(tool.displayName);
+			return {
+				name: client.serverName,
+				instruction: client.serverInstruction,
+				omitToolDescription: client.omitToolDescription || false,
+				tools: formattedTools,
+				toolNames: formattedTools.map((t) => t.displayName)
 			};
-			const toolList = client.omitToolDescription ? tools.map((t) => formatToolName(t.name)).join(", ") : tools.map((t) => `${formatToolName(t.name)}: """${t.description || "No description"}"""`).join("\n");
-			const instructionLine = client.serverInstruction ? `\n"""${client.serverInstruction}"""` : "";
-			return `\n\n### Server: ${client.serverName}${instructionLine}\n\n- Available tools:\n${toolList || "No tools available"}`;
 		});
+		return {
+			content: await this.liquid.parseAndRender(mcp_servers_description_default, { servers }),
+			toolNames: allToolNames
+		};
+	}
+	/**
+	* Gets the tool definition including available servers, tools, and skills.
+	*
+	* 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
+	*
+	* Tool names are prefixed with serverName__ when the same tool name
+	* exists on multiple servers to avoid ambiguity.
+	*
+	* @returns Tool definition with description and input schema
+	*/
+	async getDefinition() {
+		const serversResult = await this.buildServersSection();
+		const skillsSection = await this.buildSkillsSection(serversResult.toolNames);
 		return {
 			name: DescribeToolsTool.TOOL_NAME,
-			description: `## Available MCP Servers:${serverDescriptions.join("")}
-
-## Usage:
-Before 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:
-- Arguments schema needed to pass to the tool use
-- Description about each tool
-
-This tool is optimized for batch queries - you can request multiple tools at once for better performance.`,
+			description: `${serversResult.content}
+${skillsSection}`,
 			inputSchema: {
 				type: "object",
 				properties: { toolNames: {
 					type: "array",
-					items: { type: "string" },
+					items: {
+						type: "string",
+						minLength: 1
+					},
 					description: "List of tool names to get detailed information about",
 					minItems: 1
 				} },
@@ -1079,6 +1453,17 @@ This tool is optimized for batch queries - you can request multiple tools at onc
 			}
 		};
 	}
+	/**
+	* Executes tool description lookup for the requested tool and skill names.
+	*
+	* Handles three types of lookups:
+	* 1. skill__name - Returns skill information from SkillService
+	* 2. serverName__toolName - Returns tool from specific server
+	* 3. plainToolName - Returns tool(s) from all servers (multiple if clashing)
+	*
+	* @param input - Object containing toolNames array
+	* @returns CallToolResult with tool/skill descriptions or error
+	*/
 	async execute(input) {
 		try {
 			const { toolNames } = input;
@@ -1096,9 +1481,13 @@ This tool is optimized for batch queries - you can request multiple tools at onc
 				try {
 					const tools = await client.listTools();
 					const blacklist = new Set(client.toolBlacklist || []);
-					const filteredTools = tools.filter((t) => !blacklist.has(t.name));
-					serverToolsMap.set(client.serverName, filteredTools);
-					for (const tool of filteredTools) {
+					const typedTools = tools.filter((t) => !blacklist.has(t.name)).map((t) => ({
+						name: t.name,
+						description: t.description,
+						inputSchema: t.inputSchema
+					}));
+					serverToolsMap.set(client.serverName, typedTools);
+					for (const tool of typedTools) {
 						if (!toolToServers.has(tool.name)) toolToServers.set(tool.name, []);
 						toolToServers.get(tool.name).push(client.serverName);
 					}
@@ -1108,13 +1497,27 @@ This tool is optimized for batch queries - you can request multiple tools at onc
 				}
 			}));
 			const foundTools = [];
-			const notFoundTools = [];
-			for (const requestedToolName of toolNames) {
-				const { serverName, actualToolName } = parseToolName(requestedToolName);
+			const foundSkills = [];
+			const notFoundItems = [];
+			for (const requestedName of toolNames) {
+				if (requestedName.startsWith(SKILL_PREFIX$1)) {
+					const skillName = requestedName.slice(7);
+					if (this.skillService) {
+						const skill = await this.skillService.getSkill(skillName);
+						if (skill) foundSkills.push({
+							name: skill.name,
+							location: skill.basePath,
+							instructions: skill.content
+						});
+						else notFoundItems.push(requestedName);
+					} else notFoundItems.push(requestedName);
+					continue;
+				}
+				const { serverName, actualToolName } = parseToolName(requestedName);
 				if (serverName) {
 					const serverTools = serverToolsMap.get(serverName);
 					if (!serverTools) {
-						notFoundTools.push(requestedToolName);
+						notFoundItems.push(requestedName);
 						continue;
 					}
 					const tool = serverTools.find((t) => t.name === actualToolName);
@@ -1126,11 +1529,22 @@ This tool is optimized for batch queries - you can request multiple tools at onc
 							inputSchema: tool.inputSchema
 						}
 					});
-					else notFoundTools.push(requestedToolName);
+					else notFoundItems.push(requestedName);
 				} else {
 					const servers = toolToServers.get(actualToolName);
 					if (!servers || servers.length === 0) {
-						notFoundTools.push(requestedToolName);
+						if (this.skillService) {
+							const skill = await this.skillService.getSkill(actualToolName);
+							if (skill) {
+								foundSkills.push({
+									name: skill.name,
+									location: skill.basePath,
+									instructions: skill.content
+								});
+								continue;
+							}
+						}
+						notFoundItems.push(requestedName);
 						continue;
 					}
 					if (servers.length === 1) {
@@ -1157,17 +1571,27 @@ This tool is optimized for batch queries - you can request multiple tools at onc
 					}
 				}
 			}
-			if (foundTools.length === 0) return {
+			if (foundTools.length === 0 && foundSkills.length === 0) return {
 				content: [{
 					type: "text",
-					text: `None of the requested tools found on any connected server.\nRequested: ${toolNames.join(", ")}\nUse describe_tools to see available tools.`
+					text: `None of the requested tools/skills found.\nRequested: ${toolNames.join(", ")}\nUse describe_tools to see available tools and skills.`
 				}],
 				isError: true
 			};
-			const result = { tools: foundTools };
-			if (notFoundTools.length > 0) {
-				result.notFound = notFoundTools;
-				result.warnings = [`Tools not found: ${notFoundTools.join(", ")}`];
+			const result = {};
+			const nextSteps = [];
+			if (foundTools.length > 0) {
+				result.tools = foundTools;
+				nextSteps.push("For MCP tools: Use the use_tool function with toolName and toolArgs based on the inputSchema above.");
+			}
+			if (foundSkills.length > 0) {
+				result.skills = foundSkills;
+				nextSteps.push(`For skill, just follow skill's description to continue.`);
+			}
+			if (nextSteps.length > 0) result.nextSteps = nextSteps;
+			if (notFoundItems.length > 0) {
+				result.notFound = notFoundItems;
+				result.warnings = [`Items not found: ${notFoundItems.join(", ")}`];
 			}
 			return { content: [{
 				type: "text",
@@ -1187,12 +1611,44 @@ This tool is optimized for batch queries - you can request multiple tools at onc
 
 //#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:
+* 1. skill__skillName - Invokes a skill from the configured skills directory
+* 2. serverName__toolName - Invokes a tool on a specific MCP server
+* 3. plainToolName - Searches all servers for a unique tool match
+*
+* @example
+* const tool = new UseToolTool(clientManager, skillService);
+* await tool.execute({ toolName: 'skill__pdf' }); // Invoke a skill
+* await tool.execute({ toolName: 'playwright__browser_click', toolArgs: { ref: 'btn' } });
+*/
 var UseToolTool = class UseToolTool {
 	static TOOL_NAME = "use_tool";
 	clientManager;
-	constructor(clientManager) {
+	skillService;
+	/**
+	* 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
+	*/
+	constructor(clientManager, skillService) {
 		this.clientManager = clientManager;
+		this.skillService = skillService;
 	}
+	/**
+	* Returns the MCP tool definition with name, description, and input schema.
+	*
+	* The definition describes how to use this tool to execute MCP tools or skills,
+	* including the skill__ prefix format for skill invocations.
+	*
+	* @returns The tool definition conforming to MCP spec
+	*/
 	getDefinition() {
 		return {
 			name: UseToolTool.TOOL_NAME,
@@ -1205,7 +1661,8 @@ var UseToolTool = class UseToolTool {
 				properties: {
 					toolName: {
 						type: "string",
-						description: "Name of the tool to execute"
+						description: "Name of the tool to execute",
+						minLength: 1
 					},
 					toolArgs: {
 						type: "object",
@@ -1217,9 +1674,60 @@ var UseToolTool = class UseToolTool {
 			}
 		};
 	}
+	/**
+	* Returns guidance message for skill invocation.
+	*
+	* Skills are not executed via use_tool - they provide instructions that should
+	* be followed directly. This method returns a message directing users to use
+	* describe_tools to get the skill details and follow its instructions.
+	*
+	* @param skill - The skill that was requested
+	* @returns CallToolResult with guidance message
+	*/
+	executeSkill(skill) {
+		return { content: [{
+			type: "text",
+			text: `Skill "${skill.name}" found. Skills provide instructions and should not be executed via use_tool.\n\nUse describe_tools to view the skill details at: ${skill.basePath}\n\nThen follow the skill's instructions directly.`
+		}] };
+	}
+	/**
+	* Executes a tool or skill based on the provided input.
+	*
+	* Handles three invocation patterns:
+	* 1. skill__skillName - Routes to skill execution via SkillService
+	* 2. serverName__toolName - Routes to specific MCP server
+	* 3. plainToolName - Searches all servers for unique match
+	*
+	* Edge cases:
+	* - Returns error if skill not found when using skill__ prefix
+	* - Returns error if tool is blacklisted on target server
+	* - Returns disambiguation message if tool exists on multiple servers
+	*
+	* @param input - The tool/skill name and optional arguments
+	* @returns CallToolResult with execution output or error
+	*/
 	async execute(input) {
 		try {
 			const { toolName: inputToolName, toolArgs = {} } = input;
+			if (inputToolName.startsWith(SKILL_PREFIX)) {
+				const skillName = inputToolName.slice(7);
+				if (!this.skillService) return {
+					content: [{
+						type: "text",
+						text: `Skills are not configured. Cannot execute skill "${skillName}".`
+					}],
+					isError: true
+				};
+				const skill = await this.skillService.getSkill(skillName);
+				if (!skill) return {
+					content: [{
+						type: "text",
+						text: `Skill "${skillName}" not found. Use describe_tools to see available skills.`
+					}],
+					isError: true
+				};
+				return this.executeSkill(skill);
+			}
 			const clients = this.clientManager.getAllClients();
 			const { serverName, actualToolName } = parseToolName(inputToolName);
 			if (serverName) {
@@ -1261,13 +1769,19 @@ var UseToolTool = class UseToolTool {
 				return null;
 			}));
 			matchingServers.push(...results.filter((r) => r !== null));
-			if (matchingServers.length === 0) return {
-				content: [{
-					type: "text",
-					text: `Tool "${actualToolName}" not found on any connected server. Use describe_tools to see available tools.`
-				}],
-				isError: true
-			};
+			if (matchingServers.length === 0) {
+				if (this.skillService) {
+					const skill = await this.skillService.getSkill(actualToolName);
+					if (skill) return this.executeSkill(skill);
+				}
+				return {
+					content: [{
+						type: "text",
+						text: `Tool or skill "${actualToolName}" not found. Use describe_tools to see available tools and skills.`
+					}],
+					isError: true
+				};
+			}
 			if (matchingServers.length > 1) return {
 				content: [{
 					type: "text",
@@ -1328,30 +1842,53 @@ async function createServer(options) {
 		version: "0.1.0"
 	}, { capabilities: { tools: {} } });
 	const clientManager = new McpClientManagerService();
-	if (options?.configFilePath) try {
-		const config = await new ConfigFetcherService({
-			configFilePath: options.configFilePath,
-			useCache: !options.noCache
-		}).fetchConfiguration(options.noCache || false);
+	let configSkills;
+	if (options?.configFilePath) {
+		let config;
+		try {
+			config = await new ConfigFetcherService({
+				configFilePath: options.configFilePath,
+				useCache: !options.noCache
+			}).fetchConfiguration(options.noCache || false);
+		} catch (error) {
+			throw new Error(`Failed to load MCP configuration from '${options.configFilePath}': ${error instanceof Error ? error.message : String(error)}`);
+		}
+		configSkills = config.skills;
+		const failedConnections = [];
 		const connectionPromises = Object.entries(config.mcpServers).map(async ([serverName, serverConfig]) => {
 			try {
 				await clientManager.connectToServer(serverName, serverConfig);
 				console.error(`Connected to MCP server: ${serverName}`);
 			} catch (error) {
+				const err = error instanceof Error ? error : new Error(String(error));
+				failedConnections.push({
+					serverName,
+					error: err
+				});
 				console.error(`Failed to connect to ${serverName}:`, error);
 			}
 		});
 		await Promise.all(connectionPromises);
-	} catch (error) {
-		console.error("Failed to load MCP configuration:", error);
+		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 describeTools = new DescribeToolsTool(clientManager);
-	const useTool = new UseToolTool(clientManager);
+	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);
 	server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [await describeTools.getDefinition(), useTool.getDefinition()] }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
 		const { name, arguments: args } = request.params;
-		if (name === DescribeToolsTool.TOOL_NAME) return await describeTools.execute(args);
-		if (name === UseToolTool.TOOL_NAME) return await useTool.execute(args);
+		if (name === DescribeToolsTool.TOOL_NAME) try {
+			return await describeTools.execute(args);
+		} catch (error) {
+			throw new Error(`Failed to execute ${name}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (name === UseToolTool.TOOL_NAME) try {
+			return await useTool.execute(args);
+		} catch (error) {
+			throw new Error(`Failed to execute ${name}: ${error instanceof Error ? error.message : String(error)}`);
+		}
 		throw new Error(`Unknown tool: ${name}`);
 	});
 	return server;
@@ -1703,4 +2240,4 @@ var HttpTransportHandler = class {
 };
 
 //#endregion
-export { findConfigFile as a, createServer as i, SseTransportHandler as n, McpClientManagerService as o, StdioTransportHandler as r, ConfigFetcherService as s, HttpTransportHandler as t };
+export { findConfigFile as a, ConfigFetcherService as c, createServer as i, SseTransportHandler as n, SkillService as o, StdioTransportHandler as r, McpClientManagerService as s, HttpTransportHandler as t };