# PDF Retrieval MCP Server

A **completely free** Model Context Protocol (MCP) server for retrieving relevant chunks from PDF documents using hybrid search (BM25 + Vector Search).

## 🚀 Features

- **PDF Document Processing**: Automatic parsing and indexing of PDF files using Docling
- **Hybrid Retrieval**: Combines BM25 (keyword) and vector search (semantic) for accurate retrieval
- **Free Embeddings**: Uses ChromaDB's default sentence-transformers (no API costs!)
- **Pure Retrieval Mode**: Returns raw document chunks for agent processing (no LLM answer generation)
- **Fresh Start**: Clears vector database on each startup for clean indexing
- **MCP Integration**: Exposes `retrieve_pdf_chunks` tool via FastMCP for seamless agent integration

## 📋 Prerequisites

- Python 3.11 or later
- PDF documents to index
- **No API keys required!** ✨

## 🛠️ Installation

### 1. Clone the Repository (if not already done)

```bash
git clone <repository-url>
cd pdf_mcpserver
```

### 2. Install Dependencies with uv

```bash
uv sync
```

This will automatically:
- Create a virtual environment (`.venv`)
- Install all dependencies from `pyproject.toml`
- Set up the project

### 3. Add PDF Documents

Create a `documents` directory and add your PDF files:

```bash
mkdir documents
# Copy your PDF files to the documents/ directory
```

That's it! No API keys or additional configuration needed.

## 🎯 Usage

### Running the Server

```bash
uv run python main.py
```

Or activate the virtual environment first:

```bash
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
python main.py
```

The server will:
1. Start immediately (lazy initialization)
2. Load and index PDFs on first query
3. Be ready to retrieve document chunks via MCP

### Using the `retrieve_pdf_chunks` Tool

The server exposes a single MCP tool: `retrieve_pdf_chunks(query: str, max_chunks: int = 5) -> str`

**Example Query:**
```python
retrieve_pdf_chunks("machine learning algorithms", max_chunks=3)
```

**Example Response:**
```json
{
  "query": "machine learning algorithms",
  "chunks": [
    {
      "content": "Machine learning algorithms can be categorized into supervised, unsupervised, and reinforcement learning...",
      "document_name": "ml_guide.pdf",
      "page_number": 12,
      "metadata": {"source": "ml_guide.pdf"}
    },
    {
      "content": "Common supervised learning algorithms include linear regression, decision trees, and neural networks...",
      "document_name": "ml_guide.pdf",
      "page_number": 15,
      "metadata": {"source": "ml_guide.pdf"}
    }
  ],
  "total_chunks": 2
}
```

### Response Structure

| Field | Type | Description |
|-------|------|-------------|
| `query` | string | The original search query |
| `chunks` | array | List of relevant document chunks |
| `chunks[].content` | string | The text content of the chunk |
| `chunks[].document_name` | string | Source PDF filename |
| `chunks[].page_number` | int | Page number (if available) |
| `chunks[].metadata` | object | Additional metadata |
| `total_chunks` | int | Number of chunks returned |

### How Agents Use This

When an agent (like Claude) calls this tool:
1. Agent sends a search query
2. Server returns relevant document chunks
3. Agent uses chunks in its context to answer questions

**Example Agent Flow:**
```
User: "What are the main ML algorithms discussed?"
  ↓
Agent calls: retrieve_pdf_chunks("machine learning algorithms")
  ↓
Server returns: 3 relevant chunks from PDFs
  ↓
Agent reads chunks and generates answer for user
```

## 🔍 Testing with MCP Inspector

The MCP Inspector is a web-based tool for testing and debugging MCP servers interactively.

### Running the Inspector

```bash
npx @modelcontextprotocol/inspector uv run python main.py
```

This command will:
1. Start the MCP Inspector proxy server
2. Launch your PDF Retrieval Server
3. Open a web browser with the Inspector UI

### What You'll See

