@agiflowai/one-mcp 0.3.0 → 0.3.1

package/dist/cli.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const require_http = require('./http-BYBRKvD4.cjs');
+const require_http = require('./http-C4IfZSwW.cjs');
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
 let liquidjs = require("liquidjs");
@@ -69,7 +69,7 @@ async function startServer(handler) {
 /**
 * MCP Serve command
 */
-const mcpServeCommand = new commander.Command("mcp-serve").description("Start MCP server with specified transport").option("-t, --type <type>", "Transport type: stdio, http, or sse", "stdio").option("-p, --port <port>", "Port to listen on (http/sse only)", (val) => parseInt(val, 10), 3e3).option("--host <host>", "Host to bind to (http/sse only)", "localhost").option("-c, --config <path>", "Path to MCP server configuration file").option("--no-cache", "Disable configuration caching, always reload from config file").action(async (options) => {
+const mcpServeCommand = new commander.Command("mcp-serve").description("Start MCP server with specified transport").option("-t, --type <type>", "Transport type: stdio, http, or sse", "stdio").option("-p, --port <port>", "Port to listen on (http/sse only)", (val) => parseInt(val, 10), 3e3).option("--host <host>", "Host to bind to (http/sse only)", "localhost").option("-c, --config <path>", "Path to MCP server configuration file").option("--no-cache", "Disable configuration caching, always reload from config file").option("--id <id>", "Unique server identifier (overrides config file id, auto-generated if not provided)").action(async (options) => {
 	const transportType = options.type.toLowerCase();
 	if (!isValidTransportType(transportType)) {
 		console.error(`Unknown transport type: '${transportType}'. Valid options: stdio, http, sse`);
@@ -78,7 +78,8 @@ const mcpServeCommand = new commander.Command("mcp-serve").description("Start MC
 	try {
 		const serverOptions = {
 			configFilePath: options.config || require_http.findConfigFile() || void 0,
-			noCache: options.cache === false
+			noCache: options.cache === false,
+			serverId: options.id
 		};
 		if (transportType === "stdio") await startServer(new require_http.StdioTransportHandler(await require_http.createServer(serverOptions)));
 		else if (transportType === "http") await startServer(new require_http.HttpTransportHandler(await require_http.createServer(serverOptions), {
@@ -1002,7 +1003,7 @@ const prefetchCommand = new commander.Command("prefetch").description("Pre-downl
 
 //#endregion
 //#region package.json
-var version = "0.2.2";
+var version = "0.3.0";
 
 //#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-Bi2N9PUM.mjs";
+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-xi_ha63Y.mjs";
 import { writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { Liquid } from "liquidjs";
@@ -69,7 +69,7 @@ async function startServer(handler) {
 /**
 * MCP Serve command
 */
-const mcpServeCommand = new Command("mcp-serve").description("Start MCP server with specified transport").option("-t, --type <type>", "Transport type: stdio, http, or sse", "stdio").option("-p, --port <port>", "Port to listen on (http/sse only)", (val) => parseInt(val, 10), 3e3).option("--host <host>", "Host to bind to (http/sse only)", "localhost").option("-c, --config <path>", "Path to MCP server configuration file").option("--no-cache", "Disable configuration caching, always reload from config file").action(async (options) => {
+const mcpServeCommand = new Command("mcp-serve").description("Start MCP server with specified transport").option("-t, --type <type>", "Transport type: stdio, http, or sse", "stdio").option("-p, --port <port>", "Port to listen on (http/sse only)", (val) => parseInt(val, 10), 3e3).option("--host <host>", "Host to bind to (http/sse only)", "localhost").option("-c, --config <path>", "Path to MCP server configuration file").option("--no-cache", "Disable configuration caching, always reload from config file").option("--id <id>", "Unique server identifier (overrides config file id, auto-generated if not provided)").action(async (options) => {
 	const transportType = options.type.toLowerCase();
 	if (!isValidTransportType(transportType)) {
 		console.error(`Unknown transport type: '${transportType}'. Valid options: stdio, http, sse`);
@@ -78,7 +78,8 @@ const mcpServeCommand = new Command("mcp-serve").description("Start MCP server w
 	try {
 		const serverOptions = {
 			configFilePath: options.config || findConfigFile() || void 0,
-			noCache: options.cache === false
+			noCache: options.cache === false,
+			serverId: options.id
 		};
 		if (transportType === "stdio") await startServer(new StdioTransportHandler(await createServer(serverOptions)));
 		else if (transportType === "http") await startServer(new HttpTransportHandler(await createServer(serverOptions), {
@@ -1002,7 +1003,7 @@ const prefetchCommand = new Command("prefetch").description("Pre-download packag
 
 //#endregion
 //#region package.json
-var version = "0.2.2";
+var version = "0.3.0";
 
 //#endregion
 //#region src/cli.ts

package/dist/{http-BYBRKvD4.cjs → http-C4IfZSwW.cjs}

@@ -271,6 +271,7 @@ const SkillsConfigSchema = zod.z.object({ paths: zod.z.array(zod.z.string()) });
 * Full Claude Code MCP configuration schema
 */
 const ClaudeCodeMcpConfigSchema = zod.z.object({
+	id: zod.z.string().optional(),
 	mcpServers: zod.z.record(zod.z.string(), ClaudeCodeServerConfigSchema),
 	remoteConfigs: zod.z.array(RemoteConfigSourceSchema).optional(),
 	skills: SkillsConfigSchema.optional()
@@ -340,6 +341,7 @@ const McpServerConfigSchema = zod.z.discriminatedUnion("transport", [
 * Full internal MCP configuration schema
 */
 const InternalMcpConfigSchema = zod.z.object({
+	id: zod.z.string().optional(),
 	mcpServers: zod.z.record(zod.z.string(), McpServerConfigSchema),
 	skills: SkillsConfigSchema.optional()
 });
@@ -394,6 +396,7 @@ function transformClaudeCodeConfig(claudeConfig) {
 		}
 	}
 	return {
+		id: claudeConfig.id,
 		mcpServers: transformedServers,
 		skills: claudeConfig.skills
 	};
@@ -1248,6 +1251,71 @@ function extractSkillFrontMatter(content) {
 	return null;
 }
 
+//#endregion
+//#region src/utils/generateServerId.ts
+/**
+* generateServerId Utilities
+*
+* DESIGN PATTERNS:
+* - Pure functions with no side effects
+* - Single responsibility per function
+* - Functional programming approach
+*
+* CODING STANDARDS:
+* - Export individual functions, not classes
+* - Use descriptive function names with verbs
+* - Add JSDoc comments for complex logic
+* - Keep functions small and focused
+*
+* AVOID:
+* - Side effects (mutating external state)
+* - Stateful logic (use services for state)
+* - Complex external dependencies
+*/
+/**
+* Character set for generating human-readable IDs.
+* Excludes confusing characters: 0, O, 1, l, I
+*/
+const CHARSET = "23456789abcdefghjkmnpqrstuvwxyz";
+/**
+* Default length for generated server IDs (6 characters)
+*/
+const DEFAULT_ID_LENGTH = 6;
+/**
+* Generate a short, human-readable server ID.
+*
+* Uses Node.js crypto.randomBytes for cryptographically secure randomness
+* with rejection sampling to avoid modulo bias.
+*
+* The generated ID:
+* - Is 6 characters long by default
+* - Uses only lowercase alphanumeric characters
+* - Excludes confusing characters (0, O, 1, l, I)
+*
+* @param length - Length of the ID to generate (default: 6)
+* @returns A random, human-readable ID
+*
+* @example
+* generateServerId() // "abc234"
+* generateServerId(4) // "x7mn"
+*/
+function generateServerId(length = DEFAULT_ID_LENGTH) {
+	const charsetLength = 31;
+	const maxUnbiased = Math.floor(256 / charsetLength) * charsetLength - 1;
+	let result = "";
+	let remaining = length;
+	while (remaining > 0) {
+		const bytes = (0, node_crypto.randomBytes)(remaining);
+		for (let i = 0; i < bytes.length && remaining > 0; i++) {
+			const byte = bytes[i];
+			if (byte > maxUnbiased) continue;
+			result += CHARSET[byte % charsetLength];
+			remaining--;
+		}
+	}
+	return result;
+}
+
 //#endregion
 //#region src/services/SkillService.ts
 /**
@@ -1525,7 +1593,7 @@ var SkillService = class {
 * Prefix added to skill names when they clash with MCP tool names.
 * This ensures skills can be uniquely identified even when a tool has the same name.
 */
-const SKILL_PREFIX$1 = "skill__";
+const SKILL_PREFIX = "skill__";
 /**
 * Log prefix for skill detection messages.
 * Used to easily filter skill detection logs in stderr output.
@@ -1536,10 +1604,15 @@ const LOG_PREFIX_SKILL_DETECTION = "[skill-detection]";
 * Format: "prompt:{serverName}:{promptName}"
 */
 const PROMPT_LOCATION_PREFIX = "prompt:";
+/**
+* Default server ID used when no ID is provided via CLI or config.
+* This fallback is used when auto-generation also fails.
+*/
+const DEFAULT_SERVER_ID = "unknown";
 
 //#endregion
 //#region src/templates/toolkit-description.liquid?raw
-var toolkit_description_default = "<toolkit>\n<instruction>\nBefore you use any capabilities below, you MUST call this tool with a list of names to learn how to use them properly; this includes:\n- For tools: Arguments schema needed to pass to use_tool\n- For skills: Detailed instructions that will expand when invoked (Prefer to be explored first when relevant)\n\nThis tool is optimized for batch queries - you can request multiple capabilities at once for better performance.\n\nHow to invoke:\n- For MCP tools: Use use_tool with toolName and toolArgs based on the schema\n- For skills: Use this tool with the skill name to get expanded instructions\n</instruction>\n\n<available_capabilities>\n{% for server in servers -%}\n<group name=\"{{ server.name }}\">\n{% if server.instruction -%}\n<group_instruction>{{ server.instruction }}</group_instruction>\n{% endif -%}\n{% if server.omitToolDescription -%}\n{% for toolName in server.toolNames -%}\n<item name=\"{{ toolName }}\"></item>\n{% endfor -%}\n{% else -%}\n{% for tool in server.tools -%}\n<item name=\"{{ tool.displayName }}\"><description>{{ tool.description | default: \"No description\" }}</description></item>\n{% endfor -%}\n{% endif -%}\n</group>\n{% endfor -%}\n{% if skills.size > 0 -%}\n<group name=\"skills\">\n{% for skill in skills -%}\n<item name=\"{{ skill.displayName }}\"><description>{{ skill.description }}</description></item>\n{% endfor -%}\n</group>\n{% endif -%}\n</available_capabilities>\n</toolkit>\n";
+var toolkit_description_default = "<toolkit id=\"{{ serverId }}\">\n<instruction>\nBefore you use any capabilities below, you MUST call this tool with a list of names to learn how to use them properly; this includes:\n- For tools: Arguments schema needed to pass to use_tool\n- For skills: Detailed instructions that will expand when invoked (Prefer to be explored first when relevant)\n\nThis tool is optimized for batch queries - you can request multiple capabilities at once for better performance.\n\nHow to invoke:\n- For MCP tools: Use use_tool with toolName and toolArgs based on the schema\n- For skills: Use this tool with the skill name to get expanded instructions\n</instruction>\n\n<available_capabilities>\n{% for server in servers -%}\n<group name=\"{{ server.name }}\">\n{% if server.instruction -%}\n<group_instruction>{{ server.instruction }}</group_instruction>\n{% endif -%}\n{% if server.omitToolDescription -%}\n{% for toolName in server.toolNames -%}\n<item name=\"{{ toolName }}\"></item>\n{% endfor -%}\n{% else -%}\n{% for tool in server.tools -%}\n<item name=\"{{ tool.displayName }}\"><description>{{ tool.description | default: \"No description\" }}</description></item>\n{% endfor -%}\n{% endif -%}\n</group>\n{% endfor -%}\n{% if skills.size > 0 -%}\n<group name=\"skills\">\n{% for skill in skills -%}\n<item name=\"{{ skill.displayName }}\"><description>{{ skill.description }}</description></item>\n{% endfor -%}\n</group>\n{% endif -%}\n</available_capabilities>\n</toolkit>\n";
 
 //#endregion
 //#region src/tools/DescribeToolsTool.ts
@@ -1578,14 +1651,18 @@ var DescribeToolsTool = class DescribeToolsTool {
 	liquid = new liquidjs.Liquid();
 	/** Cache for auto-detected skills from prompt front-matter */
 	autoDetectedSkillsCache = null;
+	/** Unique server identifier for this one-mcp instance */
+	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, skillService) {
+	constructor(clientManager, skillService, serverId) {
 		this.clientManager = clientManager;
 		this.skillService = skillService;
+		this.serverId = serverId || DEFAULT_SERVER_ID;
 	}
 	/**
 	* Clears the cached auto-detected skills from prompt front-matter.
@@ -1810,14 +1887,15 @@ var DescribeToolsTool = class DescribeToolsTool {
 			const clashesWithMcpTool = allToolNames.has(skill.name);
 			return {
 				name: skill.name,
-				displayName: clashesWithMcpTool ? `${SKILL_PREFIX$1}${skill.name}` : skill.name,
+				displayName: clashesWithMcpTool ? `${SKILL_PREFIX}${skill.name}` : skill.name,
 				description: skill.description
 			};
 		});
 		return {
 			content: await this.liquid.parseAndRender(toolkit_description_default, {
 				servers,
-				skills
+				skills,
+				serverId: this.serverId
 			}),
 			toolNames: allToolNames
 		};
@@ -1903,8 +1981,8 @@ var DescribeToolsTool = class DescribeToolsTool {
 			const foundSkills = [];
 			const notFoundItems = [];
 			for (const requestedName of toolNames) {
-				if (requestedName.startsWith(SKILL_PREFIX$1)) {
-					const skillName = requestedName.slice(SKILL_PREFIX$1.length);
+				if (requestedName.startsWith(SKILL_PREFIX)) {
+					const skillName = requestedName.slice(SKILL_PREFIX.length);
 					if (this.skillService) {
 						const skill = await this.skillService.getSkill(skillName);
 						if (skill) {
@@ -2028,10 +2106,6 @@ var DescribeToolsTool = class DescribeToolsTool {
 //#endregion
 //#region src/tools/UseToolTool.ts
 /**
-* Prefix used to identify skill invocations (e.g., skill__pdf)
-*/
-const SKILL_PREFIX = "skill__";
-/**
 * UseToolTool executes MCP tools and skills with proper error handling.
 *
 * This tool supports three invocation patterns:
@@ -2048,14 +2122,18 @@ var UseToolTool = class UseToolTool {
 	static TOOL_NAME = "use_tool";
 	clientManager;
 	skillService;
+	/** Unique server identifier for this one-mcp instance */
+	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, skillService) {
+	constructor(clientManager, skillService, serverId) {
 		this.clientManager = clientManager;
 		this.skillService = skillService;
+		this.serverId = serverId || DEFAULT_SERVER_ID;
 	}
 	/**
 	* Returns the MCP tool definition with name, description, and input schema.
@@ -2071,6 +2149,8 @@ var UseToolTool = class UseToolTool {
 			description: `Execute an MCP tool (NOT Skill) with provided arguments. You MUST call describe_tools first to discover the tool's correct arguments. Then to use tool:
 - Provide toolName and toolArgs based on the schema
 - If multiple servers provide the same tool, specify serverName
+
+IMPORTANT: Only use tools discovered from describe_tools with id="${this.serverId}".
 `,
 			inputSchema: {
 				type: "object",
@@ -2157,7 +2237,7 @@ var UseToolTool = class UseToolTool {
 		try {
 			const { toolName: inputToolName, toolArgs = {} } = input;
 			if (inputToolName.startsWith(SKILL_PREFIX)) {
-				const skillName = inputToolName.slice(7);
+				const skillName = inputToolName.slice(SKILL_PREFIX.length);
 				if (this.skillService) {
 					const skill = await this.skillService.getSkill(skillName);
 					if (skill) return this.executeSkill(skill);
@@ -2292,6 +2372,7 @@ async function createServer(options) {
 	} });
 	const clientManager = new McpClientManagerService();
 	let configSkills;
+	let configId;
 	if (options?.configFilePath) {
 		let config;
 		try {
@@ -2303,6 +2384,7 @@ async function createServer(options) {
 			throw new Error(`Failed to load MCP configuration from '${options.configFilePath}': ${error instanceof Error ? error.message : String(error)}`);
 		}
 		configSkills = config.skills;
+		configId = config.id;
 		const failedConnections = [];
 		const connectionPromises = Object.entries(config.mcpServers).map(async ([serverName, serverConfig]) => {
 			try {
@@ -2321,13 +2403,15 @@ async function createServer(options) {
 		if (failedConnections.length > 0 && failedConnections.length < Object.keys(config.mcpServers).length) console.error(`Warning: Some MCP server connections failed: ${failedConnections.map((f) => f.serverName).join(", ")}`);
 		if (failedConnections.length > 0 && failedConnections.length === Object.keys(config.mcpServers).length) throw new Error(`All MCP server connections failed: ${failedConnections.map((f) => `${f.serverName}: ${f.error.message}`).join(", ")}`);
 	}
+	const serverId = options?.serverId || configId || generateServerId();
+	console.error(`[one-mcp] Server ID: ${serverId}`);
 	const skillsConfig = options?.skills || configSkills;
 	const toolsRef = { describeTools: null };
 	const skillService = skillsConfig && skillsConfig.paths.length > 0 ? new SkillService(process.cwd(), skillsConfig.paths, { onCacheInvalidated: () => {
 		toolsRef.describeTools?.clearAutoDetectedSkillsCache();
 	} }) : void 0;
-	const describeTools = new DescribeToolsTool(clientManager, skillService);
-	const useTool = new UseToolTool(clientManager, skillService);
+	const describeTools = new DescribeToolsTool(clientManager, skillService, serverId);
+	const useTool = new UseToolTool(clientManager, skillService, serverId);
 	toolsRef.describeTools = describeTools;
 	if (skillService) skillService.startWatching().catch((error) => {
 		console.error(`[skill-watcher] File watcher failed (non-critical): ${error instanceof Error ? error.message : "Unknown error"}`);

package/dist/{http-Bi2N9PUM.mjs → http-xi_ha63Y.mjs}

@@ -4,7 +4,7 @@ import { access, mkdir, readFile, readdir, stat, unlink, watch, writeFile } from
 import { existsSync } from "node:fs";
 import yaml from "js-yaml";
 import { z } from "zod";
-import { createHash, randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
@@ -242,6 +242,7 @@ const SkillsConfigSchema = z.object({ paths: z.array(z.string()) });
 * Full Claude Code MCP configuration schema
 */
 const ClaudeCodeMcpConfigSchema = z.object({
+	id: z.string().optional(),
 	mcpServers: z.record(z.string(), ClaudeCodeServerConfigSchema),
 	remoteConfigs: z.array(RemoteConfigSourceSchema).optional(),
 	skills: SkillsConfigSchema.optional()
@@ -311,6 +312,7 @@ const McpServerConfigSchema = z.discriminatedUnion("transport", [
 * Full internal MCP configuration schema
 */
 const InternalMcpConfigSchema = z.object({
+	id: z.string().optional(),
 	mcpServers: z.record(z.string(), McpServerConfigSchema),
 	skills: SkillsConfigSchema.optional()
 });
@@ -365,6 +367,7 @@ function transformClaudeCodeConfig(claudeConfig) {
 		}
 	}
 	return {
+		id: claudeConfig.id,
 		mcpServers: transformedServers,
 		skills: claudeConfig.skills
 	};
@@ -1219,6 +1222,71 @@ function extractSkillFrontMatter(content) {
 	return null;
 }
 
+//#endregion
+//#region src/utils/generateServerId.ts
+/**
+* generateServerId Utilities
+*
+* DESIGN PATTERNS:
+* - Pure functions with no side effects
+* - Single responsibility per function
+* - Functional programming approach
+*
+* CODING STANDARDS:
+* - Export individual functions, not classes
+* - Use descriptive function names with verbs
+* - Add JSDoc comments for complex logic
+* - Keep functions small and focused
+*
+* AVOID:
+* - Side effects (mutating external state)
+* - Stateful logic (use services for state)
+* - Complex external dependencies
+*/
+/**
+* Character set for generating human-readable IDs.
+* Excludes confusing characters: 0, O, 1, l, I
+*/
+const CHARSET = "23456789abcdefghjkmnpqrstuvwxyz";
+/**
+* Default length for generated server IDs (6 characters)
+*/
+const DEFAULT_ID_LENGTH = 6;
+/**
+* Generate a short, human-readable server ID.
+*
+* Uses Node.js crypto.randomBytes for cryptographically secure randomness
+* with rejection sampling to avoid modulo bias.
+*
+* The generated ID:
+* - Is 6 characters long by default
+* - Uses only lowercase alphanumeric characters
+* - Excludes confusing characters (0, O, 1, l, I)
+*
+* @param length - Length of the ID to generate (default: 6)
+* @returns A random, human-readable ID
+*
+* @example
+* generateServerId() // "abc234"
+* generateServerId(4) // "x7mn"
+*/
+function generateServerId(length = DEFAULT_ID_LENGTH) {
+	const charsetLength = 31;
+	const maxUnbiased = Math.floor(256 / charsetLength) * charsetLength - 1;
+	let result = "";
+	let remaining = length;
+	while (remaining > 0) {
+		const bytes = randomBytes(remaining);
+		for (let i = 0; i < bytes.length && remaining > 0; i++) {
+			const byte = bytes[i];
+			if (byte > maxUnbiased) continue;
+			result += CHARSET[byte % charsetLength];
+			remaining--;
+		}
+	}
+	return result;
+}
+
 //#endregion
 //#region src/services/SkillService.ts
 /**
@@ -1496,7 +1564,7 @@ var SkillService = class {
 * Prefix added to skill names when they clash with MCP tool names.
 * This ensures skills can be uniquely identified even when a tool has the same name.
 */
-const SKILL_PREFIX$1 = "skill__";
+const SKILL_PREFIX = "skill__";
 /**
 * Log prefix for skill detection messages.
 * Used to easily filter skill detection logs in stderr output.
@@ -1507,10 +1575,15 @@ const LOG_PREFIX_SKILL_DETECTION = "[skill-detection]";
 * Format: "prompt:{serverName}:{promptName}"
 */
 const PROMPT_LOCATION_PREFIX = "prompt:";
+/**
+* Default server ID used when no ID is provided via CLI or config.
+* This fallback is used when auto-generation also fails.
+*/
+const DEFAULT_SERVER_ID = "unknown";
 
 //#endregion
 //#region src/templates/toolkit-description.liquid?raw
-var toolkit_description_default = "<toolkit>\n<instruction>\nBefore you use any capabilities below, you MUST call this tool with a list of names to learn how to use them properly; this includes:\n- For tools: Arguments schema needed to pass to use_tool\n- For skills: Detailed instructions that will expand when invoked (Prefer to be explored first when relevant)\n\nThis tool is optimized for batch queries - you can request multiple capabilities at once for better performance.\n\nHow to invoke:\n- For MCP tools: Use use_tool with toolName and toolArgs based on the schema\n- For skills: Use this tool with the skill name to get expanded instructions\n</instruction>\n\n<available_capabilities>\n{% for server in servers -%}\n<group name=\"{{ server.name }}\">\n{% if server.instruction -%}\n<group_instruction>{{ server.instruction }}</group_instruction>\n{% endif -%}\n{% if server.omitToolDescription -%}\n{% for toolName in server.toolNames -%}\n<item name=\"{{ toolName }}\"></item>\n{% endfor -%}\n{% else -%}\n{% for tool in server.tools -%}\n<item name=\"{{ tool.displayName }}\"><description>{{ tool.description | default: \"No description\" }}</description></item>\n{% endfor -%}\n{% endif -%}\n</group>\n{% endfor -%}\n{% if skills.size > 0 -%}\n<group name=\"skills\">\n{% for skill in skills -%}\n<item name=\"{{ skill.displayName }}\"><description>{{ skill.description }}</description></item>\n{% endfor -%}\n</group>\n{% endif -%}\n</available_capabilities>\n</toolkit>\n";
+var toolkit_description_default = "<toolkit id=\"{{ serverId }}\">\n<instruction>\nBefore you use any capabilities below, you MUST call this tool with a list of names to learn how to use them properly; this includes:\n- For tools: Arguments schema needed to pass to use_tool\n- For skills: Detailed instructions that will expand when invoked (Prefer to be explored first when relevant)\n\nThis tool is optimized for batch queries - you can request multiple capabilities at once for better performance.\n\nHow to invoke:\n- For MCP tools: Use use_tool with toolName and toolArgs based on the schema\n- For skills: Use this tool with the skill name to get expanded instructions\n</instruction>\n\n<available_capabilities>\n{% for server in servers -%}\n<group name=\"{{ server.name }}\">\n{% if server.instruction -%}\n<group_instruction>{{ server.instruction }}</group_instruction>\n{% endif -%}\n{% if server.omitToolDescription -%}\n{% for toolName in server.toolNames -%}\n<item name=\"{{ toolName }}\"></item>\n{% endfor -%}\n{% else -%}\n{% for tool in server.tools -%}\n<item name=\"{{ tool.displayName }}\"><description>{{ tool.description | default: \"No description\" }}</description></item>\n{% endfor -%}\n{% endif -%}\n</group>\n{% endfor -%}\n{% if skills.size > 0 -%}\n<group name=\"skills\">\n{% for skill in skills -%}\n<item name=\"{{ skill.displayName }}\"><description>{{ skill.description }}</description></item>\n{% endfor -%}\n</group>\n{% endif -%}\n</available_capabilities>\n</toolkit>\n";
 
 //#endregion
 //#region src/tools/DescribeToolsTool.ts
@@ -1549,14 +1622,18 @@ var DescribeToolsTool = class DescribeToolsTool {
 	liquid = new Liquid();
 	/** Cache for auto-detected skills from prompt front-matter */
 	autoDetectedSkillsCache = null;
+	/** Unique server identifier for this one-mcp instance */
+	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, skillService) {
+	constructor(clientManager, skillService, serverId) {
 		this.clientManager = clientManager;
 		this.skillService = skillService;
+		this.serverId = serverId || DEFAULT_SERVER_ID;
 	}
 	/**
 	* Clears the cached auto-detected skills from prompt front-matter.
@@ -1781,14 +1858,15 @@ var DescribeToolsTool = class DescribeToolsTool {
 			const clashesWithMcpTool = allToolNames.has(skill.name);
 			return {
 				name: skill.name,
-				displayName: clashesWithMcpTool ? `${SKILL_PREFIX$1}${skill.name}` : skill.name,
+				displayName: clashesWithMcpTool ? `${SKILL_PREFIX}${skill.name}` : skill.name,
 				description: skill.description
 			};
 		});
 		return {
 			content: await this.liquid.parseAndRender(toolkit_description_default, {
 				servers,
-				skills
+				skills,
+				serverId: this.serverId
 			}),
 			toolNames: allToolNames
 		};
@@ -1874,8 +1952,8 @@ var DescribeToolsTool = class DescribeToolsTool {
 			const foundSkills = [];
 			const notFoundItems = [];
 			for (const requestedName of toolNames) {
-				if (requestedName.startsWith(SKILL_PREFIX$1)) {
-					const skillName = requestedName.slice(SKILL_PREFIX$1.length);
+				if (requestedName.startsWith(SKILL_PREFIX)) {
+					const skillName = requestedName.slice(SKILL_PREFIX.length);
 					if (this.skillService) {
 						const skill = await this.skillService.getSkill(skillName);
 						if (skill) {
@@ -1999,10 +2077,6 @@ var DescribeToolsTool = class DescribeToolsTool {
 //#endregion
 //#region src/tools/UseToolTool.ts
 /**
-* Prefix used to identify skill invocations (e.g., skill__pdf)
-*/
-const SKILL_PREFIX = "skill__";
-/**
 * UseToolTool executes MCP tools and skills with proper error handling.
 *
 * This tool supports three invocation patterns:
@@ -2019,14 +2093,18 @@ var UseToolTool = class UseToolTool {
 	static TOOL_NAME = "use_tool";
 	clientManager;
 	skillService;
+	/** Unique server identifier for this one-mcp instance */
+	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, skillService) {
+	constructor(clientManager, skillService, serverId) {
 		this.clientManager = clientManager;
 		this.skillService = skillService;
+		this.serverId = serverId || DEFAULT_SERVER_ID;
 	}
 	/**
 	* Returns the MCP tool definition with name, description, and input schema.
@@ -2042,6 +2120,8 @@ var UseToolTool = class UseToolTool {
 			description: `Execute an MCP tool (NOT Skill) with provided arguments. You MUST call describe_tools first to discover the tool's correct arguments. Then to use tool:
 - Provide toolName and toolArgs based on the schema
 - If multiple servers provide the same tool, specify serverName
+
+IMPORTANT: Only use tools discovered from describe_tools with id="${this.serverId}".
 `,
 			inputSchema: {
 				type: "object",
@@ -2128,7 +2208,7 @@ var UseToolTool = class UseToolTool {
 		try {
 			const { toolName: inputToolName, toolArgs = {} } = input;
 			if (inputToolName.startsWith(SKILL_PREFIX)) {
-				const skillName = inputToolName.slice(7);
+				const skillName = inputToolName.slice(SKILL_PREFIX.length);
 				if (this.skillService) {
 					const skill = await this.skillService.getSkill(skillName);
 					if (skill) return this.executeSkill(skill);
@@ -2263,6 +2343,7 @@ async function createServer(options) {
 	} });
 	const clientManager = new McpClientManagerService();
 	let configSkills;
+	let configId;
 	if (options?.configFilePath) {
 		let config;
 		try {
@@ -2274,6 +2355,7 @@ async function createServer(options) {
 			throw new Error(`Failed to load MCP configuration from '${options.configFilePath}': ${error instanceof Error ? error.message : String(error)}`);
 		}
 		configSkills = config.skills;
+		configId = config.id;
 		const failedConnections = [];
 		const connectionPromises = Object.entries(config.mcpServers).map(async ([serverName, serverConfig]) => {
 			try {
@@ -2292,13 +2374,15 @@ async function createServer(options) {
 		if (failedConnections.length > 0 && failedConnections.length < Object.keys(config.mcpServers).length) console.error(`Warning: Some MCP server connections failed: ${failedConnections.map((f) => f.serverName).join(", ")}`);
 		if (failedConnections.length > 0 && failedConnections.length === Object.keys(config.mcpServers).length) throw new Error(`All MCP server connections failed: ${failedConnections.map((f) => `${f.serverName}: ${f.error.message}`).join(", ")}`);
 	}
+	const serverId = options?.serverId || configId || generateServerId();
+	console.error(`[one-mcp] Server ID: ${serverId}`);
 	const skillsConfig = options?.skills || configSkills;
 	const toolsRef = { describeTools: null };
 	const skillService = skillsConfig && skillsConfig.paths.length > 0 ? new SkillService(process.cwd(), skillsConfig.paths, { onCacheInvalidated: () => {
 		toolsRef.describeTools?.clearAutoDetectedSkillsCache();
 	} }) : void 0;
-	const describeTools = new DescribeToolsTool(clientManager, skillService);
-	const useTool = new UseToolTool(clientManager, skillService);
+	const describeTools = new DescribeToolsTool(clientManager, skillService, serverId);
+	const useTool = new UseToolTool(clientManager, skillService, serverId);
 	toolsRef.describeTools = describeTools;
 	if (skillService) skillService.startWatching().catch((error) => {
 		console.error(`[skill-watcher] File watcher failed (non-critical): ${error instanceof Error ? error.message : "Unknown error"}`);

package/dist/index.cjs

@@ -1,4 +1,4 @@
-const require_http = require('./http-BYBRKvD4.cjs');
+const require_http = require('./http-C4IfZSwW.cjs');
 
 exports.HttpTransportHandler = require_http.HttpTransportHandler;
 exports.SseTransportHandler = require_http.SseTransportHandler;

package/dist/index.d.cts

@@ -8,6 +8,7 @@ import { CallToolResult, GetPromptResult, ReadResourceResult } from "@modelconte
  * @property configFilePath - Path to the MCP configuration file
  * @property noCache - Skip cache when fetching remote configuration
  * @property skills - Skills configuration with paths array (optional, skills disabled if not provided)
+ * @property serverId - CLI-provided server ID (takes precedence over config file id)
  */
 interface ServerOptions {
   configFilePath?: string;
@@ -15,6 +16,7 @@ interface ServerOptions {
   skills?: {
     paths: string[];
   };
+  serverId?: string;
 }
 declare function createServer(options?: ServerOptions): Promise<Server>;
 //#endregion
@@ -174,10 +176,12 @@ interface PromptConfig {
 }
 /**
  * Remote configuration response containing MCP server definitions
+ * @property id - Optional unique server identifier
  * @property mcpServers - Map of server names to their configurations
  * @property skills - Optional skills configuration with paths
  */
 interface RemoteMcpConfiguration {
+  id?: string;
   mcpServers: Record<string, McpServerConfig>;
   skills?: SkillsConfig;
 }

package/dist/index.d.mts

@@ -8,6 +8,7 @@ import { CallToolResult, GetPromptResult, ReadResourceResult } from "@modelconte
  * @property configFilePath - Path to the MCP configuration file
  * @property noCache - Skip cache when fetching remote configuration
  * @property skills - Skills configuration with paths array (optional, skills disabled if not provided)
+ * @property serverId - CLI-provided server ID (takes precedence over config file id)
  */
 interface ServerOptions {
   configFilePath?: string;
@@ -15,6 +16,7 @@ interface ServerOptions {
   skills?: {
     paths: string[];
   };
+  serverId?: string;
 }
 declare function createServer(options?: ServerOptions): Promise<Server>;
 //#endregion
@@ -174,10 +176,12 @@ interface PromptConfig {
 }
 /**
  * Remote configuration response containing MCP server definitions
+ * @property id - Optional unique server identifier
  * @property mcpServers - Map of server names to their configurations
  * @property skills - Optional skills configuration with paths
  */
 interface RemoteMcpConfiguration {
+  id?: string;
   mcpServers: Record<string, McpServerConfig>;
   skills?: SkillsConfig;
 }

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { i as createServer, n as SseTransportHandler, r as StdioTransportHandler, t as HttpTransportHandler } from "./http-Bi2N9PUM.mjs";
+import { i as createServer, n as SseTransportHandler, r as StdioTransportHandler, t as HttpTransportHandler } from "./http-xi_ha63Y.mjs";
 
 export { HttpTransportHandler, SseTransportHandler, StdioTransportHandler, createServer };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agiflowai/one-mcp",
   "description": "One MCP server package",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "license": "AGPL-3.0",
   "keywords": [
     "mcp",