关键词

文件搜索OpenAI APILLM 上下文检索

使用说明

项目简介

这是一个基于 Model Context Protocol (MCP) 实现的服务器，专门用于集成 OpenAI 的文件搜索（File Search）功能。它作为 LLM 客户端（如 Cline）和 OpenAI API 之间的桥梁，允许 LLM 通过标准的 MCP 工具调用来执行文件内容检索，并获取结构化的搜索结果。

主要功能点

  • 文件搜索代理: 作为 OpenAI '/v1/responses' 文件搜索功能的简单代理。
  • 检索工具: 注册一个名为 'retrieveDocs' 的 MCP 工具，供 LLM 调用以执行文件搜索。
  • 结构化结果: 从 OpenAI API 响应中提取原始的、排名靠前的文档块（chunks），并以 '{ id, text, score }' 结构的 JSON 字符串形式返回。
  • 配置灵活: 通过 'config.json' 文件配置 OpenAI Vector Store ID，通过环境变量 ('.env' 文件或系统环境变量) 配置 OpenAI API Key。
  • 健壮性: 内置了 30 秒超时机制和对特定错误（如 429, 5xx, 网络问题）的重试逻辑（最多 3 次尝试）。

安装步骤

  1. 克隆仓库: 如果还没有克隆，请使用 Git 获取仓库代码。
  2. 安装依赖: 进入仓库目录，运行 npm 安装项目所需的所有库。 
    npm install
  3. 配置服务器:
    • Vector Store ID: 复制 'config.template.json' 到 'config.json'，然后编辑 'config.json' 文件，填入你的 OpenAI Vector Store ID。 
      cp config.template.json config.json
      编辑 'config.json': 
      {
  "vectorStoreId": "vs_YOUR_VECTOR_STORE_ID"
}
    • OpenAI API Key: 复制 '.env.example' 到 '.env'，然后编辑 '.env' 文件，填入你的 OpenAI API Key。 
      cp .env.example .env
      编辑 '.env': 
      OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# 还可以选择设置 DEBUG_OPENAI=true 来开启详细日志
    • 注意: 'config.json' 和 '.env' 文件通常不应提交到 Git 仓库。
  4. 构建项目: 运行构建命令，将 TypeScript 代码编译成 JavaScript。 
    npm run build

服务器配置 (用于 MCP 客户端)

该服务器通过标准输入输出 (stdio) 进行通信，是 MCP 客户端（如 Cline）连接的常见方式。在 MCP 客户端的配置中，你需要指定如何启动这个服务器进程。

通常，MCP 客户端的服务器配置会是一个 JSON 对象数组，包含如下信息：

{
  "servers": [
    {
      "id": "给这个服务器取一个独一无二的 ID，例如: filesearch-openai",
      "command": "启动服务器的命令，对于这个项目是 'npm'",
      "args": [
        "命令的参数，对于这个项目是 'start'"
      ],
      "working_directory": "服务器代码所在的文件夹路径，例如: /path/to/openai-filesearch-mcp",
      "environment": {
        // 可选: 可以在这里直接设置环境变量，代替 .env 文件
        // "OPENAI_API_KEY": "sk-...",
        // "DEBUG_OPENAI": "true"
      },
      "description": "这个 MCP 服务器的功能描述，比如: 通过OpenAI文件搜索检索文档片段"
      // 其他 MCP 客户端可能支持的配置项，如 auto_start 等
    }
  ]
}

请注意:

  • 'vectorStoreId' 和 'OPENAI_API_KEY' 是服务器启动时自己读取的配置，必须在服务器的文件 ('config.json', '.env') 或 MCP 客户端配置的 'environment' 字段中设置好。
  • MCP 客户端通过 'command' 和 'args' 启动服务器进程，并通过 stdio 与其通信。

基本使用方法

安装并配置完成后，启动你的 MCP 客户端（如 Cline）。如果客户端配置正确，它将能够启动并连接到这个 OpenAI 文件搜索 MCP 服务器。

当客户端（或通过客户端与 LLM 交互时）需要执行文件搜索功能时，它会通过 MCP 协议调用服务器注册的 'retrieveDocs' 工具，并传递一个包含用户问题的参数，例如：

{
  "jsonrpc": "2.0",
  "method": "tool_call",
  "params": {
    "tool_name": "retrieveDocs",
    "tool_args": {
      "question": "我的项目文档里提到了哪些关于安装的步骤？"
    },
    "call_id": "..." // 客户端生成的调用 ID
  },
  "id": "..." // 客户端生成的请求 ID
}

服务器接收到请求后，会调用 OpenAI API 执行文件搜索，处理响应，然后通过 MCP 协议返回搜索到的文档块列表（作为 JSON 字符串）。LLM 客户端会接收这个结果，并可以利用这些文档块来生成更准确的回复。

你无需直接与这个服务器的 stdio 接口交互，所有通信都由支持 MCP 的 LLM 客户端自动处理。

信息

分类

AI与计算

访问项目