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

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

{
  "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"
      }
    }
  }
}

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/)

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

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