文件搜索服务

文件搜索MCP服务器

TypeScript中的最小FastMCP 2.x服务器，它公开了一个RPC--retrieveDocs(question)--它从OpenAI文件搜索返回原始排名块。

特性

• 充当OpenAI的简单代理 /v1/responses 端点使用 file_search 工具。
• 倒像 OPENAI_API_KEY 从环境变量。
• 倒像 vectorStoreId 从 config.json.
• 使用FastMCP 2.x addTool 和 ctx.log.
• 返回原始块({ id, text, score }[])作为JSON字符串，从中提取 file_search_call.results.
• 包括鲁棒性功能：30秒超时、瞬态错误（429、5xx、网络）的重试逻辑（3次尝试）和结构化错误报告。
• 可选的详细日志记录，通过 DEBUG_OPENAI 环境变量。

先决条件

• Node.js（建议使用v18或更高版本）
• npm（或pnpm/yarn）
• 一个OpenAI API密钥
• 现有的OpenAI矢量存储ID
• Git（用于克隆）

设置

1. 克隆存储库（如果适用）：

   复制

   # git clone <repository-url>
   # cd filesearch-mcp-server
   

2. 安装依赖项： 安装所需的软件包。

   复制

   npm install
   

3. 配置：

   • config.json: 复制 config.template.json 向 config.json 并添加您的矢量存储ID。

     复制

     cp config.template.json config.json
     

     然后编辑 config.json:

     复制

     {
       "vectorStoreId": "vs_YOUR_VECTOR_STORE_ID"
     }
     

     （替换 vs_YOUR_VECTOR_STORE_ID 使用您的实际ID。git通过以下方式忽略此文件 .gitignore.)

   • 环境变量： 创建一个 .env 文件（或直接设置环境变量）。您可以复制示例：

     复制

     cp .env.example .env
     

     然后编辑 .env 使用API密钥：

     复制

     # Required: Your OpenAI API Key
     OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
     
     # Optional: Set to "true" or "1" for verbose OpenAI API response logging
     # DEBUG_OPENAI=false
     

     （git通过忽略此文件 .gitignore.)

     或者，通过临床MCP设置进行配置(cline_mcp_setting.json):

     复制

     {
       "servers": [
         {
           "id": "filesearch-mcp-server",
           "command": "npm start",
           "working_directory": "path/to/filesearch-mcp-server",
           "environment": {
             "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
             "DEBUG_OPENAI": "false"
           }
         }
       ]
     }
     

4. 构建TypeScript代码：

   复制

   npm run build
   

运行服务器

npm start

此命令运行 node dist/server.js，使用启动服务器 stdio 传输（默认）。它在标准输入/输出上监听MCP请求，使其适合与Cline或其他期望进行stdio通信的MCP客户端一起使用。

发展

• 构建： npm run build （将TypeScript编译为 dist/)
• 格式： npm run format （使用Prettier格式化代码）
• 棉绒： npm run lint （使用ESLint检查代码样式）
• 观看&跑步： npm run dev （监视服务器的更改、重建和重启）

块状结构

服务器从中提取块 output[*].file_search_call.results OpenAI API响应中的字段。返回的JSON数组中的每个块都遵循 Chunk 接口： { id: string, text: string, score: number }The id 从结果对象的 id 字段（有回退）， text 是块内容，以及 score 是OpenAI提供的相关性得分。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。