Metadata-Version: 2.4
Name: carrot-mcp-pdf
Version: 0.2.2
Summary: Carrot MCP PDF Server
Requires-Python: >=3.10
Requires-Dist: litellm>=1.90.0
Requires-Dist: mcp>=1.28.0
Requires-Dist: pymupdf4llm>=1.27.2.3
Description-Content-Type: text/markdown

# carrot-mcp-pdf

Carrot MCP PDF Server — convert PDFs to structured markdown with optional OCR.

## Installation

```bash
uv sync --all-packages
```

## Usage

```bash
# Run as MCP server
uv run carrot-mcp-pdf

# Or via main CLI
uv run carrot-mcp pdf

# Or as Python module
uv run python -m carrot_mcp_pdf
```

## Tools

| Tool | Description |
|------|-------------|
| `version` | Get server version info |
| `get_toc` | Get table of contents with page ranges |
| `get_pages` | Convert specific pages to markdown (supports multimodal/OCR/force_ocr) |
| `grep` | Search for exact substring in PDF pages. Case-insensitive by default, or regex. Returns matches with page number, text, and surrounding context. |

## Architecture

```
Application Layer (server.py — MCP tools, thin routing)
    ↓ get_toc/get_pages
Conversion Layer (converter.py — pymupdf4llm → markdown + images)
    ↓ force_ocr=True
OCR Layer (ocr.py — litellm vision API)
    ↓ multimodal=False
Cache Layer (cache.py — JSON: %APPDATA%/carrot-mcp/pdf/<md5>.json)
```

- **server.py** — MCP tool definitions only, delegates to converter/cache
- **converter.py** — PDF conversion, image processing, content parsing, VLM config
- **ocr.py** — Vision model OCR via litellm (single responsibility)
- **cache.py** — Cache persistence, path management, parse_page_range

- **Cache**: `%APPDATA%/carrot-mcp/pdf/<md5>.json`
- **Dual format**: each page caches both `content` (images as base64 strings) and `ocr_content` (OCR text or images)
- **Force OCR**: PDF-level flag — renders page as image and OCRs it; if VLM not configured, falls back to returning the rendered image
- **Image return**: images returned as MCP `ImageContent` attachments (no base64 truncation)

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `CARROT_MCP_MODEL` | — | Vision model name for OCR (must be configured if using OCR) |
| `CARROT_MCP_APIKEY` | — | API key for the vision model (must be configured if using OCR) |
| `CARROT_MCP_PROXY` | — | HTTP proxy URL for API calls |
| `CARROT_MCP_FORCE_MULTIMODAL` | — | `true` = always return images as MCP ImageContent attachments; `false` = always run OCR. When not set, uses tool parameter. If VLM not configured (no model/apikey), falls back to attachments with warning. |

## Development

```bash
# Run tests
uv run pytest tests/pdf/ -v
```
