项目简介

"Semantic Search MCP Server" 是一个基于 Model Context Protocol (MCP) 构建的后端服务，专注于为大型语言模型（LLM）客户端提供强大的知识检索和文档处理能力。它通过本地、开源组件实现文档的智能摄取、多种检索模式（语义、混合、稀疏、重排序）以及轻量级知识图谱功能，确保检索结果的确定性、来源可追溯性和安全性。其独特之处在于支持零成本的本地嵌入和重排序，降低了运行成本，并赋予LLM客户端在检索和内容管理中更强的规划和决策能力。

主要功能点

零成本文档处理: 利用Ollama进行本地嵌入，并使用TEI交叉编码器进行本地重排序，避免按令牌收费，降低了运营成本。
智能文档摄取: 使用Docling高效处理PDF文档，自动提取表格、图片、标题等结构化信息，并支持增量和确定性摄取，仅处理更改过的文档。
多模式智能检索: 提供语义搜索、混合搜索、稀疏搜索、重排序搜索以及自动模式，允许LLM客户端根据查询类型选择最合适的检索策略。
轻量级知识图谱: 在摄取过程中提取实体并建立文档与实体之间的链接，支持LLM客户端通过实体进行信息枢纽查询。
MCP控制的文档更新: LLM客户端可以直接通过MCP工具执行文档的摄取、分块、元数据生成和更新操作，实现工作流的完全集成。
会话级文档优先级调整: 允许LLM客户端在会话中提升或降低特定文档的搜索优先级。
可观测性和质量保障: 提供搜索日志、阶段计时、QA框架，确保检索结果的质量和透明度。

安装步骤

克隆仓库:

git clone https://github.com/hvkshetry/knowledge-base-mcp.git
cd knowledge-base-mcp

安装 Ollama: 访问 ollama.com 下载并安装 Ollama。拉取嵌入模型：

ollama pull snowflake-arctic-embed:xs

启动 Docker 服务: 启动 Qdrant 向量数据库和 TEI Reranker 服务：
```
docker-compose up -d
```

设置 Python 环境:

python -m venv .venv
source .venv/bin/activate  # Windows 用户请使用 .venv\Scripts\activate
pip install -r requirements.txt

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

此MCP服务器是为Claude Desktop、Claude Code、Codex CLI等MCP客户端设计的。客户端需要配置服务器的启动命令和相关参数才能与之通信。以下是配置示例，您可以根据实际情况进行调整：

MCP客户端配置示例 (JSON格式，不直接粘贴到终端运行):

{
  "serverName": "知识库MCP服务器",
  "description": "提供语义搜索、RAG和文档处理功能的MCP服务器",
  "command": "/path/to/your/knowledge-base-mcp/.venv/bin/python",
  "args": ["/path/to/your/knowledge-base-mcp/server.py"],
  "env": {
    "FTS_DB_PATH": "/path/to/your/knowledge-base-mcp/data/fts.db",
    "GRAPH_DB_PATH": "/path/to/your/knowledge-base-mcp/data/graph.db",
    "SUMMARY_DB_PATH": "/path/to/your/knowledge-base-mcp/data/summary.db",
    "NOMIC_KB_SCOPES": "{\"kb\":{\"collection\":\"snowflake_kb\",\"title\":\"公司知识库\"}}",
    "LOG_LEVEL": "INFO"
    // 其他可选环境变量，例如：
    // "OLLAMA_URL": "http://localhost:11434", // Ollama服务URL
    // "OLLAMA_MODEL": "snowflake-arctic-embed:xs", // Ollama嵌入模型
    // "TEI_RERANK_URL": "http://localhost:8087", // TEI重排序服务URL
    // "QDRANT_URL": "http://localhost:6333", // Qdrant服务URL
    // "ALLOWED_DOC_ROOTS": "/path/to/your/documents" // 如果您限制了文档根目录
  },
  "startupTimeoutMs": 30000,
  "protocol": "stdio"
}

请注意：

将 '/path/to/your/knowledge-base-mcp/' 替换为您实际的项目根目录。
'NOMIC_KB_SCOPES' 定义了知识库的名称和内部Qdrant集合名称。默认配置了一个名为 "kb" 的知识库，对应Qdrant中的 "snowflake_kb" 集合。您可以在此处添加更多知识库配置。
其他 'env' 变量根据您的部署环境和需求进行调整。

基本使用方法

摄取文档: 将您的PDF、DOCX、TXT文档放入一个目录（例如 '/path/to/your/documents'）。运行摄取脚本，将文档添加到名为 'my_docs' 的知识库中：

python ingest.py \
  --root /path/to/your/documents \
  --collection my_docs \
  --ext .pdf,.docx,.txt \
  --fts-db data/my_docs_fts.db

注意: 首次摄取可能需要一些时间来处理文档、生成嵌入和构建索引。

通过MCP客户端进行搜索和交互: 启动您的MCP客户端（例如 Claude Desktop），并确保它已正确配置上述服务器信息。在客户端的交互界面中，您可以调用服务器暴露的MCP工具进行检索和查询。例如，客户端可能会自动调用 'kb.search' 工具进行搜索，或者在特定场景下调用 'ingest.upsert' 来更新文档。您可以尝试向客户端提问关于您已摄取文档的问题，客户端将使用此MCP服务器作为其知识来源进行回答。例如，客户端可能会生成并执行以下工具调用 (JSON-RPC 请求):

{
  "jsonrpc": "2.0",
  "method": "kb.search",
  "params": {
    "query": "您的搜索问题，例如：如何处理废水中的化学物质？",
    "collection": "my_docs",
    "mode": "auto",
    "top_k": 5
  },
  "id": 1
}

服务器会处理此请求并返回相关的文档片段和元数据。

关键词

项目简介

主要功能点

安装步骤

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

基本使用方法

信息