@becrafter/prompt-manager 0.0.18 → 0.0.19

package/packages/resources/tools/filesystem/filesystem.tool.js

@@ -0,0 +1,184 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+/**
+ * 文件系统工具
+ * @param {Object} params - 工具参数
+ * @param {string} mode - 操作模式
+ * @returns {Promise<Object>} 执行结果
+ */
+export default async function filesystem(params, mode = 'execute') {
+  // 根据模式执行不同的操作
+  switch (mode) {
+    case 'manual':
+      // 生成 Markdown 格式的手册
+      return generateManual();
+
+    case 'execute':
+      // 执行模式 - 实际执行操作
+      const { action, path: filePath, content } = params;
+      
+      if (!action) {
+        throw new Error('缺少必需参数: action');
+      }
+      
+      if (!filePath) {
+        throw new Error('缺少必需参数: path');
+      }
+      
+      switch (action) {
+        case 'read':
+          try {
+            const fileContent = await fs.readFile(filePath, 'utf8');
+            return {
+              success: true,
+              action: 'read',
+              path: filePath,
+              content: fileContent
+            };
+          } catch (error) {
+            throw new Error(`读取文件失败: ${error.message}`);
+          }
+          
+        case 'write':
+          if (content === undefined) {
+            throw new Error('写入文件需要提供 content 参数');
+          }
+          try {
+            await fs.writeFile(filePath, content, 'utf8');
+            return {
+              success: true,
+              action: 'write',
+              path: filePath,
+              message: '文件写入成功'
+            };
+          } catch (error) {
+            throw new Error(`写入文件失败: ${error.message}`);
+          }
+          
+        case 'list':
+          try {
+            const items = await fs.readdir(filePath);
+            return {
+              success: true,
+              action: 'list',
+              path: filePath,
+              items: items
+            };
+          } catch (error) {
+            throw new Error(`列出目录内容失败: ${error.message}`);
+          }
+          
+        case 'delete':
+          try {
+            const stats = await fs.stat(filePath);
+            if (stats.isDirectory()) {
+              await fs.rm(filePath, { recursive: true });
+              return {
+                success: true,
+                action: 'delete',
+                path: filePath,
+                type: 'directory',
+                message: '目录删除成功'
+              };
+            } else {
+              await fs.unlink(filePath);
+              return {
+                success: true,
+                action: 'delete',
+                path: filePath,
+                type: 'file',
+                message: '文件删除成功'
+              };
+            }
+          } catch (error) {
+            throw new Error(`删除文件或目录失败: ${error.message}`);
+          }
+          
+        default:
+          throw new Error(`不支持的操作类型: ${action}`);
+      }
+      
+    default:
+      throw new Error(`不支持的模式: ${mode}`);
+  }
+}
+
+/**
+ * 生成 Markdown 格式的手册
+ * @returns {string} Markdown 格式的手册
+ */
+function generateManual() {
+  return `# 🔧 filesystem
+
+> 文件系统工具 - 用于文件操作
+
+## 📋 基础信息
+
+- **标识**: \`tool://filesystem\`
+- **分类**: 系统工具
+
+## ✅ 适用场景
+
+- 读取文件内容进行分析
+- 写入文件内容保存数据
+- 列出目录内容查看文件结构
+- 删除文件或目录进行清理
+
+## 📝 参数定义
+
+### execute 模式参数
+
+| 参数 | 类型 | 必需 | 描述 | 默认值 |
+|------|------|------|------|--------|
+| action | string (read|write|list|delete) | ✅ | 操作类型 | - |
+| path | string | ✅ | 文件或目录路径 | - |
+| content | string | ❌ | 写入的文件内容 (仅在action为write时需要) | - |
+
+## 💻 使用示例
+
+通过 toolx 调用，使用 YAML 格式：
+
+\`\`\`yaml
+# 读取文件内容
+tool: tool://filesystem
+mode: execute
+parameters:
+  action: read
+  path: /path/to/file.txt
+
+# 写入文件内容
+tool: tool://filesystem
+mode: execute
+parameters:
+  action: write
+  path: /path/to/file.txt
+  content: "Hello, World!"
+
+# 列出目录内容
+tool: tool://filesystem
+mode: execute
+parameters:
+  action: list
+  path: /path/to/directory
+
+# 删除文件或目录
+tool: tool://filesystem
+mode: execute
+parameters:
+  action: delete
+  path: /path/to/file-or-directory
+\`\`\`
+
+## 🚨 业务错误
+
+| 错误码 | 描述 | 解决方案 | 可重试 |
+|--------|------|----------|--------|
+| MISSING_ACTION | 缺少必需参数: action | 提供 action 参数 | ❌ |
+| MISSING_PATH | 缺少必需参数: path | 提供 path 参数 | ❌ |
+| READ_FAILED | 读取文件失败 | 检查文件路径是否存在且可读 | ✅ |
+| WRITE_FAILED | 写入文件失败 | 检查文件路径是否可写 | ✅ |
+| LIST_FAILED | 列出目录内容失败 | 检查目录路径是否存在且可读 | ✅ |
+| DELETE_FAILED | 删除文件或目录失败 | 检查文件或目录是否存在且可删除 | ✅ |
+`;
+}

