ly rag MCP

LlamaIndex RAG MCP服务器

具有OpenAI/Gemini嵌入、混合搜索（语义+BM25）、Cohere-reranking、HyDE查询增强和MCP服务器集成的本地RAG系统。

特性

• 增量更新：仅根据mtime/大小跟踪处理新/修改的文件
• 混合搜索：基于RRF融合的语义（向量）+关键字（BM25）检索
• 自适应模式选择：自动检测类似代码的查询并切换到混合搜索
• HyDE查询增强：假设性文档嵌入，以更好地进行概念匹配
• 两阶段检索：灵活的top_k（1-50）+可选的Cohere v3.5重新评级
• 智能项目路由：多项目隔离，自动查询路由到最佳项目
• 多个嵌入提供程序：OpenAI或谷歌双子座
• 模型：OpenAI text-embedding-3-large 或双子座 text-embedding-004 +科恩 rerank-v3.5
• MCP集成：适用于标准MCP客户端（Claude Desktop、Chatwise、Cherry Studio等）
• 35+文件格式：通过LlamaIndex阅读器读取代码（16个文本）、文档（16个字符）、图像（3个字符）
• 本地存储：每个项目ChromaDB矢量数据库 storage/{project}/
• 可选Vue.js用户界面：MCP实时监控 / 运行api_server.py时
• 线程安全：所有管理器都使用带锁的单例模式；元数据的跨平台文件锁定

安装

git clone https://github.com/hrayleung/ly_rag_mcp.git
cd ly_rag_mcp

conda create -n deep-learning python=3.10
conda activate deep-learning

# Core dependencies
pip install llama-index llama-index-embeddings-openai llama-index-vector-stores-chroma
pip install llama-index-postprocessor-cohere-rerank chromadb fastmcp

# Gemini support (optional)
pip install google-genai

# New features (Hybrid Search & Web Crawling)
pip install rank-bm25 llama-index-retrievers-bm25 firecrawl-py

快速开始

1.设置API密钥

选项A:OpenAI嵌入（默认）

export EMBEDDING_PROVIDER=openai
export EMBEDDING_MODEL=text-embedding-3-large
export OPENAI_API_KEY='your-openai-api-key'
export COHERE_API_KEY='your-cohere-api-key'     # Optional: For Reranking
export FIRECRAWL_API_KEY='your-firecrawl-key'   # Optional: For Web Crawling

选项B：双子座嵌入

export EMBEDDING_PROVIDER=gemini
export EMBEDDING_MODEL=text-embedding-004
export GEMINI_API_KEY='your-gemini-api-key'
export COHERE_API_KEY='your-cohere-api-key'     # Optional: For Reranking
export FIRECRAWL_API_KEY='your-firecrawl-key'   # Optional: For Web Crawling

2.索引文件

# Incremental update (default - only processes new/modified files)
python build_index.py /path/to/your/documents

# Force full rebuild
python build_index.py /path/to/your/documents --rebuild

3.配置MCP客户端

添加到MCP客户端配置中：

选项A:OpenAI嵌入

{
  "mcpServers": {
    "llamaindex-rag": {
      "command": "/path/to/conda/envs/deep-learning/bin/python",
      "args": ["/path/to/ly_rag_mcp/mcp_server.py"],
      "cwd": "/path/to/ly_rag_mcp",
      "env": {
        "EMBEDDING_PROVIDER": "openai",
        "EMBEDDING_MODEL": "text-embedding-3-large",
        "OPENAI_API_KEY": "your-openai-key",
        "COHERE_API_KEY": "your-cohere-key",
        "FIRECRAWL_API_KEY": "your-firecrawl-key"
      }
    }
  }
}

选项B：双子座嵌入

{
  "mcpServers": {
    "llamaindex-rag": {
      "command": "/path/to/conda/envs/deep-learning/bin/python",
      "args": ["/path/to/ly_rag_mcp/mcp_server.py"],
      "cwd": "/path/to/ly_rag_mcp",
      "env": {
        "EMBEDDING_PROVIDER": "gemini",
        "EMBEDDING_MODEL": "text-embedding-004",
        "GEMINI_API_KEY": "your-gemini-key",
        "COHERE_API_KEY": "your-cohere-key",
        "FIRECRAWL_API_KEY": "your-firecrawl-key"
      }
    }
  }
}

配置位置：

• 克劳德代码: ~/Library/Application Support/Claude/claude_desktop_config.json
• Chatwise/樱桃工作室：应用程序设置

4.查询

重新启动MCP客户端并提问：

What are these documents about?
Use query_rag to search for "parallel computing"
Show me the index statistics

支持的文件格式

文件大小限制：每个文件100MB

