Content
# Tool List
## Overview
The RAG MCP Server is a document-based retrieval augmented generation (RAG) system that provides document question-answering services through the MCP (Model Context Protocol).
## Project Introduction
This project involves parsing documents, storing vectors, and exposing tools through the MCP server to enable intelligent retrieval based on document content.
**Core Features**:
- Each book is stored as an independent collection, with no interference between collections
- Intelligent fuzzy matching query, supporting automatic keyword location in books
- High-performance retrieval, optimized for 2C2G servers
- Support for multiple document formats (EPUB/PDF/TXT/Markdown)
## Technical Architecture
```
┌─────────────┐ ┌─────────────┐ ┌──────────────┐
│ Document Files │────>│ Parsing + Chunking │────>│ Chroma DB │
└─────────────┘ └─────────────┘ │ Multi-Collection │
└──────────────┘
│
▼
┌─────────────┐ ┌─────────────┐
│ MCP Client │<────│ MCP Server │
└─────────────┘ │ Smart Query │
└─────────────┘
```
## Project Structure
```
rag_mcp_server/
├── config.py # Configuration (model, chunking, vector database parameters)
├── document_parser.py # Document parser (EPUB/PDF/TXT/Markdown)
├── epub_parser.py # EPUB parser
├── text_chunker.py # Text chunker
├── vector_store.py # Vector store (Chroma + BGE embedding)
├── mcp_server.py # MCP server (HTTP mode)
├── main.py # Command-line tool (import EPUB books)
├── requirements.txt # Dependencies
└── chroma_db/ # Vector database persistence directory
```
## Supported Document Formats
- **EPUB** - E-book format, extracting chapter titles and content
- **PDF** - Supports extracting content by directory or page grouping
- **TXT** - Plain text files, automatically recognizing chapter structure
- **Markdown** - Splitting chapters by `#` titles
## Dependencies
- `chromadb` - Vector database
- `sentence-transformers` - BGE embedding model
- `pypdf` - PDF parsing
- `mcp` - MCP SDK
- `tqdm` - Progress bar
## Configuration Instructions
Configure the following parameters in `config.py`:
| Parameter | Default Value | Description |
|------|--------|------|
| EMBEDDING_MODEL | Local path | BGE-m3 embedding model path |
| EMBEDDING_DEVICE | cpu | Device (cpu/cuda/mps) |
| CHUNK_SIZE | 500 | Text block size (characters) |
| CHUNK_OVERLAP | 50 | Block overlap area |
| CHROMA_PERSIST_DIR | ./chroma_db | Vector database persistence directory |
| CHROMA_HOST | Environment variable | Remote Chroma server (optional) |
| RETRIEVAL_TOP_K | 5 | Number of retrieval returns |
## Usage
### 1. Install Dependencies
```bash
pip install -r requirements.txt
```
### 2. Start MCP Server
```bash
# Use default configuration (0.0.0.0:8080)
python mcp_server.py
# Custom port and address
python mcp_server.py --host 127.0.0.1 --port 9000
```
### 3. MCP Tools
| Tool | Description |
|------|------|
| `import_document` | Import document to vector database (each book is an independent collection, supporting EPUB/PDF/TXT/Markdown) |
| `query_rag_smart` | Smart query (supporting fuzzy matching book titles, automatically retrieving relevant books) |
| `query_rag` | Retrieve relevant documents and return context (need to specify collection) |
| `search_documents` | Search relevant documents (including similarity) |
| `clear_vector_store` | Clear vector database |
| `list_books` | List all collections and document counts |
### 4. Smart Query Example
```python
# View all imported books
list_books()
# Smart fuzzy query (recommended)
query_rag_smart(query="What is virtual memory?", book_keyword="computer")
# Automatically match books containing "computer" and retrieve from all matching books
# Precise query specifying a book
query_rag(query="What is virtual memory?", book_title="深入理解计算机系统")
```
## Command-Line Tool
Locally import documents (supporting multiple formats):
```bash
# Import document (automatically use file name as collection name)
python main.py --book your_book.epub
python main.py --book document.pdf
python main.py --book notes.txt
python main.py --book guide.md
# Specify collection name
python main.py --book your_book.epub --collection "My Book Title"
# Clear specified collection
python main.py --clear "My Book Title"
```
**Note**: Import operations are executed locally and do not go through the MCP service. The MCP service only provides query interfaces.
## Workflow
### Import Process (Local Script)
1. **Parsing**: Read documents, extract chapter titles and content
2. **Chunking**: Split long text into small blocks (default 500 characters, with 50 characters overlap)
3. **Vectorization**: Use BGE-m3 model to generate text embeddings
4. **Storage**: Store in independent Chroma collection (each book has one collection)
### Query Process (MCP Service)
1. **Smart Matching**: Fuzzy match relevant book collections based on keywords
2. **Vectorization**: Convert query text into vector
3. **Retrieval**: Retrieve most relevant document blocks in matched collections
4. **Ranking**: Rank results by similarity
5. **Return**: Return retrieval results (including book source and similarity) as context
## Performance Optimization
- **On-demand loading**: Only load matched collections for each query, saving memory
- **Smart matching**: Automatically locate target books, avoiding full search
- **Resource-friendly**: Optimized for 2C2G cloud servers, supporting multiple books online simultaneously
## Precautions
- BGE embedding model needs to be downloaded and configured locally
- Vector database data is saved in `./chroma_db` directory, with each book having one collection
- Supports remote Chroma server (configured via `CHROMA_HOST` environment variable)
- Document parsing automatically attempts multiple encodings (UTF-8, GBK, GB2312, Latin-1)
- Collection names automatically clean special characters, using file names or specified names
- Recommended to use `query_rag_smart` for smart fuzzy matching during queries
## Collection Management
```bash
# View all books (collections)
list_books()
# Delete specified book's collection
python main.py --clear "Book Title"
# Restart MCP service to load latest data
```
