Skip to main content
Glama
deenesjakoruzh
channico

MCP Knowledge Assistant

by channico
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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

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

工具

输入

用途

search

query: string

返回紧凑的相关文档引用。

fetch

id: string

检索搜索中选中的一份完整文档。

将发现与检索分离，可以避免在需要之前发送完整文档，并为模型提供稳定的文档 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 服务器绑定在安全出站隧道之后，而不是 开放入站防火墙端口。

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

参考资料

Available Tools

2 tools
fetchA

Retrieve one complete document using an ID returned by search.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
idYes
urlYes
textYes
titleYes
metadataNo

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral disclosure burden. It reveals that this returns a complete document (not a summary) and that it depends on search-generated IDs, but doesn't mention error handling, permissions, or potential side effects. For a simple read operation this is adequate but has gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, no redundant details, and the key information (retrieve by ID) is front-loaded. Perfect conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema is present and there is only one parameter, the description sufficiently covers the essential context and its relationship to the sibling search tool. It could be improved by mentioning error cases or what happens if the ID is invalid, but for this simplicity it is complete enough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'id' has no schema description, so the description's phrase 'returned by search' provides crucial semantic context, explaining where the ID comes from and how it should be used to retrieve the document.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Retrieve' with the resource 'one complete document' and the qualifier 'using an ID returned by search', which clearly defines the tool's scope and distinguishes it from the sibling tool 'search'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states that the ID must come from search, establishing a clear workflow (search first, then fetch). It doesn't explicitly mention alternatives, but the context is clear enough for an agent to know when to use this tool versus search.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedfetch
    • First observedsearch
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored across 2 tools

Disambiguation5/5

search and fetch have clearly distinct purposes: one finds documents by query, the other retrieves a specific document by ID. There is no overlap or ambiguity.

Naming Consistency5/5

Both tools use simple, consistent single-verb names ('search' and 'fetch') that clearly indicate their actions. The pattern is uniform.

Tool Count3/5

With only 2 tools, the server is minimal but functionally complete for a simple search-and-retrieve pattern. It feels thin but is reasonable for a narrow purpose.

Completeness4/5

The two tools cover the core workflow of searching and retrieving documents. Minor gaps could include listing all documents or getting metadata, but the essential lifecycle is covered.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • RAG Docs MCP Server

    gorizond
    A
    license
    Not graded
    quality
    A
    maintenance
    An MCP server that provides tools for retrieving and processing documentation through vector search, enabling AI assistants to augment their responses with relevant documentation context.
    24 npm
    MIT

  • File AI

    flyfish-dev
    A
    license
    B
    quality
    D
    maintenance
    A read-only MCP server that provides document awareness for agents by parsing local files into structured profiles, blocks, chunks, and search results, enabling agents to understand and cite document content without dealing with raw file formats.
    5
    43 npm
    3
    Apache 2.0

  • CasioPlus MCP

    hadiranweb
    F
    license
    Not graded
    quality
    B
    maintenance
    An MCP server that connects the Casio Plus knowledge base (playbooks, architecture, learning resources) to AI clients, offering read-only search and validation tools along with controlled feedback intake and review workflows.
    -