默认情况下排除： node_modules, __pycache__, .git、venv、构建输出和IDE文件。

MCP工具

查询工具

• query_rag(question, top_k=6, search_mode='semantic', use_rerank=True, use_hyde=False, return_metadata=False, project=None)

- search_mode：“语义”（向量）、“混合”（BM25+带RRF的向量）或“关键字”（仅BM25）。自动检测混合动力的代码模式。 - use_hyde：启用假设文档嵌入-生成合成答案，以便更好地检索概念查询 - top_k：结果数量（1-50） - return_metadata：当为True时，返回带源、分数、元数据的结构化JSON；否则返回格式化文本 - project：显式项目名称，或通过智能路由自动路由

摄入工具

• index_documents(path, project=None) -从目录中索引文档（支持所有格式）
• add_text(text, metadata=None, project=None) -将原始文本添加到索引
• inspect_directory(path) -在索引之前分析文件夹内容（显示文件类型、计数）
• crawl_website(url, max_pages=10, project=None) -通过Firecrawl抓取网站

项目确认： 摄入工具需要 project 争论。如果省略，则返回 {"action_required": "select_project", ...} 并提出建议。

管理工具

• manage_project(action, project=None, keywords=None, description=None)

- 行动： list, create, switch, update, analyze, choose

• get_stats(stat_type='index') -系统统计
• list_documents(project=None, limit=100) -列出索引文档
• clear_index(project=None, confirm=False) -破坏性：明确项目指标

HTTP API服务器（可选）

跑 python api_server.py 对于遥测端点和Vue UI：

• GET /api/mcp/tools -工具元数据（名称、类型、描述）
• GET /api/mcp/requests -最近的请求示例（状态、路由、延迟、工具、用户）
• GET /api/mcp/logs -服务器日志环缓冲区
• GET /api/mcp/stats -系统指标（正常运行时间、RPM、错误、索引统计数据）
• GET /api/mcp/health -正常运行时间状态的健康检查
• GET / -Vue UI前端（使用 npm run build 在 frontend/)

看 README_UI.md 查看详细的前端文档。

调试

• python debug_rag.py -全面的诊断（环境、存储、索引质量、性能）
• python verify_setup.py -快速设置验证
• 集 RAG_LOG_LEVEL=DEBUG 查看详细日志

建筑

回收管道

Query → Search Mode Detection (Adaptive)
    ↓
(Optional) HyDE Query Augmentation (if weak results)
    ↓
Parallel: Vector Search + BM25 Keyword Search
    ↓
RRF (Reciprocal Rank Fusion) Merge
    ↓
(Optional) Cohere Reranking
    ↓
Results (top_k)

数据摄取管道

Documents → DocumentLoader (20+ formats)
    ↓
DocumentProcessor (UTF-8 sanitize + context injection)
    ↓
DocumentChunker (AST for code, sentence for docs)
    ↓
IndexManager → LlamaIndex Storage
    ↓
Persist: ChromaDB + JSON manifests

多项目隔离

storage/
└── {project_name}/
    ├── chroma_db/          # ChromaDB vector collection
    ├── project_metadata.json    # Project config, keywords
    ├── ingest_manifest.json     # File change tracking
    ├── indexed_files.json       # mtime/size tracking
    ├── docstore.json       # LlamaIndex document store
    ├── index_store.json    # LlamaIndex index metadata
    └── graph_store.json    # LlamaIndex graph store

搜索策略

自适应模式选择

当查询包含以下内容时，自动切换到混合搜索：

• 3位以上数字令牌（例如“HTTP_200”）
• 大写模式： [A-Z_]{2,}
• 代码字符： {}();=<>*/+-
• 路径式令牌： /, \
• 带有3+个尾随字符的令牌中的点（例如。， module.function)
• > 30%大写或>40%数字

HyDE（假想文档嵌入）

• 触发：结果≤1或最高分数≤0.1或所有分数\0.05或结果太少（\")` 显示得分的候选人
• 摄入工具自动更新 default_paths 并维护 last_indexed_at 时间戳

关键词学习

成功的查询会通过以下方式自动更新项目关键字 MetadataManager.learn_from_query()随着时间的推移，随着系统学习查询项目关联，路由会得到改善。

重新排名策略

多轮搜索（推荐）

不要在单个查询中请求多个结果，而是使用迭代细化：

示例1：开始专注，必要时扩展

1. Use iterative_search("Python async patterns", initial_top_k=3)
2. Review the 3 most relevant results
3. If more context needed: query_rag("Python async patterns", similarity_top_k=10)
4. Or refine: query_rag("asyncio event loop internals", similarity_top_k=5)

示例2：渐进式深化

