PDF RAG MCP Server

A Model Context Protocol (MCP) server that provides powerful RAG (Retrieval-Augmented Generation) capabilities for PDF documents. This server uses ChromaDB for vector storage, sentence-transformers for embeddings, and semantic chunking for intelligent text segmentation.

Features

• Semantic Chunking: Intelligently groups sentences together instead of splitting at arbitrary character limits
• Vector Search: Find semantically similar content using embeddings
• Keyword Search: Traditional keyword-based search for exact terms
• OCR Support: Automatic detection and OCR processing for scanned/image-based PDFs
• Source Tracking: Maintains document names and page numbers for all chunks
• Add/Remove PDFs: Easily manage your document collection
• Persistent Storage: ChromaDB persists your embeddings to disk
• Multiple Output Formats: Get results in Markdown or JSON format
• Progress Reporting: Real-time feedback during long operations

Architecture

• Embedding Model: multi-qa-mpnet-base-dot-v1 (optimized for question-answering)
• Vector Database: ChromaDB with cosine similarity
• Chunking Strategy: Semantic chunking with configurable sentence grouping and overlap
• PDF Extraction: PyMuPDF for text extraction with OCR fallback for scanned PDFs

Installation

From Source

1. Clone the repository:

git clone <repository-url>
cd pdfrag

1. Install the package:

pip install -e .

1. Verify installation:

pdfrag --help
pdfrag-cli --help

NLTK Data (Automatic)

The server automatically downloads required NLTK punkt tokenizer data on first run.

Tesseract (Optional - for OCR)

For scanned PDF support, install Tesseract:

• macOS: brew install tesseract
• Ubuntu/Debian: sudo apt-get install tesseract-ocr
• Windows: Download from https://github.com/UB-Mannheim/tesseract/wiki

The server automatically detects scanned pages and uses OCR when Tesseract is available.

Configuration

Database Location

The server stores its ChromaDB database in a configurable location. You can specify the database path using the --db-path command line argument:

# Use default location (~/.dotfiles/files/mcps/pdfrag/chroma_db)
pdfrag

# Use custom database location
pdfrag --db-path /path/to/your/database

Chunking Parameters

Default chunking settings:

• Chunk Size: 3 sentences per chunk
• Overlap: 1 sentence overlap between chunks

These can be customized when adding PDFs:

{
  "pdf_path": "/path/to/document.pdf",
  "chunk_size": 5,      # Use 5 sentences per chunk
  "overlap": 2          # 2 sentences overlap
}

Character Limit

Responses are limited to 25,000 characters by default. If exceeded, results are automatically truncated with a warning message.

Project Structure

pdfrag/
 src/pdfrag/          # Main package
    server.py        # FastMCP server with 5 tools
    database.py      # ChromaDB interface
    embeddings.py    # Embedding generation
    pdf.py           # PDF text extraction
    chunking.py      # Semantic chunking
    cli.py           # MCP CLI tool
 tests/               # Test suite
 docs/                # Documentation
 examples/            # Configuration examples
 pyproject.toml       # Package configuration

MCP Tools

1. pdf_add

Add a PDF document to the RAG database.

Input:

{
  "pdf_path": "/absolute/path/to/document.pdf",
  "chunk_size": 3,  // optional, default: 3
  "overlap": 1      // optional, default: 1
}

Output:

{
  "status": "success",
  "message": "Successfully added 'document.pdf' to the database",
  "document_id": "a1b2c3d4...",
  "filename": "document.pdf",
  "pages": 15,
  "chunks": 127,
  "chunk_size": 3,
  "overlap": 1
}

Example Use Cases:

• Adding research papers for reference
• Indexing documentation
• Building a searchable knowledge base

2. pdf_remove

Remove a PDF document from the database.

Input:

{
  "document_id": "a1b2c3d4..."  // Get from pdf_list
}

Output:

{
  "status": "success",
  "message": "Successfully removed 'document.pdf' from the database",
  "document_id": "a1b2c3d4...",
  "removed_chunks": 127
}

3. pdf_list

List all PDF documents in the database.

Input:

{
  "response_format": "markdown"  // or "json"
}

Output (Markdown):

# PDF Documents (2 total)

## research_paper.pdf
**Document ID:** a1b2c3d4...
**Chunks:** 127
**Added:** N/A

## documentation.pdf
**Document ID:** e5f6g7h8...
**Chunks:** 89
**Added:** N/A

Output (JSON):

{
  "count": 2,
  "documents": [
    {
      "document_id": "a1b2c3d4...",
      "filename": "research_paper.pdf",
      "chunk_count": 127
    },
    {
      "document_id": "e5f6g7h8...",
      "filename": "documentation.pdf",
      "chunk_count": 89
    }
  ]
}

4. pdf_search_similarity

Search using semantic similarity (vector search).

Input:

{
  "query": "machine learning techniques for text classification",
  "top_k": 5,                    // optional, default: 5
  "document_filter": null,       // optional, search specific doc
  "response_format": "markdown"  // optional, default: markdown
}

Output (Markdown):

# Search Results for: 'machine learning techniques for text classification'

Found 5 relevant chunks:

## Result 1
**Document:** research_paper.pdf
**Page:** 7
**Similarity Score:** 0.8754

**Content:**
Machine learning approaches to text classification have evolved significantly...

---

Use Cases:

• Finding relevant information without exact keywords
• Discovering related concepts
• Question answering over documents

5. pdf_search_keywords

Search using keyword matching.

Input:

{
  "keywords": "neural network backpropagation",
  "top_k": 5,                    // optional, default: 5
  "document_filter": null,   …