package/packages/resources/tools/index.js

@@ -0,0 +1,16 @@
+/**
+ * ToolX 工具系统 - 提供各种服务内部工具的统一调用接口
+ * 
+ * 工具目录结构:
+ * - 所有工具都位于 /tools 目录下
+ * - 每个工具是一个独立的 JS 文件
+ * - 工具导出一个默认函数，接受参数和模式作为输入
+ */
+
+// 导出所有可用的工具
+export { default as filesystem } from './filesystem/filesystem.tool.js';
+
+// 工具列表
+export const availableTools = [
+  'filesystem'
+];

package/packages/server/mcp/mcp.handler.js

@@ -9,7 +9,7 @@ export async function handleGetPrompt(args) {
   const promptId = args.prompt_id || args.name;
   
   if (!promptId) {
-    throw new Error("缺少必需参数: prompt_id 或 name");
+    throw new Error("缺少必需参数: prompt_id");
   }
   
   const promptManager = await util.getPromptManager();
@@ -39,7 +39,7 @@ export async function handleGetPrompt(args) {
   return convertToText({
     success: true,
     prompt: promptInfo
-  });
+  }, 'detail');
 }
 
 // 处理 search_prompts 工具调用
@@ -60,7 +60,7 @@ export async function handleSearchPrompts(args) {
       query: searchTerm || '',
       count: simplifiedPrompts.length,
       results: simplifiedPrompts
-    });
+    }, 'list');
   }
   
   // 实现相似度匹配算法
@@ -95,7 +95,7 @@ export async function handleSearchPrompts(args) {
     }
   }
 
