知识库-mcp-服务器

Name: 知识库-mcp-服务器
Author: jeanibarz

作者：jeanibarz33 星标更新：2025-10-20

安装使用来源：spider==github.com

项目介绍

知识库MCP服务器

此MCP服务器提供了从不同知识库中列出和检索内容的工具。

安装指南

这些说明假设您的系统上已安装了Node.js和npm。

通过Smithery安装

要通过Smithery自动安装Claude Desktop的知识库服务器：

npx -y @smithery/cli install @jeanibarz/knowledge-base-mcp-server --client claude

手动安装

先决条件

Node.js（版本16或更高）
npm（Node包管理器）

克隆仓库：

git clone <repository_url>
cd knowledge-base-mcp-server

安装依赖项：
```
npm install
```
配置环境变量：

此服务器支持两种嵌入提供者：Ollama（推荐用于可靠性）和HuggingFace（备用选项）。

选项1：Ollama配置（推荐）
- 设置EMBEDDING_PROVIDER=ollama以使用本地Ollama嵌入
- 安装Ollama并拉取嵌入模型：ollama pull dengcao/Qwen3-Embedding-0.6B:Q8_0
- 配置以下环境变量：
```
EMBEDDING_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434  # 默认Ollama URL
OLLAMA_MODEL=dengcao/Qwen3-Embedding-0.6B:Q8_0          # 默认嵌入模型
KNOWLEDGE_BASES_ROOT_DIR=$HOME/knowledge_bases
```
选项2：HuggingFace配置（备用）
- 设置EMBEDDING_PROVIDER=huggingface或留空（默认）
- 从HuggingFace获取免费API密钥
- 配置以下环境变量：
```
EMBEDDING_PROVIDER=huggingface          # 可选，默认值
HUGGINGFACE_API_KEY=your_api_key_here
HUGGINGFACE_MODEL_NAME=sentence-transformers/all-MiniLM-L6-v2
KNOWLEDGE_BASES_ROOT_DIR=$HOME/knowledge_bases
```
额外配置
- 服务器支持FAISS_INDEX_PATH环境变量来指定FAISS索引的路径。如果没有设置，它将默认为$HOME/knowledge_bases/.faiss。
- 日志可以通过设置LOG_FILE=/path/to/logs/knowledge-base.log路由到文件。日志详细程度默认为info，可以使用LOG_LEVEL=debug|info|warn|error进行调整。
- 您可以在.bashrc或.zshrc文件中设置这些环境变量，或者直接在MCP设置中设置。
构建服务器：
```
npm run build
```

将服务器添加到MCP设置中：

编辑位于/home/jean/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/的cline_mcp_settings.json文件。
向mcpServers对象添加以下配置：
选项1：Ollama配置

"knowledge-base-mcp-ollama": {
  "command": "node",
  "args": [
    "/path/to/knowledge-base-mcp-server/build/index.js"
  ],
  "disabled": false,
  "autoApprove": [],
  "env": {
    "KNOWLEDGE_BASES_ROOT_DIR": "/path/to/knowledge_bases",
    "EMBEDDING_PROVIDER": "ollama",
    "OLLAMA_BASE_URL": "http://localhost:11434",
    "OLLAMA_MODEL": "dengcao/Qwen3-Embedding-0.6B:Q8_0"
  },
  "description": "基于查询使用Ollama从知识库中检索相似片段。"
},

选项2：HuggingFace配置

"knowledge-base-mcp-huggingface": {
  "command": "node",
  "args": [
    "/path/to/knowledge-base-mcp-server/build/index.js"
  ],
  "disabled": false,
  "autoApprove": [],
  "env": {
    "KNOWLEDGE_BASES_ROOT_DIR": "/path/to/knowledge_bases",
    "EMBEDDING_PROVIDER": "huggingface",
    "HUGGINGFACE_API_KEY": "YOUR_HUGGINGFACE_API_KEY",
    "HUGGINGFACE_MODEL_NAME": "sentence-transformers/all-MiniLM-L6-v2"
  },
  "description": "基于查询使用HuggingFace从知识库中检索相似片段。"
},

**注意：**您只需向cline_mcp_settings.json文件添加上述配置之一（Ollama或HuggingFace），取决于您首选的嵌入提供者。


*   将`/path/to/knowledge-base-mcp-server`替换为服务器目录的实际路径。
*   将`/path/to/knowledge_bases`替换为知识库目录的实际路径。

创建知识库目录：
- 在KNOWLEDGE_BASES_ROOT_DIR内为每个知识库创建子目录（例如，company，it_support，onboarding）。
- 将包含知识库内容的文本文件（如.txt，.md）放置在这些子目录中。

服务器递归读取指定知识库子目录内的所有文本文件（如.txt，.md）。
服务器跳过隐藏文件和目录（以.开头）。
对于每个文件，服务器计算SHA256哈希，并将其存储在一个名为相同的文件中，在一个隐藏的.index子目录中。此哈希用于确定自上次索引以来文件是否已被修改。
文件内容使用langchain/text_splitter中的MarkdownTextSplitter分割成块。
每个块的内容随后被添加到FAISS索引中，用于相似性搜索。
当服务器启动时，FAISS索引会自动初始化。它检查知识库文件的变化并相应地更新索引。

使用方法

服务器公开了两个工具：

list_knowledge_bases：列出可用的知识库。
retrieve_knowledge：根据查询从知识库中检索相似片段。如果指定了知识库，则仅搜索该知识库；否则，考虑所有可用的知识库。默认情况下，返回最多10个文档片段，其得分低于阈值2。可选地，可以通过threshold参数提供不同的阈值。

您可以使用MCP界面使用这些工具。

retrieve_knowledge工具使用FAISS索引来执行语义搜索。当服务器启动或知识库中的文件被修改时，索引会自动更新。

retrieve_knowledge工具的输出是一个Markdown格式化的字符串，具有以下结构：

## 语义搜索结果

**结果1：**

[最相似片段的内容]

**来源：**
```json
{
  "source": "[包含片段的文件路径]"
}
```

---

**结果2：**

[第二相似片段的内容]

**来源：**
```json
{
  "source": "[包含片段的文件路径]"
}
```

> **免责声明：**提供的结果可能并非全部相关。请交叉检查信息的相关性。

每个结果包括最相似片段的内容、源文件以及相似度分数。

故障排除与日志记录

设置LOG_FILE以捕获结构化日志（JSON-RPC流量继续使用stdout）。这在诊断MCP握手错误时特别有用，因为所有诊断消息都写入stderr和可选的日志文件。
创建或更新FAISS索引时出现权限错误会在控制台和日志文件中显示明确的消息。验证进程能否写入FAISS_INDEX_PATH和每个知识库内部的.index目录。
运行npm test以执行Jest套件（使用--runInBand序列化），该套件涵盖了日志器回退行为和FAISS权限处理。