# pdfrag
## 基本信息
- Slug: `wesleygriffin-pdfrag`
- Source: modelscope
- Publisher: @wesleygriffin/pdfrag
- Categories: rag-systems / vector-databases / documentation-access
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@wesleygriffin/pdfrag
## 简介
暂无描述。
## 安装提示

```bash
git clone <repository-url> cd pdfrag ``` 2. Install the package: ```bash pip install -e .
```

## MCP Server 详情

# 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:
```bash
git clone <repository-url>
cd pdfrag
```

2. Install the package:
```bash
pip install -e .
```

3. Verify installation:
```bash
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:

```bash
# 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:

```python
{
  "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:**
```json
{
  "pdf_path": "/absolute/path/to/document.pdf",
  "chunk_size": 3,  // optional, default: 3
  "overlap": 1      // optional, default: 1
}
```

**Output:**
```json
{
  "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:**
```json
{
  "document_id": "a1b2c3d4..."  // Get from pdf_list
}
```

**Output:**
```json
{
  "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:**
```json
{
  "response_format": "markdown"  // or "json"
}
```

**Output (Markdown):**
```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):**
```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:**
```json
{
  "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):**
```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:**
```json
{
  "keywords": "neural network backpropagation",
  "top_k": 5,                    // optional, default: 5
  "document_filter": null,   …