🚀 rag - mcp：一个过度设计的检索系统
rag - mcp 是一个旨在回答古老问题的项目：“如果我们把一个原本不错的想法——检索增强生成，变得极其复杂，使其成为我们自负的象征，会怎样？” 这是一个模型上下文协议（MCP）服务器，它像嗑了药的游击手一样处理文本嵌入，使用 PostgreSQL 和 pgvector 扩展，说实话，谁还需要简单性呢？
这个项目是为真正的 “怪人” 准备的，那些看到问题会想 “我本可以用一个简单的脚本解决，但如果我构建一个由相互关联的部分组成的复杂系统，维护起来会是一场噩梦，那会怎样？” 的人。你们就是我的 “同道中人”。
🚀 快速开始
准备工作
- 安装 Python 3.x 版本（能正常运行即可）。
- 安装 PostgreSQL 并启用
pgvector扩展。若不知如何操作，请自行谷歌搜索。
安装步骤
- 克隆仓库：
git clone [仓库地址]
- 安装 Python 依赖：
pip install -r requirements.txt
- 配置数据库：连接到你的 PostgreSQL 实例，运行
create_tables.pgsql脚本，它会创建所需的表和用于快速向量搜索的 HNSW 索引。 - 设置环境变量：创建
.env文件或直接设置环境变量，内容如下：
# 数据库相关
rm_db_host=localhost
rm_db_port=5432
rm_db_name=your_db_name
rm_db_user=your_db_user
rm_db_password=your_super_secret_password
# 嵌入模型相关
rm_openai_api_key=your_api_key
rm_openai_endpoint=your_model_endpoint_url
启动服务
python rag_mcp_server.py
若服务未崩溃，它将开始监听并向外界暴露 MCP 工具。你可以从任何 MCP 客户端调用 search_style、search_qa 和 search_semantic_similarity 等工具。
客户端连接
若你使用 VSCode 中的 AI 助手或 Claude 桌面版等，需要告知它们如何找到我们的服务器。你可能需要编辑一些 JSON 设置文件，找到 mcpServers 部分并添加如下内容：
{
"mcpServers": {
"RAG - MCP Knoledge Base Server": {
"command": "uv",
"args": [
"run",
"--with",
"fastmcp",
"fastmcp",
"run",
"/location/of/the/script/rag_mcp_server.py:mcp"
],
"env": {
"RM_DB_HOST": "localhost",
"RM_DB_PORT": "5432",
"RM_DB_NAME": "your_db_name",
"RM_DB_USER": "your_db_user",
"RM_DB_PASSWORD": "your_super_secret_password",
"RM_OPENAI_API_KEY": "your_api_key",
"RM_OPENAI_ENDPOINT": "your_model_endpoint_url"
},
"transport": "stdio",
"type": null,
"cwd": null,
"timeout": null,
"description": null,
"icon": null,
"authentication": null
}
}
}
请将 /location/of/the/script/rag_mcp_server.py:mcp 替换为实际的脚本路径，并填写 env 中的密钥信息。
✨ 主要特性
搜索模态多样
rag - mcp 是一个 Python 服务器，提供了一套用于搜索文本知识库的工具。它拥有多种搜索模态，每种模态就像不同口味的搜索方式，针对特定任务进行了优化：
- 语义搜索：当你想找到与查询 “氛围” 相符的内容时使用。
- 问答搜索：你提出问题，它假装能给出答案，经典实用。
- 风格搜索：找到 “感觉” 相似的内容，就像文本的品酒师，既做作又实用。
基于 fastmcp 框架
该系统基于 fastmcp 框架构建，这意味着你可以通过其他 AI 代理与之交互，形成一个荒谬且自引用的代码循环。
📦 安装指南
克隆仓库
git clone [仓库地址]
安装依赖
pip install -r requirements.txt
数据库设置
运行 create_tables.pgsql 脚本创建数据库表和索引：
-- 运行 create_tables.pgsql 脚本
psql -U your_user -d your_database -f create_tables.pgsql
环境变量设置
创建 .env 文件并设置以下环境变量：
# 数据库相关
rm_db_host=localhost
rm_db_port=5432
rm_db_name=your_db_name
rm_db_user=your_db_user
rm_db_password=your_super_secret_password
# 嵌入模型相关
rm_openai_api_key=your_api_key
rm_openai_endpoint=your_model_endpoint_url
💻 使用示例
基础用法
启动服务器：
python rag_mcp_server.py
从 MCP 客户端调用搜索工具：
# 假设存在一个 MCP 客户端类
from mcp_client import MCPClient
client = MCPClient()
result = client.call('search_semantic_similarity', query='your_query')
print(result)
高级用法
若要使用不同的搜索模态，可根据需求调用相应的工具：
# 调用问答搜索
result = client.call('search_qa', question='your_question')
print(result)
# 调用风格搜索
result = client.call('search_style', style='your_style')
print(result)
📚 详细文档
系统架构
这是一个复杂而有序的系统，其架构如下：
- 服务器 (
rag_mcp_server.py)：这是整个系统的核心，负责处理传入的请求、与数据库通信并保持稳定运行。 - 数据库 (
postgresql+pgvector)：用于存储所有文本及其对应的向量嵌入。create_tables.pgsql脚本定义了整个数据库架构，包括documents、document_chunks和embeddings表，它们相互关联，结构合理。 - 嵌入引擎（OpenAI 兼容）：将文本转换为向量。服务器会调用与 OpenAI 兼容的 API 来生成嵌入向量，你可以提供自己的 API 端点，使用任何自定义模型。
- 工具：服务器将搜索模态作为 MCP 工具暴露出来，目前有
search_semantic_similarity、search_qa和search_style等工具。
系统扩展
你可以轻松扩展这个系统，添加自己的搜索模态。详细的操作指南请参考 manual.md，它会指导你如何添加新的模型、任务和工具函数。
🔧 技术细节
数据库设计
数据库使用 PostgreSQL 并结合 pgvector 扩展，通过 create_tables.pgsql 脚本创建了 documents、document_chunks 和 embeddings 表，这些表通过外键关联，用于存储文本及其向量嵌入。使用 HNSW 索引加速向量搜索。
嵌入生成
服务器调用 OpenAI 兼容的 API 生成文本的向量嵌入，你可以根据需要配置不同的 API 端点和密钥。
服务器实现
rag_mcp_server.py 脚本使用 Python 编写，基于 fastmcp 框架实现了请求处理、数据库交互和搜索功能。
📄 许可证
本项目按 “原样” 提供，不提供任何明示或暗示的保证。若使用本项目导致你的计算机出现问题，责任自负。你选择了这种 “复杂” 的生活。