AI导哈

RAG MCP 服务器

一个自托管的模型上下文协议（MCP）服务器，用于爬取文档站点、存储语义块并通过Next.js仪表板提供实时作业可见性。

  • by CipherScout
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 CipherScout/rag-mcp-server

使用说明

RAG MCP 服务器

自托管的模型上下文协议（MCP）服务器，使用Crawl4AI爬取文档网站，将语义块存储在PostgreSQL + pgvector中，并通过Next.js仪表板提供实时作业可见性。

工具链与栈（或堆栈）

  • 后端： Python 3.12，FastMCP，异步作业流水线，UV用于依赖管理
  • 前端： Next.js 15 App Router，TypeScript，TailwindCSS，pnpm 工作区
  • 数据： PostgreSQL 16 + pgvector（HNSW索引），Alembic 迁移工具
  • 嵌入（或表示）： 本地Ollama（embeddinggemma:300m) 可从容器通过……访问 host.docker.internal:11434
  • 集装箱化： 带有专用功能的Docker Compose v2 Dockerfile.backend 并且 Dockerfile.frontend
  • 命令运行器： just 巩固安装/构建/测试/开发工作流

建筑细节历久弥新 docs/architecture/ （见 tech-stack.md， source-tree.md， coding-standards.md （用于强制性公约）。

先决条件

快速入门

# 1. Clone repo
git clone <repo-url> && cd rag-mcp-server

# 2. Configure environment variables
cp .env.example .env
# Edit .env if needed (defaults work for local development)

# 3. Start PostgreSQL with pgvector
just docker-up               # Start PostgreSQL container in background

# 4. Verify pgvector installation
docker exec rag-mcp-postgres psql -U raguser -d rag_mcp_db -c "SELECT * FROM pg_extension WHERE extname = 'vector';"
# Expected: Row with extname='vector' (version 0.8.1)

# 5. Install dependencies
just install-frontend        # pnpm install --frozen-lockfile in /frontend
just install-server          # uv sync - resolve backend deps

# 6. Launch services (in separate terminals)
just run-server              # uv run python app.py (FastMCP server, runs migrations)
just run-frontend            # pnpm dev (Next.js dashboard)

# 7. Run tests
just test-server             # uv run pytest
just test-frontend           # pnpm test:unit

常用命令（justfile）

命令 描述
just install-server 通过 uv 安装后端依赖项
just install-frontend 使用 pnpm 安装前端依赖
just build-server 通过 uv 构建后端包
just build-frontend 构建 Next.js 应用
just run-server 运行 FastMCP 服务器（应用迁移）
just run-frontend 运行 Next.js 开发服务器
just test-server 后端 pytest 套件（/server/tests）
just test-frontend 前端单元套件
just docker-up 在后台启动 PostgreSQL 容器
just docker-down 停止 PostgreSQL 容器
just docker-logs 查看 PostgreSQL 容器日志
just docker-reset 停止容器并移除卷（重新开始）
just compose-up / just compose-down 管理完整的Docker Compose堆栈（当后端/前端采用容器化时）

数据库设置

带有pgvector的PostgreSQL

该项目使用了带有pgvector扩展的PostgreSQL 16来进行向量相似度搜索。Docker Compose负责自动完成设置。

配置：

  • 数据库凭据在（某处）定义 .env （复制自 .env.example）
  • 默认值： raguser / ragpass / rag_mcp_db
  • 连接字符串： postgresql://raguser:ragpass@localhost:5432/rag_mcp_db
  • 数据持久保存在本地目录中： ./data/postgres/

启动数据库：

just docker-up

验证 pgvector 扩展：

docker exec rag-mcp-postgres psql -U raguser -d rag_mcp_db -c "SELECT * FROM pg_extension WHERE extname = 'vector';"

预期输出：包含以下内容的行 extname='vector' 和 extversion='0.8.1' （或之后）

查看日志：

just docker-logs

全新开始（清除所有数据）：

just docker-down
rm -rf data/postgres
mkdir -p data/postgres
just docker-up

注： PostgreSQL 数据存储在本地 ./data/postgres/要备份您的数据库，只需复制此目录即可。