-  return convertToText(result);
+  return convertToText(result, 'list');
 }
 
 /**
@@ -150,17 +150,116 @@ function formatResults(results = []) {
 }
 
 /**
- * 将对象转换为text类型
- * @param {*} object 
+ * 处理列表格式输出
+ * @param {*} result 
+ * @returns 
+ */
+function formatListOutput(result) {
+  // 生成当前时间戳
+  const now = new Date();
+  const formattedDate = `${now.getFullYear()}/${(now.getMonth() + 1).toString().padStart(2, '0')}/${now.getDate().toString().padStart(2, '0')} ${now.getHours().toString().padStart(2, '0')}:${now.getMinutes().toString().padStart(2, '0')}:${now.getSeconds().toString().padStart(2, '0')}`;
+  
+  // 构建新的输出格式
+  let output = "";
+  output += "[PROMPT_HEADER_AREA]\n";
+  output += "🎭 **PromptManager 提示词清单**\n";
+  output += `📅 ${formattedDate}\n\n`;
+  output += "--------------------------------------------------\n";
+  output += "[PROMPT_LIST_AREA]\n\n";
+  output += `📦 **提示词列表** (${result.count}个)\n`;
+  
+  // 添加提示词列表
+  if (result.results && Array.isArray(result.results) && result.results.length > 0) {
+    result.results.forEach(prompt => {
+      output += `- [${prompt.id}] ${prompt.name}\n`;
+      output += `  - ${prompt.description}\n`;
+    });
+  } else {
+    output += "(无提示词)\n";
+  }
+  
+  output += "\n--------------------------------------------------\n";
+  output += "[STATE_AREA]\n";
+  output += "📍 **当前状态**：prompts_completed\n";
+  
+  // 返回格式化文本
+  return output;
+}
+
+/**
+ * 处理详情格式输出
+ * @param {*} result 
+ * @returns string
+ */
+function formatDetailOutput(result) {
+  const prompt = result.prompt;
+  
+  // 生成当前时间戳
+  const now = new Date();
+  const formattedDate = `${now.getFullYear()}/${(now.getMonth() + 1).toString().padStart(2, '0')}/${now.getDate().toString().padStart(2, '0')} ${now.getHours().toString().padStart(2, '0')}:${now.getMinutes().toString().padStart(2, '0')}:${now.getSeconds().toString().padStart(2, '0')}`;
+  
+  // 构建新的输出格式
+  let output = "";
+  output += "--------------------------------------------------\n";
+  output += "[PROMPT_HEADER_AREA]\n";
+  output += `- id: ${prompt.id}\n`;
+  output += `- name: ${prompt.name}\n`;
+  output += `- description: ${prompt.description}\n`;
+  output += `- filepath: ${prompt.filePath}\n\n`;
+  output += "--------------------------------------------------\n";
+  output += "[PROMPT_PARAMS_AREA]\n";
+  
+  // 添加参数信息
+  if (prompt.arguments && Array.isArray(prompt.arguments) && prompt.arguments.length > 0) {
+    prompt.arguments.forEach(param => {
+      const requiredText = param.required ? "必填" : "非必填";
+      output += `- ${param.name}: ${param.type}; ${requiredText}; ${param.description}\n`;
+    });
+  } else {
+    output += "(无参数)\n";
+  }
+  
+  output += "\n--------------------------------------------------\n";
+  output += "[PROMPT_CONTENT_AREA]\n";
+  
+  // 添加消息内容
+  if (prompt.messages && Array.isArray(prompt.messages)) {
+    const userMessages = prompt.messages.filter(msg => msg.role !== "");
+    if (userMessages.length > 0 && userMessages[0].content && userMessages[0].content.text) {
+      output += userMessages[0].content.text + "\n";
+    }
+  }
+  
+  output += "\n[STATE_AREA]\n";
+  output += "📍 **当前状态**：prompt_loaded\n";
+  
+  return output;
+}
+
+/**
+ * 将对象转换为格式化的text类型输出
+ * @param {*} result 
+ * @param {string} format - 输出格式类型: 'list' 或 'detail'
  * @returns 
  */
-function convertToText(result) {
+function convertToText(result, format) {
+  let ret = ""
+  switch (format) {
+    case 'list':
+      ret = formatListOutput(result);
+      break;
+    case 'detail':
+      ret = formatDetailOutput(result);
+      break;
+    default:
+      ret =JSON.stringify(result, null, 2);
+  }
   return {
     content: [
       {
         type: "text",
-        text: JSON.stringify(result, null, 2)
+        text: ret
       }
     ]
   };
-}
+}

package/packages/server/mcp/mcp.server.js

@@ -1,10 +1,12 @@
 import { config } from '../utils/config.js';
+import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import {
     handleGetPrompt,
     handleSearchPrompts,
     handleReloadPrompts
 } from './mcp.handler.js';
