MCP 知识助手

一个只读的模型上下文协议（MCP）服务器，让 AI 客户端能够搜索知识库并检索完整的源文档。该项目从一个本地小原型开始，然后将相同的工具契约应用于 OpenAI 向量存储的语义检索。

本项目的演示内容

• 具有单一 search 和 fetch 职责的 MCP 工具设计

• 使用 FastMCP 和 Pydantic 的结构化输入与输出

• 对上传至 OpenAI 向量存储的文档进行语义检索

• 当向量搜索返回多个匹配分块时，进行文档级去重

• 可流式 HTTP 和 stdio MCP 传输

• 通过 OpenAI Responses API 和安全 MCP 隧道的端到端工具使用

• 通过环境变量进行配置，源代码中不包含任何凭据

• 不调用付费 API 的单元测试和协议级测试

Related MCP server: File AI

架构

OpenAI Responses API
        |
        | MCP tool calls through an outbound secure tunnel
        v
Local FastMCP server (Streamable HTTP)
        |
        | vector-store search and file retrieval
        v
OpenAI vector store -> uploaded documents

该仓库还包含一条完全本地的学习路径：

Local demo client -> FastMCP server (stdio) -> data/documents.json

两个服务器暴露相同的公共工具契约：

将发现与检索分离，可以避免在需要之前发送完整文档，并为模型提供稳定的文档 ID 以供后续调用使用。

项目结构

.
├── data/documents.json                   # Sample local knowledge base
├── sample_data/cats.pdf                  # Public-domain vector-store sample
├── src/mcp_knowledge_assistant/
│   ├── knowledge_base.py                 # Local keyword retrieval
│   ├── models.py                         # Shared response schemas
│   ├── server.py                         # Local stdio MCP server
│   └── vector_store_server.py            # OpenAI vector-store MCP server
├── tests/                                # Offline unit and MCP tests
├── demo_client.py                        # Local stdio demonstration
├── vector_store_demo_client.py           # Direct HTTP MCP demonstration
└── api_client.py                         # Responses API + secure tunnel demonstration

环境要求

• Python 3.11 或更高版本

• 一个启用了计费的 OpenAI API 项目（用于向量存储路径）

• 随附的示例 PDF，或您自己上传到 OpenAI 向量存储的文档

• 仅用于安全隧道演示的 OpenAI 隧道客户端

本地 JSON 服务器和完整测试套件不需要 API 密钥。

示例文档署名

向量存储演示使用了 Cats: Their Points and Characteristics 作者 W. Gordon Stables，Project Gutenberg 电子书 #43429。该示例 PDF 由 OpenAI 托管，并根据 Project Gutenberg 版本制作。有关 Project Gutenberg 许可证和相应的重用条款，请参阅该 PDF。

设置

克隆仓库、创建虚拟环境并安装项目：

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

对于 OpenAI 支持的示例，请复制环境模板：

cp .env.example .env.local

然后向 .env.local 中添加您自己的值：

OPENAI_API_KEY=your_project_api_key
VECTOR_STORE_ID=vs_your_vector_store_id

.env.local、PyCharm 设置、虚拟环境和本地隧道配置文件 均被 Git 排除。

1. 运行本地原型

第一个服务器使用 stdio，因此 MCP 客户端将其作为子进程启动， 并通过标准输入和输出进行通信：

python demo_client.py

该演示会发现两个工具、搜索示例 JSON 知识库，并 获取选中的文档。

您也可以通过已安装的命令启动服务器：

mcp-knowledge-assistant

对于没有连接客户端的 stdio 服务器来说，保持静默等待进程是正常现象。

2. 运行向量存储服务器

将 sample_data/cats.pdf 上传到 OpenAI 向量存储，然后在 .env.local 中设置 OPENAI_API_KEY 和 VECTOR_STORE_ID。您也可以替换为 自己的文档和查询。启动可流式 HTTP 服务器：

mcp-vector-store-assistant

默认情况下，其 MCP 端点为：

http://127.0.0.1:8000/mcp

在第二个终端中，直接测试该端点：

python vector_store_demo_client.py

向量搜索基于分块运行，因此一篇长文档可能产生多个 具有相同文件 ID 的匹配项。MCP search 工具会特意将这些 匹配项合并为一个文档结果。随后 fetch 工具会检索并 合并该文档的解析内容以供模型使用。

3. 通过 Responses API 调用

按照 OpenAI 的 安全 MCP 隧道指南 创建隧道，将其忽略的本地配置文件指向 http://127.0.0.1:8000/mcp，然后启动隧道客户端。将生成的 ID 添加到 .env.local：

MCP_TUNNEL_ID=tunnel_your_tunnel_id

隧道客户端从 CONTROL_PLANE_API_KEY 读取其自身的运行时凭据。请同样将该值保存在本地。在向量服务器 和隧道客户端都运行的情况下，执行：

python api_client.py

Responses API 请求仅声明只读的 search 和 fetch MCP 工具。模型可以搜索、获取选中的源文档，并根据 检索到的内容撰写答案。

测试

使用以下命令运行所有测试：

pytest

测试覆盖本地排序与获取、MCP 工具发现、向量结果 去重、内容组装和输入验证。OpenAI 调用均被模拟， 因此测试套件可重复运行，且不会消耗 API 额度。

设计决策与范围

• 只读优先： 两个 MCP 工具都不会修改文件或外部状态。

• 稳定的兼容性契约： search(query) 返回文档引用； fetch(id) 返回完整的内容和元数据。

• 文档级结果，而非分块级结果： 分块是向量存储内部的检索证据， 而 MCP 客户端接收的是稳定的文件 ID。

• MCP 作为抽象层： 对于单个 OpenAI 托管的向量存储， Responses API 内置的 File Search 工具更为简单。当 同一检索接口需要服务多个客户端、隐藏后端细节， 或将来添加授权和领域逻辑时，MCP 就变得更有价值。

• 经过验证的集成边界： 本地服务器、直接 MCP 客户端以及 通过安全隧道的 Responses API 路径均在开发过程中经过实际测试。 本仓库不声称提供已部署的公共服务器或已发布的 ChatGPT 应用。

安全说明

• 切勿提交 .env.local、API 密钥、隧道运行时密钥或组织 ID。

• 使用项目级凭据，并仅授予所需的最小权限。

• 将本地 MCP 服务器绑定在安全出站隧道之后，而不是 开放入站防火墙端口。

• 在添加任何写入或重大操作之前，请审查工具权限。

参考资料

• OpenAI MCP 指南

• OpenAI File Search 指南

• OpenAI 安全 MCP 隧道指南

• FastMCP 文档