@agiflowai/one-mcp 0.2.6 → 0.3.0

package/README.md

@@ -128,6 +128,12 @@ mcpServers:
     command: node
     args: ["server.js"]
     disabled: true
+
+  # Custom timeout for slow servers
+  slow-server:
+    command: npx
+    args: ["-y", "@heavy/mcp-package"]
+    timeout: 60000  # 60 seconds (default: 30000)
 ```
 
 ### Environment Variables
@@ -259,9 +265,51 @@ When multiple paths are configured, skills from earlier paths take precedence ov
 
 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
+#### Auto-Detection from Front-Matter (Recommended)
+
+The easiest way to create prompt-based skills is to add YAML front-matter directly in your prompt content. one-mcp automatically detects prompts with `name` and `description` front-matter and exposes them as skills.
+
+**Prompt content with front-matter:**
+```markdown
+---
+name: code-reviewer
+description: Review code for best practices and potential issues
+---
+
+# Code Review Instructions
+
+When reviewing code, follow these guidelines...
+```
 
-Add a `prompts` section under a server's `config`:
+MCP servers like `@agiflowai/scaffold-mcp` support the `--prompt-as-skill` flag to automatically add front-matter to prompts:
+
+```yaml
+mcpServers:
+  scaffold-mcp:
+    command: npx
+    args:
+      - -y
+      - "@agiflowai/scaffold-mcp"
+      - "mcp-serve"
+      - "--prompt-as-skill"  # Enables front-matter in prompts
+```
+
+**Multi-line descriptions** are supported using YAML block scalars:
+
+```markdown
+---
+name: complex-skill
+description: |
+  A skill that does multiple things:
+  - First capability
+  - Second capability
+  - Third capability
+---
+```
+
+#### Explicit Configuration (Alternative)
+
+You can also explicitly configure which prompts should be exposed as skills:
 
 ```yaml
 mcpServers:
@@ -286,14 +334,14 @@ mcpServers:
 
 #### 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`
+1. **Discovery**: one-mcp scans all prompts from connected servers for front-matter with `name` and `description`
+2. **Fallback**: Explicitly configured prompts (in `config.prompts`) take precedence over auto-detected ones
 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
+#### Skill Configuration Fields (Explicit Config)
 
 | Field | Required | Description |
 |-------|----------|-------------|
@@ -301,6 +349,12 @@ mcpServers:
 | `description` | Yes | Brief description of what the skill does |
 | `folder` | No | Optional folder path for skill resources |
 
+#### Skill Naming and Precedence
+
+- **File-based skills** take precedence over prompt-based skills with the same name
+- Skills are only prefixed with `skill__` when they clash with MCP tool names
+- Skills that only clash with other skills are deduplicated (first one wins, no prefix)
+
 #### Example Use Case
 
 Convert a complex prompt from an MCP server into a reusable skill:
@@ -366,6 +420,9 @@ npx @agiflowai/one-mcp mcp-serve --config ./mcp-config.yaml --type http --port 3
 # Initialize config file
 npx @agiflowai/one-mcp init --output mcp-config.yaml
 
+# Pre-download packages for faster startup
+npx @agiflowai/one-mcp prefetch --config ./mcp-config.yaml
+
 # List all tools from configured servers
 npx @agiflowai/one-mcp list-tools --config ./mcp-config.yaml
 
