文件管理智能代理

FilesAssistant-MCP 翻译为中文是：“文件助手-MCP”（注：MCP可能是一个特定项目、产品或功能的缩写，具体含义需根据上下文确定）

这是什么？

该项目是一个模板，用于构建基于自定义模型上下文协议（MCP）的代理，这些代理通过与OpenAI兼容的API与大型语言模型（LLM）集成。它为创建能够处理自然语言查询并通过预定义工具执行任务的智能代理提供了基础。出于演示目的，该模板实现了文件系统操作，并配备了强大的安全机制，以防止意外修改或删除文件。MCP服务器处理JSON-RPC请求，而客户端则与大型语言模型（如DeepSeek、OpenAI或Ollama）通信，以根据用户输入确定要调用的工具。

特点/特性

• 智能文件管理利用大型语言模型（LLM）来解析自然语言查询并选择适当的文件操作。
• MCP 服务器实现了一个JSON-RPC 2.0服务器，用于处理工具调用，支持批量请求和初始化。
• 文件系统工具：
  • analyze_logs使用正则表达式在日志文件中搜索模式（例如，错误）。
  • search_files通过文件名、内容或元数据（例如，修改日期）来查找文件。
  • organize_files按文件扩展名或创建日期将文件分组到子目录中。
  • replace_text在文件中执行批量文本替换（例如，将“http”更改为“https”）。
  • delete_file删除文件，可通过配置限制来防止未经授权的删除操作。
• 多LLM支持兼容任何OpenAI风格的API（DeepSeek、OpenAI、Ollama等），通过可配置的提供者系统实现。
• 安全:
  • 限制文件操作仅在指定区域进行 WORKING_DIR 以防止未经授权的访问。
  • 需要 MCP_SERVER_AUTH_TOKEN 用于MCP服务器的身份验证。
  • 默认情况下禁用文件删除功能ALLOW_DELETE=false）以确保安全。
• 模块化设计工具在单独的模块中定义（tools.js)，便于轻松添加新功能。
• 可配置的设置（API提供商、密钥、目录等）在 config.json。

如何使用

先决条件

• Node.js（建议使用v18或更高版本）。
• NPM 包： axios， readline-sync， glob。
• 根据您提供的信息，以下是原文内容的翻译：“为您的所选大型语言模型（LLM）提供商（例如，来自DeepSeek的）获取一个API密钥。” platform.deepseek.com（可译为）：深搜平台（或“深思平台”，具体翻译取决于“deepseek”在该语境下的具体含义，这里“深搜”是较为通用的翻译，表示深入搜索或深度探索的平台））。

安装

1. 克隆仓库或复制项目文件。
2. 安装依赖项：
   复制

   npm install axios readline-sync glob
   

3. 编辑 config.json 在项目根目录中进行配置以匹配您的环境：
   • API_PROVIDER选项包括 deepseek， openai， ollama或者自定义提供者。
   • LLM_API_KEY大语言模型提供商的API密钥（Ollama不需要）。
   • MODEL模型名称（例如。， gpt-4 对于OpenAI来说， llama3 （适用于Ollama）。
   • MCP_SERVER_AUTH_TOKEN用于MCP服务器认证的令牌。
   • WORKING_DIR允许文件操作的目录。
   • ALLOW_DELETE设置为 true 以启用文件删除功能（默认： false）。

运行应用程序

1. 启动MCP服务器：
   复制

   node mcp-server.js
   

   服务器将在 http://localhost:3000/mcp。
2. 启动客户端：
   复制

   node llm-client.js
   

3. 在客户端控制台中输入查询，例如：
   • “查找所有包含‘error’的文件，并将‘http’替换为‘https’。”
   • “按文件扩展名整理文件。”
   • “分析 access.log 中的‘404’错误。”
4. 要退出客户端，请输入 exit。

示例工作流程

• 查询“查找包含‘error’的文件，并将‘http’替换为‘https’。”
• 过程：
  1. 客户端将查询发送给大型语言模型（例如，DeepSeek）。
  2. 大型语言模型（LLM）决定进行调用 search_files 与……一起；带有；用 query: "error"， by: "content"。
  3. MCP服务器执行该工具并返回匹配的文件路径。
  4. 然后，大型语言模型（LLM）调用 replace_text 对于每个文件。
  5. 客户端显示最终响应。

如何延长

此模板设计便于自定义。以下是添加新功能的关键区域：

添加新工具

1. 定义工具：
   • 开放 tools.js 并添加一个新功能到 module.exports例如：
     复制

     // EXTENSION POINT: Example tool for compressing files
     compress_files: async ({ filename }) => {
       // Implement compression logic (e.g., using 'archiver' package)
       const filePath = ensureSafePath(filename);
       // ...
       return `File ${filePath} compressed`;
     },
     

2. 更新客户端工具定义：
   • 在 llm-client.js，将工具添加到 tools 带有其模式的数组：
     复制

     {
       name: 'compress_files',
       description: 'Compress a file into a zip archive',
       parameters: {
         type: 'object',
         properties: { filename: { type: 'string' } },
         required: ['filename'],
       },
     },
     

3. 使用类似“将file.txt压缩成zip文件”的查询来测试新工具

添加外部API集成

• 添加一个工具来与外部API交互，例如公共的JSONPlaceholder API（无需令牌）：
  复制

  // EXAMPLE: REST API CALL - Fetch data from public JSONPlaceholder API
  fetch_external_data: async ({ endpoint = 'posts' }) => {
    try {
      const response = await axios.get(`https://jsonplaceholder.typicode.com/${endpoint}`);
      return {
        data: response.data,
        count: Array.isArray(response.data) ? response.data.length : 1,
        message: `Fetched ${endpoint} data successfully`
      };
    } catch (error) {
      throw new Error(`API call failed: ${error.message}`);
    }
  },
  

• 添加相应的模式到 llm-client.js：
  复制

  {
    name: 'fetch_external_data',
    description: 'Fetch user list for saving to files',
    parameters: {
      type: 'object',
      properties: { endpoint: { type: 'string', enum: ['posts', 'users', 'comments'] } },
      required: ['endpoint'],
    },
  },
  

• 测试查询，例如“从JSONPlaceholder获取帖子并保存到posts.json文件中。”

添加新的大型语言模型（LLM）提供商

1. 更新提供商：
   • 在 llm-client.js，延长/扩展 providers 对象：
     复制

     // EXTENSION POINT: Add new providers
     anthropic: {
       url: 'https://your-anthropic-adapter-url/v1/chat/completions',
       model: 'claude-3-opus',
       apiKey: config.LLM_API_KEY,
     },
     

2. 更新 config.json 与新供应商合作：
   复制

   {
     "API_PROVIDER": "anthropic",
     "LLM_API_KEY": "your_anthropic_key",
     "MODEL": "claude-3-opus"
   }
   

其他扩展

• 实时监控添加一个工具到 tools.js 使用 fs.watch 监控文件变化并通知大型语言模型（LLM）。
• 持久历史记录将消息历史保存到文件或数据库中 llm-client.js。
• 增强的安全性添加速率限制或登录功能 mcp-server.js 对于MCP服务器。
• 流式响应修改 callLLM 在里面 llm-client.js 如果大型语言模型（LLM）提供商支持，将处理流式响应。

注释

• 确保新工具得到尊重 WORKING_DIR 使用时的限制 ensureSafePath。
• 启用时进行彻底测试 ALLOW_DELETE 以避免意外文件丢失。
• 查阅大型语言模型（LLM）提供商的文档以获取具体信息 tool_calls 或模型要求。