@agiflowai/one-mcp 0.2.4 → 0.2.6

package/README.md

@@ -192,6 +192,135 @@ filesystem:
   read_file, list_directory, search_files
 ```
 
+### Skills
+
+Skills are reusable prompt templates that provide specialized capabilities to AI agents. They are markdown files with YAML frontmatter that get loaded and made available through the `describe_tools` output.
+
+#### Configuration
+
+Enable skills by adding a `skills` section to your config:
+
+```yaml
+mcpServers:
+  # ... your MCP servers
+
+skills:
+  paths:
+    - ".claude/skills"           # Relative to config file
+    - "/absolute/path/to/skills" # Absolute paths also supported
+```
+
+#### Skill File Structure
+
+Skills can be organized in two ways:
+
+**Flat structure:**
+```
+.claude/skills/
+├── pdf/
+│   └── SKILL.md
+└── data-analysis/
+    └── SKILL.md
+```
+
+**Skill file format (`SKILL.md`):**
+```markdown
+---
+name: pdf
+description: Create and manipulate PDF documents
+---
+
+# PDF Skill
+
+This skill helps you work with PDF files...
+
+## Usage
+...
+```
+
+#### Required Frontmatter
+
+Each `SKILL.md` must have:
+- `name`: Unique identifier for the skill
+- `description`: Brief description shown to AI agents
+
+#### How Skills Work
+
+1. Skills are discovered from configured paths at startup
+2. Available skills are listed in the `describe_tools` output
+3. AI agents can invoke skills by name (e.g., `skill: "pdf"`)
+4. The skill's content expands as a prompt providing specialized instructions
+
+#### Precedence
+
+When multiple paths are configured, skills from earlier paths take precedence over skills with the same name from later paths.
+
+### Prompt-Based Skills
+
+You can also convert MCP server prompts into skills. This allows you to expose prompts from MCP servers as executable skills that AI agents can invoke.
+
+#### Configuration
+
+Add a `prompts` section under a server's `config`:
+
+```yaml
+mcpServers:
+  my-server:
+    command: npx
+    args:
+      - -y
+      - "@mycompany/mcp-server"
+    config:
+      instruction: "My MCP server"
+      prompts:
+        code-review:
+          skill:
+            name: code-reviewer
+            description: "Review code for best practices and potential issues"
+            folder: "./prompts/code-review"  # Optional: resource folder
+        documentation:
+          skill:
+            name: doc-generator
+            description: "Generate documentation from code"
+```
+
+#### How Prompt-Based Skills Work
+
+1. **Configuration**: Define which prompts should be exposed as skills in the server config
+2. **Discovery**: Prompt-based skills appear alongside file-based skills in `describe_tools`
+3. **Invocation**: When an AI agent requests a prompt-based skill, one-mcp:
+   - Fetches the prompt content from the MCP server
+   - Returns the prompt messages as skill instructions
+4. **Execution**: The AI agent follows the skill instructions
+
+#### Skill Configuration Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique skill identifier shown to AI agents |
+| `description` | Yes | Brief description of what the skill does |
+| `folder` | No | Optional folder path for skill resources |
+
+#### Example Use Case
+
+Convert a complex prompt from an MCP server into a reusable skill:
+
+```yaml
+mcpServers:
+  architect-mcp:
+    command: npx
+    args: ["-y", "@agiflowai/architect-mcp", "mcp-serve"]
+    config:
+      instruction: "Architecture and design patterns"
+      prompts:
+        design-review:
+          skill:
+            name: design-reviewer
+            description: "Review code architecture and suggest improvements"
+```
+
+When the AI agent invokes `design-reviewer`, it receives the full prompt content from `architect-mcp`'s `design-review` prompt, enabling sophisticated code review capabilities.
+
 ---
 
 ## MCP Tools

package/dist/cli.cjs

@@ -1,21 +1,20 @@
 #!/usr/bin/env node
-const require_http = require('./http-3v8zyDO3.cjs');
+const require_http = require('./http-xSfxBa8A.cjs');
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
+let liquidjs = require("liquidjs");
 let commander = require("commander");
 let __agiflowai_aicode_utils = require("@agiflowai/aicode-utils");
-let liquidjs = require("liquidjs");
 
 //#region src/types/index.ts
 /**
-* Transport mode types
+* Transport mode constants
 */
-let TransportMode = /* @__PURE__ */ function(TransportMode$1) {
-	TransportMode$1["STDIO"] = "stdio";
-	TransportMode$1["HTTP"] = "http";
-	TransportMode$1["SSE"] = "sse";
-	return TransportMode$1;
-}({});
+const TRANSPORT_MODE = {
+	STDIO: "stdio",
+	HTTP: "http",
+	SSE: "sse"
+};
 
 //#endregion
 //#region src/commands/mcp-serve.ts
@@ -40,7 +39,16 @@ let TransportMode = /* @__PURE__ */ function(TransportMode$1) {
 * - Not cleaning up resources on shutdown
 */
 /**
+* Type guard to validate transport type
+* @param type - The transport type string to validate
+* @returns True if the type is a valid transport type
+*/
+function isValidTransportType(type) {
+	return type === "stdio" || type === "http" || type === "sse";
+}
+/**
 * Start MCP server with given transport handler
+* @param handler - The transport handler to start
 */
 async function startServer(handler) {
 	await handler.start();
@@ -60,30 +68,30 @@ async function startServer(handler) {
 /**
 * MCP Serve command
 */
-const mcpServeCommand = new commander.Command("mcp-serve").description("Start MCP server with specified transport").option("-t, --type <type>", "Transport type: stdio, http, or sse", "stdio").option("-p, --port <port>", "Port to listen on (http/sse only)", (val) => parseInt(val, 10), 3e3).option("--host <host>", "Host to bind to (http/sse only)", "localhost").option("-c, --config <path>", "Path to MCP server configuration file").option("--no-cache", "Force reload configuration from source, bypassing cache").action(async (options) => {
+const mcpServeCommand = new commander.Command("mcp-serve").description("Start MCP server with specified transport").option("-t, --type <type>", "Transport type: stdio, http, or sse", "stdio").option("-p, --port <port>", "Port to listen on (http/sse only)", (val) => parseInt(val, 10), 3e3).option("--host <host>", "Host to bind to (http/sse only)", "localhost").option("-c, --config <path>", "Path to MCP server configuration file").option("--no-cache", "Disable configuration caching, always reload from config file").action(async (options) => {
+	const transportType = options.type.toLowerCase();
+	if (!isValidTransportType(transportType)) {
+		console.error(`Unknown transport type: '${transportType}'. Valid options: stdio, http, sse`);
+		process.exit(1);
+	}
 	try {
-		const transportType = options.type.toLowerCase();
 		const serverOptions = {
-			configFilePath: options.config || require_http.findConfigFile(),
+			configFilePath: options.config || require_http.findConfigFile() || void 0,
 			noCache: options.cache === false
 		};
 		if (transportType === "stdio") await startServer(new require_http.StdioTransportHandler(await require_http.createServer(serverOptions)));
 		else if (transportType === "http") await startServer(new require_http.HttpTransportHandler(await require_http.createServer(serverOptions), {
-			mode: TransportMode.HTTP,
+			mode: TRANSPORT_MODE.HTTP,
 			port: options.port || Number(process.env.MCP_PORT) || 3e3,
 			host: options.host || process.env.MCP_HOST || "localhost"
 		}));
 		else if (transportType === "sse") await startServer(new require_http.SseTransportHandler(await require_http.createServer(serverOptions), {
-			mode: TransportMode.SSE,
+			mode: TRANSPORT_MODE.SSE,
 			port: options.port || Number(process.env.MCP_PORT) || 3e3,
 			host: options.host || process.env.MCP_HOST || "localhost"
 		}));
-		else {
-			console.error(`Unknown transport type: ${transportType}. Use: stdio, http, or sse`);
-			process.exit(1);
-		}
 	} catch (error) {
-		console.error("Failed to start MCP server:", error);
+		console.error(`Failed to start MCP server with transport '${transportType}' on ${options.host}:${options.port}:`, error);
 		process.exit(1);
 	}
 });
@@ -213,7 +221,11 @@ const describeToolsCommand = new commander.Command("describe-tools").description
 			console.error("No MCP servers connected");
 			process.exit(1);
 		}
+		const cwd = process.env.PROJECT_PATH || process.cwd();
+		const skillPaths = config.skills?.paths || [];
+		const skillService = skillPaths.length > 0 ? new require_http.SkillService(cwd, skillPaths) : void 0;
 		const foundTools = [];
+		const foundSkills = [];
 		const notFoundTools = [...toolNames];
 		for (const client of clients) {
 			if (options.server && client.serverName !== options.server) continue;
@@ -236,8 +248,30 @@ const describeToolsCommand = new commander.Command("describe-tools").description
 				if (!options.json) console.error(`Failed to list tools from ${client.serverName}:`, error);
 			}
 		}
+		if (skillService && notFoundTools.length > 0) {
+			const skillsToCheck = [...notFoundTools];
+			for (const toolName of skillsToCheck) {
+				const skillName = toolName.startsWith("skill__") ? toolName.slice(7) : toolName;
+				const skill = await skillService.getSkill(skillName);
+				if (skill) {
+					foundSkills.push({
+						name: skill.name,
+						location: skill.basePath,
+						instructions: skill.content
+					});
+					const idx = notFoundTools.indexOf(toolName);
+					if (idx > -1) notFoundTools.splice(idx, 1);
+				}
+			}
+		}
+		const nextSteps = [];
+		if (foundTools.length > 0) nextSteps.push("For MCP tools: Use the use_tool function with toolName and toolArgs based on the inputSchema above.");
+		if (foundSkills.length > 0) nextSteps.push(`For skill, just follow skill's description to continue.`);
 		if (options.json) {
-			const result = { tools: foundTools };
+			const result = {};
+			if (foundTools.length > 0) result.tools = foundTools;
+			if (foundSkills.length > 0) result.skills = foundSkills;
+			if (nextSteps.length > 0) result.nextSteps = nextSteps;
 			if (notFoundTools.length > 0) result.notFound = notFoundTools;
 			console.log(JSON.stringify(result, null, 2));
 		} else {
@@ -252,9 +286,23 @@ const describeToolsCommand = new commander.Command("describe-tools").description
 					console.log("");
 				}
 			}
