@agiflowai/one-mcp 0.2.0 → 0.2.2

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

@@ -1,16 +1,18 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, 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 { 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 { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import express from "express";
-import { randomUUID } from "node:crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 
 //#region src/utils/mcpConfigSchema.ts
@@ -80,6 +82,95 @@ function interpolateEnvVarsInObject(obj) {
 	return obj;
 }
 /**
+* Private IP range patterns for SSRF protection
+* Covers both IPv4 and IPv6 loopback, private, and link-local ranges
+*/
+const PRIVATE_IP_PATTERNS = [
+	/^127\./,
+	/^10\./,
+	/^172\.(1[6-9]|2\d|3[01])\./,
+	/^192\.168\./,
+	/^169\.254\./,
+	/^0\./,
+	/^224\./,
+	/^240\./,
+	/^localhost$/i,
+	/^.*\.localhost$/i,
+	/^\[::\]/,
+	/^\[::1\]/,
+	/^\[0:0:0:0:0:0:0:1\]/,
+	/^\[0{1,4}:0{1,4}:0{1,4}:0{1,4}:0{1,4}:0{1,4}:0{1,4}:1\]/i,
+	/^\[fe80:/i,
+	/^\[fc00:/i,
+	/^\[fd00:/i,
+	/^\[::ffff:127\./i,
+	/^\[::ffff:7f[0-9a-f]{2}:/i,
+	/^\[::ffff:10\./i,
+	/^\[::ffff:a[0-9a-f]{2}:/i,
+	/^\[::ffff:172\.(1[6-9]|2\d|3[01])\./i,
+	/^\[::ffff:ac1[0-9a-f]:/i,
+	/^\[::ffff:192\.168\./i,
+	/^\[::ffff:c0a8:/i,
+	/^\[::ffff:169\.254\./i,
+	/^\[::ffff:a9fe:/i,
+	/^\[::ffff:0\./i,
+	/^\[::127\./i,
+	/^\[::7f[0-9a-f]{2}:/i,
+	/^\[::10\./i,
+	/^\[::a[0-9a-f]{2}:/i,
+	/^\[::192\.168\./i,
+	/^\[::c0a8:/i
+];
+/**
+* Validate URL for SSRF protection
+*
+* @param url - The URL to validate (after env var interpolation)
+* @param security - Security settings
+* @throws Error if URL is unsafe
+*/
+function validateUrlSecurity(url, security) {
+	const allowPrivateIPs = security?.allowPrivateIPs ?? false;
+	const enforceHttps = security?.enforceHttps ?? true;
+	let parsedUrl;
+	try {
+		parsedUrl = new URL(url);
+	} catch (error) {
+		throw new Error(`Invalid URL format: ${url}`);
+	}
+	const protocol = parsedUrl.protocol.replace(":", "");
+	if (enforceHttps && protocol !== "https") throw new Error(`HTTPS is required for security. URL uses '${protocol}://'. Set security.enforceHttps: false to allow HTTP.`);
+	if (protocol !== "http" && protocol !== "https") throw new Error(`Invalid URL protocol '${protocol}://'. Only http:// and https:// are allowed.`);
+	if (!allowPrivateIPs) {
+		const hostname = parsedUrl.hostname.toLowerCase();
+		if (PRIVATE_IP_PATTERNS.some((pattern) => pattern.test(hostname))) throw new Error(`Private IP addresses and localhost are blocked for security (${hostname}). Set security.allowPrivateIPs: true to allow internal networks.`);
+	}
+}
+/**
+* Validate a remote config source against its validation rules
+*
+* @param source - Remote config source with validation rules
+* @throws Error if validation fails
+*/
+function validateRemoteConfigSource(source) {
+	const interpolatedUrl = interpolateEnvVars(source.url);
+	validateUrlSecurity(interpolatedUrl, source.security);
+	if (!source.validation) return;
+	if (source.validation.url) {
+		if (!new RegExp(source.validation.url).test(interpolatedUrl)) throw new Error(`Remote config URL "${interpolatedUrl}" does not match validation pattern: ${source.validation.url}`);
+	}
+	if (source.validation.headers && Object.keys(source.validation.headers).length > 0) {
+		if (!source.headers) {
+			const requiredHeaders = Object.keys(source.validation.headers);
+			throw new Error(`Remote config is missing required headers: ${requiredHeaders.join(", ")}`);
+		}
+		for (const [headerName, pattern] of Object.entries(source.validation.headers)) {
+			if (!(headerName in source.headers)) throw new Error(`Remote config is missing required header: ${headerName}`);
+			const interpolatedHeaderValue = interpolateEnvVars(source.headers[headerName]);
+			if (!new RegExp(pattern).test(interpolatedHeaderValue)) throw new Error(`Remote config header "${headerName}" value "${interpolatedHeaderValue}" does not match validation pattern: ${pattern}`);
+		}
+	}
+}
+/**
 * Claude Code / Claude Desktop standard MCP config format
 * This is the format users write in their config files
 */
@@ -105,10 +196,32 @@ const ClaudeCodeHttpServerSchema = z.object({
 	config: AdditionalConfigSchema
 });
 const ClaudeCodeServerConfigSchema = z.union([ClaudeCodeStdioServerSchema, ClaudeCodeHttpServerSchema]);
+const RemoteConfigValidationSchema = z.object({
+	url: z.string().optional(),
+	headers: z.record(z.string(), z.string()).optional()
+}).optional();
+const RemoteConfigSecuritySchema = z.object({
+	allowPrivateIPs: z.boolean().optional(),
+	enforceHttps: z.boolean().optional()
+}).optional();
+const RemoteConfigSourceSchema = z.object({
+	url: z.string(),
+	headers: z.record(z.string(), z.string()).optional(),
+	validation: RemoteConfigValidationSchema,
+	security: RemoteConfigSecuritySchema,
+	mergeStrategy: z.enum([
+		"local-priority",
+		"remote-priority",
+		"merge-deep"
+	]).optional()
+});
 /**
 * Full Claude Code MCP configuration schema
 */
-const ClaudeCodeMcpConfigSchema = z.object({ mcpServers: z.record(z.string(), ClaudeCodeServerConfigSchema) });
+const ClaudeCodeMcpConfigSchema = z.object({
+	mcpServers: z.record(z.string(), ClaudeCodeServerConfigSchema),
+	remoteConfigs: z.array(RemoteConfigSourceSchema).optional()
+});
 /**
 * Internal MCP config format
 * This is the normalized format used internally by the proxy
@@ -217,6 +330,226 @@ function parseMcpConfig(rawConfig) {
 	return InternalMcpConfigSchema.parse(internalConfig);
 }
 
+//#endregion
+//#region src/services/RemoteConfigCacheService.ts
+/**
+* RemoteConfigCacheService
+*
+* DESIGN PATTERNS:
+* - Service pattern for cache management
+* - Single responsibility principle
+* - File-based caching with TTL support
+*
+* CODING STANDARDS:
+* - Use async/await for asynchronous operations
+* - Handle file system errors gracefully
+* - Keep cache organized by URL hash
+* - Implement automatic cache expiration
+*
+* AVOID:
+* - Storing sensitive data in cache (headers with tokens)
+* - Unbounded cache growth
+* - Missing error handling for file operations
+*/
+/**
+* Service for caching remote MCP configurations
+*/
+var RemoteConfigCacheService = class {
+	cacheDir;
+	cacheTTL;
+	readEnabled;
+	writeEnabled;
+	constructor(options) {
+		this.cacheDir = join(tmpdir(), "one-mcp-cache", "remote-configs");
+		this.cacheTTL = options?.ttl || 3600 * 1e3;
+		this.readEnabled = options?.readEnabled !== void 0 ? options.readEnabled : true;
+		this.writeEnabled = options?.writeEnabled !== void 0 ? options.writeEnabled : true;
+	}
+	/**
+	* Generate a hash key from remote config URL
+	* Only uses URL for hashing to avoid caching credentials in the key
+	*/
+	generateCacheKey(url) {
+		return createHash("sha256").update(url).digest("hex");
+	}
+	/**
+	* Get the cache file path for a given cache key
+	*/
+	getCacheFilePath(cacheKey) {
+		return join(this.cacheDir, `${cacheKey}.json`);
+	}
+	/**
+	* Initialize cache directory
+	* Uses mkdir with recursive option which handles existing directories gracefully
+	* (no TOCTOU race condition from existsSync check)
+	*/
+	async ensureCacheDir() {
+		try {
+			await mkdir(this.cacheDir, { recursive: true });
+		} catch (error) {
+			if (error?.code !== "EEXIST") throw error;
+		}
+	}
+	/**
+	* Get cached data for a remote config URL
+	*/
+	async get(url) {
+		if (!this.readEnabled) return null;
+		try {
+			await this.ensureCacheDir();
+			const cacheKey = this.generateCacheKey(url);
+			const cacheFilePath = this.getCacheFilePath(cacheKey);
+			if (!existsSync(cacheFilePath)) return null;
+			const cacheContent = await readFile(cacheFilePath, "utf-8");
+			const cacheEntry = JSON.parse(cacheContent);
+			const now = Date.now();
+			if (now > cacheEntry.expiresAt) {
+				await unlink(cacheFilePath).catch(() => {});
+				return null;
+			}
+			const expiresInSeconds = Math.round((cacheEntry.expiresAt - now) / 1e3);
+			console.error(`Remote config cache hit for ${url} (expires in ${expiresInSeconds}s)`);
+			return cacheEntry.data;
+		} catch (error) {
+			console.error(`Failed to read remote config cache for ${url}:`, error);
+			return null;
+		}
+	}
+	/**
+	* Set cached data for a remote config URL
+	*/
+	async set(url, data) {
+		if (!this.writeEnabled) return;
+		try {
+			await this.ensureCacheDir();
+			const cacheKey = this.generateCacheKey(url);
+			const cacheFilePath = this.getCacheFilePath(cacheKey);
+			const now = Date.now();
+			const cacheEntry = {
+				data,
+				timestamp: now,
+				expiresAt: now + this.cacheTTL,
+				url
+			};
+			await writeFile(cacheFilePath, JSON.stringify(cacheEntry, null, 2), "utf-8");
+			console.error(`Cached remote config for ${url} (TTL: ${Math.round(this.cacheTTL / 1e3)}s)`);
+		} catch (error) {
+			console.error(`Failed to write remote config cache for ${url}:`, error);
+		}
+	}
+	/**
+	* Clear cache for a specific URL
+	*/
+	async clear(url) {
+		try {
+			const cacheKey = this.generateCacheKey(url);
+			const cacheFilePath = this.getCacheFilePath(cacheKey);
+			if (existsSync(cacheFilePath)) {
+				await unlink(cacheFilePath);
+				console.error(`Cleared remote config cache for ${url}`);
+			}
+		} catch (error) {
+			console.error(`Failed to clear remote config cache for ${url}:`, error);
+		}
+	}
+	/**
+	* Clear all cached remote configs
+	*/
+	async clearAll() {
+		try {
+			if (!existsSync(this.cacheDir)) return;
+			const files = await readdir(this.cacheDir);
+			const deletePromises = files.filter((file) => file.endsWith(".json")).map((file) => unlink(join(this.cacheDir, file)).catch(() => {}));
+			await Promise.all(deletePromises);
+			console.error(`Cleared all remote config cache entries (${files.length} files)`);
+		} catch (error) {
+			console.error("Failed to clear all remote config cache:", error);
+		}
+	}
+	/**
+	* Clean up expired cache entries
+	*/
+	async cleanExpired() {
+		try {
+			if (!existsSync(this.cacheDir)) return;
+			const now = Date.now();
+			const files = await readdir(this.cacheDir);
+			let expiredCount = 0;
+			for (const file of files) {
+				if (!file.endsWith(".json")) continue;
+				const filePath = join(this.cacheDir, file);
+				try {
+					const content = await readFile(filePath, "utf-8");
+					if (now > JSON.parse(content).expiresAt) {
+						await unlink(filePath);
+						expiredCount++;
+					}
+				} catch (error) {
+					await unlink(filePath).catch(() => {});
+					expiredCount++;
+				}
+			}
+			if (expiredCount > 0) console.error(`Cleaned up ${expiredCount} expired remote config cache entries`);
+		} catch (error) {
+			console.error("Failed to clean expired remote config cache:", error);
+		}
+	}
+	/**
+	* Get cache statistics
+	*/
+	async getStats() {
+		try {
+			if (!existsSync(this.cacheDir)) return {
+				totalEntries: 0,
+				totalSize: 0
+			};
+			const jsonFiles = (await readdir(this.cacheDir)).filter((file) => file.endsWith(".json"));
+			let totalSize = 0;
+			for (const file of jsonFiles) {
+				const filePath = join(this.cacheDir, file);
+				try {
+					const content = await readFile(filePath, "utf-8");
+					totalSize += Buffer.byteLength(content, "utf-8");
+				} catch {}
+			}
+			return {
+				totalEntries: jsonFiles.length,
+				totalSize
+			};
+		} catch (error) {
+			console.error("Failed to get remote config cache stats:", error);
+			return {
+				totalEntries: 0,
+				totalSize: 0
+			};
+		}
+	}
+	/**
+	* Check if read from cache is enabled
+	*/
+	isReadEnabled() {
+		return this.readEnabled;
+	}
+	/**
+	* Check if write to cache is enabled
+	*/
+	isWriteEnabled() {
+		return this.writeEnabled;
+	}
+	/**
+	* Set read enabled state
+	*/
+	setReadEnabled(enabled) {
+		this.readEnabled = enabled;
+	}
+	/**
+	* Set write enabled state
+	*/
+	setWriteEnabled(enabled) {
+		this.writeEnabled = enabled;
+	}
+};
+
 //#endregion
 //#region src/services/ConfigFetcherService.ts
 /**
@@ -238,35 +571,62 @@ function parseMcpConfig(rawConfig) {
 * - Direct tool implementation (services should be tool-agnostic)
 */
 /**
-* Service for fetching and caching MCP server configurations from local file
+* Service for fetching and caching MCP server configurations from local file and remote sources
+* Supports merging multiple remote configs with local config
 */
 var ConfigFetcherService = class {
 	configFilePath;
 	cacheTtlMs;
 	cachedConfig = null;
 	lastFetchTime = 0;
+	remoteConfigCache;
 	constructor(options) {
 		this.configFilePath = options.configFilePath;
 		this.cacheTtlMs = options.cacheTtlMs || 6e4;
+		const useCache = options.useCache !== void 0 ? options.useCache : true;
+		this.remoteConfigCache = new RemoteConfigCacheService({
+			ttl: options.remoteCacheTtlMs || 3600 * 1e3,
+			readEnabled: useCache,
+			writeEnabled: true
+		});
 		if (!this.configFilePath) throw new Error("configFilePath must be provided");
 	}
 	/**
-	* Fetch MCP configuration from local file with caching
+	* 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
 	*/
 	async fetchConfiguration(forceRefresh = false) {
 		const now = Date.now();
 		if (!forceRefresh && this.cachedConfig && now - this.lastFetchTime < this.cacheTtlMs) return this.cachedConfig;
-		const config = await this.loadFromFile();
-		if (!config.mcpServers || typeof config.mcpServers !== "object") throw new Error("Invalid MCP configuration: missing or invalid mcpServers");
-		this.cachedConfig = config;
+		const localConfigData = await this.loadRawConfigFromFile();
+		const remoteConfigSources = localConfigData.remoteConfigs || [];
+		let mergedConfig = await this.parseConfig(localConfigData);
+		const remoteConfigPromises = remoteConfigSources.map(async (remoteSource) => {
+			try {
+				validateRemoteConfigSource(remoteSource);
+				return {
+					config: await this.loadFromUrl(remoteSource),
+					mergeStrategy: remoteSource.mergeStrategy || "local-priority",
+					url: remoteSource.url
+				};
+			} catch (error) {
+				if (error instanceof Error) console.error(`Failed to fetch remote config from ${remoteSource.url}: ${error.message}`);
+				return null;
+			}
+		});
+		const remoteConfigResults = await Promise.all(remoteConfigPromises);
+		for (const result of remoteConfigResults) if (result !== null) mergedConfig = this.mergeConfigurations(mergedConfig, result.config, result.mergeStrategy);
+		if (!mergedConfig.mcpServers || typeof mergedConfig.mcpServers !== "object") throw new Error("Invalid MCP configuration: missing or invalid mcpServers");
+		this.cachedConfig = mergedConfig;
 		this.lastFetchTime = now;
-		return config;
+		return mergedConfig;
 	}
 	/**
-	* Load configuration from a local file (supports JSON and YAML)
+	* Load raw configuration data from a local file (supports JSON and YAML)
+	* Returns unparsed config data to allow access to remoteConfigs
 	*/
-	async loadFromFile() {
+	async loadRawConfigFromFile() {
 		if (!this.configFilePath) throw new Error("No config file path provided");
 		if (!existsSync(this.configFilePath)) throw new Error(`Config file not found: ${this.configFilePath}`);
 		try {
@@ -274,13 +634,117 @@ var ConfigFetcherService = class {
 			let rawConfig;
 			if (this.configFilePath.endsWith(".yaml") || this.configFilePath.endsWith(".yml")) rawConfig = yaml.load(content);
 			else rawConfig = JSON.parse(content);
-			return parseMcpConfig(rawConfig);
+			return rawConfig;
 		} catch (error) {
 			if (error instanceof Error) throw new Error(`Failed to load config file: ${error.message}`);
 			throw new Error("Failed to load config file: Unknown error");
 		}
 	}
 	/**
+	* Parse raw config data using Zod schema
+	* Filters out remoteConfigs to avoid including them in the final config
+	*/
+	async parseConfig(rawConfig) {
+		try {
+			const { remoteConfigs, ...configWithoutRemote } = rawConfig;
+			return parseMcpConfig(configWithoutRemote);
+		} catch (error) {
+			if (error instanceof Error) throw new Error(`Failed to parse config: ${error.message}`);
+			throw new Error("Failed to parse config: Unknown error");
+		}
+	}
+	/**
+	* 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.
+	*/
+	async loadFromUrl(source) {
+		try {
+			const interpolatedUrl = this.interpolateEnvVars(source.url);
+			const cachedConfig = await this.remoteConfigCache.get(interpolatedUrl);
+			if (cachedConfig) return cachedConfig;
+			const interpolatedHeaders = source.headers ? Object.fromEntries(Object.entries(source.headers).map(([key, value]) => [key, this.interpolateEnvVars(value)])) : {};
+			const response = await fetch(interpolatedUrl, { headers: interpolatedHeaders });
+			if (!response.ok) throw new Error(`Failed to fetch remote config: ${response.status} ${response.statusText}`);
+			const config = parseMcpConfig(await response.json());
+			await this.remoteConfigCache.set(interpolatedUrl, config);
+			return config;
+		} catch (error) {
+			if (error instanceof Error) throw new Error(`Failed to fetch remote config from ${source.url}: ${error.message}`);
+			throw new Error(`Failed to fetch remote config from ${source.url}: Unknown error`);
+		}
+	}
+	/**
+	* Interpolate environment variables in a string
+	* Supports ${VAR_NAME} syntax
+	*/
+	interpolateEnvVars(value) {
+		return value.replace(/\$\{([^}]+)\}/g, (_, varName) => {
+			const envValue = process.env[varName];
+			if (envValue === void 0) {
+				console.warn(`Environment variable ${varName} is not defined, keeping placeholder`);
+				return `\${${varName}}`;
+			}
+			return envValue;
+		});
+	}
+	/**
+	* 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
+	*/
+	mergeConfigurations(localConfig, remoteConfig, mergeStrategy) {
+		switch (mergeStrategy) {
+			case "local-priority": return { mcpServers: {
+				...remoteConfig.mcpServers,
+				...localConfig.mcpServers
+			} };
+			case "remote-priority": return { mcpServers: {
+				...localConfig.mcpServers,
+				...remoteConfig.mcpServers
+			} };
+			case "merge-deep": {
+				const merged = { ...remoteConfig.mcpServers };
+				for (const [serverName, localServerConfig] of Object.entries(localConfig.mcpServers)) if (merged[serverName]) {
+					const remoteServer = merged[serverName];
+					const mergedConfig = {
+						...remoteServer.config,
+						...localServerConfig.config
+					};
+					const remoteEnv = "env" in remoteServer.config ? remoteServer.config.env : void 0;
+					const localEnv = "env" in localServerConfig.config ? localServerConfig.config.env : void 0;
+					if (remoteEnv || localEnv) mergedConfig.env = {
+						...remoteEnv || {},
+						...localEnv || {}
+					};
+					const remoteHeaders = "headers" in remoteServer.config ? remoteServer.config.headers : void 0;
+					const localHeaders = "headers" in localServerConfig.config ? localServerConfig.config.headers : void 0;
+					if (remoteHeaders || localHeaders) mergedConfig.headers = {
+						...remoteHeaders || {},
+						...localHeaders || {}
+					};
+					merged[serverName] = {
+						...remoteServer,
+						...localServerConfig,
+						config: mergedConfig
+					};
+				} else merged[serverName] = localServerConfig;
+				return { mcpServers: merged };
+			}
+			default: throw new Error(`Unknown merge strategy: ${mergeStrategy}`);
+		}
+	}
+	/**
 	* Clear the cached configuration
 	*/
 	clearCache() {
@@ -487,6 +951,75 @@ var McpClientManagerService = class {
 	}
 };
 
+//#endregion
+//#region src/utils/findConfigFile.ts
+/**
+* Config File Finder Utility
+*
+* DESIGN PATTERNS:
+* - Utility function pattern for reusable logic
+* - Fail-fast pattern with early returns
+* - Environment variable configuration pattern
+*
+* CODING STANDARDS:
+* - Use sync filesystem operations for config discovery (performance)
+* - Check PROJECT_PATH environment variable first
+* - Fall back to current working directory
+* - Support both .yaml and .json extensions
+* - Return null if no config file is found
+*
+* AVOID:
+* - Throwing errors (return null instead for optional config)
+* - Hardcoded file names without extension variants
+* - Ignoring environment variables
+*/
+/**
+* Find MCP configuration file by checking PROJECT_PATH first, then cwd
+* Looks for both mcp-config.yaml and mcp-config.json
+*
+* @returns Absolute path to config file, or null if not found
+*/
+function findConfigFile() {
+	const configFileNames = [
+		"mcp-config.yaml",
+		"mcp-config.yml",
+		"mcp-config.json"
+	];
+	const projectPath = process.env.PROJECT_PATH;
+	if (projectPath) for (const fileName of configFileNames) {
+		const configPath = resolve(projectPath, fileName);
+		if (existsSync(configPath)) return configPath;
+	}
+	const cwd = process.cwd();
+	for (const fileName of configFileNames) {
+		const configPath = join(cwd, fileName);
+		if (existsSync(configPath)) return configPath;
+	}
+	return null;
+}
+
+//#endregion
+//#region src/utils/parseToolName.ts
+/**
+* Parse tool name to extract server and actual tool name
+* Supports both plain tool names and prefixed format: {serverName}__{toolName}
+*
+* @param toolName - The tool name to parse (e.g., "my_tool" or "server__my_tool")
+* @returns Parsed result with optional serverName and actualToolName
+*
+* @example
+* parseToolName("my_tool") // { actualToolName: "my_tool" }
+* parseToolName("server__my_tool") // { serverName: "server", actualToolName: "my_tool" }
+*/
+function parseToolName(toolName) {
+	const separatorIndex = toolName.indexOf("__");
+	if (separatorIndex > 0) return {
+		serverName: toolName.substring(0, separatorIndex),
+		actualToolName: toolName.substring(separatorIndex + 2)
+	};
+	return { actualToolName: toolName };
+}
+
 //#endregion
 //#region src/tools/DescribeToolsTool.ts
 var DescribeToolsTool = class DescribeToolsTool {
@@ -497,46 +1030,50 @@ var DescribeToolsTool = class DescribeToolsTool {
 	}
 	async getDefinition() {
 		const clients = this.clientManager.getAllClients();
-		const serverDescriptions = await Promise.all(clients.map(async (client) => {
+		const toolToServers = /* @__PURE__ */ new Map();
+		const serverToolsMap = /* @__PURE__ */ new Map();
+		await Promise.all(clients.map(async (client) => {
 			try {
 				const tools = await client.listTools();
 				const blacklist = new Set(client.toolBlacklist || []);
 				const filteredTools = tools.filter((t) => !blacklist.has(t.name));
-				const toolList = client.omitToolDescription ? filteredTools.map((t) => t.name).join(", ") : filteredTools.map((t) => `${t.name}: ${t.description || "No description"}`).join("\n");
-				const instructionLine = client.serverInstruction ? `\n- Description: ${client.serverInstruction}` : "";
-				return `\n\n### Server: ${client.serverName}${instructionLine}\n- Available tools:${toolList ? "\n" + toolList : ""}`;
+				serverToolsMap.set(client.serverName, filteredTools);
+				for (const tool of filteredTools) {
+					if (!toolToServers.has(tool.name)) toolToServers.set(tool.name, []);
+					toolToServers.get(tool.name).push(client.serverName);
+				}
 			} catch (error) {
 				console.error(`Failed to list tools from ${client.serverName}:`, error);
-				const instructionLine = client.serverInstruction ? `\n- Description: ${client.serverInstruction}` : "";
-				return `\n\n**Server: ${client.serverName}**${instructionLine}\n`;
+				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;
+			};
+			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 {
 			name: DescribeToolsTool.TOOL_NAME,
-			description: `Learn how to use multiple MCP tools before using them. Below are supported tools and capabilities.
-
-## Available MCP Servers:${serverDescriptions.join("")}
+			description: `## Available MCP Servers:${serverDescriptions.join("")}
 
 ## Usage:
-You MUST call this tool with a list of tool names to learn how to use them properly before use_tool; this includes:
+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.`,
 			inputSchema: {
 				type: "object",
-				properties: {
-					toolNames: {
-						type: "array",
-						items: { type: "string" },
-						description: "List of tool names to get detailed information about",
-						minItems: 1
-					},
-					serverName: {
-						type: "string",
-						description: "Optional server name to search within. If not specified, searches all servers."
-					}
-				},
+				properties: { toolNames: {
+					type: "array",
+					items: { type: "string" },
+					description: "List of tool names to get detailed information about",
+					minItems: 1
+				} },
 				required: ["toolNames"],
 				additionalProperties: false
 			}
@@ -544,7 +1081,7 @@ This tool is optimized for batch queries - you can request multiple tools at onc
 	}
 	async execute(input) {
 		try {
-			const { toolNames, serverName } = input;
+			const { toolNames } = input;
 			const clients = this.clientManager.getAllClients();
 			if (!toolNames || toolNames.length === 0) return {
 				content: [{
@@ -553,127 +1090,85 @@ This tool is optimized for batch queries - you can request multiple tools at onc
 				}],
 				isError: true
 			};
-			if (serverName) {
-				const client = this.clientManager.getClient(serverName);
-				if (!client) return {
-					content: [{
-						type: "text",
-						text: `Server "${serverName}" not found. Available servers: ${clients.map((c) => c.serverName).join(", ")}`
-					}],
-					isError: true
-				};
-				const tools = await client.listTools();
-				const blacklist = new Set(client.toolBlacklist || []);
-				const filteredTools = tools.filter((t) => !blacklist.has(t.name));
-				const foundTools$1 = [];
-				const notFoundTools$1 = [];
-				for (const toolName of toolNames) {
-					if (blacklist.has(toolName)) {
-						notFoundTools$1.push(toolName);
-						continue;
-					}
-					const tool = filteredTools.find((t) => t.name === toolName);
-					if (tool) foundTools$1.push({
-						server: serverName,
-						tool: {
-							name: tool.name,
-							description: tool.description,
-							inputSchema: tool.inputSchema
-						}
-					});
-					else notFoundTools$1.push(toolName);
-				}
-				if (foundTools$1.length === 0) return {
-					content: [{
-						type: "text",
-						text: `None of the requested tools found on server "${serverName}".\nRequested: ${toolNames.join(", ")}\nAvailable tools: ${tools.map((t) => t.name).join(", ")}`
-					}],
-					isError: true
-				};
-				const result$1 = { tools: foundTools$1 };
-				if (notFoundTools$1.length > 0) {
-					result$1.notFound = notFoundTools$1;
-					result$1.warning = `Some tools were not found on server "${serverName}": ${notFoundTools$1.join(", ")}`;
-				}
-				return { content: [{
-					type: "text",
-					text: JSON.stringify(result$1, null, 2)
-				}] };
-			}
-			const foundTools = [];
-			const notFoundTools = [...toolNames];
-			const toolMatches = /* @__PURE__ */ new Map();
-			const results = await Promise.all(clients.map(async (client) => {
+			const serverToolsMap = /* @__PURE__ */ new Map();
+			const toolToServers = /* @__PURE__ */ new Map();
+			await Promise.all(clients.map(async (client) => {
 				try {
 					const tools = await client.listTools();
 					const blacklist = new Set(client.toolBlacklist || []);
 					const filteredTools = tools.filter((t) => !blacklist.has(t.name));
-					const matches = [];
-					for (const toolName of toolNames) {
-						if (blacklist.has(toolName)) continue;
-						const tool = filteredTools.find((t) => t.name === toolName);
-						if (tool) matches.push({
-							toolName,
-							server: client.serverName,
-							tool
-						});
+					serverToolsMap.set(client.serverName, filteredTools);
+					for (const tool of filteredTools) {
+						if (!toolToServers.has(tool.name)) toolToServers.set(tool.name, []);
+						toolToServers.get(tool.name).push(client.serverName);
 					}
-					return matches;
 				} catch (error) {
 					console.error(`Failed to list tools from ${client.serverName}:`, error);
-					return [];
+					serverToolsMap.set(client.serverName, []);
 				}
 			}));
-			for (const matches of results) for (const match of matches) {
-				if (!toolMatches.has(match.toolName)) toolMatches.set(match.toolName, []);
-				toolMatches.get(match.toolName).push({
-					server: match.server,
-					tool: match.tool
-				});
-			}
-			const ambiguousTools = [];
-			for (const toolName of toolNames) {
-				const matches = toolMatches.get(toolName);
-				if (!matches || matches.length === 0) continue;
-				if (matches.length === 1) {
-					const match = matches[0];
-					foundTools.push({
-						server: match.server,
+			const foundTools = [];
+			const notFoundTools = [];
+			for (const requestedToolName of toolNames) {
+				const { serverName, actualToolName } = parseToolName(requestedToolName);
+				if (serverName) {
+					const serverTools = serverToolsMap.get(serverName);
+					if (!serverTools) {
+						notFoundTools.push(requestedToolName);
+						continue;
+					}
+					const tool = serverTools.find((t) => t.name === actualToolName);
+					if (tool) foundTools.push({
+						server: serverName,
 						tool: {
-							name: match.tool.name,
-							description: match.tool.description,
-							inputSchema: match.tool.inputSchema
+							name: tool.name,
+							description: tool.description,
+							inputSchema: tool.inputSchema
 						}
 					});
-					const idx = notFoundTools.indexOf(toolName);
-					if (idx > -1) notFoundTools.splice(idx, 1);
+					else notFoundTools.push(requestedToolName);
 				} else {
-					ambiguousTools.push({
-						toolName,
-						servers: matches.map((m) => m.server)
-					});
-					const idx = notFoundTools.indexOf(toolName);
-					if (idx > -1) notFoundTools.splice(idx, 1);
+					const servers = toolToServers.get(actualToolName);
+					if (!servers || servers.length === 0) {
+						notFoundTools.push(requestedToolName);
+						continue;
+					}
+					if (servers.length === 1) {
+						const server = servers[0];
+						const tool = serverToolsMap.get(server).find((t) => t.name === actualToolName);
+						foundTools.push({
+							server,
+							tool: {
+								name: tool.name,
+								description: tool.description,
+								inputSchema: tool.inputSchema
+							}
+						});
+					} else for (const server of servers) {
+						const tool = serverToolsMap.get(server).find((t) => t.name === actualToolName);
+						foundTools.push({
+							server,
+							tool: {
+								name: tool.name,
+								description: tool.description,
+								inputSchema: tool.inputSchema
+							}
+						});
+					}
 				}
 			}
-			if (foundTools.length === 0 && ambiguousTools.length === 0) return {
+			if (foundTools.length === 0) return {
 				content: [{
 					type: "text",
-					text: `None of the requested tools found on any connected server.\nRequested: ${toolNames.join(", ")}\nUse describe_tools without arguments to see available servers.`
+					text: `None of the requested tools found on any connected server.\nRequested: ${toolNames.join(", ")}\nUse describe_tools to see available tools.`
 				}],
 				isError: true
 			};
 			const result = { tools: foundTools };
-			if (notFoundTools.length > 0) result.notFound = notFoundTools;
-			if (ambiguousTools.length > 0) result.ambiguous = ambiguousTools.map((item) => ({
-				toolName: item.toolName,
-				servers: item.servers,
-				message: `Tool "${item.toolName}" found on multiple servers: ${item.servers.join(", ")}. Please specify serverName to disambiguate.`
-			}));
-			const warnings = [];
-			if (notFoundTools.length > 0) warnings.push(`Tools not found: ${notFoundTools.join(", ")}`);
-			if (ambiguousTools.length > 0) warnings.push(`Ambiguous tools (specify serverName): ${ambiguousTools.map((t) => t.toolName).join(", ")}`);
-			if (warnings.length > 0) result.warnings = warnings;
+			if (notFoundTools.length > 0) {
+				result.notFound = notFoundTools;
+				result.warnings = [`Tools not found: ${notFoundTools.join(", ")}`];
+			}
 			return { content: [{
 				type: "text",
 				text: JSON.stringify(result, null, 2)
@@ -715,10 +1210,6 @@ var UseToolTool = class UseToolTool {
 					toolArgs: {
 						type: "object",
 						description: "Arguments to pass to the tool, as discovered from describe_tools"
-					},
-					serverName: {
-						type: "string",
-						description: "Optional server name to disambiguate when multiple servers have the same tool"
 					}
 				},
 				required: ["toolName"],
@@ -728,8 +1219,9 @@ var UseToolTool = class UseToolTool {
 	}
 	async execute(input) {
 		try {
-			const { toolName, toolArgs = {}, serverName } = input;
+			const { toolName: inputToolName, toolArgs = {} } = input;
 			const clients = this.clientManager.getAllClients();
+			const { serverName, actualToolName } = parseToolName(inputToolName);
 			if (serverName) {
 				const client$1 = this.clientManager.getClient(serverName);
 				if (!client$1) return {
@@ -739,20 +1231,20 @@ var UseToolTool = class UseToolTool {
 					}],
 					isError: true
 				};
-				if (client$1.toolBlacklist && client$1.toolBlacklist.includes(toolName)) return {
+				if (client$1.toolBlacklist && client$1.toolBlacklist.includes(actualToolName)) return {
 					content: [{
 						type: "text",
-						text: `Tool "${toolName}" is blacklisted on server "${serverName}" and cannot be executed.`
+						text: `Tool "${actualToolName}" is blacklisted on server "${serverName}" and cannot be executed.`
 					}],
 					isError: true
 				};
 				try {
-					return await client$1.callTool(toolName, toolArgs);
+					return await client$1.callTool(actualToolName, toolArgs);
 				} catch (error) {
 					return {
 						content: [{
 							type: "text",
-							text: `Failed to call tool "${toolName}" on server "${serverName}": ${error instanceof Error ? error.message : "Unknown error"}`
+							text: `Failed to call tool "${actualToolName}" on server "${serverName}": ${error instanceof Error ? error.message : "Unknown error"}`
 						}],
 						isError: true
 					};
@@ -761,8 +1253,8 @@ var UseToolTool = class UseToolTool {
 			const matchingServers = [];
 			const results = await Promise.all(clients.map(async (client$1) => {
 				try {
-					if (client$1.toolBlacklist && client$1.toolBlacklist.includes(toolName)) return null;
-					if ((await client$1.listTools()).some((t) => t.name === toolName)) return client$1.serverName;
+					if (client$1.toolBlacklist && client$1.toolBlacklist.includes(actualToolName)) return null;
+					if ((await client$1.listTools()).some((t) => t.name === actualToolName)) return client$1.serverName;
 				} catch (error) {
 					console.error(`Failed to list tools from ${client$1.serverName}:`, error);
 				}
@@ -772,14 +1264,14 @@ var UseToolTool = class UseToolTool {
 			if (matchingServers.length === 0) return {
 				content: [{
 					type: "text",
-					text: `Tool "${toolName}" not found on any connected server. Use describe_tools to see available tools.`
+					text: `Tool "${actualToolName}" not found on any connected server. Use describe_tools to see available tools.`
 				}],
 				isError: true
 			};
 			if (matchingServers.length > 1) return {
 				content: [{
 					type: "text",
-					text: `Multiple servers provide tool "${toolName}". Please specify serverName. Available servers: ${matchingServers.join(", ")}`
+					text: `Tool "${actualToolName}" found on multiple servers. Use prefixed format to specify: ${matchingServers.map((s) => `${s}__${actualToolName}`).join(", ")}`
 				}],
 				isError: true
 			};
@@ -793,12 +1285,12 @@ var UseToolTool = class UseToolTool {
 				isError: true
 			};
 			try {
-				return await client.callTool(toolName, toolArgs);
+				return await client.callTool(actualToolName, toolArgs);
 			} catch (error) {
 				return {
 					content: [{
 						type: "text",
-						text: `Failed to call tool "${toolName}": ${error instanceof Error ? error.message : "Unknown error"}`
+						text: `Failed to call tool "${actualToolName}": ${error instanceof Error ? error.message : "Unknown error"}`
 					}],
 					isError: true
 				};
@@ -837,7 +1329,10 @@ async function createServer(options) {
 	}, { capabilities: { tools: {} } });
 	const clientManager = new McpClientManagerService();
 	if (options?.configFilePath) try {
-		const config = await new ConfigFetcherService({ configFilePath: options.configFilePath }).fetchConfiguration(options.noCache || false);
+		const config = await new ConfigFetcherService({
+			configFilePath: options.configFilePath,
+			useCache: !options.noCache
+		}).fetchConfiguration(options.noCache || false);
 		const connectionPromises = Object.entries(config.mcpServers).map(async ([serverName, serverConfig]) => {
 			try {
 				await clientManager.connectToServer(serverName, serverConfig);
@@ -990,14 +1485,14 @@ var SseTransportHandler = class {
 		}
 	}
 	async start() {
-		return new Promise((resolve, reject) => {
+		return new Promise((resolve$1, reject) => {
 			try {
 				this.server = this.app.listen(this.config.port, this.config.host, () => {
 					console.error(`@agiflowai/one-mcp MCP server started with SSE transport on http://${this.config.host}:${this.config.port}`);
 					console.error(`SSE endpoint: http://${this.config.host}:${this.config.port}/sse`);
 					console.error(`Messages endpoint: http://${this.config.host}:${this.config.port}/messages`);
 					console.error(`Health check: http://${this.config.host}:${this.config.port}/health`);
-					resolve();
+					resolve$1();
 				});
 				this.server.on("error", (error) => {
 					reject(error);
@@ -1008,17 +1503,17 @@ var SseTransportHandler = class {
 		});
 	}
 	async stop() {
-		return new Promise((resolve, reject) => {
+		return new Promise((resolve$1, reject) => {
 			if (this.server) {
 				this.sessionManager.clear();
 				this.server.close((err) => {
 					if (err) reject(err);
 					else {
 						this.server = null;
-						resolve();
+						resolve$1();
 					}
 				});
-			} else resolve();
+			} else resolve$1();
 		});
 	}
 	getPort() {
@@ -1170,12 +1665,12 @@ var HttpTransportHandler = class {
 		this.sessionManager.deleteSession(sessionId);
 	}
 	async start() {
-		return new Promise((resolve, reject) => {
+		return new Promise((resolve$1, reject) => {
 			try {
 				this.server = this.app.listen(this.config.port, this.config.host, () => {
 					console.error(`@agiflowai/one-mcp MCP server started on http://${this.config.host}:${this.config.port}/mcp`);
 					console.error(`Health check: http://${this.config.host}:${this.config.port}/health`);
-					resolve();
+					resolve$1();
 				});
 				this.server.on("error", (error) => {
 					reject(error);
@@ -1186,17 +1681,17 @@ var HttpTransportHandler = class {
 		});
 	}
 	async stop() {
-		return new Promise((resolve, reject) => {
+		return new Promise((resolve$1, reject) => {
 			if (this.server) {
 				this.sessionManager.clear();
 				this.server.close((err) => {
 					if (err) reject(err);
 					else {
 						this.server = null;
-						resolve();
+						resolve$1();
 					}
 				});
-			} else resolve();
+			} else resolve$1();
 		});
 	}
 	getPort() {
@@ -1208,4 +1703,4 @@ var HttpTransportHandler = class {
 };
 
 //#endregion
-export { McpClientManagerService as a, createServer as i, SseTransportHandler as n, ConfigFetcherService as o, StdioTransportHandler as r, HttpTransportHandler as t };
+export { findConfigFile as a, createServer as i, SseTransportHandler as n, McpClientManagerService as o, StdioTransportHandler as r, ConfigFetcherService as s, HttpTransportHandler as t };