@agiflowai/one-mcp 0.3.6 → 0.3.7

package/dist/cli.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const require_http = require('./http-CRloqAb_.cjs');
+const require_http = require('./http-CKXz9Gp8.cjs');
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
 let liquidjs = require("liquidjs");
@@ -1051,7 +1051,7 @@ const prefetchCommand = new commander.Command("prefetch").description("Pre-downl
 
 //#endregion
 //#region package.json
-var version = "0.3.5";
+var version = "0.3.6";
 
 //#endregion
 //#region src/cli.ts

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as SkillService, c as ConfigFetcherService, i as createServer, n as SseTransportHandler, o as findConfigFile, r as StdioTransportHandler, s as McpClientManagerService, t as HttpTransportHandler } from "./http-DV3-1Emn.mjs";
+import { c as findConfigFile, i as createServer, l as McpClientManagerService, n as SseTransportHandler, r as StdioTransportHandler, s as SkillService, t as HttpTransportHandler, u as ConfigFetcherService } from "./http-BzTXYfkN.mjs";
 import { writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { Liquid } from "liquidjs";
@@ -1051,7 +1051,7 @@ const prefetchCommand = new Command("prefetch").description("Pre-download packag
 
 //#endregion
 //#region package.json
-var version = "0.3.5";
+var version = "0.3.6";
 
 //#endregion
 //#region src/cli.ts

package/dist/{http-DV3-1Emn.mjs → http-BzTXYfkN.mjs}

@@ -2837,4 +2837,4 @@ var HttpTransportHandler = class {
 };
 
 //#endregion
-export { SkillService as a, ConfigFetcherService as c, createServer as i, SseTransportHandler as n, findConfigFile as o, StdioTransportHandler as r, McpClientManagerService as s, HttpTransportHandler as t };
+export { UseToolTool as a, findConfigFile as c, createServer as i, McpClientManagerService as l, SseTransportHandler as n, DescribeToolsTool as o, StdioTransportHandler as r, SkillService as s, HttpTransportHandler as t, ConfigFetcherService as u };

package/dist/{http-CRloqAb_.cjs → http-CKXz9Gp8.cjs}

@@ -2872,6 +2872,12 @@ Object.defineProperty(exports, 'ConfigFetcherService', {
     return ConfigFetcherService;
   }
 });
+Object.defineProperty(exports, 'DescribeToolsTool', {
+  enumerable: true,
+  get: function () {
+    return DescribeToolsTool;
+  }
+});
 Object.defineProperty(exports, 'HttpTransportHandler', {
   enumerable: true,
   get: function () {
@@ -2902,6 +2908,12 @@ Object.defineProperty(exports, 'StdioTransportHandler', {
     return StdioTransportHandler;
   }
 });
+Object.defineProperty(exports, 'UseToolTool', {
+  enumerable: true,
+  get: function () {
+    return UseToolTool;
+  }
+});
 Object.defineProperty(exports, '__toESM', {
   enumerable: true,
   get: function () {

package/dist/index.cjs

@@ -1,6 +1,11 @@
-const require_http = require('./http-CRloqAb_.cjs');
+const require_http = require('./http-CKXz9Gp8.cjs');
 
+exports.ConfigFetcherService = require_http.ConfigFetcherService;
+exports.DescribeToolsTool = require_http.DescribeToolsTool;
 exports.HttpTransportHandler = require_http.HttpTransportHandler;
+exports.McpClientManagerService = require_http.McpClientManagerService;
+exports.SkillService = require_http.SkillService;
 exports.SseTransportHandler = require_http.SseTransportHandler;
 exports.StdioTransportHandler = require_http.StdioTransportHandler;
+exports.UseToolTool = require_http.UseToolTool;
 exports.createServer = require_http.createServer;

package/dist/index.d.cts

@@ -341,4 +341,455 @@ declare class HttpTransportHandler implements HttpTransportHandler$1 {
   getHost(): string;
 }
 //#endregion
-export { HttpTransportHandler, McpClientConnection, McpHttpConfig, McpPromptInfo, McpResourceInfo, McpServerConfig, McpServerTransportConfig, McpServerTransportType, McpSseConfig, McpStdioConfig, McpToolInfo, PromptConfig, PromptSkillConfig, RemoteMcpConfiguration, type ServerOptions, Skill, SkillMetadata, SkillsConfig, SseTransportHandler, StdioTransportHandler, TRANSPORT_MODE, Tool, ToolDefinition, TransportConfig, TransportHandler, TransportMode, createServer };
+//#region src/services/McpClientManagerService.d.ts
+/**
+ * Service for managing MCP client connections to remote servers
+ */
+declare class McpClientManagerService {
+  private clients;
+  constructor();
+  /**
+   * Cleanup all resources on exit (child processes)
+   */
+  private cleanupOnExit;
+  /**
+   * Connect to an MCP server based on its configuration with timeout
+   * Uses the timeout from server config, falling back to default (30s)
+   */
+  connectToServer(serverName: string, config: McpServerConfig): Promise<void>;
+  /**
+   * Perform the actual connection to MCP server
+   */
+  private performConnection;
+  private connectStdioClient;
+  private connectHttpClient;
+  private connectSseClient;
+  /**
+   * Get a connected client by server name
+   */
+  getClient(serverName: string): McpClientConnection | undefined;
+  /**
+   * Get all connected clients
+   */
+  getAllClients(): McpClientConnection[];
+  /**
+   * Disconnect from a specific server
+   */
+  disconnectServer(serverName: string): Promise<void>;
+  /**
+   * Disconnect from all servers
+   */
+  disconnectAll(): Promise<void>;
+  /**
+   * Check if a server is connected
+   */
+  isConnected(serverName: string): boolean;
+}
+//#endregion
+//#region src/services/SkillService.d.ts
+/**
+ * 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();
+ */
+declare class SkillService {
+  private cwd;
+  private skillPaths;
+  private cachedSkills;
+  private skillsByName;
+  /** Active file watchers for skill directories */
+  private watchers;
+  /** Callback invoked when cache is invalidated due to file changes */
+  private 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: string, skillPaths: string[], options?: {
+    onCacheInvalidated?: () => void;
+  });
+  /**
+   * 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
+   */
+  getSkills(): Promise<Skill[]>;
+  /**
+   * 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
+   */
+  getSkill(name: string): Promise<Skill | undefined>;
+  /**
+   * 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(): void;
+  /**
+   * 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();
+   */
+  startWatching(): Promise<void>;
+  /**
+   * Stops all active file watchers.
+   * Should be called when the service is being disposed.
+   */
+  stopWatching(): void;
+  /**
+   * Watches a directory for changes to SKILL.md files.
+   * @param dirPath - Directory path to watch
+   * @param signal - AbortSignal to stop watching
+   */
+  private watchDirectory;
+  /**
+   * 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', ... }]
+   */
+  private loadSkillsFromDirectory;
+  /**
+   * 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
+   * @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
+   */
+  private loadSkillFile;
+}
+//#endregion
+//#region src/tools/DescribeToolsTool.d.ts
+/**
+ * Input schema for the DescribeToolsTool
+ * @property toolNames - Array of tool names to get detailed information about
+ */
+interface DescribeToolsToolInput {
+  toolNames: string[];
+}
+/**
+ * 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'] });
+ */
+declare class DescribeToolsTool implements Tool<DescribeToolsToolInput> {
+  static readonly TOOL_NAME = "describe_tools";
+  private clientManager;
+  private skillService;
+  private readonly liquid;
+  /** Cache for auto-detected skills from prompt front-matter */
+  private autoDetectedSkillsCache;
+  /** Unique server identifier for this one-mcp instance */
+  private 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: McpClientManagerService, skillService?: SkillService, serverId?: string);
+  /**
+   * 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(): void;
+  /**
+   * 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
+   */
+  private detectSkillsFromPromptFrontMatter;
+  /**
+   * Collects skills derived from prompt configurations across all connected MCP servers.
+   * Includes both explicitly configured prompts and auto-detected skills from front-matter.
+   *
+   * @returns Array of skill template data derived from prompts
+   */
+  private collectPromptSkills;
+  /**
+   * Finds a prompt-based skill by name from all connected MCP servers.
+   * 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
+   */
+  private findPromptSkill;
+  /**
+   * 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
+   */
+  private getPromptSkillContent;
+  /**
+   * Builds the combined toolkit description using a single 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. Skill names are prefixed with skill__ when they
+   * clash with MCP tools or other skills.
+   *
+   * @returns Object with rendered description and set of all tool names
+   */
+  private buildToolkitDescription;
+  /**
+   * Gets the tool definition including available tools and skills in a unified format.
+   *
+   * The definition includes:
+   * - 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 clashing.
+   * Skill names are prefixed with skill__ when clashing.
+   *
+   * @returns Tool definition with description and input schema
+   */
+  getDefinition(): Promise<ToolDefinition>;
+  /**
+   * 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
+   */
+  execute(input: DescribeToolsToolInput): Promise<CallToolResult>;
+}
+//#endregion
+//#region src/tools/UseToolTool.d.ts
+/**
+ * Input schema for UseToolTool
+ * @property toolName - Name of the tool or skill to execute
+ * @property toolArgs - Arguments to pass to the tool (from describe_tools schema)
+ */
+interface UseToolToolInput {
+  toolName: string;
+  toolArgs?: Record<string, unknown>;
+}
+/**
+ * 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' } });
+ */
+declare class UseToolTool implements Tool<UseToolToolInput> {
+  static readonly TOOL_NAME = "use_tool";
+  private clientManager;
+  private skillService;
+  /** Unique server identifier for this one-mcp instance */
+  private 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: McpClientManagerService, skillService?: SkillService, serverId?: string);
+  /**
+   * 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(): ToolDefinition;
+  /**
+   * 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
+   */
+  private executeSkill;
+  /**
+   * Finds a prompt-based skill by name from all connected MCP servers.
+   *
+   * @param skillName - The skill name to search for
+   * @returns PromptSkillMatch if found, undefined otherwise
+   */
+  private findPromptSkill;
+  /**
+   * Returns guidance message for prompt-based skill invocation.
+   *
+   * @param promptSkill - The prompt skill match that was found
+   * @returns CallToolResult with guidance message
+   */
+  private executePromptSkill;
+  /**
+   * 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
+   */
+  execute(input: UseToolToolInput): Promise<CallToolResult>;
+}
+//#endregion
+//#region src/services/ConfigFetcherService.d.ts
+interface ConfigFetcherOptions {
+  configFilePath?: string;
+  cacheTtlMs?: number;
+  useCache?: boolean;
+  remoteCacheTtlMs?: number;
+}
+/**
+ * Service for fetching and caching MCP server configurations from local file and remote sources
+ * Supports merging multiple remote configs with local config
+ */
+declare class ConfigFetcherService {
+  private configFilePath?;
+  private cacheTtlMs;
+  private cachedConfig;
+  private lastFetchTime;
+  private remoteConfigCache;
+  constructor(options: ConfigFetcherOptions);
+  /**
+   * Fetch MCP configuration from local file and remote sources with caching
+   * Merges remote configs with local config based on merge strategy
+   * @param forceRefresh - Force reload from source, bypassing cache
+   */
+  fetchConfiguration(forceRefresh?: boolean): Promise<RemoteMcpConfiguration>;
+  /**
+   * Load raw configuration data from a local file (supports JSON and YAML)
+   * Returns unparsed config data to allow access to remoteConfigs
+   */
+  private loadRawConfigFromFile;
+  /**
+   * Parse raw config data using Zod schema
+   * Filters out remoteConfigs to avoid including them in the final config
+   */
+  private parseConfig;
+  /**
+   * Load configuration from a remote URL with caching
+   *
+   * SECURITY NOTE: This method fetches remote configs based on URLs from the local config file.
+   * This is intentional and safe because:
+   * 1. URLs are user-controlled via their local config file (not external input)
+   * 2. SSRF protection validates URLs before fetching (blocks private IPs, enforces HTTPS)
+   * 3. Users explicitly opt-in to remote configs in their local configuration
+   * 4. This enables centralized config management (intended feature, not a vulnerability)
+   *
+   * CodeQL alert "file-access-to-http" is a false positive here - we're not leaking
+   * file contents to arbitrary URLs, we're fetching configs from user-specified sources.
+   */
+  private loadFromUrl;
+  /**
+   * Interpolate environment variables in a string
+   * Supports ${VAR_NAME} syntax
+   */
+  private interpolateEnvVars;
+  /**
+   * Merge two MCP configurations based on the specified merge strategy
+   * @param localConfig Configuration loaded from local file
+   * @param remoteConfig Configuration loaded from remote URL
+   * @param mergeStrategy Strategy for merging configs
+   * @returns Merged configuration
+   */
+  private mergeConfigurations;
+  /**
+   * Clear the cached configuration
+   */
+  clearCache(): void;
+  /**
+   * Check if cache is valid
+   */
+  isCacheValid(): boolean;
+}
+//#endregion
+export { ConfigFetcherService, DescribeToolsTool, HttpTransportHandler, McpClientConnection, McpClientManagerService, McpHttpConfig, McpPromptInfo, McpResourceInfo, McpServerConfig, McpServerTransportConfig, McpServerTransportType, McpSseConfig, McpStdioConfig, McpToolInfo, PromptConfig, PromptSkillConfig, RemoteMcpConfiguration, type ServerOptions, Skill, SkillMetadata, SkillService, SkillsConfig, SseTransportHandler, StdioTransportHandler, TRANSPORT_MODE, Tool, ToolDefinition, TransportConfig, TransportHandler, TransportMode, UseToolTool, createServer };

package/dist/index.d.mts

@@ -341,4 +341,455 @@ declare class HttpTransportHandler implements HttpTransportHandler$1 {
   getHost(): string;
 }
 //#endregion
-export { HttpTransportHandler, McpClientConnection, McpHttpConfig, McpPromptInfo, McpResourceInfo, McpServerConfig, McpServerTransportConfig, McpServerTransportType, McpSseConfig, McpStdioConfig, McpToolInfo, PromptConfig, PromptSkillConfig, RemoteMcpConfiguration, type ServerOptions, Skill, SkillMetadata, SkillsConfig, SseTransportHandler, StdioTransportHandler, TRANSPORT_MODE, Tool, ToolDefinition, TransportConfig, TransportHandler, TransportMode, createServer };
+//#region src/services/McpClientManagerService.d.ts
+/**
+ * Service for managing MCP client connections to remote servers
+ */
+declare class McpClientManagerService {
+  private clients;
+  constructor();
+  /**
+   * Cleanup all resources on exit (child processes)
+   */
+  private cleanupOnExit;
+  /**
+   * Connect to an MCP server based on its configuration with timeout
+   * Uses the timeout from server config, falling back to default (30s)
+   */
+  connectToServer(serverName: string, config: McpServerConfig): Promise<void>;
+  /**
+   * Perform the actual connection to MCP server
+   */
+  private performConnection;
+  private connectStdioClient;
+  private connectHttpClient;
+  private connectSseClient;
+  /**
+   * Get a connected client by server name
+   */
+  getClient(serverName: string): McpClientConnection | undefined;
+  /**
+   * Get all connected clients
+   */
+  getAllClients(): McpClientConnection[];
+  /**
+   * Disconnect from a specific server
+   */
+  disconnectServer(serverName: string): Promise<void>;
+  /**
+   * Disconnect from all servers
+   */
+  disconnectAll(): Promise<void>;
+  /**
+   * Check if a server is connected
+   */
+  isConnected(serverName: string): boolean;
+}
+//#endregion
+//#region src/services/SkillService.d.ts
+/**
+ * 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();
+ */
+declare class SkillService {
+  private cwd;
+  private skillPaths;
+  private cachedSkills;
+  private skillsByName;
+  /** Active file watchers for skill directories */
+  private watchers;
+  /** Callback invoked when cache is invalidated due to file changes */
+  private 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: string, skillPaths: string[], options?: {
+    onCacheInvalidated?: () => void;
+  });
+  /**
+   * 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
+   */
+  getSkills(): Promise<Skill[]>;
+  /**
+   * 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
+   */
+  getSkill(name: string): Promise<Skill | undefined>;
+  /**
+   * 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(): void;
+  /**
+   * 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();
+   */
+  startWatching(): Promise<void>;
+  /**
+   * Stops all active file watchers.
+   * Should be called when the service is being disposed.
+   */
+  stopWatching(): void;
+  /**
+   * Watches a directory for changes to SKILL.md files.
+   * @param dirPath - Directory path to watch
+   * @param signal - AbortSignal to stop watching
+   */
+  private watchDirectory;
+  /**
+   * 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', ... }]
+   */
+  private loadSkillsFromDirectory;
+  /**
+   * 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
+   * @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
+   */
+  private loadSkillFile;
+}
+//#endregion
+//#region src/tools/DescribeToolsTool.d.ts
+/**
+ * Input schema for the DescribeToolsTool
+ * @property toolNames - Array of tool names to get detailed information about
+ */
+interface DescribeToolsToolInput {
+  toolNames: string[];
+}
+/**
+ * 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'] });
+ */
+declare class DescribeToolsTool implements Tool<DescribeToolsToolInput> {
+  static readonly TOOL_NAME = "describe_tools";
+  private clientManager;
+  private skillService;
+  private readonly liquid;
+  /** Cache for auto-detected skills from prompt front-matter */
+  private autoDetectedSkillsCache;
+  /** Unique server identifier for this one-mcp instance */
+  private 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: McpClientManagerService, skillService?: SkillService, serverId?: string);
+  /**
+   * 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(): void;
+  /**
+   * 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
+   */
+  private detectSkillsFromPromptFrontMatter;
+  /**
+   * Collects skills derived from prompt configurations across all connected MCP servers.
+   * Includes both explicitly configured prompts and auto-detected skills from front-matter.
+   *
+   * @returns Array of skill template data derived from prompts
+   */
+  private collectPromptSkills;
+  /**
+   * Finds a prompt-based skill by name from all connected MCP servers.
+   * 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
+   */
+  private findPromptSkill;
+  /**
+   * 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
+   */
+  private getPromptSkillContent;
+  /**
+   * Builds the combined toolkit description using a single 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. Skill names are prefixed with skill__ when they
+   * clash with MCP tools or other skills.
+   *
+   * @returns Object with rendered description and set of all tool names
+   */
+  private buildToolkitDescription;
+  /**
+   * Gets the tool definition including available tools and skills in a unified format.
+   *
+   * The definition includes:
+   * - 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 clashing.
+   * Skill names are prefixed with skill__ when clashing.
+   *
+   * @returns Tool definition with description and input schema
+   */
+  getDefinition(): Promise<ToolDefinition>;
+  /**
+   * 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
+   */
+  execute(input: DescribeToolsToolInput): Promise<CallToolResult>;
+}
+//#endregion
+//#region src/tools/UseToolTool.d.ts
+/**
+ * Input schema for UseToolTool
+ * @property toolName - Name of the tool or skill to execute
+ * @property toolArgs - Arguments to pass to the tool (from describe_tools schema)
+ */
+interface UseToolToolInput {
+  toolName: string;
+  toolArgs?: Record<string, unknown>;
+}
+/**
+ * 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' } });
+ */
+declare class UseToolTool implements Tool<UseToolToolInput> {
+  static readonly TOOL_NAME = "use_tool";
+  private clientManager;
+  private skillService;
+  /** Unique server identifier for this one-mcp instance */
+  private 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: McpClientManagerService, skillService?: SkillService, serverId?: string);
+  /**
+   * 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(): ToolDefinition;
+  /**
+   * 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
+   */
+  private executeSkill;
+  /**
+   * Finds a prompt-based skill by name from all connected MCP servers.
+   *
+   * @param skillName - The skill name to search for
+   * @returns PromptSkillMatch if found, undefined otherwise
+   */
+  private findPromptSkill;
+  /**
+   * Returns guidance message for prompt-based skill invocation.
+   *
+   * @param promptSkill - The prompt skill match that was found
+   * @returns CallToolResult with guidance message
+   */
+  private executePromptSkill;
+  /**
+   * 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
+   */
+  execute(input: UseToolToolInput): Promise<CallToolResult>;
+}
+//#endregion
+//#region src/services/ConfigFetcherService.d.ts
+interface ConfigFetcherOptions {
+  configFilePath?: string;
+  cacheTtlMs?: number;
+  useCache?: boolean;
+  remoteCacheTtlMs?: number;
+}
+/**
+ * Service for fetching and caching MCP server configurations from local file and remote sources
+ * Supports merging multiple remote configs with local config
+ */
+declare class ConfigFetcherService {
+  private configFilePath?;
+  private cacheTtlMs;
+  private cachedConfig;
+  private lastFetchTime;
+  private remoteConfigCache;
+  constructor(options: ConfigFetcherOptions);
+  /**
+   * Fetch MCP configuration from local file and remote sources with caching
+   * Merges remote configs with local config based on merge strategy
+   * @param forceRefresh - Force reload from source, bypassing cache
+   */
+  fetchConfiguration(forceRefresh?: boolean): Promise<RemoteMcpConfiguration>;
+  /**
+   * Load raw configuration data from a local file (supports JSON and YAML)
+   * Returns unparsed config data to allow access to remoteConfigs
+   */
+  private loadRawConfigFromFile;
+  /**
+   * Parse raw config data using Zod schema
+   * Filters out remoteConfigs to avoid including them in the final config
+   */
+  private parseConfig;
+  /**
+   * Load configuration from a remote URL with caching
+   *
+   * SECURITY NOTE: This method fetches remote configs based on URLs from the local config file.
+   * This is intentional and safe because:
+   * 1. URLs are user-controlled via their local config file (not external input)
+   * 2. SSRF protection validates URLs before fetching (blocks private IPs, enforces HTTPS)
+   * 3. Users explicitly opt-in to remote configs in their local configuration
+   * 4. This enables centralized config management (intended feature, not a vulnerability)
+   *
+   * CodeQL alert "file-access-to-http" is a false positive here - we're not leaking
+   * file contents to arbitrary URLs, we're fetching configs from user-specified sources.
+   */
+  private loadFromUrl;
+  /**
+   * Interpolate environment variables in a string
+   * Supports ${VAR_NAME} syntax
+   */
+  private interpolateEnvVars;
+  /**
+   * Merge two MCP configurations based on the specified merge strategy
+   * @param localConfig Configuration loaded from local file
+   * @param remoteConfig Configuration loaded from remote URL
+   * @param mergeStrategy Strategy for merging configs
+   * @returns Merged configuration
+   */
+  private mergeConfigurations;
+  /**
+   * Clear the cached configuration
+   */
+  clearCache(): void;
+  /**
+   * Check if cache is valid
+   */
+  isCacheValid(): boolean;
+}
+//#endregion
+export { ConfigFetcherService, DescribeToolsTool, HttpTransportHandler, McpClientConnection, McpClientManagerService, McpHttpConfig, McpPromptInfo, McpResourceInfo, McpServerConfig, McpServerTransportConfig, McpServerTransportType, McpSseConfig, McpStdioConfig, McpToolInfo, PromptConfig, PromptSkillConfig, RemoteMcpConfiguration, type ServerOptions, Skill, SkillMetadata, SkillService, SkillsConfig, SseTransportHandler, StdioTransportHandler, TRANSPORT_MODE, Tool, ToolDefinition, TransportConfig, TransportHandler, TransportMode, UseToolTool, createServer };

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { i as createServer, n as SseTransportHandler, r as StdioTransportHandler, t as HttpTransportHandler } from "./http-DV3-1Emn.mjs";
+import { a as UseToolTool, i as createServer, l as McpClientManagerService, n as SseTransportHandler, o as DescribeToolsTool, r as StdioTransportHandler, s as SkillService, t as HttpTransportHandler, u as ConfigFetcherService } from "./http-BzTXYfkN.mjs";
 
-export { HttpTransportHandler, SseTransportHandler, StdioTransportHandler, createServer };
+export { ConfigFetcherService, DescribeToolsTool, HttpTransportHandler, McpClientManagerService, SkillService, SseTransportHandler, StdioTransportHandler, UseToolTool, createServer };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agiflowai/one-mcp",
   "description": "One MCP server package",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "license": "AGPL-3.0",
   "keywords": [
     "mcp",
@@ -27,7 +27,7 @@
     "js-yaml": "^4.1.0",
     "liquidjs": "^10.21.0",
     "zod": "^3.24.1",
-    "@agiflowai/aicode-utils": "1.0.12"
+    "@agiflowai/aicode-utils": "1.0.13"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",