使用说明

RAG MCP服务器

生产准备就绪 检索增强生成（RAG） 服务器实现 模型上下文协议（MCP）。专为与Cline等人工智能助手无缝集成而构建，为您的文档提供强大的语义搜索功能。

✨ 特性

🔍 语义搜索：使用具有向量相似性的自然语言查询文档
🌐 网站索引：自动抓取和索引整个网站
🚀 双重嵌入支持：在本地（Xenova变压器）或OpenAI嵌入之间进行选择
🐳 Docker就绪：使用PostgreSQL+pgvector和Redis完成Docker Compose设置
📊 健康监测：内置健康检查和指标端点
🔄 批量操作：高效的批量文档处理
💾 Redis缓存：使用智能缓存快速查询结果
🛡️ 生产等级：优雅的关机、错误处理和全面的日志记录

🏗️ 建筑

┌─────────────┐
│   Cline AI  │
└──────┬──────┘
       │ MCP Protocol (stdio)
       ↓
┌─────────────────────────┐
│   RAG MCP Server        │
│  - Query Handler        │
│  - Document Manager     │
│  - Website Crawler      │
└──────┬──────────────────┘
       │
       ├──→ PostgreSQL + pgvector (Vector DB)
       ├──→ Redis (Cache Layer)
       └──→ Embedding Service (Local/OpenAI)

🚀 快速开始

使用Docker（推荐）

克隆和设置:

git clone <your-repo-url>
cd rag-mcp-server
cp .env.example .env

配置环境:

编辑 .env 并设置您的偏好：

EMBEDDING_PROVIDER=local  # or 'openai'
OPENAI_API_KEY=sk-...     # only if using OpenAI

启动服务:
```
npm run docker:up
```
验证健康状况:
```
curl http://localhost:3000/health
```

地方发展

先决条件:
- Node.js 20+
- PostgreSQL 16与pgvector
- Redis 7+
安装依赖项:
```
npm install
```
设置数据库:
```
psql -U postgres -f docker/init.sql
```

配置环境:

cp .env.example .env
# Edit .env with your database credentials

构建并运行:
```
npm run build
npm start
```
或者用于热重载开发：
```
npm run dev
```

⚙️ 配置

嵌入提供者

本地嵌入（默认）

用途氙气/变压器对于设备上的嵌入：

EMBEDDING_PROVIDER=local

✅ 免费和私人
✅ 不需要API密钥
✅ 离线工作
⚠️ 质量低于OpenAI
⚠️ 大批量生产速度较慢

OpenAI嵌入

使用OpenAI的嵌入模型实现最高质量：

EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-your-api-key
OPENAI_EMBEDDING_MODEL=text-embedding-3-small  # or text-embedding-3-large

✅ 最佳质量嵌入件
✅ 快速批量处理
⚠️ 需要API密钥，而且成本高昂
⚠️ 将数据发送到OpenAI

环境变量

变量	描述	默认值
`EMBEDDING_PROVIDER`	`local` 或 `openai`	`local`
`OPENAI_API_KEY`	OpenAI API密钥（如果提供程序=OpenAI）	-
`OPENAI_EMBEDDING_MODEL`	OpenAI模型名称	`text-embedding-3-small`
`DB_HOST`	PostgreSQL主机	`localhost`
`DB_PORT`	PostgreSQL端口	`5432`
`DB_NAME`	数据库名称	`rag_db`
`DB_USER`	数据库用户	`rag_user`
`DB_PASSWORD`	数据库密码	-
`REDIS_HOST`	Redis主机	`localhost`
`REDIS_PORT`	Redis端口	`6379`
`REDIS_DB`	Redis数据库编号	`1`
`PORT`	HTTP服务器端口	`3000`
`NODE_ENV`	环境	`production`

🛠️ MCP工具参考

`rag_query`

向RAG系统查询相关文件。

参数:

query （字符串，必填）：搜索查询
topK （数字，可选）：结果数量（默认值：5）
similarityThreshold （数字，可选）：最小相似度0-1（默认值：0.7）

示例:

{
  "query": "How to deploy with Docker?",
  "topK": 3,
  "similarityThreshold": 0.75
}

`rag_add_document`

将单个文档添加到系统中。

参数:

content （字符串，必填）：文档文本
metadata （对象，可选）：自定义元数据

示例:

{
  "content": "Docker deployment guide...",
  "metadata": {
    "source": "docs",
    "tags": ["docker", "deployment"]
  }
}

`rag_add_documents`

批量添加多个文档（更高效）。

参数:

documents （array，必填）：文档对象数组

示例:

{
  "documents": [
    {"content": "First doc...", "metadata": {"tag": "intro"}},
    {"content": "Second doc...", "metadata": {"tag": "advanced"}}
  ]
}

`rag_delete_document`

按ID删除文档。

参数:

documentId （数字，必填）：要删除的文档ID

`rag_index_website`

抓取并索引整个网站。

参数:

url （字符串，必填）：网站URL
maxDepth （数字，可选）：爬行深度（默认值：2）
maxPages （数字，可选）：要爬网的最大页面数（默认值：50）

示例:

{
  "url": "https://docs.example.com",
  "maxDepth": 3,
  "maxPages": 100
}

`rag_get_stats`

获取系统统计数据和运行状况信息。

🏥 健康检查和监测

健康端点

curl http://localhost:3000/health

答复：

{
  "status": "healthy",
  "uptime": 3600,
  "database": "connected",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

指标端点

curl http://localhost:3000/metrics

答复：

{
  "requestCount": 1247,
  "errorCount": 3,
  "uptime": 86400,
  "errorRate": "0.24%"
}

📦 开发命令

npm run build        # Compile TypeScript to dist/
npm run dev          # Development mode with hot reload
npm start            # Start production server
npm test             # Run tests
npm run lint         # Run ESLint

# Docker commands
npm run docker:build # Build Docker image
npm run docker:up    # Start all services
npm run docker:down  # Stop all services
npm run docker:logs  # View server logs

🗄️ 数据库模式

表格

rag.文档

id：主键
content：文档文本
metadata：JSONB元数据
source_url：源URL
title：文档标题
created_at, updated_at：时间戳

rag.embeddings

id：主键
document_id：文档的外键
embedding：矢量（384）-嵌入矢量
created_at, updated_at：时间戳

索引

HNSW指数在快速向量相似性嵌入中的应用
JSON查询元数据的GIN索引
常见查询字段上的B-树索引

🔧 故障排除

数据库连接问题

# Check PostgreSQL is running
docker-compose ps

# Check database logs
docker-compose logs postgres

嵌入模型下载问题

# Clear model cache
rm -rf models/

# Restart with fresh download
npm run docker:down && npm run docker:up

端口冲突

如果端口3000、5432或6379已在使用中，请更新 .env:

PORT=3001
DB_PORT=5433
REDIS_PORT=6380

📚 了解更多

内置于❤️ 对于AI社区