1. query_rag("machine learning", similarity_top_k=5) - understand scope
2. query_rag("neural network backpropagation", similarity_top_k=5) - focus on specific topic
3. query_rag("gradient descent optimization", similarity_top_k=3) - deep dive

好处:

• 更高的准确性：专注于最相关的结果
• 令牌效率：只检索您需要的东西
• 课程修正：根据实际发现进行改进
• 更少的噪音：避免用相关性较弱的文档稀释上下文

两阶段检索

1. 向量搜索：检索2名候选人（例如，前10名中有20名候选人，最低10名）
2. 重新排序：Cohere v3.5按语义相关性重新排序

动态调整基于 top_k:

• top_k=3 → 检索10→ 再银行→ 返回3
• top_k=10 → 检索20→ 再银行→ 返回10
• top_k=15 → 检索30→ 再银行→ 返回15

启用：添加 COHERE_API_KEY 环境 禁用：设置 use_rerank=False 在查询中

测试

该项目使用pytest，目标覆盖率≥70%。

运行测试

# Full suite with coverage
pytest tests/ --cov=rag --cov-report=term -v

# Single file
pytest tests/test_query_tools.py --cov-report=term -v

# Single test
pytest tests/test_query_tools.py::test_specific_function --cov-report=term -v

测试文件

总计： 18个测试文件

测试模式

• 集成测试 (test_*.py)：使用模拟/补丁进行完整模块测试
• 快速单元测试 (test_*_small.py)：CI速度的轻量级模拟测试
• 模仿策略: DummyMCP/FakeMCP 班级， SimpleNamespace 嘲笑， unittest.mock.patch
• 螺纹安全测试：用于并发操作的多线程测试
• 向后兼容性测试：加载旧JSON格式，缺少字段

配置

嵌入模型

通过MCP配置中的环境变量设置：

OpenAI模型：

"env": {
  "EMBEDDING_PROVIDER": "openai",
  "EMBEDDING_MODEL": "text-embedding-3-large"  // or "text-embedding-3-small"
}

Gemini型号：

"env": {
  "EMBEDDING_PROVIDER": "gemini",
  "EMBEDDING_MODEL": "text-embedding-004"  // or "embedding-001"
}

注： 使用一个嵌入模型创建的索引与另一个不兼容。如果切换模型，请使用以下命令重建索引 --rebuild.

重新排列模型

集 COHERE_API_KEY 环境变量。默认型号： rerank-v3.5 （用于 rag/retrieval/reranker.py).

配置参数（RAG设置）

支持的文件扩展名

代码（16个扩展名）： .py, .js, .ts, .jsx, .tsx, .java, .cpp, .c, .go, .rs, .sh, .sql, .yaml, .toml, .vue, .html, .css

文件（16个扩展名）： .txt, .pdf, .docx, .md, .json, .xml, .csv, .ipynb, .epub, .doc, .ppt, .pptx, .pptm, .xls, .xlsx, .rtf

图片（3个扩展名）： .jpg, .jpeg, .png

默认排除项： node_modules, __pycache__, .git, .svn, .hg, venv, env, .venv, .env, build, dist, target, out, .idea, .vscode, .vs, *.pyc, *.pyo, *.so, *.dylib, *.dll, .DS_Store, Thumbs.db

项目结构

ly_rag_mcp/
├── mcp_server.py           # FastMCP server entry point (MCP stdio)
├── api_server.py           # Optional HTTP API + Vue UI
├── build_index.py          # CLI index builder (incremental)
├── verify_setup.py         # Setup verification
├── debug_rag.py            # Debug & profiling tool
├── rag/                    # Core package (modular architecture)
│   ├── __init__.py         # Lazy exports
│   ├── config.py           # RAGSettings, logging, constants
│   ├── models.py           # Data models (SearchMode, ProjectMetadata, etc.)
│   ├── embeddings.py       # Embedding factory (OpenAI/Gemini)
│   ├── storage/            # Storage layer
│   │   ├── chroma.py       # ChromaDB client manager (singleton)
│   │   └── index.py        # LlamaIndex storage manager (singleton)
│   ├── retrieval/          # Retrieval layer
│   │   ├── search.py       # Unified search engine (hybrid/semantic/keyword)
│   │   ├── reranker.py     # Cohere reranking manager
│   │   ├── bm25.py         # BM25 keyword search manager
│   │   └── hyde.py         # HyDE query augmentation
│   ├── ingestion/          # Ingestion layer
│   │   ├── loader.py       # Multi-format document loading
│   │   ├── processor.py    # Text cleaning, context injection
│   │   └── chunker.py      # Smart chunking (AST for code, sentence for docs)
│   ├── project/            # Multi-project isolation
│   │   ├── manager.py      # Project lifecycle, smart routing/selection
│   │   └── metadata.py     # Project metadata storage (atomic writes)
│   └── tools/              # MCP tool definitions
│       ├── __init__.py     # Tool registration facade
│       ├── query.py        # Search & retrieval tools
│       ├── ingest.py       # Document ingestion tools
│       └── admin.py        # Admin & management tools
├── tests/                  # Test suite (pytest)
├── frontend/               # Optional Vue 3 + Vite UI
│   ├── src/
│   │   ├── components/     # Vue components
│   │   ├── composables/    # API & polling composables
│   │   └── views/          # Page views
│   ├── index.html
│   ├── package.json
│   └── vite.config.ts
├── .env.example            # Environment template
│
└── storage/                # Generated indexes (git-ignored)
    └── {project}/          # Per-project isolation
        ├── chroma_db/      # ChromaDB vector database
        ├── project_metadata.json  # Project config
        ├── ingest_manifest.json   # Ingestion tracking
        ├── indexed_files.json     # File change tracking
        ├── docstore.json       # LlamaIndex document store
        ├── index_store.json    # LlamaIndex index metadata
        └── graph_store.json    # LlamaIndex graph store

