MCP Jina Supabase Rag

🚀 MCP Jina Supabase RAG

這是一個輕量級且專注的MCP服務器，用於爬取文檔網站，並將其索引到Supabase，以實現檢索增強生成（RAG）功能。

🚀 快速開始

MCP Jina Supabase RAG 可助力你高效地爬取文檔網站並將其索引到 Supabase。以下是使用本項目的基本步驟：

1. 完成安裝所需的依賴和配置（詳見“📦 安裝指南”）。
2. 啟動 MCP 服務器（詳見“💻 使用示例”）。
3. 配置 MCP 客戶端，以便與服務器進行交互。
4. 運用工具函數開展文檔的爬取、索引和搜索操作（詳見“📚 詳細文檔”）。

✨ 主要特性

• 智能URL發現：優先嚐試使用 sitemap.xml，若不可用則採用 Crawl4AI 遞歸發現機制。
• 混合內容提取：藉助 Jina AI 實現快速內容提取，以 Crawl4AI 作為複雜頁面提取的備用方案。
• 多項目支持：可將多個文檔網站索引到不同的 Supabase 項目中。
• 高效分塊：具備智能文本分塊功能，支持自定義塊大小和重疊度。
• 向量嵌入：將 OpenAI 嵌入向量存儲於 Supabase 的 pgvector 中。

📦 安裝指南

前提條件

• Python 3.12 及以上版本
• Supabase 賬戶
• OpenAI API 密鑰
• Jina AI API 密鑰（可選，但推薦）

安裝步驟

1. 克隆倉庫：

git clone https://github.com/yourusername/mcp-jina-supabase-rag.git
cd mcp-jina-supabase-rag

2. 安裝依賴：

# 使用 uv（推薦）
uv venv
source .venv/bin/activate  # 若為 Windows 系統，使用 .venv\Scripts\activate
uv pip install -e .

# 或者使用 pip
pip install -e .

3. 配置 Supabase 數據庫：

# 在 Supabase SQL 編輯器中運行 supabase_schema.sql 中的 SQL 語句

4. 配置環境變量：

cp .env.example .env
# 在 .env 文件中填寫你的憑證信息

💻 使用示例

啟動 MCP 服務器

# SSE 傳輸（推薦用於遠程連接）
python src/main.py

# 服務器將在 http://localhost:8052/sse 啟動

配置 MCP 客戶端

Claude 代碼配置

claude mcp add --transport sse jina-supabase http://localhost:8052/sse

Cursor / Claude 桌面端配置

{
  "mcpServers": {
    "jina-supabase": {
      "transport": "sse",
      "url": "http://localhost:8052/sse"
    }
  }
}

斜槓命令

創建 /home/marty/.claude/commands/jina.md 文件：

---
allowed-tools: mcp__jina-supabase
argument-hint: <url_pattern> <project_name>
description: 爬取文檔並索引到 Supabase RAG
---

# 將文檔索引到 Supabase

使用 jina-supabase MCP 服務器爬取並索引文檔。

參數：
- $1: URL 模式（例如，https://docs.example.com/*）
- $2: 用於隔離的項目名稱

示例：
/jina https://docs.anthropic.com/claude/* anthropic-docs

📚 詳細文檔

crawl_and_index

爬取文檔網站並將其索引到 Supabase。

參數：

• url_pattern（字符串）：要爬取的 URL 或模式
• project_name（字符串）：用於隔離的項目標識符
• discovery_method（字符串，可選）：auto、sitemap 或 crawl
• extraction_method（字符串，可選）：auto、jina 或 crawl4ai

示例：

await crawl_and_index(
    url_pattern="https://docs.supabase.com/docs/*",
    project_name="supabase-docs",
    discovery_method="auto",
    extraction_method="jina"
)

list_projects

列出所有已索引的項目。

返回值： 包含項目名稱和文檔計數的列表

search_documents

使用向量相似度搜索已索引的文檔。

參數：

• query（字符串）：搜索查詢
• project_name（字符串，可選）：按項目進行過濾
• limit（整數，可選）：最大結果數（默認值：5）

示例：

results = await search_documents(
    query="How do I set up authentication?",
    project_name="supabase-docs",
    limit=10
)

🔧 技術細節

架構

┌─────────────────────────────────────────────────────────────┐
│                    MCP Server Tools                         │
├─────────────────────────────────────────────────────────────┤
│  1. crawl_and_index(url_pattern, project_name)             │
│  2. list_projects()                                         │
│  3. search_documents(query, project_name, limit)           │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   Discovery Layer                           │
├─────────────────────────────────────────────────────────────┤
│  • Try sitemap.xml (fast)                                   │
│  • Try common doc patterns                                  │
│  • Crawl4AI recursive discovery (fallback)                  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                  Extraction Layer                           │
├─────────────────────────────────────────────────────────────┤
│  • Jina AI Reader API (primary, fast)                       │
│  • Crawl4AI (fallback for complex pages)                    │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              Chunking & Embedding Layer                     │
├─────────────────────────────────────────────────────────────┤
│  • Smart text chunking                                      │
│  • OpenAI embeddings (text-embedding-3-small)               │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   Supabase Storage                          │
├─────────────────────────────────────────────────────────────┤
│  • pgvector for similarity search                           │
│  • Project isolation via source column                      │
└─────────────────────────────────────────────────────────────┘

配置選項

發現方法

• auto：優先嚐試使用 sitemap，若不可用則進行爬取。
• sitemap：僅使用 sitemap.xml（速度快，但若無 sitemap 則會失敗）。
• crawl：僅使用 Crawl4AI 遞歸發現機制（速度慢，但全面）。

提取方法

• auto：對於批量提取（超過 10 個 URL）使用 Jina，否則使用 Crawl4AI。
• jina：使用 Jina AI Reader API（速度快，需要 API 密鑰）。
• crawl4ai：使用 Crawl4AI 瀏覽器自動化（速度慢，無需 API 密鑰）。

開發相關

# 安裝開發依賴
uv pip install -e ".[dev]"

# 運行測試
pytest

# 格式化代碼
black src/

# 代碼檢查
ruff check src/

與 mcp-crawl4ai-rag 的差異

📄 許可證

本項目採用 MIT 許可證。

貢獻說明

歡迎貢獻代碼！請先創建一個 issue 來討論修改內容。