故障排除

端口5432已被占用：

  • 检查本地是否正在运行 PostgreSQL： lsof -i :5432
  • 停止本地 PostgreSQL 服务： brew services stop postgresql (macOS) 或 sudo systemctl stop postgresql (Linux)
  • 或者更改端口在 docker-compose.yml： "5433:5432" 并更新 DATABASE_URL 在 .env

数据卷上的权限错误：

  • 确保 ./data/postgres/ 目录可写
  • 如果使用Linux，PostgreSQL容器将以用户身份运行 postgres (用户ID 999)
  • 修复： sudo chown -R 999:999 data/postgres/ 在Linux系统上

Docker 守护进程未运行：

  • 启动 Docker Desktop（适用于 macOS/Windows）
  • 或者启动 Docker 服务： sudo systemctl start docker (Linux)

未找到 pgvector 扩展：

  • 使用（以下方法）进行验证 pgvector/pgvector:pg16 图片在 docker-compose.yml
  • 检查初始化脚本是否已执行： docker logs rag-mcp-postgres | grep "CREATE EXTENSION"
  • 如缺失，请手动创建： docker exec rag-mcp-postgres psql -U raguser -d rag_mcp_db -c "CREATE EXTENSION vector;"

数据库迁移（Alembic）

该项目使用Alembic进行数据库模式迁移。迁移将在服务器启动时自动应用。

迁移命令：

# Apply all pending migrations
just alembic-up

# Rollback last migration
just alembic-down

# View migration history
just alembic-history

# Check current migration revision
just alembic-current

# Create a new migration (for future use when models exist)
just alembic-revision "migration message"

启动时自动迁移

FastMCP服务器自动运行 alembic upgrade head 在启动之前，确保数据库架构始终保持最新状态。如果迁移失败，服务器将无法启动。

迁移工作流程：

  1. 创建迁移文件： 一旦定义了SQLAlchemy模型（后续故事），则使用 just alembic-revision "description" 创建一个新的迁移文件
  2. 应用迁移： 跑 just alembic-up 或者让服务器在启动时自动应用它们
  3. 回滚： 使用 just alembic-down 撤销最后一次迁移

故障排除：

迁移过程中数据库连接失败：

  • 确保 PostgreSQL 正在运行： just docker-up
  • 验证 DATABASE_URL 在 .env 与您的 PostgreSQL 凭据匹配
  • 检查连接： docker exec rag-mcp-postgres psql -U raguser -d rag_mcp_db -c "SELECT 1;"

未找到修订版本：

  • 查看视图迁移历史： just alembic-history
  • 确保在运行命令时位于仓库根目录
  • 检查一下 /server/migrations/versions/ 包含迁移文件

如果服务器无法启动，则手动执行迁移操作：

  • 手动运行迁移： just alembic-up
  • 检查迁移状态： just alembic-current
  • 在服务器日志中查看错误详情

仓库布局（摘录）

/
├── docs/                # PRD, architecture, stories (sharded)
├── frontend/            # Next.js App Router app (pnpm workspace)
│   ├── app/
│   ├── components/
│   ├── lib/
│   ├── __tests__/
│   └── playwright/
├── server/              # FastMCP service
│   ├── app.py
│   ├── jobs/
│   ├── integrations/
│   ├── persistence/
│   └── tests/           # unit + integration suites
├── migrations/          # Alembic env & version scripts
├── scripts/             # Helper scripts invoked via just recipes
├── docker-compose.yml
├── Dockerfile.backend
├── Dockerfile.frontend
├── justfile
├── .gitignore
└── README.md

参考文献

  • PRD： docs/prd.md （在以下进行分片 docs/prd/）
  • 建筑套件： docs/architecture/
  • 故事库： docs/stories/ 带有命名规范 [epic].[story_number].story.md （例如。， 1.1.story.md)

如需了解详细要求、验收标准和顺序安排，请查阅产品需求文档（PRD）及相应的史诗故事/用户故事。每个用户故事的开发备注中总结了相关的架构背景，以确保构建任务的简洁性。***

相关 MCP