MCP Kbdb

🚀 rag - mcp：一个过度设计的检索系统

rag - mcp 是一个旨在回答古老问题的项目：“如果我们把一个原本不错的想法——检索增强生成，变得极其复杂，使其成为我们自负的象征，会怎样？” 这是一个模型上下文协议（MCP）服务器，它像嗑了药的游击手一样处理文本嵌入，使用 PostgreSQL 和 pgvector 扩展，说实话，谁还需要简单性呢？

这个项目是为真正的 “怪人” 准备的，那些看到问题会想 “我本可以用一个简单的脚本解决，但如果我构建一个由相互关联的部分组成的复杂系统，维护起来会是一场噩梦，那会怎样？” 的人。你们就是我的 “同道中人”。

🚀 快速开始

准备工作

• 安装 Python 3.x 版本（能正常运行即可）。
• 安装 PostgreSQL 并启用 pgvector 扩展。若不知如何操作，请自行谷歌搜索。

安装步骤

1. 克隆仓库：

git clone [仓库地址]

2. 安装 Python 依赖：

pip install -r requirements.txt

3. 配置数据库：连接到你的 PostgreSQL 实例，运行 create_tables.pgsql 脚本，它会创建所需的表和用于快速向量搜索的 HNSW 索引。
4. 设置环境变量：创建 .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)

📚 详细文档

系统架构

这是一个复杂而有序的系统，其架构如下：

1. 服务器 (rag_mcp_server.py)：这是整个系统的核心，负责处理传入的请求、与数据库通信并保持稳定运行。
2. 数据库 (postgresql + pgvector)：用于存储所有文本及其对应的向量嵌入。create_tables.pgsql 脚本定义了整个数据库架构，包括 documents、document_chunks 和 embeddings 表，它们相互关联，结构合理。
3. 嵌入引擎（OpenAI 兼容）：将文本转换为向量。服务器会调用与 OpenAI 兼容的 API 来生成嵌入向量，你可以提供自己的 API 端点，使用任何自定义模型。
4. 工具：服务器将搜索模态作为 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 框架实现了请求处理、数据库交互和搜索功能。

📄 许可证

本项目按 “原样” 提供，不提供任何明示或暗示的保证。若使用本项目导致你的计算机出现问题，责任自负。你选择了这种 “复杂” 的生活。