FileSearch MCP Server

基本能力

产品定位

openai-filesearch-mcp 是一个轻量级的 FastMCP 2.x 服务器，主要用于代理 OpenAI 的文件搜索功能，提供文档检索服务。

核心功能

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

适用场景

• 需要集成 OpenAI 文件搜索功能的开发项目。
• 快速检索和排名文档内容的应用程序。

工具列表

• retrieveDocs(question)：返回从 OpenAI 文件搜索中获取的原始排名块。

常见问题解答

• 如何配置 vectorStoreId？通过编辑 config.json 文件并添加您的 Vector Store ID。
• 如何设置 API 密钥？通过 .env 文件或直接设置环境变量。

使用教程

使用依赖

• Node.js（推荐 v18 或更高版本）
• npm（或 pnpm/yarn）
• OpenAI API 密钥
• 现有的 OpenAI Vector Store ID
• Git（用于克隆）

安装教程

1. 克隆仓库（如适用）： bash git clone <repository-url> cd filesearch-mcp-server
2. 安装依赖： bash npm install
3. 配置：
4. 复制 config.template.json 到 config.json 并添加您的 Vector Store ID。 bash cp config.template.json config.json
5. 编辑 config.json： json { "vectorStoreId": "vs_YOUR_VECTOR_STORE_ID" }
6. 创建 .env 文件并添加您的 API 密钥： dotenv OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx DEBUG_OPENAI=false
7. 构建 TypeScript 代码： bash npm run build

调试方式

• 运行服务器： bash npm start
• 开发命令：
• 构建：npm run build
• 格式化代码：npm run format
• 检查代码风格：npm run lint
• 监视并运行：npm run dev

许可证

该项目遵循 Other 开源许可条款，请参阅 Other 了解完整条款。