嵌入 MCP 服务器
由 txtai 提供支持的模型上下文协议 (MCP) 服务器实现，通过标准化接口提供语义搜索、知识图谱功能和 AI 驱动的文本处理。
txtai 的强大功能：一体化嵌入数据库
该项目利用txtai ，这是一个用于 RAG 的一体化嵌入数据库，利用语义搜索、知识图谱构建和语言模型工作流。txtai 具有几个主要优势：
- 统一矢量数据库：在单一平台中整合矢量索引、图网络和关系数据库
- 语义搜索：根据含义而非仅仅根据关键词来查找信息
- 知识图谱集成：自动从数据中构建和查询知识图谱
- 便携式知识库：将整个知识库保存为压缩档案（.tar.gz），可以轻松共享和加载
- 可扩展的管道系统：通过统一的 API 处理文本、文档、音频、图像和视频
- 本地优先架构：在本地运行所有内容，无需将数据发送到外部服务
工作原理
该项目包含一个知识库构建工具和一个 MCP 服务器。知识库构建工具是一个用于创建和管理知识库的命令行界面。MCP 服务器提供了一个标准化的接口来访问知识库。
构建知识库并非必须使用知识库构建器工具。您可以随时使用 txtai 的编程接口，通过编写 Python 脚本或使用 Jupyter Notebook 来构建知识库。只要使用 txtai 构建的知识库，MCP 服务器就可以加载它。更棒的是，知识库可以是文件系统上的文件夹，也可以是导出的 .tar.gz 文件。只需将其提供给 MCP 服务器，它就会加载它。
1. 使用 kb_builder 构建知识库
kb_builder模块提供了用于创建和管理知识库的命令行界面：
- 处理来自各种来源的文档（文件、目录、JSON）
- 提取文本并创建嵌入
- 自动构建知识图谱
- 导出便携式知识库
请注意，它的功能可能有限，目前仅为方便起见而提供。
2. 启动 MCP 服务器
MCP 服务器提供了访问知识库的标准化接口：
- 语义搜索功能
- 知识图谱查询与可视化
- 文本处理管道（摘要、提取等）
- 完全符合模型上下文协议
安装
推荐：使用 Python 3.10+ 的 uv
为了获得最佳体验，我们建议将uv与 Python 3.10 或更高版本一起使用。这可以提供更好的依赖项管理并确保行为的一致性。
# Install uv if you don't have it already
pip install -U uv
# Create a virtual environment with Python 3.10 or newer
uv venv --python=3.10 # or 3.11, 3.12, etc.
# Activate the virtual environment (bash/zsh)
source .venv/bin/activate
# For fish shell
# source .venv/bin/activate.fish
# Install from PyPI
uv pip install kb-mcp-server
注意：我们将 transforms 固定到 4.49.0 版本，以避免在 4.50.0 及更新版本中出现有关transformers.agents.tools的弃用警告。如果您使用更新版本的 transforms，可能会看到这些警告，但它们不会影响功能。
使用 conda
# Create a new conda environment (optional)
conda create -n embedding-mcp python=3.10
conda activate embedding-mcp
# Install from PyPI
pip install kb-mcp-server
来自源
# Create a new conda environment
conda create -n embedding-mcp python=3.10
conda activate embedding-mcp
# Clone the repository
git clone https://github.com/Geeksfino/kb-mcp-server.git.git
cd kb-mcp-server
# Install dependencies
pip install -e .
使用 uv（更快的替代方案）
# Install uv if not already installed
pip install uv
# Create a new virtual environment
uv venv
source .venv/bin/activate
# Option 1: Install from PyPI
uv pip install kb-mcp-server
# Option 2: Install from source (for development)
uv pip install -e .
使用 uvx（无需安装）
uvx允许您直接从 PyPI 运行包而无需安装它们：
# Run the MCP server
uvx --from kb-mcp-server@0.3.0 kb-mcp-server --embeddings /path/to/knowledge_base
# Build a knowledge base
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/documents --config config.yml
# Search a knowledge base
uvx --from kb-mcp-server@0.3.0 kb-search /path/to/knowledge_base "Your search query"
命令行用法
建立知识库
您可以使用从 PyPI 安装的命令行工具、直接使用 Python 模块或方便的 shell 脚本：
使用 PyPI 安装的命令
# Build a knowledge base from documents
kb-build --input /path/to/documents --config config.yml
# Update an existing knowledge base with new documents
kb-build --input /path/to/new_documents --update
# Export a knowledge base for portability
kb-build --input /path/to/documents --export my_knowledge_base.tar.gz
# Search a knowledge base
kb-search /path/to/knowledge_base "What is machine learning?"
# Search with graph enhancement
kb-search /path/to/knowledge_base "What is machine learning?" --graph --limit 10
使用 uvx（无需安装）
# Build a knowledge base from documents
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/documents --config config.yml
# Update an existing knowledge base with new documents
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/new_documents --update
# Export a knowledge base for portability
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/documents --export my_knowledge_base.tar.gz
# Search a knowledge base
uvx --from kb-mcp-server@0.3.0 kb-search /path/to/knowledge_base "What is machine learning?"
# Search with graph enhancement
uvx --from kb-mcp-server@0.3.0 kb-search /path/to/knowledge_base "What is machine learning?" --graph --limit 10
使用 Python 模块
# Build a knowledge base from documents
python -m kb_builder build --input /path/to/documents --config config.yml
# Update an existing knowledge base with new documents
python -m kb_builder build --input /path/to/new_documents --update
# Export a knowledge base for portability
python -m kb_builder build --input /path/to/documents --export my_knowledge_base.tar.gz
使用便捷脚本
该存储库包含方便的包装脚本，可以更轻松地构建和搜索知识库：
# Build a knowledge base using a template configuration
./scripts/kb_build.sh /path/to/documents technical_docs
# Build using a custom configuration file
./scripts/kb_build.sh /path/to/documents /path/to/my_config.yml
# Update an existing knowledge base
./scripts/kb_build.sh /path/to/documents technical_docs --update
# Search a knowledge base
./scripts/kb_search.sh /path/to/knowledge_base "What is machine learning?"
# Search with graph enhancement
./scripts/kb_search.sh /path/to/knowledge_base "What is machine learning?" --graph
运行./scripts/kb_build.sh --help或./scripts/kb_search.sh --help获取更多选项。
启动 MCP 服务器
使用 PyPI 安装命令
# Start with a specific knowledge base folder
kb-mcp-server --embeddings /path/to/knowledge_base_folder
# Start with a given knowledge base archive
kb-mcp-server --embeddings /path/to/knowledge_base.tar.gz
使用 uvx（无需安装）
# Start with a specific knowledge base folder
uvx kb-mcp-server@0.2.6 --embeddings /path/to/knowledge_base_folder
# Start with a given knowledge base archive
uvx kb-mcp-server@0.2.6 --embeddings /path/to/knowledge_base.tar.gz
使用 Python 模块
# Start with a specific knowledge base folder
python -m txtai_mcp_server --embeddings /path/to/knowledge_base_folder
# Start with a given knowledge base archive
python -m txtai_mcp_server --embeddings /path/to/knowledge_base.tar.gz
MCP 服务器配置
MCP 服务器使用环境变量或命令行参数进行配置，而不是使用 YAML 文件。YAML 文件仅用于在知识库构建期间配置 txtai 组件。
配置 MCP 服务器的方法如下：
# Start the server with command-line arguments
kb-mcp-server --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000
# Or using uvx (no installation required)
uvx kb-mcp-server@0.2.6 --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000
# Or using the Python module
python -m txtai_mcp_server --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000
# Or use environment variables
export TXTAI_EMBEDDINGS=/path/to/knowledge_base
export MCP_SSE_HOST=0.0.0.0
export MCP_SSE_PORT=8000
python -m txtai_mcp_server
常用配置选项：
--embeddings ：知识库路径（必需）--host ：绑定到的主机地址（默认值：localhost）--port ：监听端口（默认值：8000）--transport ：要使用的传输，可以是“sse”或“stdio”（默认值：stdio）--enable-causal-boost ：启用因果提升功能以增强相关性评分--causal-config ：自定义因果提升配置 YAML 文件的路径
配置 LLM 客户端以使用 MCP 服务器
要配置 LLM 客户端使用 MCP 服务器，您需要创建一个 MCP 配置文件。以下是mcp_config.json示例：
直接使用服务器
如果您使用虚拟 Python 环境来安装服务器，则可以使用以下配置 - 请注意，如果您使用虚拟环境，像 Claude 这样的 MCP 主机将无法连接到服务器，您需要使用执行“pip install”或“uv pip install”的虚拟环境的 Python 可执行文件的绝对路径，例如
{
"mcpServers": {
"kb-server": {
"command": "/your/home/project/.venv/bin/kb-mcp-server",
"args": [
"--embeddings",
"/path/to/knowledge_base.tar.gz"
],
"cwd": "/path/to/working/directory"
}
}
}
使用系统默认的 Python
如果你使用系统默认的Python，则可以使用以下配置：
{
"rag-server": {
"command": "python3",
"args": [
"-m",
"txtai_mcp_server",
"--embeddings",
"/path/to/knowledge_base.tar.gz",
"--enable-causal-boost"
],
"cwd": "/path/to/working/directory"
}
}
或者，如果您正在使用 uvx，假设您已经通过“brew install uvx”等在系统中安装了 uvx，或者您已经安装了 uvx 并通过以下方式使其可全局访问：
# Create a symlink to /usr/local/bin (which is typically in the system PATH)
sudo ln -s /Users/cliang/.local/bin/uvx /usr/local/bin/uvx
这将创建一个从用户特定安装到系统范围位置的符号链接。对于像 Claude Desktop 这样的 macOS 应用程序，你可以通过创建或编辑 launchd 配置文件来修改系统范围的 PATH：
# Create a plist file to set environment variables for all GUI applications
sudo nano /Library/LaunchAgents/environment.plist
添加此内容：
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>my.startup</string>
<key>ProgramArguments</key>
<array>
<string>sh</string>
<string>-c</string>
<string>launchctl setenv PATH $PATH:/Users/cliang/.local/bin</string>
</array>
<key>RunAtLoad</key>
<true/>
</dict>
</plist>
然后加载它：
sudo launchctl load -w /Library/LaunchAgents/environment.plist
不过，您需要重新启动计算机才能使其生效。
{
"mcpServers": {
"kb-server": {
"command": "uvx",
"args": [
"kb-mcp-server@0.2.6",
"--embeddings", "/path/to/knowledge_base",
"--host", "localhost",
"--port", "8000"
],
"cwd": "/path/to/working/directory"
}
}
}
将此配置文件放置在 LLM 客户端可访问的位置，并配置客户端以使用它。具体配置步骤取决于您的 LLM 客户端。
高级知识库配置
使用 txtai 构建知识库需要一个 YAML 配置文件来控制嵌入过程的各个方面。此配置由kb_builder工具使用，而非 MCP 服务器本身。
可能需要调整分割/分块策略、嵌入模型和评分方法，以及配置图形构建、因果提升、混合搜索的权重等。
幸运的是，txtai 提供了强大的 YAML 配置系统，无需任何编码。以下是一个知识库构建的全面配置示例：
# Path to save/load embeddings index
path: ~/.txtai/embeddings
writable: true
# Content storage in SQLite
content:
path: sqlite:///~/.txtai/content.db
# Embeddings configuration
embeddings:
# Model settings
path: sentence-transformers/nli-mpnet-base-v2
backend: faiss
gpu: true
batch: 32
normalize: true
# Scoring settings
scoring: hybrid
hybridalpha: 0.75
# Pipeline configuration
pipeline:
workers: 2
queue: 100
timeout: 300
# Question-answering pipeline
extractor:
path: distilbert-base-cased-distilled-squad
maxlength: 512
minscore: 0.3
# Graph configuration
graph:
backend: sqlite
path: ~/.txtai/graph.db
similarity: 0.75 # Threshold for creating graph connections
limit: 10 # Maximum connections per node
配置示例
src/kb_builder/configs目录包含针对不同用例和存储后端的配置模板：
存储和后端配置
memory.yml ：内存向量（开发速度最快，无持久性）sqlite-faiss.yml ：用于内容的 SQLite + 用于向量的 FAISS（基于本地文件的持久性）postgres-pgvector.yml ：PostgreSQL + pgvector（生产就绪，具有完全持久性）
特定领域配置
base.yml ：基本配置模板code_repositories.yml ：针对代码存储库进行了优化data_science.yml ：为数据科学文档配置general_knowledge.yml ：通用知识库research_papers.yml ：针对学术论文进行了优化technical_docs.yml ：配置技术文档
您可以使用这些作为您自己的配置的起点：
python -m kb_builder build --input /path/to/documents --config src/kb_builder/configs/technical_docs.yml
# Or use a storage-specific configuration
python -m kb_builder build --input /path/to/documents --config src/kb_builder/configs/postgres-pgvector.yml
高级功能
知识图谱功能
MCP 服务器利用 txtai 的内置图形功能来提供强大的知识图谱功能：
- 自动图形构建：自动从文档构建知识图谱
- 图遍历：浏览相关概念和文档
- 路径寻找：发现不同信息之间的联系
- 社区检测：识别相关信息的集群
因果提升机制
MCP 服务器包含一个复杂的因果增强机制，通过识别和确定因果关系的优先级来增强搜索的相关性：
- 模式识别：检测查询和文档中的因果语言模式
- 多语言支持：根据检测到的查询语言自动应用适当的模式
- 可配置的提升乘数：不同类型的因果匹配可获得可定制的提升因子
- 增强相关性：解释因果关系的结果在搜索结果中优先显示
该机制通过呈现解释概念之间关系的内容，显著提升了对“为什么”和“如何”问题的回答。因果提升配置可通过 YAML 文件高度自定义，从而适应不同的领域和语言。
执照
MIT 许可证 - 详情请参阅许可证文件