@@ -376,6 +433,31 @@ npx @agiflowai/one-mcp describe-tools --config ./mcp-config.yaml --tools read_fi
 npx @agiflowai/one-mcp use-tool --config ./mcp-config.yaml --tool-name read_file --args '{"path": "/tmp/test.txt"}'
 ```
 
+### Prefetch Command
+
+Pre-download packages used by MCP servers (npx, pnpx, uvx, uv) to speed up initial connections:
+
+```bash
+# Prefetch all packages
+npx @agiflowai/one-mcp prefetch --config ./mcp-config.yaml
+
+# Dry run - see what would be prefetched
+npx @agiflowai/one-mcp prefetch --config ./mcp-config.yaml --dry-run
+
+# Run prefetch in parallel (faster)
+npx @agiflowai/one-mcp prefetch --config ./mcp-config.yaml --parallel
+
+# Filter by package manager
+npx @agiflowai/one-mcp prefetch --config ./mcp-config.yaml --filter npx
+```
+
+| Option | Description |
+|--------|-------------|
+| `-c, --config` | Path to config file |
+| `-p, --parallel` | Run prefetch commands in parallel |
+| `-d, --dry-run` | Show what would be prefetched without executing |
+| `-f, --filter` | Filter by package manager: `npx`, `pnpx`, `uvx`, or `uv` |
+
 ### Server Options
 
 | Option | Description | Default |

package/dist/cli.cjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
-const require_http = require('./http-xSfxBa8A.cjs');
+const require_http = require('./http-BYBRKvD4.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 node_child_process = require("node:child_process");
 
 //#region src/types/index.ts
 /**
@@ -546,9 +547,462 @@ const initCommand = new commander.Command("init").description("Initialize MCP co
 	}
 });
 
+//#endregion
+//#region src/services/PrefetchService/constants.ts
+/**
+* PrefetchService Constants
+*
+* Constants for package manager commands and process configuration.
+*/
+/** Transport type for stdio-based MCP servers */
+const TRANSPORT_STDIO = "stdio";
+/** npx command name */
+const COMMAND_NPX = "npx";
+/** npm command name */
+const COMMAND_NPM = "npm";
+/** pnpx command name (pnpm's npx equivalent) */
+const COMMAND_PNPX = "pnpx";
+/** pnpm command name */
+const COMMAND_PNPM = "pnpm";
+/** uvx command name */
+const COMMAND_UVX = "uvx";
+/** uv command name */
+const COMMAND_UV = "uv";
+/** Path suffix for npx command */
+const COMMAND_NPX_SUFFIX = "/npx";
+/** Path suffix for pnpx command */
+const COMMAND_PNPX_SUFFIX = "/pnpx";
+/** Path suffix for uvx command */
+const COMMAND_UVX_SUFFIX = "/uvx";
+/** Path suffix for uv command */
+const COMMAND_UV_SUFFIX = "/uv";
+/** Run subcommand for uv */
+const ARG_RUN = "run";
+/** Tool subcommand for uv */
+const ARG_TOOL = "tool";
+/** Install subcommand for uv tool and npm/pnpm */
+const ARG_INSTALL = "install";
+/** Add subcommand for pnpm */
+const ARG_ADD = "add";
+/** Global flag for npm/pnpm install */
+const ARG_GLOBAL = "-g";
+/** Flag prefix for command arguments */
+const FLAG_PREFIX = "-";
+/** npx --package flag (long form) */
+const FLAG_PACKAGE_LONG = "--package";
+/** npx -p flag (short form) */
+const FLAG_PACKAGE_SHORT = "-p";
+/** Equals delimiter used in flag=value patterns */
+const EQUALS_DELIMITER = "=";
+/**
+* Regex pattern for valid package names (npm, pnpm, uvx, uv)
+* Allows: @scope/package-name@version, package-name, package_name
+* Prevents shell metacharacters that could enable command injection
+* @example
+* // Valid: '@scope/package@1.0.0', 'my-package', 'my_package', '@org/pkg'
+* // Invalid: 'pkg; rm -rf /', 'pkg$(cmd)', 'pkg`whoami`', 'pkg|cat /etc/passwd'
+*/
+const VALID_PACKAGE_NAME_PATTERN = /^(@[a-zA-Z0-9_-]+\/)?[a-zA-Z0-9._-]+(@[a-zA-Z0-9._-]+)?$/;
+/** Windows platform identifier */
+const PLATFORM_WIN32 = "win32";
+/** Success exit code */
+const EXIT_CODE_SUCCESS = 0;
+/** Stdio option to ignore stream */
+const STDIO_IGNORE = "ignore";
+/** Stdio option to pipe stream */
+const STDIO_PIPE = "pipe";
+
+//#endregion
+//#region src/services/PrefetchService/PrefetchService.ts
+/**
+* PrefetchService
+*
+* DESIGN PATTERNS:
+* - Service pattern for business logic encapsulation
+* - Single responsibility principle
+*
+* CODING STANDARDS:
+* - Use async/await for asynchronous operations
+* - Throw descriptive errors for error cases
+* - Keep methods focused and well-named
+* - Document complex logic with comments
+*
+* AVOID:
+* - Mixing concerns (keep focused on single domain)
+* - Direct tool implementation (services should be tool-agnostic)
+*/
+/**
+* Type guard to check if a config object is an McpStdioConfig
+* @param config - Config object to check
+* @returns True if config has required McpStdioConfig properties
+*/
+function isMcpStdioConfig(config) {
+	return typeof config === "object" && config !== null && "command" in config;
+}
+/**
+* PrefetchService handles pre-downloading packages used by MCP servers.
+* Supports npx (Node.js), uvx (Python/uv), and uv run commands.
+*
+* @example
+* ```typescript
+* const service = new PrefetchService({
+*   mcpConfig: await configFetcher.fetchConfiguration(),
+*   parallel: true,
+* });
+* const packages = service.extractPackages();
+* const summary = await service.prefetch();
+* ```
+*/
+var PrefetchService = class {
+	config;
+	/**
+	* Creates a new PrefetchService instance
+	* @param config - Service configuration options
+	*/
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* Extract all prefetchable packages from the MCP configuration
+	* @returns Array of package info objects
+	*/
+	extractPackages() {
+		const packages = [];
+		const { mcpConfig, filter } = this.config;
+		for (const [serverName, serverConfig] of Object.entries(mcpConfig.mcpServers)) {
+			if (serverConfig.disabled) continue;
+			if (serverConfig.transport !== TRANSPORT_STDIO) continue;
+			if (!isMcpStdioConfig(serverConfig.config)) continue;
+			const packageInfo = this.extractPackageInfo(serverName, serverConfig.config);
+			if (packageInfo) {
+				if (filter && packageInfo.packageManager !== filter) continue;
+				packages.push(packageInfo);
+			}
+		}
+		return packages;
+	}
+	/**
+	* Prefetch all packages from the configuration
+	* @returns Summary of prefetch results
+	* @throws Error if prefetch operation fails unexpectedly
+	*/
+	async prefetch() {
+		try {
+			const packages = this.extractPackages();
+			const results = [];
+			if (packages.length === 0) return {
+				totalPackages: 0,
+				successful: 0,
+				failed: 0,
+				results: []
+			};
+			if (this.config.parallel) {
+				const promises = packages.map(async (pkg) => this.prefetchPackage(pkg));
+				results.push(...await Promise.all(promises));
+			} else for (const pkg of packages) {
+				const result = await this.prefetchPackage(pkg);
+				results.push(result);
+			}
+			const successful = results.filter((r) => r.success).length;
+			const failed = results.filter((r) => !r.success).length;
+			return {
+				totalPackages: packages.length,
+				successful,
+				failed,
+				results
+			};
+		} catch (error) {
+			throw new Error(`Failed to prefetch packages: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	/**
+	* Prefetch a single package
+	* @param pkg - Package info to prefetch
+	* @returns Result of the prefetch operation
+	*/
+	async prefetchPackage(pkg) {
+		try {
+			const [command, ...args] = pkg.fullCommand;
+			const result = await this.runCommand(command, args);
+			return {
+				package: pkg,
+				success: result.success,
+				output: result.output
+			};
+		} catch (error) {
+			return {
+				package: pkg,
+				success: false,
+				output: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	/**
+	* Validate package name to prevent command injection
+	* @param packageName - Package name to validate
+	* @returns True if package name is safe, false otherwise
+	* @remarks Rejects package names containing shell metacharacters
+	* @example
+	* isValidPackageName('@scope/package') // true
+	* isValidPackageName('my-package@1.0.0') // true
+	* isValidPackageName('pkg; rm -rf /') // false (shell injection)
+	* isValidPackageName('pkg$(whoami)') // false (command substitution)
+	*/
+	isValidPackageName(packageName) {
+		return VALID_PACKAGE_NAME_PATTERN.test(packageName);
+	}
+	/**
+	* Extract package info from a server's stdio config
+	* @param serverName - Name of the MCP server
+	* @param config - Stdio configuration for the server
+	* @returns Package info if extractable, null otherwise
+	*/
+	extractPackageInfo(serverName, config) {
+		const command = config.command.toLowerCase();
+		const args = config.args || [];
+		if (command === COMMAND_NPX || command.endsWith(COMMAND_NPX_SUFFIX)) {
+			const packageName = this.extractNpxPackage(args);
+			if (packageName && this.isValidPackageName(packageName)) return {
+				serverName,
+				packageManager: COMMAND_NPX,
+				packageName,
+				fullCommand: [
+					COMMAND_NPM,
+					ARG_INSTALL,
+					ARG_GLOBAL,
+					packageName
+				]
+			};
+		}
+		if (command === COMMAND_PNPX || command.endsWith(COMMAND_PNPX_SUFFIX)) {
+			const packageName = this.extractNpxPackage(args);
+			if (packageName && this.isValidPackageName(packageName)) return {
+				serverName,
+				packageManager: COMMAND_PNPX,
+				packageName,
+				fullCommand: [
+					COMMAND_PNPM,
+					ARG_ADD,
+					ARG_GLOBAL,
+					packageName
+				]
+			};
+		}
+		if (command === COMMAND_UVX || command.endsWith(COMMAND_UVX_SUFFIX)) {
+			const packageName = this.extractUvxPackage(args);
+			if (packageName && this.isValidPackageName(packageName)) return {
+				serverName,
+				packageManager: COMMAND_UVX,
+				packageName,
+				fullCommand: [COMMAND_UVX, packageName]
+			};
+		}
+		if ((command === COMMAND_UV || command.endsWith(COMMAND_UV_SUFFIX)) && args.includes(ARG_RUN)) {
+			const packageName = this.extractUvRunPackage(args);
+			if (packageName && this.isValidPackageName(packageName)) return {
+				serverName,
+				packageManager: COMMAND_UV,
+				packageName,
+				fullCommand: [
+					COMMAND_UV,
+					ARG_TOOL,
+					ARG_INSTALL,
+					packageName
+				]
+			};
+		}
+		return null;
+	}
+	/**
+	* Extract package name from npx command args
+	* @param args - Command arguments
+	* @returns Package name or null
+	* @remarks Handles --package=value, --package value, -p value patterns.
+	*          Falls back to first non-flag argument if no --package/-p flag found.
+	*          Returns null if flag has no value or is followed by another flag.
+	*          When multiple --package flags exist, returns the first valid one.
+	* @example
+	* extractNpxPackage(['--package=@scope/pkg']) // returns '@scope/pkg'
+	* extractNpxPackage(['--package', 'pkg-name']) // returns 'pkg-name'
+	* extractNpxPackage(['-p', 'pkg']) // returns 'pkg'
+	* extractNpxPackage(['-y', 'pkg-name', '--flag']) // returns 'pkg-name' (fallback)
+	* extractNpxPackage(['--package=']) // returns null (empty value)
+	*/
+	extractNpxPackage(args) {
+		for (let i = 0; i < args.length; i++) {
+			const arg = args[i];
+			if (arg.startsWith(FLAG_PACKAGE_LONG + EQUALS_DELIMITER)) return arg.slice(FLAG_PACKAGE_LONG.length + EQUALS_DELIMITER.length) || null;
+			if (arg === FLAG_PACKAGE_LONG && i + 1 < args.length) {
+				const nextArg = args[i + 1];
+				if (!nextArg.startsWith(FLAG_PREFIX)) return nextArg;
+			}
+			if (arg === FLAG_PACKAGE_SHORT && i + 1 < args.length) {
+				const nextArg = args[i + 1];
+				if (!nextArg.startsWith(FLAG_PREFIX)) return nextArg;
+			}
+		}
+		for (const arg of args) {
+			if (arg.startsWith(FLAG_PREFIX)) continue;
+			return arg;
+		}
+		return null;
+	}
+	/**
+	* Extract package name from uvx command args
+	* @param args - Command arguments
+	* @returns Package name or null
+	* @remarks Assumes the first non-flag argument is the package name.
+	*          Handles both single (-) and double (--) dash flags.
+	* @example
+	* extractUvxPackage(['mcp-server-fetch']) // returns 'mcp-server-fetch'
+	* extractUvxPackage(['--quiet', 'pkg-name']) // returns 'pkg-name'
+	*/
+	extractUvxPackage(args) {
+		for (const arg of args) {
+			if (arg.startsWith(FLAG_PREFIX)) continue;
+			return arg;
+		}
+		return null;
+	}
+	/**
+	* Extract package name from uv run command args
+	* @param args - Command arguments
+	* @returns Package name or null
+	* @remarks Looks for the first non-flag argument after the 'run' subcommand.
+	*          Returns null if 'run' is not found in args.
+	* @example
+	* extractUvRunPackage(['run', 'mcp-server']) // returns 'mcp-server'
+	* extractUvRunPackage(['run', '--verbose', 'pkg']) // returns 'pkg'
+	* extractUvRunPackage(['install', 'pkg']) // returns null (no 'run')
+	*/
+	extractUvRunPackage(args) {
+		const runIndex = args.indexOf(ARG_RUN);
+		if (runIndex === -1) return null;
+		for (let i = runIndex + 1; i < args.length; i++) {
+			const arg = args[i];
+			if (arg.startsWith(FLAG_PREFIX)) continue;
+			return arg;
+		}
+		return null;
+	}
+	/**
+	* Run a shell command and capture output
+	* @param command - Command to run
+	* @param args - Command arguments
+	* @returns Promise with success status and output
+	*/
+	runCommand(command, args) {
+		return new Promise((resolve$1) => {
+			const proc = (0, node_child_process.spawn)(command, args, {
+				stdio: [
+					STDIO_IGNORE,
+					STDIO_PIPE,
+					STDIO_PIPE
+				],
+				shell: process.platform === PLATFORM_WIN32
+			});
+			let stdout = "";
+			let stderr = "";
+			proc.stdout?.on("data", (data) => {
+				stdout += data.toString();
+			});
+			proc.stderr?.on("data", (data) => {
+				stderr += data.toString();
+			});
+			proc.on("close", (code) => {
+				resolve$1({
+					success: code === EXIT_CODE_SUCCESS,
+					output: stdout || stderr
+				});
+			});
+			proc.on("error", (error) => {
+				resolve$1({
+					success: false,
+					output: error.message
+				});
+			});
+		});
+	}
+};
+
+//#endregion
+//#region src/commands/prefetch.ts
+/**
+* Prefetch Command
+*
+* DESIGN PATTERNS:
+* - Command pattern with Commander for CLI argument parsing
+* - Async/await pattern for asynchronous operations
+* - Error handling pattern with try-catch and proper exit codes
+*
+* CODING STANDARDS:
+* - Use async action handlers for asynchronous operations
+* - Provide clear option descriptions and default values
+* - Handle errors gracefully with process.exit()
+* - Log progress and errors to console
+* - Use Commander's .option() and .argument() for inputs
+*
+* AVOID:
+* - Synchronous blocking operations in action handlers
+* - Missing error handling (always use try-catch)
+* - Hardcoded values (use options or environment variables)
+* - Not exiting with appropriate exit codes on errors
+*/
+/**
+* Pre-download packages used by MCP servers (npx, pnpx, uvx, uv)
+*/
+const prefetchCommand = new commander.Command("prefetch").description("Pre-download packages used by MCP servers (npx, pnpx, uvx, uv)").option("-c, --config <path>", "Path to MCP server configuration file").option("-p, --parallel", "Run prefetch commands in parallel", false).option("-d, --dry-run", "Show what would be prefetched without executing", false).option("-f, --filter <type>", "Filter by package manager type: npx, pnpx, uvx, or uv").action(async (options) => {
+	try {
+		const configFilePath = options.config || require_http.findConfigFile();
+		if (!configFilePath) {
+			__agiflowai_aicode_utils.print.error("No MCP configuration file found.");
+			__agiflowai_aicode_utils.print.info("Use --config <path> to specify a config file, or run \"one-mcp init\" to create one.");
+			process.exit(1);
+		}
+		__agiflowai_aicode_utils.print.info(`Loading configuration from: ${configFilePath}`);
+		const prefetchService = new PrefetchService({
+			mcpConfig: await new require_http.ConfigFetcherService({
+				configFilePath,
+				useCache: false
+			}).fetchConfiguration(true),
+			filter: options.filter,
+			parallel: options.parallel
+		});
+		const packages = prefetchService.extractPackages();
+		if (packages.length === 0) {
+			__agiflowai_aicode_utils.print.warning("No packages found to prefetch.");
+			__agiflowai_aicode_utils.print.info("Prefetch supports: npx, pnpx, uvx, and uv run commands");
+			return;
+		}
+		__agiflowai_aicode_utils.print.info(`Found ${packages.length} package(s) to prefetch:`);
+		for (const pkg of packages) __agiflowai_aicode_utils.print.item(`${pkg.serverName}: ${pkg.packageManager} ${pkg.packageName}`);
+		if (options.dryRun) {
+			__agiflowai_aicode_utils.print.newline();
+			__agiflowai_aicode_utils.print.header("Dry run mode - commands that would be executed:");
+			for (const pkg of packages) __agiflowai_aicode_utils.print.indent(pkg.fullCommand.join(" "));
+			return;
+		}
+		__agiflowai_aicode_utils.print.newline();
+		__agiflowai_aicode_utils.print.info("Prefetching packages...");
+		const summary = await prefetchService.prefetch();
+		__agiflowai_aicode_utils.print.newline();
+		if (summary.failed === 0) __agiflowai_aicode_utils.print.success(`Prefetch complete: ${summary.successful} succeeded, ${summary.failed} failed`);
+		else __agiflowai_aicode_utils.print.warning(`Prefetch complete: ${summary.successful} succeeded, ${summary.failed} failed`);
+		if (summary.failed > 0) {
+			__agiflowai_aicode_utils.print.newline();
+			__agiflowai_aicode_utils.print.error("Failed packages:");
+			for (const result of summary.results.filter((r) => !r.success)) __agiflowai_aicode_utils.print.item(`${result.package.serverName} (${result.package.packageName}): ${result.output.trim()}`);
+			process.exit(1);
+		}
+	} catch (error) {
+		__agiflowai_aicode_utils.print.error("Error executing prefetch:", error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	}
+});
+
 //#endregion
 //#region package.json
-var version = "0.2.5";
+var version = "0.2.2";
 
 //#endregion
 //#region src/cli.ts
@@ -574,15 +1028,24 @@ var version = "0.2.5";
 * Main entry point
 */
 async function main() {
-	const program = new commander.Command();
-	program.name("one-mcp").description("One MCP server package").version(version);
-	program.addCommand(initCommand);
-	program.addCommand(mcpServeCommand);
-	program.addCommand(listToolsCommand);
-	program.addCommand(describeToolsCommand);
-	program.addCommand(useToolCommand);
-	await program.parseAsync(process.argv);
+	try {
+		const program = new commander.Command();
+		program.name("one-mcp").description("One MCP server package").version(version);
+		program.addCommand(initCommand);
+		program.addCommand(mcpServeCommand);
+		program.addCommand(listToolsCommand);
+		program.addCommand(describeToolsCommand);
+		program.addCommand(useToolCommand);
+		program.addCommand(prefetchCommand);
+		await program.parseAsync(process.argv);
+	} catch (error) {
+		console.error(`CLI execution failed: ${error instanceof Error ? error.message : error}`);
+		process.exit(1);
+	}
 }
-main();
+main().catch((error) => {
+	console.error(`Fatal error: ${error instanceof Error ? error.message : error}`);
+	process.exit(1);
+});
 
 //#endregion