PDF MCP Server

A Model Context Protocol (MCP) server for querying PDF documents using AI-powered retrieval-augmented generation (RAG).

🚀 Features

• PDF Document Processing: Automatic parsing and indexing of PDF files using Docling

• Hybrid Retrieval: Combines BM25 and vector search for accurate information retrieval

• Structured Responses: Returns JSON with answers, source citations, and confidence scores

• MCP Integration: Exposes query_pdf tool via FastMCP for seamless integration

📋 Prerequisites

• Python 3.11 or later

• OpenAI API key

• PDF documents to query

🛠️ Installation

1. Clone the Repository (if not already done)

2. Install Dependencies with uv

This will automatically:

• Create a virtual environment (.venv)

• Install all dependencies from pyproject.toml

• Set up the project

3. Configure Environment

Copy the example environment file and add your OpenAI API key:

Edit .env and set your OpenAI API key:

5. Add PDF Documents

Create a documents directory and add your PDF files:

🎯 Usage

Running the Server

Or activate the virtual environment first:

The server will:

1. Validate configuration

2. Load and index all PDF files from the documents/ directory

3. Build hybrid retriever (BM25 + Vector Search)

4. Start the MCP server

Using the query_pdf Tool

The server exposes a single MCP tool: query_pdf(question: str) -> str

Example Query:

Example Response:

Response Structure

🏗️ Architecture

Key Components

• PDFProcessor: Singleton class that loads PDFs, converts to Markdown using Docling, and builds hybrid retriever

• QueryHandler: Processes queries, retrieves relevant chunks, and generates answers using OpenAI GPT-4o-mini

• FastMCP: MCP server framework that exposes the query_pdf tool

🔧 Configuration

Environment Variables

🧪 Testing

Run unit 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

OpenAI API key missing

Error: OPENAI_API_KEY is required

Solution: Set your OpenAI API key in the .env file

Import errors

Error: ModuleNotFoundError: No module named 'docling'

Solution: Ensure all dependencies are installed: uv sync

📚 Dependencies

• fastmcp: MCP server framework

• docling: Document processing and parsing

• chromadb: Vector database for embeddings

• langchain: RAG framework

• openai: LLM provider

• loguru: Logging

🤝 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 architecture.