Content
# Modular RAG MCP Server
> A pluggable, observable modular RAG (Retrieval-Augmented Generation) service framework
[](LICENSE)
[](https://www.python.org/)
---
## 🔧 Project Features
This project is an **enterprise-level intelligent question answering and knowledge retrieval system** that can be applied to the following scenarios:
- **📖 Document Q&A**: Supports intelligent Q&A for multi-format documents such as PDF, Markdown, and code files, quickly extracting precise answers from massive documents
- **🔍 Semantic Search**: Based on hybrid retrieval technology, it provides more intelligent semantic understanding capabilities than traditional keyword search
- **💡 Knowledge Base Construction**: Transforms internal enterprise documents and technical materials into searchable knowledge bases, improving team collaboration efficiency
- **🤖 AI Assistant Integration**: Through the MCP (Model Context Protocol) protocol, it can seamlessly connect to AI assistants such as Claude and GitHub Copilot
- **🎯 Personalized Applications**: Can be extended into vertical field applications such as customer service robots, technical documentation assistants, and code search engines
> 💼 **Interview Weapon**: The modular design and complete implementation of this project can be directly used as a resume project display, covering the core knowledge points of the RAG technology stack, and is an excellent project case for large model/AI engineer interviews.
---
## 🎯 Project Features
### 1️⃣ **Pluggable Architecture**
- **Flexible LLM Backend Switching**: Supports multiple backends such as Azure OpenAI, OpenAI API, and local models (Ollama/vLLM), and can be switched with one click through configuration files without any code modification
- **Free Replacement of Model Components**: Core components such as Embedding models, Rerank models, document parsers, and segmentation strategies all adopt abstract interface designs, supporting "Lego-style" combination
- **Configurable Retrieval Strategies**: Supports dynamic configuration of multiple modes such as pure vector retrieval, BM25 keyword retrieval, and hybrid retrieval
### 2️⃣ **Full-Link Observable**
- **Structured Log Tracking**: Each module outputs detailed structured logs for easy problem location and performance analysis
- **Evaluation Metric System**: Integrates Ragas/DeepEval and other RAG evaluation frameworks to quantify retrieval quality and generation effect
- **Monitoring and Debugging Friendly**: Provides complete request link tracking and supports real-time performance monitoring
### 3️⃣ **MCP Protocol Integration (Model Context Protocol)**
- **Standardized Interface**: Fully implements the MCP protocol specification and can seamlessly connect to MCP-supported AI assistants such as Claude Desktop and GitHub Copilot
- **Out-of-the-Box**: Exposes RAG capabilities through the MCP Server, allowing AI assistants to directly call the project's retrieval and Q&A functions without additional development
- **Tooling Package**: Encapsulates the RAG process into MCP Tools, allowing AI to autonomously decide when to call retrieval and how to combine multiple tools to complete complex tasks
- **Context Enhancement**: Provides real-time knowledge base support for AI conversations, enabling general-purpose large models to have domain expertise
### 4️⃣ **Engineering RAG Practice**
- **Intelligent Chunking Strategy**: Semantic-aware document segmentation, retaining complete semantic units
- **Hybrid Search**: BM25 + Dense Embedding fusion, balancing precision and recall
- **Two-Stage Fine Ranking**: Coarse-grained recall → Rerank fine ranking, achieving optimal balance between performance and accuracy
---
## 📚 AI-Driven Development: Let AI Become Your Collaboration Partner
### 💡 Core Concept
> **"Documents are specifications, implementation is handed over to AI"**
This project adopts an innovative **AI collaborative development model**, allowing you to focus on architecture design and business logic, and efficiently delegate code implementation to AI:
#### ✨ Project Features
- **Complete Skills System**: Through carefully designed Markdown skill files (`.github/skills/`), AI can understand project specifications, follow best practices, and automatically complete code implementation
- **VibeCoding Practice**: Master the latest AI collaborative development techniques (VibeCoding), describe requirements in natural language, and let AI automatically generate code that meets specifications
- **Specification-Driven Development**: `DEV_SPEC.md` serves as the project's "constitution", defining core specifications such as architecture, module design, and technology selection, and AI strictly follows the document to complete coding
- **Quick Start with Zero Background**: Even if you are not familiar with the RAG technology stack, you only need to understand the document and modify the requirement description, and AI will automatically transform your ideas into production-level code
#### 🚀 Workflow
```
1. 📝 Understand the document (DEV_SPEC.md) → Master the project design concept and technical architecture
2. ✏️ Modify the specification document → Adjust the design plan or add new modules according to requirements
3. 🤖 Call Skills to AI → Use skills such as dev-workflow and implement to let AI complete coding
4. ✅ Verification and iteration → Review code, run tests, and continuously optimize
```
#### 📖 Supporting Resources
This project provides **three-in-one** learning resources to help you quickly master the AI collaborative development model:
| Resource Type | Content Description |
|---------|---------|
| 📄 **Detailed Technical Documentation** | `DEV_SPEC.md` provides complete architecture design, technology selection, and module details |
| 💻 **Skills Workflow** | `.github/skills/` contains AI skills such as spec-sync, implement, and testing, guiding AI to complete development tasks |
| 🎬 **Video Tutorials** | Full practical demonstration from environment setup to core module implementation |
> 💡 **Hint**: For detailed design concepts, technology selection, and module design, please refer to [DEV_SPEC.md](DEV_SPEC.md)
### 🎁 What You Will Gain
By learning and practicing this project, you will master:
#### 🔥 **The Latest AI Collaboration Skills**
- **Skills Engineering**: Learn to build reusable AI skill libraries and let AI become your "programming assistant"
- **VibeCoding Techniques**: Master the development model of efficient collaboration with AI and improve development efficiency by 10 times
- **Document-Driven Development**: Understand how to guide AI to complete complex engineering projects through specification documents
#### 🎯 **RAG Technology Full-Stack Capabilities**
- **In-Depth Every Detail**: From document parsing, intelligent chunking, vectorization, hybrid retrieval to Rerank reordering, master every link in the RAG chain one by one
- **Engineering Practice**: Not only theory, but also production-level code implementation, understand how to implement paper technology into actual projects
- **Performance Optimization**: Learn how to balance retrieval speed and accuracy, optimize Embedding strategies, and tune Rerank models
#### 💼 **Interview Competitiveness Improvement**
- **Resume Project Bonus**: This project covers the core technology stack of large model/AI engineer positions and can be directly written into the resume as a highlight project
- **Interview Question Response**: The supporting interview question bank helps you deal with frequently asked questions such as "How to optimize the recall rate of RAG" and "How to choose an Embedding model"
- **Technical Depth Display**: Modular design, pluggable architecture and other engineering practices demonstrate your system design capabilities
---
## 🎓 Learning Resources and Community
### 📺 Supporting Video Tutorials
This project provides **comprehensive video explanations**, covering:
- ✅ **In-Depth Analysis of RAG Core Technologies**: From chunking strategies, hybrid retrieval to Rerank reordering, comprehensively deconstructing RAG technical details
- ✅ **Code Practice Line-by-Line Explanation**: Environment configuration, module implementation, performance optimization, take you to complete the project step by step
- ✅ **Analysis of Real Interview Questions for Large Models**: Selected interview questions from major manufacturers, combined with project practice to explain problem-solving ideas
- ✅ **Career Transition Job Search Guide**: Resume writing skills, interview preparation strategies, career planning advice
**🎬 Get video tutorials and more resources:**
- 🔍 Search on Xiaohongshu: **不转到大模型不改名**
- 🆔 Xiaohongshu ID: **4740535877**
### 🎁 Additional Benefits
Continuously updated content:
- 📝 **Resume Template Based on This Project**: How to write technical highlights into your resume
- 🎤 **Collection of Common Interview Questions**: Frequently asked interview questions and reference answers for RAG projects
- 💼 **Job Search Experience Sharing**: The complete path from technical learning to getting an Offer
---
## 🚀 Quick Start
```bash
# Clone the project
git clone https://github.com/yourusername/Modular-RAG-MCP-Server.git
cd Modular-RAG-MCP-Server
# Install dependencies
pip install -r requirements.txt
# Configure environment variables (copy the configuration template)
cp .env.example .env
# Edit the .env file and fill in your API Keys
# Run the service
python src/main.py
```
For detailed environment configuration, deployment guide and usage examples, please refer to [DEV_SPEC.md](DEV_SPEC.md).
---
## 📂 Project Structure
```
.
├── DEV_SPEC.md # Core design document (project "constitution")
├── .github/
│ └── skills/ # AI collaborative development skill library
│ ├── spec-sync/ # Specification synchronization
│ ├── implement/ # Code implementation
│ ├── testing-stage/ # Test verification
│ └── ...
├── src/ # Source code
│ ├── retrieval/ # Retrieval module (Hybrid Search, Rerank)
│ ├── generation/ # Generation module (LLM call)
│ ├── pipeline/ # RAG process orchestration
│ └── ...
├── tests/ # Test cases
└── docs/ # Supplementary documentation
```
---
## 🤝 Contribution Guide
Welcome to submit Issues and Pull Requests! Before contributing code, please:
1. Read [DEV_SPEC.md](DEV_SPEC.md) to understand the project architecture and design concepts
2. Follow the project's code specifications (see the "Development Specifications" section in `DEV_SPEC.md`)
3. Ensure that the tests pass (`pytest tests/`)
---
## 📄 License
[MIT License](LICENSE)
---
## 🌟 Star History
If this project is helpful to you, welcome to Star ⭐️ to support!
---
**📢 Follow my Xiaohongshu: 不转到大模型不改名 (ID: 4740535877)**
Get more RAG technology sharing, interview experience and career development advice 🚀
Connection Info
You Might Also Like
Filesystem
Node.js MCP Server for filesystem operations with dynamic access control.
Sequential Thinking
A structured MCP server for dynamic problem-solving and reflective thinking.
Fetch
Retrieve and process content from web pages by converting HTML into markdown format.
Context 7
Context7 MCP provides up-to-date code documentation for any prompt.
context7-mcp
Context7 MCP Server provides natural language access to documentation for...
chrome-devtools-mcp
Chrome DevTools for coding agents