-			if (notFoundTools.length > 0) console.error(`\nTools not found: ${notFoundTools.join(", ")}`);
-			if (foundTools.length === 0) {
-				console.error("No tools found");
+			if (foundSkills.length > 0) {
+				console.log("\nFound skills:\n");
+				for (const skill of foundSkills) {
+					console.log(`Skill: ${skill.name}`);
+					console.log(`Location: ${skill.location}`);
+					console.log(`Instructions:\n${skill.instructions}`);
+					console.log("");
+				}
+			}
+			if (nextSteps.length > 0) {
+				console.log("\nNext steps:");
+				for (const step of nextSteps) console.log(`  • ${step}`);
+				console.log("");
+			}
+			if (notFoundTools.length > 0) console.error(`\nTools/skills not found: ${notFoundTools.join(", ")}`);
+			if (foundTools.length === 0 && foundSkills.length === 0) {
+				console.error("No tools or skills found");
 				process.exit(1);
 			}
 		}
@@ -355,7 +403,29 @@ const useToolCommand = new commander.Command("use-tool").description("Execute an
 			if (!options.json) console.error(`Failed to list tools from ${client$1.serverName}:`, error);
 		}
 		if (matchingServers.length === 0) {
-			console.error(`Tool "${toolName}" not found on any connected server`);
+			const cwd = process.env.PROJECT_PATH || process.cwd();
+			const skillPaths = config.skills?.paths || [];
+			if (skillPaths.length > 0) try {
+				const skillService = new require_http.SkillService(cwd, skillPaths);
+				const skillName = toolName.startsWith("skill__") ? toolName.slice(7) : toolName;
+				const skill = await skillService.getSkill(skillName);
+				if (skill) {
+					const result = { content: [{
+						type: "text",
+						text: skill.content
+					}] };
+					if (options.json) console.log(JSON.stringify(result, null, 2));
+					else {
+						console.log("\nSkill content:");
+						console.log(skill.content);
+					}
+					await clientManager.disconnectAll();
+					return;
+				}
+			} catch (error) {
+				if (!options.json) console.error(`Failed to lookup skill "${toolName}":`, error);
+			}
+			console.error(`Tool or skill "${toolName}" not found on any connected server or configured skill paths`);
 			await clientManager.disconnectAll();
 			process.exit(1);
 		}