架构优势

• 模块化：每个模块都有一个单独的职责（每个文件约200-300行）
• 可测试的：18个测试文件的干净界面，目标覆盖率≥70%
• 线程安全：所有管理者都使用单例模式 threading.Lock() 或 RLock()
• 原子写入：元数据使用临时文件+fsync+跨平台文件锁
• 可扩展：易于添加新的检索器、分块器或工具

管理器单例（延迟初始化，线程安全）

数据模型(rag/models.py)

枚举：

• SearchMode: SEMANTIC, HYBRID, KEYWORD
• ChangeType: NEW, MODIFIED, REMOVED
• ContentType: CODE, DOCUMENT, MIXED

数据类：

• FileMetadata: path, mtime_ns, size
• ProjectMetadata: name, display_name, description, keywords[], default_paths[], last_indexed, created_at, updated_at
• RetrievalResult: text, score, metadata, node_id, preview
• SearchResult: results[], query, search_mode, reranked, used_hyde, generated_query, project, total
• IngestResult: success, message, documents_processed, chunks_created, skipped_unsupported, skipped_oversize, skipped_other, error
• CacheStats：索引、重新分级、色度、bm25的性能指标

故障排除

快速诊断

# Run the comprehensive debug tool first!
python debug_rag.py

# This will check:
# - Environment variables (API keys)
# - Storage integrity
# - Index quality
# - Performance metrics
# - Edge cases

MCP服务器未连接

1. 验证MCP配置中的Python路径
2. 在中检查API密钥 env 章节
3. 确保 cwd 指向项目目录
4. 重新启动MCP客户端
5. 检查日志 RAG_LOG_LEVEL=DEBUG 在MCP配置中

未检索到文档

# Check if index has documents
python -c "from mcp_server import get_index_stats; print(get_index_stats())"

# If document_count is 0:
python build_index.py /path/to/your/documents

性能缓慢

# Profile retrieval performance
python debug_rag.py --profile

# Check cache efficiency
python -c "from mcp_server import get_cache_stats; print(get_cache_stats())"

# If cache hit rate < 90% after multiple queries:
# - Check MCP client logs for server restarts
# - Server should stay running between queries

相关性差

• 尝试 iterative_search() 而不是 query_rag() 为了更好地改进
• 检查结果中的相关性得分（匹配良好时应大于0.7）
• 使用多轮搜索：从3个结果开始，根据结果进行优化
• 增加 similarity_top_k 获得更多候选人

添加新文档

# Just re-run the same command - it will only process new/modified files
python build_index.py /path/to/your/documents

# Force full rebuild if needed
python build_index.py /path/to/your/documents --rebuild

增量更新检测到：

• 添加到目录中的新文件
• 已修改的文件（基于修改时间和文件大小）
• 自动跳过未更改的文件

何时使用 --rebuild:

• 更改嵌入模型
• 损坏的索引
• 想要从索引中删除已删除的文件

调试日志记录

添加到MCP配置中：

"env": {
  "OPENAI_API_KEY": "...",
  "COHERE_API_KEY": "...",
  "RAG_LOG_LEVEL": "DEBUG"
}

这将记录：

• 查询验证和参数
• 缓存命中/未命中
• 检索和重新排序详细信息
• 性能计时
• 完整的错误堆栈跟踪

技术细节

模型

设计理念

服务器仅检索文档并对其进行排名。MCP客户端的LLM生成答案，提供：

• 灵活使用任何LLM
• 降低运营成本
• 更好的上下文可见性

许可证

MIT许可证

致谢

• Llama索引
• FastMCP
• 色度数据库
• 开放人工智能
• 凝聚