AI导哈

文档向量化与语义搜索服务器

RAG MCP Server是一个基于检索增强生成（RAG）的文档向量化和语义搜索服务器，支持文档自动分块、向量化存储和自然语言查询。

  • by bjeremy23
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 bjeremy23/rag-server

使用说明

RAG MCP服务器

使用RAG（检索增强生成）进行文档矢量化和语义搜索的模型上下文协议（MCP）服务器。

特性

  • 文件摄入：添加具有自动分块和矢量化功能的文档
  • 语义搜索：使用自然语言查询查找相关信息
  • 元数据支持：使用自定义元数据标记文档并过滤搜索
  • 持久化存储：基于ChromaDB的具有持久性的矢量存储
  • 高效嵌入：使用句子变换器进行快速本地嵌入

提供的工具

1. add_file

从文件系统中添加并矢量化文件以进行RAG搜索。

参数：

  • file_path （字符串，必填）： 完全绝对路径 到文件系统上的文件
  • doc_id （字符串，可选）：文档的唯一标识符（默认为文件名）
  • metadata （对象，可选）：文档元数据（标题、作者、来源、日期）

重要要求：

  • 必须使用完整的绝对路径：文件路径必须完整（例如。， /localdata/brownjer/docs/readme.txt)
  • 必须装载目录：文件的父目录必须通过MCP配置JSON作为卷挂载到Docker容器中
  • 容器用户必须能够读取该文件

例子：

{
  "file_path": "/localdata/brownjer/documents/python_guide.txt",
  "doc_id": "python_intro",
  "metadata": {
    "title": "Introduction to Python",
    "author": "John Doe"
  }
}

MCP配置要求：

对于 add_file 要访问文件系统，您必须在MCP配置中挂载相应的目录。在 mcp.json:

{
  "mcpServers": {
    "rag": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/localdata/brownjer:/localdata/brownjer:ro",
        "-v", "/localdata/brownjer/.rag_data:/data",
        "rag-server:latest"
      ],
      "disabled": false
    }
  }
}

备注:

  • 这 --rm 标志在容器退出时自动删除容器
  • 这 :ro 建议源目录使用（只读）标志，以防止意外修改
  • 每个jibberish会话都会创建新的容器

2. search

在所有矢量化文档中执行语义搜索。

参数：

  • query （字符串，必填）：搜索查询
  • n_results （整数，可选）：要返回的结果数（默认值：5，最大值：20）
  • filter_metadata （object，可选）：按元数据过滤（例如。， {"author": "John Doe"})

例子：

{
  "query": "How do I use Python lists?",
  "n_results": 3
}

3. delete_document

从矢量数据库中删除文档及其所有块。

参数：

  • doc_id （字符串，必填）：要删除的文档ID

例子：

{
  "doc_id": "python_intro"
}

4. list_documents

列出矢量数据库中的所有文档及其元数据。

参数： 无

安装

选项1:Docker（推荐）

使用GitHub容器注册表中的预构建映像

最简单的开始方法是使用预构建的映像：

# In your ~/.jbrsh-mcp-servers.json or docker run command, use:
ghcr.io/bjeremy23/rag-server:latest

MCP配置示例：

{
  "rag": {
    "enabled": true,
    "command": "docker",
    "args": [
      "run", "-i", "--rm",
      "-v", "/path/to/your/data:/localdata:ro",
      "-v", "/path/to/your/data/.rag_data:/data",
      "ghcr.io/bjeremy23/rag-server:latest"
    ]
  }
}

如果您无法提取图像 （例如，由于网络限制或VPN策略），请在本地构建。

在当地建立形象

如果你没有从GitHub容器注册表中提取的权限，或者更喜欢在本地构建：

git clone https://github.com/bjeremy23/rag-server.git
cd rag-server
docker build -t rag-server:latest .

然后使用 rag-server:latest 在MCP配置中：

{
  "rag": {
    "enabled": true,
    "command": "docker",
    "args": [
      "run", "-i", "--rm",
      "-v", "/path/to/your/data:/localdata:ro",
      "-v", "/path/to/your/data/.rag_data:/data",
      "rag-server:latest"
    ]
  }
}

带本地模型缓存的Docker（离线环境）

如果你的Docker容器内没有互联网接入，或者想避免在每次容器启动时重新下载模型，你可以将嵌入模型预下载到一个持久挂载的目录中。

脱机安装设置

步骤1：在离线主机上创建数据目录

mkdir -p /path/to/your/data/.rag_data

