Kb MCP Server

嵌入MCP服务器

由txtai驱动的模型上下文协议（MCP）服务器实现，通过标准化接口提供语义搜索、知识图功能和AI驱动的文本处理。

txtai的力量：多功能嵌入式数据库

该项目利用 txtai，一个用于RAG的一体化嵌入数据库，利用语义搜索、知识图构建和语言模型工作流。txtai提供了几个关键优势：

• 统一矢量数据库：在单个平台中组合向量索引、图网络和关系数据库
• 语义搜索：根据含义查找信息，而不仅仅是关键字
• 知识图谱集成：根据您的数据自动构建和查询知识图
• 便携式知识库：将整个知识库保存为压缩档案（.tar.gz），以便轻松共享和加载
• 可扩展管道系统：通过统一的API处理文本、文档、音频、图像和视频
• 地方第一建筑：在本地运行所有内容，而不向外部服务发送数据

运作原理

该项目包含一个知识库构建工具和一个MCP服务器。知识库构建工具是一个用于创建和管理知识库的命令行界面。MCP服务器提供了一个标准化的接口来访问知识库。

不需要使用知识库构建工具来构建知识库。您始终可以通过编写Python脚本，甚至使用jupyter笔记本，使用txtai的编程接口构建知识库。只要使用txtai构建知识库，MCP服务器就可以加载它。更好的是，知识库可以是文件系统上的文件夹或导出的.tar.gz文件。只需将其交给MCP服务器，它就会加载它。

1.使用kb_builder构建知识库

这 kb_builder 模块提供了一个用于创建和管理知识库的命令行界面：

• 处理来自不同来源的文档（文件、目录、JSON）
• 提取文本并创建嵌入
• 自动构建知识图谱
• 导出便携式知识库

请注意，它的功能可能有限，目前仅为方便起见而提供。

2.启动MCP服务器

MCP服务器提供了一个标准化的接口来访问知识库：

• 语义搜索功能
• 知识图查询与可视化
• 文本处理管道（摘要、提取等）
• 完全符合模型上下文协议

安装

推荐：在Python 3.10中使用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

备注：我们将变压器固定到4.49.0版本，以避免有关以下内容的弃用警告 transformers.agents.tools 出现在版本4.50.0及更高版本中。如果您使用较新版本的变压器，您可能会看到这些警告，但它们不会影响功能。

使用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 .

使用紫外线（更快的替代品）

# 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 Installed命令

# 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主机将无法连接到服务器，你需要使用虚拟环境的Python可执行文件的绝对路径，例如“pip安装”或“uv pip安装”

{
  "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

添加此内容：

  Label
  my.startup
  ProgramArguments
  
    sh
    -c
    launchctl setenv PATH $PATH:/Users/cliang/.local/bin
  
  RunAtLoad
  

然后加载它：

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许可证-有关详细信息，请参阅许可证文件