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 来讨论修改内容。