@@ -478,7 +548,7 @@ const initCommand = new commander.Command("init").description("Initialize MCP co
 
 //#endregion
 //#region package.json
-var version = "0.2.3";
+var version = "0.2.5";
 
 //#endregion
 //#region src/cli.ts

package/dist/cli.mjs

@@ -1,21 +1,20 @@
 #!/usr/bin/env node
-import { a as findConfigFile, i as createServer, n as SseTransportHandler, o as McpClientManagerService, r as StdioTransportHandler, s as ConfigFetcherService, t as HttpTransportHandler } from "./http-CzQfsUEI.mjs";
+import { a as findConfigFile, c as ConfigFetcherService, i as createServer, n as SseTransportHandler, o as SkillService, r as StdioTransportHandler, s as McpClientManagerService, t as HttpTransportHandler } from "./http-D9BDXhHn.mjs";
 import { writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { Liquid } from "liquidjs";
 import { Command } from "commander";
 import { log } from "@agiflowai/aicode-utils";
-import { Liquid } from "liquidjs";
 
 //#region src/types/index.ts
 /**
-* Transport mode types
+* Transport mode constants
 */
-let TransportMode = /* @__PURE__ */ function(TransportMode$1) {
-	TransportMode$1["STDIO"] = "stdio";
-	TransportMode$1["HTTP"] = "http";
-	TransportMode$1["SSE"] = "sse";
-	return TransportMode$1;
-}({});
+const TRANSPORT_MODE = {
+	STDIO: "stdio",
+	HTTP: "http",
+	SSE: "sse"
+};
 
 //#endregion
 //#region src/commands/mcp-serve.ts
@@ -40,7 +39,16 @@ let TransportMode = /* @__PURE__ */ function(TransportMode$1) {
 * - Not cleaning up resources on shutdown
 */
 /**
+* Type guard to validate transport type
+* @param type - The transport type string to validate
+* @returns True if the type is a valid transport type
+*/
+function isValidTransportType(type) {
+	return type === "stdio" || type === "http" || type === "sse";
+}
+/**
 * Start MCP server with given transport handler
+* @param handler - The transport handler to start
 */
 async function startServer(handler) {
 	await handler.start();
@@ -60,30 +68,30 @@ async function startServer(handler) {
 /**
 * MCP Serve command
 */
-const mcpServeCommand = new Command("mcp-serve").description("Start MCP server with specified transport").option("-t, --type <type>", "Transport type: stdio, http, or sse", "stdio").option("-p, --port <port>", "Port to listen on (http/sse only)", (val) => parseInt(val, 10), 3e3).option("--host <host>", "Host to bind to (http/sse only)", "localhost").option("-c, --config <path>", "Path to MCP server configuration file").option("--no-cache", "Force reload configuration from source, bypassing cache").action(async (options) => {
+const mcpServeCommand = new Command("mcp-serve").description("Start MCP server with specified transport").option("-t, --type <type>", "Transport type: stdio, http, or sse", "stdio").option("-p, --port <port>", "Port to listen on (http/sse only)", (val) => parseInt(val, 10), 3e3).option("--host <host>", "Host to bind to (http/sse only)", "localhost").option("-c, --config <path>", "Path to MCP server configuration file").option("--no-cache", "Disable configuration caching, always reload from config file").action(async (options) => {
+	const transportType = options.type.toLowerCase();
+	if (!isValidTransportType(transportType)) {
+		console.error(`Unknown transport type: '${transportType}'. Valid options: stdio, http, sse`);
+		process.exit(1);
+	}
 	try {
-		const transportType = options.type.toLowerCase();
 		const serverOptions = {
-			configFilePath: options.config || findConfigFile(),
+			configFilePath: options.config || findConfigFile() || void 0,
 			noCache: options.cache === false
 		};
 		if (transportType === "stdio") await startServer(new StdioTransportHandler(await createServer(serverOptions)));
 		else if (transportType === "http") await startServer(new HttpTransportHandler(await createServer(serverOptions), {
-			mode: TransportMode.HTTP,
+			mode: TRANSPORT_MODE.HTTP,
 			port: options.port || Number(process.env.MCP_PORT) || 3e3,
 			host: options.host || process.env.MCP_HOST || "localhost"
 		}));
 		else if (transportType === "sse") await startServer(new SseTransportHandler(await createServer(serverOptions), {
-			mode: TransportMode.SSE,
+			mode: TRANSPORT_MODE.SSE,
 			port: options.port || Number(process.env.MCP_PORT) || 3e3,
 			host: options.host || process.env.MCP_HOST || "localhost"
 		}));
-		else {
-			console.error(`Unknown transport type: ${transportType}. Use: stdio, http, or sse`);
-			process.exit(1);
-		}
 	} catch (error) {
-		console.error("Failed to start MCP server:", error);
+		console.error(`Failed to start MCP server with transport '${transportType}' on ${options.host}:${options.port}:`, error);
 		process.exit(1);
 	}
 });
@@ -213,7 +221,11 @@ const describeToolsCommand = new Command("describe-tools").description("Describe
 			console.error("No MCP servers connected");
 			process.exit(1);
 		}
+		const cwd = process.env.PROJECT_PATH || process.cwd();
+		const skillPaths = config.skills?.paths || [];
+		const skillService = skillPaths.length > 0 ? new SkillService(cwd, skillPaths) : void 0;
 		const foundTools = [];
+		const foundSkills = [];
 		const notFoundTools = [...toolNames];
 		for (const client of clients) {
 			if (options.server && client.serverName !== options.server) continue;
@@ -236,8 +248,30 @@ const describeToolsCommand = new Command("describe-tools").description("Describe
 				if (!options.json) console.error(`Failed to list tools from ${client.serverName}:`, error);
 			}
 		}
+		if (skillService && notFoundTools.length > 0) {
+			const skillsToCheck = [...notFoundTools];
+			for (const toolName of skillsToCheck) {
+				const skillName = toolName.startsWith("skill__") ? toolName.slice(7) : toolName;
+				const skill = await skillService.getSkill(skillName);
+				if (skill) {
+					foundSkills.push({
+						name: skill.name,
+						location: skill.basePath,
+						instructions: skill.content
+					});
+					const idx = notFoundTools.indexOf(toolName);
+					if (idx > -1) notFoundTools.splice(idx, 1);
+				}
+			}
+		}
+		const nextSteps = [];
+		if (foundTools.length > 0) nextSteps.push("For MCP tools: Use the use_tool function with toolName and toolArgs based on the inputSchema above.");
+		if (foundSkills.length > 0) nextSteps.push(`For skill, just follow skill's description to continue.`);
 		if (options.json) {
-			const result = { tools: foundTools };
+			const result = {};
+			if (foundTools.length > 0) result.tools = foundTools;
+			if (foundSkills.length > 0) result.skills = foundSkills;
+			if (nextSteps.length > 0) result.nextSteps = nextSteps;
 			if (notFoundTools.length > 0) result.notFound = notFoundTools;
 			console.log(JSON.stringify(result, null, 2));
 		} else {
@@ -252,9 +286,23 @@ const describeToolsCommand = new Command("describe-tools").description("Describe
 					console.log("");
 				}
 			}
-			if (notFoundTools.length > 0) console.error(`\nTools not found: ${notFoundTools.join(", ")}`);
-			if (foundTools.length === 0) {
-				console.error("No tools found");
+			if (foundSkills.length > 0) {
+				console.log("\nFound skills:\n");
+				for (const skill of foundSkills) {
+					console.log(`Skill: ${skill.name}`);
+					console.log(`Location: ${skill.location}`);
+					console.log(`Instructions:\n${skill.instructions}`);
+					console.log("");
+				}
+			}
+			if (nextSteps.length > 0) {
+				console.log("\nNext steps:");
+				for (const step of nextSteps) console.log(`  • ${step}`);
+				console.log("");
+			}
+			if (notFoundTools.length > 0) console.error(`\nTools/skills not found: ${notFoundTools.join(", ")}`);
+			if (foundTools.length === 0 && foundSkills.length === 0) {
+				console.error("No tools or skills found");
 				process.exit(1);
 			}
 		}
@@ -355,7 +403,29 @@ const useToolCommand = new Command("use-tool").description("Execute an MCP tool
 			if (!options.json) console.error(`Failed to list tools from ${client$1.serverName}:`, error);
 		}
 		if (matchingServers.length === 0) {
-			console.error(`Tool "${toolName}" not found on any connected server`);
+			const cwd = process.env.PROJECT_PATH || process.cwd();
+			const skillPaths = config.skills?.paths || [];
+			if (skillPaths.length > 0) try {
+				const skillService = new SkillService(cwd, skillPaths);
+				const skillName = toolName.startsWith("skill__") ? toolName.slice(7) : toolName;
+				const skill = await skillService.getSkill(skillName);
+				if (skill) {
+					const result = { content: [{
+						type: "text",
+						text: skill.content
+					}] };
+					if (options.json) console.log(JSON.stringify(result, null, 2));
+					else {
+						console.log("\nSkill content:");
+						console.log(skill.content);
+					}
+					await clientManager.disconnectAll();
+					return;
+				}
+			} catch (error) {
+				if (!options.json) console.error(`Failed to lookup skill "${toolName}":`, error);
+			}
+			console.error(`Tool or skill "${toolName}" not found on any connected server or configured skill paths`);
 			await clientManager.disconnectAll();
 			process.exit(1);
 		}
@@ -478,7 +548,7 @@ const initCommand = new Command("init").description("Initialize MCP configuratio
 
 //#endregion
 //#region package.json
-var version = "0.2.3";
+var version = "0.2.5";
 
 //#endregion
 //#region src/cli.ts