The Inspector provides:
- **Tool Discovery**: View available tools (`retrieve_pdf_chunks`)
- **Interactive Testing**: Test queries with custom parameters
- **Real-time Responses**: See JSON responses in real-time
- **Request/Response Logs**: Debug the MCP protocol communication

### Example Inspector Workflow

1. **Open the Inspector** - Browser opens automatically at `http://localhost:6274`
2. **Wait for Initialization** - Server loads and indexes PDFs on first query (~1-2 minutes)
3. **Select Tool** - Click on `retrieve_pdf_chunks` in the tools list
4. **Enter Query** - Type your search query (e.g., "machine learning")
5. **Set Parameters** - Optionally adjust `max_chunks` (default: 5)
6. **Execute** - Click "Run" to see the results
7. **View Response** - Inspect the returned chunks and metadata

### Inspector Tips

- **First query is slow**: PDF indexing happens on first query (87 seconds for typical PDFs)
- **Subsequent queries are fast**: Embeddings are cached in ChromaDB
- **Fresh start**: Server clears ChromaDB on each restart for clean indexing
- **Check logs**: Terminal shows detailed logging of the indexing process


## 🏗️ Architecture

```
pdf_mcpserver/
├── src/
│   ├── config.py              # Configuration management
│   ├── constants.py           # Configuration constants
│   ├── models.py              # Pydantic response models
│   ├── pdf_processor.py       # PDF loading and hybrid retrieval
│   └── retrieval_handler.py   # Document chunk retrieval
├── main.py                    # MCP server entry point
├── pyproject.toml             # Project metadata
└── .env                       # Environment configuration
```

### Key Components

- **PDFProcessor**: Singleton class that loads PDFs, converts to Markdown using Docling, and builds hybrid retriever (BM25 + Vector Search)
- **RetrievalHandler**: Retrieves relevant chunks for queries - no LLM answer## 🔧 Configuration

Configuration is managed through environment variables. Create a `.env` file in the project root:

```bash
# Optional: PDF Documents Directory (defaults to ./documents)
PDF_DOCUMENTS_DIR=./documents

# Optional: ChromaDB Directory (defaults to ./chroma_db)
CHROMA_DB_DIR=./chroma_db

# Optional: Log Level (defaults to INFO)
LOG_LEVEL=INFO
```

### Configuration Options

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PDF_DOCUMENTS_DIR` | No | `./documents` | Directory containing PDF files to index |
| `CHROMA_DB_DIR` | No | `./chroma_db` | Directory for ChromaDB vector storage |
| `LOG_LEVEL` | No | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |

**Note**: No API keys required! ChromaDB uses free local embeddings (sentence-transformers).

## 🧪 Testing

Run unit tests:

```bash
uv run pytest tests/
```

## 📝 Troubleshooting

### No PDF files found

**Error**: `No PDF files found in ./documents`

**Solution**: Add PDF files to the `documents/` directory or update `PDF_DOCUMENTS_DIR` in `.env`

### Import errors

**Error**: `ModuleNotFoundError: No module named 'docling'`

**Solution**: Ensure all dependencies are installed: `uv sync`

### CUDA out of memory

**Error**: `CUDA out of memory`

**Solution**: The server is configured to use CPU-only mode. If you still see this error, check that `CUDA_VISIBLE_DEVICES=""` is set in `src/pdf_processor.py`

## 📚 Dependencies

- **fastmcp**: MCP server framework
- **docling**: Document processing and parsing
- **chromadb**: Vector database with free sentence-transformers embeddings
- **langchain**: RAG framework and retrievers
- **loguru**: Logging

**No paid APIs required!** All embeddings are generated locally using ChromaDB's default model (all-MiniLM-L6-v2).

## 🤝 Contributing

This is a Proof of Concept (PoC) implementation. For production use, consider:
- Adding caching for processed documents
- Implementing multi-agent workflow with fact verification
- Supporting additional document formats (DOCX, TXT, etc.)
- Adding authentication and rate limiting

## 📄 License

[Your License Here]

## 🙏 Acknowledgments

Based on the [docchat-docling](https://github.com/HaileyTQuach/docchat-docling) architecture.