local-rag-mcp

local-rag-mcp

A RAG knowledge base MCP server using FastMCP and LanceDB, enabling hybrid search, document ingestion, and full MCP tool/resource/prompt support.

Category
访问服务器

README

RAG MCP Server v2.1.0

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

V2.0 核心升级

特性 V1.x V2.0
向量存储 llama_index VectorStoreIndex LanceDB (Rust 核心, mmap, 无服务器)
检索算法 AutoMergingRetriever (纯语义) 混合检索 (IVF-PQ + BM25 + RRF 重排)
文档解析 DoclingReader (黑盒) 自研 ETL (PyPDF/docx/pandas, 可控可采样)
分块策略 256/512/1024 层级分块 智能分块 (600char + 句尾防截断)
文件监控 启动时 manifest 比对 Watchdog 实时监控 + 1.0s 防抖
日志系统 logging + RotatingFileHandler Loguru (按天轮转 + zip 压缩)
MCP 工具 3 个 (health_check/status/query) 7 个 (完整 CRUD + 混合检索)
MCP 特性 仅 Tools Tools + Resources + Prompts + Sampling + Roots

项目结构

src/rag_mcp/
├── __init__.py         # 包标记
├── server.py           # FastMCP 入口 — 7 工具 + 2 资源 + 1 提示词 + Sampling + Roots
├── engine.py           # [Cython] 核心引擎 — 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. 构建 wheel + 安装
.\.venv\Scripts\python.exe build\build_release.py --install

# 4. 启动
rag-mcp

安装与运行

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

# ---- 生产模式 (wheel 安装) ----
# 构建 (Cython .pyd 加密核心模块)
.venv\Scripts\python.exe build\build_release.py

# 安装
pip install dist\rag_mcp-2.1.0-py3-none-any.whl

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

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

# 卸载
pip uninstall rag-mcp -y

接入 MCP 客户端

SSE 模式（推荐）

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

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

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

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

环境变量

变量 默认值 说明
RAG_PROJECT_PATH (必填) 文档项目目录，启动时自动加载索引 + 文件监控
EMBED_BASE_URL http://localhost:11434 Ollama Embedding 服务地址
EMBED_MODEL_NAME bge-m3 Embedding 模型名称 (1024 维)
EMBED_TIMEOUT 60.0 Embedding 请求超时（秒）
MCP_TRANSPORT sse 传输模式: sse (守护进程) 或 stdio (子进程)
MCP_HOST 127.0.0.1 SSE 监听地址
MCP_PORT 8042 SSE 监听端口
RAG_HYBRID_WEIGHT 0.7 混合检索权重 (0=纯BM25, 1=纯向量)
RAG_CHUNK_SIZE 600 分块大小（字符数）
RAG_CHUNK_OVERLAP 60 块间重叠（字符数）
RAG_WATCH_DEBOUNCE 1.0 文件监控防抖间隔（秒）
LOG_LEVEL INFO 日志级别

MCP 工具 (7)

工具 参数 说明
query_documents query, limit?, scope? 混合检索 (密集向量 + BM25 + RRF)，返回原始文档片段
read_chunk_neighbors file_id, chunk_id, direction 读取相邻块 (prev/next/both)，防止断章取义
ingest_file path 索引单个文件 (PDF/Word/Excel/MD/TXT/HTML)
ingest_data content, metadata? 注入文本/Markdown 字符串到向量库
list_files 无 已索引文件清单及块统计
delete_file file_id 物理擦除文件索引 + 重建 FTS
status 无 系统健康诊断 (DB 统计 + Embedding + 文件监控)

MCP 资源 (2)

URI 说明
localrag://system/status 系统健康快照 (JSON): DB 统计 / Embedding / 文件监控
localrag://files/list 已索引文件清单 (JSON): 文件路径 + 块数量

MCP 提示词 (1)

名称 参数 说明
review-codebase focus_area 代码库评审 SOP 模板，自动注入 RAG 检索工作流

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

文件归档

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

服务状态追踪

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

状态 说明
INITIALIZING 服务启动中
IDLE 空闲，等待请求
LOADING_DOCS 正在扫描/加载文档
INDEXING 正在构建向量索引
INGESTING 正在摄取文件/文本
QUERYING 正在执行混合检索
WATCHING 文件监控运行中
ERROR 发生错误（含错误信息）

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"

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选