# python-rag-mcp

**Repository Path**: wdb123/python-rag-mcp

## Basic Information

- **Project Name**: python-rag-mcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-04
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mcp-rag-server

基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 的 RAG 知识库服务。将文档切块、向量化后存入 PostgreSQL（pgvector），供 Cursor 等 MCP 客户端通过自然语言检索项目文档。

## 功能

- **文档入库**：将本地文本/Markdown 文件切块并写入向量库
- **语义检索**：根据问题检索最相关的文档片段
- **Cursor 集成**：通过 `.cursor/mcp.json` 在 IDE 内直接调用 MCP 工具

## MCP 工具

| 工具 | 说明 | 参数 |
|------|------|------|
| `rag_add_document` | 将文件加入知识库 | `file_path`：文件绝对或相对路径 |
| `rag_query` | 检索知识库 | `query`：自然语言问题 |

## 技术栈

- **MCP 服务**：Python [mcp](https://pypi.org/project/mcp/) + FastMCP（stdio 传输）
- **向量模型**：`sentence-transformers/all-MiniLM-L6-v2`（384 维）
- **向量存储**：PostgreSQL + [pgvector](https://github.com/pgvector/pgvector)

## 项目结构

```
mcp-rag-server/
├── main.py              # MCP 服务入口
├── vector_store.py      # PGVector 封装
├── .cursor/mcp.json     # Cursor MCP 配置
├── docs/
│   └── rbac.md          # 示例文档（RBAC 权限设计）
├── scripts/
│   ├── init_db.py       # 初始化数据库与 pgvector 扩展
│   └── add_doc.py       # 导入文档并测试检索
├── requirements.txt
└── pyproject.toml
```

## 环境要求

- Python >= 3.13
- PostgreSQL（需安装 pgvector 扩展）
- 首次运行会自动下载 embedding 模型（约 80MB）

## 快速开始

### 1. 安装依赖

```powershell
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

Linux / macOS：

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### 2. 配置数据库

在项目根目录创建 `.env`（可选，不配置则使用默认值）：

```env
DATABASE_URL=postgresql://postgres:your_password@localhost:5432/rag_db
```

初始化数据库（创建 `rag_db` 并启用 pgvector）：

```powershell
.venv\Scripts\python.exe scripts\init_db.py
```

### 3. 导入示例文档

```powershell
.venv\Scripts\python.exe scripts\add_doc.py
```

该脚本会将 `docs/rbac.md` 导入知识库，并执行一次检索测试。

### 4. 在 Cursor 中启用 MCP

项目已包含 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "rag": {
      "command": ".venv/Scripts/python.exe",
      "args": ["main.py"],
      "cwd": "."
    }
  }
}
```

Linux / macOS 请将 `command` 改为 `.venv/bin/python`。

修改配置后，在 Cursor **Settings → MCP** 中重载服务，或重启 Cursor。

## 使用示例

在 Cursor 对话中，Agent 可调用 MCP 工具完成以下操作：

**导入文档：**

```
调用 rag_add_document，参数：docs/rbac.md
```

**检索知识库：**

```
调用 rag_query，参数：RBAC 有哪些内置角色？
```

**命令行手动测试：**

```powershell
.venv\Scripts\python.exe -c "import asyncio, main; print(asyncio.run(main.rag_query('RBAC 数据表有哪几张')))"
```

## 工作原理

```
文档文件 → 按 1000 字符切块 → SentenceTransformer 向量化 → 写入 PGVector
                                                              ↓
用户提问 → 问题向量化 → 余弦距离检索 Top-K → 返回相关片段
```

- 默认每次检索返回 **3** 条最相似片段（可在 `vector_store.py` 的 `search()` 中调整 `limit`）
- 向量维度为 **384**，与 `all-MiniLM-L6-v2` 模型一致

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DATABASE_URL` | `postgresql://postgres:root@localhost:5432/rag_db` | PostgreSQL 连接串 |

## 常见问题

**MCP 服务无法启动**

- 确认 `.venv` 中已安装 `mcp` 依赖
- 确认 `mcp.json` 中的 Python 路径指向虚拟环境

**工具调用报数据库连接错误**

- 确认 PostgreSQL 已启动
- 确认已执行 `scripts/init_db.py`
- 检查 `.env` 中的用户名、密码、数据库名

**首次调用较慢**

- 首次使用会下载 `all-MiniLM-L6-v2` 模型，后续调用会快很多

**重复导入同一文档**

- 当前实现为追加写入，重复导入会产生重复向量。重新导入前可手动清空表：

```sql
DELETE FROM rag_documents;
```

## 开发说明

本地直接启动 MCP 服务（stdio 模式，供 Cursor 调用）：

```powershell
.venv\Scripts\python.exe main.py
```

## License

MIT