PDF RAG MCP 服务器

一个强大的文档知识库系统，利用 PDF 处理、向量存储和 MCP（模型上下文协议）为 PDF 文档提供语义搜索功能。该系统允许您通过现代 Web 界面或 MCP 协议上传、处理和查询 PDF 文档，以便与 Cursor 等 AI 工具集成。

特征

PDF 文档上传和处理：上传 PDF 并自动提取、分块和矢量化内容
实时处理状态：文档处理过程中基于 WebSocket 的实时状态更新
语义搜索：对所有已处理文档进行基于向量的语义搜索
MCP 协议支持：使用模型上下文协议与 Cursor 等 AI 工具集成
现代 Web 界面：用于文档管理和查询的 React/Chakra UI 前端
快速依赖管理：使用 uv 进行高效的 Python 依赖管理

Related MCP server: FastGPT Knowledge Base MCP

系统架构

该系统包括：

FastAPI 后端：处理 API 请求、PDF 处理和矢量存储
React Frontend ：提供用户友好的文档管理界面
矢量数据库：存储用于语义搜索的嵌入
WebSocket 服务器：提供文档处理的实时更新
MCP 服务器：向兼容 MCP 的客户端公开知识库

快速入门

先决条件

Python 3.8 或更高版本
uv - 快速 Python 软件包安装程序和解析器
Git
光标（可选，用于 MCP 集成）

使用 uv 和 run.py 快速安装和启动

克隆存储库：

git clone https://github.com/yourusername/PdfRagMcpServer.git
cd PdfRagMcpServer

如果尚未安装 uv，请安装它：

curl -sS https://astral.sh/uv/install.sh | bash

使用 uv 安装依赖项：

uv init .
uv venv
source .venv/bin/activate
uv pip install -r backend/requirements.txt

使用便捷的脚本启动应用程序：
```
uv run run.py
```
访问http://localhost:8000 的Web 界面
与游标一起使用

前往“设置”->“Cursor 设置”->“MCP”->“添加新的全局 MCP 服务器”，将以下内容粘贴到 Cursor 的 ~/.cursor/mcp.json 文件中。更多信息，请参阅 Cursor MCP 文档。

{
  "mcpServers": {
    "pdf-rag": {
      "url": "http://localhost:7800/mcp"
    }
  }
}

您也可以将 localhost 更改为您部署服务的主机 IP。将此配置添加到 mcp json 后，您将在 Cursor mcp 配置页面看到 mcp 服务器，将其切换为 on 即可启用服务器：

构建前端（针对开发人员）

如果需要重建前端，您有两个选择：

选项 1：使用提供的脚本（推荐）

# Make the script executable if needed
chmod +x build_frontend.py

# Run the script
./build_frontend.py

该脚本将自动：

安装前端依赖项
构建前端
将构建输出复制到后端的静态目录

选项 2：手动构建过程

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Build the frontend
npm run build

# Create static directory if it doesn't exist
mkdir -p ../backend/static

# Copy build files
cp -r dist/* ../backend/static/

构建前端后，您可以使用 run.py 脚本启动应用程序。

简单的生产设置

对于已经构建静态文件的生产环境：

将预先构建的前端放在backend/static目录中

启动服务器：

cd backend
uv pip install -r requirements.txt
python -m app.main

开发设置（单独服务）

如果您想要单独运行服务以进行开发：

后端

导航到后端目录：
```
cd backend
```
使用 uv 安装依赖项：
```
uv pip install -r requirements.txt
```

运行后端服务器：

python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

前端

导航到前端目录：
```
cd frontend
```
安装依赖项：
```
npm install
```
运行开发服务器：
```
npm run dev
```

用法

上传文件

访问http://localhost:8000 的Web 界面
点击“上传新 PDF”并选择一个 PDF 文件
系统将处理该文件，并实时显示进度
处理完成后，文档将可供搜索

搜索文档

使用 Web 界面中的搜索功能
或者使用 MCP 协议与 Cursor 集成

MCP 与 Cursor 集成

打开游标
前往“设置”→“AI 和 MCP”
添加自定义 MCP 服务器，URL： http://localhost:8000/mcp/v1
保存设置
现在您可以直接从 Cursor 查询您的 PDF 知识库

故障排除

连接问题

验证端口 8000 未被其他应用程序使用
检查 WebSocket 连接是否正常工作
确保您的浏览器支持 WebSockets

处理问题

检查您的 PDF 是否包含可提取的文本（某些扫描的 PDF 可能不包含）
确保系统有足够的资源（内存和CPU）
检查后端日志以获取详细的错误消息

项目结构

PdfRagMcpServer/
├── backend/               # FastAPI backend
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py        # Main FastAPI application
│   │   ├── database.py    # Database models
│   │   ├── pdf_processor.py # PDF processing logic
│   │   ├── vector_store.py # Vector database interface
│   │   └── websocket.py   # WebSocket handling
│   ├── static/            # Static files for the web interface
│   └── requirements.txt   # Backend dependencies
├── frontend/              # React frontend
│   ├── public/
│   ├── src/
│   │   ├── components/    # UI components
│   │   ├── context/       # React context
│   │   ├── pages/         # Page components
│   │   └── App.jsx        # Main application component
│   ├── package.json       # Frontend dependencies
│   └── vite.config.js     # Vite configuration
├── uploads/               # PDF file storage
└── README.md              # This documentation

贡献

欢迎贡献代码！欢迎提交 Pull 请求。

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

PDF RAG MCP Server