+import { handleToolX } from './toolx.handler.js';
 
 class Server {
     constructor() {
@@ -19,7 +21,13 @@ class Server {
 
     registerTools(tools) {
         for (const tool of tools) {
-            this.server.tool(tool.name, tool.description, tool.inputSchema, tool.handler);
+            this.server.registerTool(tool.name,
+                {
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                },
+                tool.handler
+            );
         }
     }
 
@@ -31,48 +39,139 @@ class Server {
 export const getMcpServer = () => {
     const mcpServer = new Server();
     mcpServer.registerTools([
+        {
+            name: 'search_prompts',
+            description: `功能：智能检索提示词库，匹配用户需求\n描述：根据用户输入内容（可为空）搜索匹配的提示词，返回候选提示词的 ID、名称、简短描述。若输入为空则返回全部提示词列表。帮助用户快速定位适合的提示词，无需记忆具体名称。\n\n示例：\n- 用户："我想写一首诗" → 工具返回：[ID:001, 名称:诗歌创作, 描述:生成古典/现代风格诗歌]\n- 用户："（无输入）" → 工具返回：完整提示词库概览`,
+            inputSchema: {
+                name: z.string().optional().describe('提示词名称或关键词，用于搜索匹配提示词'),
+            },
+            handler: async (args) => {
+                return handleSearchPrompts(args);
+            }
+        },
         {
             name: 'get_prompt',
-            description: 'Retrieve the complete content of a specific prompt by its ID, including all messages, arguments, and metadata.',
+            description: `功能：精准获取并应用提示词详情\n描述：根据提示词 ID 或名称 调用具体内容，自动将其嵌入当前对话上下文，无需用户手动复制。支持通过 search_prompts 返回的 ID/名称直接获取。\n\n示例：\n- 用户："使用 ID 001" → 工具自动加载诗歌创作提示词并生成内容\n- 用户："调用'营销文案生成'" → 工具匹配名称后应用对应提示词`,
             inputSchema: {
-                type: 'object',
-                properties: {
-                    prompt_id: {
-                        type: 'string',
-                        description: 'the unique identifier of the prompt to retrieve'
-                    }
-                },
-                required: ['prompt_id']
+                prompt_id: z.string().describe('提示词的唯一标识 ID/名称'),
             },
             handler: async (args) => {
                 return handleGetPrompt(args);
             }
         },
         {
-            name: 'search_prompts',
-            description: 'For keyword search matching, retrieve or return all prompts. When a corresponding prompt word is matched, utilize the prompt ID to invoke the get_prompt tool to query the complete content of the prompt word.',
+            name: 'toolx',
+            description: `ToolX is the Prompt Manager tool runtime for loading and executing various tools.
+
+## Why ToolX Exists
+
+ToolX is your gateway to the Prompt Manager tool ecosystem. Think of it as:
+- A **universal remote control** for all Prompt Manager tools
+- Your **interface** to specialized capabilities (file operations, etc.)
+- The **bridge** between you (AI agent) and powerful system tools
+
+Without ToolX, you cannot access any Prompt Manager ecosystem tools.
+
+## When to Use ToolX
+
+### Common Scenarios (IF-THEN rules):
+- IF user needs file operations → USE tool://filesystem via toolx
+- IF you see tool:// in any context → USE toolx to call it
+
+### First Time Using Any Tool
+⚠️ **MUST run mode: manual first** to read the tool's documentation
+⚠️ Example: toolx with mode: manual for tool://filesystem
+
+## How to Use ToolX (Copy These Patterns)
+
+### Pattern 1: Read Tool Manual (First Time)
+
+**Exact code to use:**
+\`\`\`javascript
+// Call the toolx function with this exact structure:
+toolx({
+  yaml: \`tool: tool://filesystem\nmode: manual\`
+})
+\`\`\`
+
+**What this does:** Shows you how to use the filesystem tool
+
+### Pattern 2: Execute Tool with Parameters
+
+**Exact code to use:**
+\`\`\`javascript
+toolx({
+  yaml: \`tool: tool://filesystem\nmode: execute\nparameters:\n  path: /path/to/file.txt\n  action: read\`
+})
+\`\`\`
+
+**What this does:** Reads a file at the specified path
+
+### Pattern 3: Configure Tool Environment
+
+**Exact code to use:**
+\`\`\`javascript
+toolx({
+  yaml: \`tool: tool://my-tool\nmode: configure\nparameters:\n  API_KEY: sk-xxx123\n  TIMEOUT: 30000\`
+})
+\`\`\`
+
+**What this does:** Sets environment variables for the tool
+
+## Critical Rules (Must Follow)
+
+### ✅ Correct Format
+The yaml parameter MUST be a complete YAML document:
+- Start with \`tool: tool://tool-name\`
+- Add \`mode: execute\` (or manual/configure)
+- If needed, add \`parameters:\` section with proper indentation
+
+### ❌ Common Mistakes to Avoid
+- DON'T pass just "tool://filesystem" (missing YAML structure)
+- DON'T add @ prefix like "@tool://filesystem" (system handles it)
+- DON'T forget "tool://" prefix (not "tool: filesystem")
+- DON'T forget to read manual first for new tools
+
+## Available System Tools
+
+Quick reference of built-in tools:
+- **tool://filesystem** - File operations (read/write/list/delete)
+
+To see all available tools: check the tools directory
+
+## Step-by-Step Workflow
+
+### Step 1: Discover Available Tools
+Check the tools directory to see what tools exist
+
+### Step 2: Read Tool Manual
+\`\`\`javascript
+toolx({
+  yaml: \`tool: tool://TOOLNAME\nmode: manual\`
+})
+\`\`\`
+
+### Step 3: Execute Tool
+Copy the example from manual, modify parameters for your needs
+
+### Step 4: Handle Errors
+If execution fails, check:
+- Is the tool name correct?
+- Are parameters properly indented?
+- Did you read the manual first?
+
+`,
             inputSchema: {
-                type: 'object',
-                properties: {
-                    name: {
-                        type: 'string',
-                        description: 'Optional name filter for prompts'
-                    }
-                },
-                required: []
+                yaml: z.string().describe('YAML 格式的工具调用配置')
             },
             handler: async (args) => {
-                return handleSearchPrompts(args);
+                return handleToolX(args);
             }
-        },
+        }
         // {
         //     name: 'reload_prompts',
         //     description: 'Force a reload of all preset prompts to overwrite the cache.',
-        //     inputSchema: {
-        //         type: 'object',
-        //         properties: {},
-        //         required: []
-        //     },
+        //     inputSchema: {},
         //     handler: async (args) => {
         //         return handleReloadPrompts(args);
         //     }

package/packages/server/mcp/toolx.handler.js

@@ -0,0 +1,131 @@
+// 导入自定义模块
+import { config } from '../utils/config.js';
+import { logger } from '../utils/logger.js';
+import { util } from '../utils/util.js';
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import YAML from 'yaml';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// 处理 toolx 工具调用
+export async function handleToolX(args) {
+  const { yaml: yamlInput } = args;
+  
+  if (!yamlInput) {
+    throw new Error("缺少必需参数: yaml");
+  }
+  
+  try {
+    // Auto-correct common AI mistakes
+    let yamlContent = yamlInput.trim();
+
+    // Case 1: Just a plain URL string like "tool://filesystem" or "@tool://filesystem"
+    if (yamlContent.match(/^@?tool:\/\/[\w-]+$/)) {
+      const toolName = yamlContent.replace(/^@?tool:\/\//, '');
+      yamlContent = `tool: tool://${toolName}\nmode: execute`;
+    }
+
+    // Case 2: Handle escaped backslashes and quotes: tool: \"@tool://xxx\"
+    // This happens when AI generates YAML in a JSON string
+    yamlContent = yamlContent.replace(/\\\\/g, '\\').replace(/\\"/g, '"');
+
+    // Case 3: Remove @ prefix from tool URLs: @tool://xxx -> tool://xxx
+    yamlContent = yamlContent.replace(/@tool:\/\//g, 'tool://');
+
+    // Case 4: Remove quotes around tool URLs: tool: "tool://xxx" -> tool: tool://xxx
+    yamlContent = yamlContent.replace(/(tool|toolUrl|url):\s*"(tool:\/\/[^\"]+)"/g, '$1: $2');
+
+    // YAML → JSON conversion
+    const configObj = YAML.parse(yamlContent);
+
+    // Normalize field names (support aliases for AI-friendliness)
+    // Priority: tool > toolUrl > url
+    const toolIdentifier = configObj.tool || configObj.toolUrl || configObj.url;
+
+    // Priority: mode > operation
+    const operationMode = configObj.mode || configObj.operation;
+
+    // Validate required fields
+    if (!toolIdentifier) {
+      throw new Error('Missing required field: tool\nExample: tool: tool://filesystem\nAliases supported: tool / toolUrl / url');
+    }
+
+    // Validate URL format
+    if (!toolIdentifier.startsWith('tool://')) {
+      throw new Error(`Invalid tool format: ${toolIdentifier}\nMust start with tool://`);
+    }
+
+    // Get tool name
+    const toolName = toolIdentifier.replace('tool://', '');
+    
+    // Check if tool exists in our local tools directory
+    const rootDir = path.join(__dirname, '..', '..', '..');
+    const toolsDir = path.join(rootDir, 'packages', 'resources', 'tools');
+    const toolPath = path.join(toolsDir, `${toolName}`, `${toolName}.tool.js`);
+    
+    if (!fs.existsSync(toolPath)) {
+      // List available tools
+      const availableTools = await fs.readdir(toolsDir);
+      const toolList = availableTools.filter(file => file.endsWith('.js')).map(file => path.basename(file, '.js'));
+      
+      throw new Error(`Tool '${toolName}' not found\nAvailable tools: ${toolList.join(', ')}\nTools are located in: ${toolsDir}`);
+    }
+
+    // Load and execute the tool
+    const toolModule = await import(toolPath);
+    const toolFunction = toolModule.default || toolModule.execute || toolModule.run;
+    
+    if (typeof toolFunction !== 'function') {
+      throw new Error(`Tool '${toolName}' does not export a valid function`);
+    }
+
+    // Execute the tool with provided parameters
+    const result = await toolFunction(configObj.parameters || {}, operationMode || 'execute');
+    
+    // 如果是 manual 模式，直接返回 Markdown 格式的手册
+    if (operationMode === 'manual') {
+      return {
+        content: [
+          {
+            type: "text",
+            text: result
+          }
+        ]
+      };
+    }
+    
+    // 其他模式返回 JSON 格式的结果
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            tool: toolName,
+            mode: operationMode || 'execute',
+            result: result
+          }, null, 2)
+        }
+      ]
+    };
+  } catch (error) {
+    // YAML parsing errors
+    if (error.name === 'YAMLException') {
+      // Check for multiline string issues
+      if (error.message.includes('bad indentation') || error.message.includes('mapping entry')) {
+        throw new Error(`YAML format error: ${error.message}\n\nMultiline content requires | symbol, example:\ncontent: |\n  First line\n  Second line\n\nNote: Newline after |, indent content with 2 spaces`);
+      }
+      throw new Error(`YAML format error: ${error.message}\nCheck indentation (use spaces) and syntax`);
+    }
+
+    // Tool not found
+    if (error.message?.includes('Tool not found')) {
+      throw new Error(error.message);
+    }
+
+    throw error;
+  }
+}

package/packages/server/utils/config.js

@@ -95,7 +95,7 @@ export class Config {
 
     // 其他配置
     this.serverName = process.env.MCP_SERVER_NAME || 'prompt-manager';
-    this.serverVersion = process.env.MCP_SERVER_VERSION || '0.0.18';
+    this.serverVersion = process.env.MCP_SERVER_VERSION || '0.0.19';
     this.logLevel = process.env.LOG_LEVEL || 'info';
     this.maxPrompts = parseInt(process.env.MAX_PROMPTS) || 1000;
     this.recursiveScan = process.env.RECURSIVE_SCAN !== 'false'; // 默认启用递归扫描