Local RAG MCP Server v2.1.0

基于 FastMCP + LanceDB 的 RAG 知识库 MCP 服务器，完整实现 MCP 五大核心特征 (Tools / Resources / Prompts / Sampling / Roots)。

V2.0 核心升级

项目结构

src/local_rag_mcp/
├── __init__.py         # 包标记
├── server.py           # FastMCP 入口 — 7 工具 + 2 资源 + 1 提示词 + Sampling + Roots
├── engine.py           # 核心引擎 — EmbeddingClient + HybridSearchEngine + IngestionPipeline
├── lancedb_store.py    # LanceDB 存储层 (IVF-PQ + BM25 FTS)
├── chunker.py          # 智能分块器 (600char/60overlap, 句尾防截断)
├── parsers/            # 多模态 ETL 解析器
│   ├── __init__.py     # 解析器工厂 get_parser()
│   ├── pdf_parser.py   # PyPDF 流式段落解析 + 高噪检测 → Sampling
│   ├── word_parser.py  # python-docx 对象树遍历 + 表格序列化
│   ├── excel_parser.py # pandas 矩阵序列化 ("列A: 值A; 列B: 值B")
│   └── text_parser.py  # MD/TXT/HTML 通用解析
├── watcher.py          # Watchdog 文件监控 + 1.0s 防抖状态机
├── sampling.py         # MCP Sampling 反向采样 (高噪文本清洗)
├── logger.py           # Loguru 按天轮转 + zip 压缩 + 10 天保留
└── status.py           # 线程安全服务状态追踪 (8 种状态)

快速开始

# 1. 克隆项目，创建虚拟环境
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .

# 2. 配置 .env（Embedding 地址 + 文档路径）
# 编辑 .env，关键配置:
#   EMBED_BASE_URL=http://localhost:11434
#   EMBED_MODEL_NAME=qwen3-embedding:8b
#   RAG_PROJECT_PATH=./documents

# 3. 启动
local-rag-mcp

安装与运行

# ---- 开发模式 (源码直接跑) ----
.venv\Scripts\python.exe -m src.local_rag_mcp.server

# ---- 生产模式 (PyPI 安装) ----
pip install local-rag-mcp

# 或本地构建 wheel 后安装
.venv\Scripts\python.exe -m build
pip install dist\local_rag_mcp-2.1.0-py3-none-any.whl

# 运行 (SSE 默认, 端口 8042)
local-rag-mcp

# 运行 (stdio 模式)
$env:MCP_TRANSPORT="stdio"; local-rag-mcp

# 卸载
pip uninstall local-rag-mcp -y

接入 MCP 客户端

SSE 模式（推荐）

先启动服务 local-rag-mcp，保持窗口打开：

{
  "mcpServers": {
    "enterprise-local-rag": {
      "type": "sse",
      "url": "http://127.0.0.1:8042/sse"
    }
  }
}

stdio 模式（子进程，客户端自动拉起）

{
  "mcpServers": {
    "enterprise-local-rag": {
      "command": "local-rag-mcp",
      "env": {
        "MCP_TRANSPORT": "stdio",
        "RAG_PROJECT_PATH": "./documents",
        "EMBED_BASE_URL": "http://localhost:11434",
        "EMBED_MODEL_NAME": "qwen3-embedding:8b"
      }
    }
  }
}

环境变量

MCP 工具 (7)

MCP 资源 (2)

MCP 提示词 (1)

RAG 管道 (V2.0)

1. 文件监控 — Watchdog 实时监控增删改，1.0s 防抖，自动触发 ETL
2. 多模态解析 — 自研解析器 (PyPDF/docx/pandas)，PDF 高噪自动触发 Sampling 清洗
3. 智能分块 — 600 字符块 + 60 字符重叠 + 句尾标点语义切分
4. 向量化 — Ollama bge-m3 (1024 维)，直接调用 /api/embeddings
5. 双索引 — LanceDB IVF-PQ 密集向量索引 + BM25 稀疏全文倒排索引
6. 混合检索 — ANN + FTS 双路并行召回，RRF 无监督融合 (k=60, 权重可配置)

RRF 融合公式

$$RRF_Score(d) = \frac{w}{60 + R_{dense}(d)} + \frac{1 - w}{60 + R_{sparse}(d)}$$

• w = RAG_HYBRID_WEIGHT (默认 0.7)
• 当 w=0.7 时，兼顾深层语义并精确匹配代码/编号/专有名词

日志系统

控制台输出

彩色日志输出到 stderr，格式：时间 | 级别 | 线程名 | 模块:行号 | 内容

20:53:55 | INFO     | MainThread   | local_rag_mcp.server:67 | Enterprise RAG MCP Server v2.0 启动
20:53:55 | INFO     | MainThread   | local_rag_mcp.engine:85 | Embedding: bge-m3 @ http://localhost:11434 (dim=1024)
20:53:55 | INFO     | MainThread   | local_rag_mcp.lancedb_store:68 | LanceDB 已连接 (.ragdb_lance/)

文件归档

• 按天切分: 每日 00:00 自动切分，文件名 server_YYYY-MM-DD.log
• 自动压缩: 旧日志 zip 压缩
• 保留 10 天: 超期日志自动物理擦除
• 全链路 Trace: [Trace] ▶ ... / [Trace] ✓ ... (XXms) 毫秒级耗时审计

服务状态追踪

status.py 维护线程安全的全局状态单例，包含 8 种状态：

Sampling 反向采样

当 PDF 解析器检测到高噪文本 (noise_level > 0.35) 时：

1. 后台服务挂起当前文件的写入事务
2. 通过 MCP sampling/createMessage 反向请求前台大模型进行文本清洗
3. 前台大模型完成推理清洗，返回结构化文本 + 核心关键词
4. 后台接收清洗结果，继续 ETL 流水线

价值: "白嫖"前台大模型的能力反哺本地知识库，本地服务保持轻量 (闲置物理内存 ≤ 35MB)。

Roots 隐私隔离

当用户在编辑器中切换项目工作区时：

1. 客户端通过 roots/list 通知新的工作区路径
2. 服务器自动切换 LanceDB 命名空间，确保数据强隔离
3. 文件监控焦点无缝切换至新路径
4. 项目 A 的资产绝不会在项目 B 的对话中被意外召回

测试

# 全部测试 (需要 Ollama 的会自动跳过)
.venv\Scripts\python.exe -m pytest tests/ -v

# 仅本地单元测试 (无需网络)
.venv\Scripts\python.exe -m pytest tests/ -v -m "not network"