替换 /path/to/your/data/ 使用您要存储模型缓存的实际路径。

步骤2：在可上网的机器上下载模型

在任何可以上网的机器上，下载Hugging Face模型：

mkdir -p ~/rag_model_cache
TRANSFORMERS_CACHE=~/rag_model_cache python3 << 'EOF'
from sentence_transformers import SentenceTransformer
print("Downloading embedding model...")
model = SentenceTransformer('all-MiniLM-L6-v2')
print(f"✓ Model downloaded")
EOF

步骤3：将模型转移到离线主机

将下载的模型从连接互联网的计算机复制到离线主机：

scp -r ~/rag_model_cache/* username@offline_host:/path/to/your/data/.rag_data/

替换：

  • username 使用您的SSH用户名
  • offline_host 使用您的实际主机名或IP地址
  • /path/to/your/data/ 使用您在步骤1中创建的相同路径

例子：

scp -r ~/rag_model_cache/* brownjer@192.168.1.100:/data/models/.rag_data/

步骤4：在MCP配置中挂载目录

在您的离线主机上 ~/.jbrsh-mcp-servers.json，配置RAG服务器以将此目录装载为 /data:

{
  "rag": {
    "enabled": true,
    "command": "docker",
    "args": [
      "run", "-i", "--rm",
      "-v", "/path/to/your/data:/localdata:ro",
      "-v", "/path/to/your/data/.rag_data:/data",
      "rag-server:latest"
    ],
    "description": "RAG server for document vectorization and semantic search",
    "tool_prefix": "rag"
  }
}

替换 /path/to/your/data/ 使用脱机主机上的实际目录路径。

它是如何工作的：

  • 模型文件存储在 /path/to/your/data/.rag_data 在您的主机上
  • 当容器运行时，此目录被挂载在 /data 集装箱内
  • 服务器在装载的卷中找到预下载的模型并直接使用它
  • 集装箱内不需要互联网连接
  • 模型缓存在容器重新启动后仍然存在

优点：

  • 完全离线工作
  • 无重复模型下载
  • 更快的容器启动（型号已可用）
  • 可以设置一次并无限期重复使用

选项2：本地Python

安装依赖项：

pip install -r requirements.txt

配置

Jibberish集成

添加到 ~/.jbrsh-mcp-servers.json:

{
  "rag": {
    "enabled": true,
    "command": "docker",
    "args": [
      "run",
      "-i",
      "--rm",
      "-v", "`/path/to/your/data/:`/path/to/your/data/:ro",
      "-v", "`/path/to/your/data/.rag_data:/data",
      "rag-server:latest"
    ],
    "description": "RAG server for document vectorization and semantic search",
    "tool_prefix": "rag"
  }
}

或者对于本地Python安装：

{
  "rag": {
    "enabled": true,
    "command": "python",
    "args": [
      "`/path/to/your/rag-server/mcp_rag_server.py"
    ],
    "env": {
      "RAG_DATA_DIR": "`/path/to/your/data/.rag_data"
    },
    "description": "RAG server for document vectorization and semantic search",
    "tool_prefix": "rag"
  }
}

用法示例

从文件系统添加文件

# Using jibberish with MCP - must use full absolute path
?add file /localdata/brownjer/documents/kubernetes-guide.txt to the RAG database

# With custom document ID and metadata
?add file /localdata/brownjer/notes/python-tutorial.md with id "python_basics" to the RAG database

重要：包含文件的目录（例如。， /localdata/brownjer/documents/)必须安装在Docker容器配置中。

搜索文档

?search for information about container orchestration

列出所有文档

?list all documents in the RAG database

删除文档

?delete document with id "k8s_intro"

数据存储

文档以持久方式存储在ChromaDB中：

  • 码头工人: /data 卷（映射到主机目录）
  • 本地: $RAG_DATA_DIR 环境变量（默认值： /tmp/rag_data)

技术细节

  • 嵌入模型: all-MiniLM-L6-v2 （384个维度）
  • 分块策略：递归字符分割，500个字符块，50个字符重叠
  • 矢量数据库：具有持久存储的ChromaDB
  • 相似性度量：余弦相似性

故障排除

问题：服务器无法启动

  • 检查Docker日志： docker logs <container_id>
  • 验证数据目录权限

问题：搜索不返回任何结果

  • 确保文件已添加 list_documents
  • 尝试增加 n_results

问题：嵌入生成缓慢

  • 第一次运行下载嵌入模型（~80MB）
  • 后续运行使用缓存模型

相关 MCP