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 框架實現了請求處理、數據庫交互和搜索功能。

📄 許可證

本項目按 “原樣” 提供，不提供任何明示或暗示的保證。若使用本項目導致你的計算機出現問題，責任自負。你選擇了這種 “複雜” 的生活。