verse-rag
Local-first RAG MCP Server for Verse / UEFN Documentation
Fully air-gapped · Ollama embeddings · pgvector · Model Context Protocol
概述
诗歌抹布 生产准备好了吗 模型上下文协议(MCP) 服务器,使AI编码助手能够抓取、索引和语义搜索文档——完全在本地基础设施上。
最初分叉自 coleam00/mcp-crawl4ai-rag,这个fork是对存储层和嵌入层的彻底重写:
| 上游 | 这个叉子 |
|---|---|
| OpenAI嵌入 | Ollama(qwen3-embedding:8b,4096调光) |
| Supabase云 | 自托管pgvector+PostgREST |
supabase-py 客户端 |
直接 httpx 调用PostgREST |
| 阻止嵌入+存储 | 即发即弃后台任务 |
结果是一个完全离线运行的堆栈,没有外部API调用,没有云依赖,也没有API成本。
建筑```
Claude Code / AI Client
│ SSE (port 8051)
▼
┌─────────────┐
│ MCP Server │ crawl4ai_mcp.py — FastMCP + Crawl4AI
└──────┬──────┘
│ httpx
▼
┌──────────────┐ ┌─────────────────┐
│ PostgREST │──────▶│ PostgreSQL 16 │
│ (REST API) │ │ + pgvector │
└──────────────┘ └─────────────────┘
│
│ /api/embed
▼
┌─────────────┐
│ Ollama │ qwen3-embedding:8b (4096 dims)
└─────────────┘
**服务(Docker Compose):**
|容器|图像|角色|
|---|---|---|
| `verse-rag-db` | `pgvector/pgvector:pg16` |矢量存储|
| `verse-rag-postgrest` | `postgrest/postgrest:v12.2.0` |PostgreSQL上的REST API|
| `verse-rag-mcp` | `verse-rag:latest` (本地构建)|MCP服务器|
Ollama在主机上(或在另一个容器中)作为单独的服务运行——这个堆栈通过 `ollama` Docker网络。
______________________________________________________________________
## MCP工具
|工具|说明|
|---|---|
| `crawl_single_page` |抓取一个URL并将其排队以进行索引|
| `smart_crawl_url` |根据内部链接递归抓取网站|
| `crawl_verse_docs` |抓取Verse/UEFN官方文档的快捷方式|
| `perform_rag_query` |语义(或混合)搜索,可选源过滤|
| `get_available_sources` |列出数据库中的所有索引源|
所有抓取工具都会立即返回——嵌入和存储在后台任务中运行,因此MCP调用永远不会阻止等待Ollama。
______________________________________________________________________
## 先决条件
- **码头工人** 和 **Docker Compose**
- **奥拉玛** 跑步与 `qwen3-embedding:8b` 拉:```bash
ollama pull qwen3-embedding:8b
- 三个外部Docker网络:
mcps,nginx, `ollama````bash
docker network create mcps
docker network create nginx
docker network create ollama
______________________________________________________________________
## 快速开始
### 1.克隆```bash
git clone https://github.com/berry-13/verse-rag.git
cd verse-rag
2.构建MCP镜像```bash
docker build -f docker/Dockerfile -t verse-rag:latest .
### 3.启动堆栈```bash
docker compose -f docker/compose.yml up -d
这将开始:
- PostgreSQL与pgvector(
verse-rag-db) - PostgREST自动REST层(
verse-rag-postgrest) - 端口上的MCP服务器
8051(verse-rag-mcp)
4.连接您的MCP客户端
克劳德代码:```bash
claude mcp add-json verse-rag '{"type":"sse","url":"http://localhost:8051/sse"}' --scope user
**任何SSE兼容客户端:**```json
{
"mcpServers": {
"verse-rag": {
"transport": "sse",
"url": "http://localhost:8051/sse"
}
}
}
配置
所有配置都是通过环境变量进行的。中的默认值 docker/compose.yml 已准备好用于标准本地设置。
| 变量 | 默认值 | 描述 |
|---|---|---|
OLLAMA_BASE_URL |
http://ollama:11434 |
奥拉马终点 |
EMBEDDING_MODEL |
qwen3-embedding:8b |
Ollama嵌入模型 |
SUPABASE_URL |
http://postgrest:3000 |
PostgREST端点 |
SUPABASE_SERVICE_KEY |
(JWT在composity.yml中) | PostgREST JWT令牌 |
USE_HYBRID_SEARCH |
true |
结合矢量+全文搜索 |
USE_RERANKING |
true |
交叉编码器对结果进行重新排序 |
HOST |
0.0.0.0 |
MCP服务器绑定地址 |
PORT |
8051 |
MCP服务器端口 |
TRANSPORT |
sse |
MCP传输(sse 或 stdio) |
MAX_CRAWL_DEPTH |
3 |
最大递归爬行深度 |
MAX_CONCURRENT_CRAWLS |
5 |
并行爬行工人 |
RAG战略
混合搜索(USE_HYBRID_SEARCH=true)
将pgvector余弦相似度与PostgreSQL全文搜索相结合(tsvector).结果以加权组合的形式评分(0.7 矢量+ 0.3 文本)使用a FULL OUTER JOIN 在 hybrid_search_crawled_pages SQL函数。
最适合技术文档,其中精确的术语匹配(函数名、关键字)与语义相似性都很重要。
重新排名(USE_RERANKING=true)
初始检索后,应用交叉编码器模型(cross-encoder/ms-marco-MiniLM-L-6-v2)根据原始查询对结果进行重新评分和排序。在CPU上本地运行,无需API成本。增加约100-200毫秒的查询延迟,以换取更好的结果排序。
数据库模式
这 init.sql 创建:
crawled_pages--主桌vector(4096)嵌入(匹配qwen3-embedding:8b)、来源标签和aUNIQUE(url, chunk_number)幂等扰动的约束match_crawled_pages()--向量相似性搜索函数hybrid_search_crawled_pages()--组合式矢量+全文搜索功能- GIN指数
content用于全文搜索 - B-树指数
source_id用于源过滤
> 注:
ivfflat/hnsw 索引限制为2000个维度。在4096个dims时,查询使用顺序扫描——这对于文档规模的数据集来说是可以接受的。
业绩说明
- 批量嵌入: 页面中的所有块都嵌入在一个单独的块中
/api/embed打电话给Ollama - 批量追加销售: 所有记录都写在一个单独的
POST使用以下方式发布gRESTPrefer: resolution=merge-duplicates - 信号量: 嵌入请求通过以下方式序列化
asyncio.Semaphore(1)因为Ollama一次处理一个嵌入作业 - 即发即弃: 爬行工具立即返回;背景
asyncio.Task处理嵌入+存储。通过以下方式监控进度:```bash
docker logs verse-rag-mcp -f
______________________________________________________________________
## 发展
### 代码更改后重建
只有最后一个Docker层(`COPY src/`)在源代码更改时无效,因此重建很快:```bash
docker build -f docker/Dockerfile -t verse-rag:latest . && \
docker compose -f docker/compose.yml up -d mcp
项目结构```
verse-rag/
├── src/
│ ├── crawl4ai_mcp.py # MCP server, tool definitions, lifespan
│ └── utils.py # Embeddings, chunking, PostgREST client
├── docker/
│ ├── Dockerfile # Build definition
│ ├── compose.yml # Full stack definition
│ └── init.sql # PostgreSQL schema + functions
├── knowledge_graphs/ # Optional Neo4j hallucination detection
└── pyproject.toml
______________________________________________________________________
## 故障排除
**CUDA不可用/Olama SIGABRT**
GPU可能在 `Exclusive_Process` 模式。重置它:```bash
sudo nvidia-smi -c 0
此操作在重新启动时重置,必须在驱动程序重新加载后重新应用。
容器重启后MCP工具挂起
Claude Code缓存SSE会话ID。重新启动MCP容器后,在使用任何工具之前,重新启动Claude Code以清除过时的会话。
嵌入无声地失败
检查后台任务输出:bash
docker logs verse-rag-mcp -f | grep -E "✅|❌"
许可证
麻省理工学院
