# Paper Reader MCP

[English](README.md) | [简体中文](README.zh-CN.md)

Paper Reader MCP is a local, read-only Model Context Protocol server for evidence-first analysis of research papers and slide decks. It supports PDF, DOCX, PPT, and PPTX files while minimizing tool round trips, repeated context, and unnecessary visual tokens.

The default pipeline is MarkItDown text extraction plus original whole-page native vision. A single `paper_batch_search` call returns both compact text and labeled MCP image content. The calling vision-capable model reads the attached pages. Docling is an explicitly selected alternative, not the default.

Version **0.7.1**: [download the installable wheel or source package](releases/v0.7.1/README.md), [changes](CHANGELOG.md), and [60-question evaluation](docs/evaluation/2026-10-14/README.md). Visual calls may be repeated as needed; page and pixel limits apply per call.

## Highlights

- **Token-efficient retrieval:** one `paper_batch_search` call handles up to 32 questions and returns a deduplicated evidence bank.
- **Long-document support:** adaptive context budgets, ranked chunks, exact numbered-reference routing, and compact wide-table serialization.
- **Native vision inputs:** labeled source images, with standard (500k/image, 1.3M/batch) and high (2M/image, 4M/batch) pixel budgets. High detail protects dense formulas and tiny chart labels.
- **Integrated native reading:** MarkItDown preserves original PDF page boundaries, including empty pages; the same batch call attaches whole pages independently of precise layout detection or OCR.
- **Evidence traceability:** results retain source page or slide references and stable evidence identifiers.
- **Local and read-only:** source documents are never modified or uploaded by the server.
- **Verified source cache:** text and images use the same retained source snapshot; replacing or deleting the original cannot silently change visual evidence.
- **Weak-model oriented:** the retrieval contract is designed to reduce planning and tool-loop errors in smaller models.

## Supported formats

| Format | Pipeline | Notes |
|---|---|---|
| PDF | MarkItDown + original whole-page MCP images | Native client vision reads tables, plots, formulas and scans |
| DOCX | MarkItDown + embedded images | Section provenance; no fabricated pagination |
| PPTX | MarkItDown + embedded images | Slide references; images do not reproduce full-slide layout |
| PPT | PowerPoint or LibreOffice conversion, then MarkItDown | Requires PowerPoint on Windows or LibreOffice |

## MCP tools

| Tool | Intended use |
|---|---|
| `paper_batch_search` | Primary entry point; text plus labeled whole-page native images in one round trip; `include_visual=true`, `detail=high` by default |
| `paper_search` | One focused follow-up when the batch result reports a genuine evidence gap |
| `paper_ingest` | Explicit pre-ingestion and outline generation |
| `paper_visual` | Render one exact region or a batched set of evidence crops for visual verification |

```text
local document
    -> content hash and cache lookup
    -> immutable source snapshot + MarkItDown conversion
    -> one batch call: Markdown evidence AND labeled original page images
    -> native model reads attached images
    -> repeat focused visual calls for missing, failed, unreadable or newly located evidence
    -> page/slide-grounded answer
```

## Installation

Python 3.10–3.12 is required. Python 3.10 is the tested version.

```powershell
git clone https://github.com/oylx666/paper-reader-mcp.git
cd paper-reader-mcp
py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
```

Only for the optional `PAPER_READER_BACKEND=docling` backend, download local models once:

```powershell
.\.venv\Scripts\docling-tools.exe models download layout tableformer rapidocr `
  --output-dir "$env:USERPROFILE\.cache\paper-reader-models"
```

Default reading needs no Docling model downloads or local GPU. `auto` is an alias for the MarkItDown native-page workflow. Select `docling` explicitly for layout/TableFormer/OCR; the server never downloads missing models during reading.

## MCP configuration

Add a STDIO server entry to your MCP client, using absolute paths:

```json
{
  "mcpServers": {
    "paper-reader": {
      "command": "C:\\path\\to\\paper-reader-mcp\\.venv\\Scripts\\paper-reader-mcp.exe",
      "env": {
        "PAPER_READER_MODELS": "C:\\Users\\YOUR_NAME\\.cache\\paper-reader-models"
      }
    }
  }
}
```

Ask questions naturally and include the local document path. The batch tool automatically attaches original PDF pages. Clients must support MCP image content; a text-only client cannot perform native visual reading.

## Configuration

| Variable | Default | Values / purpose |
|---|---|---|
| `PAPER_READER_CACHE` | `%LOCALAPPDATA%\paper-reader-mcp` | Cache directory |
| `PAPER_READER_BACKEND` | `auto` | `auto` or `markitdown`: MarkItDown + native whole-page images; `docling`: explicit structured backend |
| `PAPER_READER_MODELS` | `~\.cache\paper-reader-models` | Offline Docling model directory |
| `PAPER_READER_PDF_PIPELINE` | `standard` | `standard` or reduced-quality emergency mode `native` |
| `PAPER_READER_TABLE_MODE` | `fast` | `fast` or `accurate`; `fast` is recommended by the local A/B test |
| `PAPER_READER_OCR_MODE` | `auto` | `auto`, `always`, or `off` |
| `PAPER_READER_FORMULA_MODEL` | `off` | `off`, `codeformulav2`, or `granite_docling` |

## Native visual review

The local MCP server extracts text and returns actual images; the calling vision-capable model reads them. It does not call a hosted model or reuse the client's account credentials. MarkItDown is not OCR, and a figure caption is not evidence for plotted values.

Since 0.7.1, `paper_batch_search` returns structured evidence plus actual MCP `ImageContent` blocks in the same response. `attached_images` maps each image to its original page. It attaches up to six unique retrieved pages, bounded to 4M pixels total and 2M per image in the default high profile. `visual_pages_omitted` and `visual_errors` explicitly expose incomplete attachments; unreadable small text still needs a focused follow-up. `include_visual=false` is an explicit text-only opt-out. `all_questions_covered` remains lexical only, not semantic or visual completeness.

Example primary call:

```json
{"path": "C:\\papers\\paper.pdf", "questions": ["Read Table 2 and Equation (1)"]}
```

For a missing or unreadable page, use `paper_visual`:

```json
{"paper_id": "<returned ID>", "evidence_ids": ["<id1>", "<id2>"], "detail": "high"}
```

For scans or MarkItDown full-page evidence, use `page_numbers: [1, 2]` instead of `evidence_ids`. Evidence spanning several pages is labeled explicitly; an evidence-ID batch displays its first page only. Extra focused requests are permitted for missing pages or unreadable details. Pixel limits apply to whole pages and Office assets too, and resolution profiles use separate image caches.

Fast PDF conversion splits the source into original pages before conversion, preserving blank pages and reliable citations. It lacks precise region geometry, layout validation and OCR; sparse pages remain flagged for original-image review. Fast DOCX conversion provides section evidence and real embedded image files, with no invented page numbers. Fast PPTX retains original slide boundaries and raster assets, but embedded assets do not reconstruct full slide layout.

Version 0.7.1 uses cache profile v8 and stores a verified source snapshot. Visual rendering verifies its SHA-256 even before an image-cache hit. Legacy caches without a verified snapshot require re-ingestion before visual reading; original inputs remain untouched. Shared table excerpts prioritize a matching row for each question; final serialized engine output respects its character budget, reports dropped evidence as gaps, or rejects routing that cannot fit. Restart/reconnect an already-running MCP server after upgrading. Cold conversions run in a separate worker capped at 840 seconds. Optional Docling RapidOCR uses Torch checkpoints; its automatic OCR heuristic remains imperfect for mixed image/text documents.

## 2026-10-14 controlled comparison

Four PDFs (31 pages), 30 frozen questions, one stateless `gpt-6.1-sol` high-reasoning reader per profile. Before changing defaults, 0.7.0 Docling CPU/GPU profiles both scored 25/30; MarkItDown text alone scored 21/30; 0.7.0 MarkItDown with separately fetched native pages scored 30/30. A fresh production-launcher acceptance run scored 30/30 for 0.7.1's integrated single-call path on the same documents. These are sample-specific results, not general accuracy or modality-token claims.

## Expanded 60-question evaluation

The expanded 60-question evaluation scored **60/60 after follow-up reading**, including the negative control; the first-round diagnostic scored **56/60**. The completed workflow used two additional `paper_visual` calls in this sample, with no total call limit. Other MCP profiles were evaluated only with their preset initial evidence, so their scores do not establish a completed-workflow ranking. See the [method, limitations and measured costs](docs/evaluation/2026-10-14/README.md).

## Historical evaluation results

The older tests below used `gpt-5.6-luna` with low reasoning effort so retrieval and tool-use weaknesses could not be hidden by a stronger model.

### Fifteen-question paper stress test

| Pipeline | Correctness | Gross input tokens | Output tokens | Traceable page coverage | Cold conversion |
|---|---:|---:|---:|---:|---:|
| **Paper Reader MCP** | **56/60 (93.33%)** | 227,113 | 3,925 | **15/15** | 22.32 s |
| Docling Markdown | 54/60 (90.00%) | **30,722** | **2,017** | 0/15 | 85.56 s |
| MarkItDown Markdown | 55/60 (91.67%) | 43,646 | 2,651 | 0/15 | **2.40 s** |
| Raw PDF workflow | 54/60 (90.00%) | 240,665 | 4,221 | **15/15** | 0 s |

The original implementation used 13 retrieval calls. The current batch-first interface starts with one retrieval call, followed by as many focused `paper_visual` calls as needed to obtain sufficient readable evidence. The six-image and pixel budgets apply per call; they do not limit total calls. Omitted, failed, unreadable or newly identified evidence pages may require multiple batches, single-page reads or crops. Gross token counts above describe the conservative pre-batching stress run and are not the optimized lower bound.

### TableFormer A/B on 16 manually reviewed paper tables

| Mode | Weight size | Exact table shapes | Numeric recall | Total full-document time |
|---|---:|---:|---:|---:|
| **fast** | **138.7 MB** | **16/16** | **100%** | **81.92 s** |
| accurate | 202.9 MB | 13/16 | 99.76% | 82.87 s |

The reviewed reference was initially produced by the fast model and then manually checked, so this comparison may still favor that model. A fully independent cell-level HTML corpus and TEDS evaluation would be required for an unbiased model benchmark.

Visual input tokens are not reported because the platform did not expose modality-level token usage. Pixel counts were measured instead; missing visual-token telemetry must not be interpreted as zero usage. These historical benchmarks do not measure the version 0.7 hybrid implementation, and must not be read as a new accuracy or speed claim.

## Accuracy limits

- Reading order on complex multi-column pages is inferred and can be wrong.
- OCR output is unsuitable as sole evidence for exact quotations, formulas, subscripts, or very small table cells.
- Merged cells, dense tables, and chart markers should be verified against rendered source regions.
- Formula decoding is not proof of mathematical correctness; formula evidence remains visually verifiable.
- Office slide/page numbers are parser-derived and may differ from application UI numbering.
- The `native` PDF pipeline sacrifices layout, table, and OCR quality and is intended only as an emergency fallback.

## Development

```powershell
.\.venv\Scripts\python.exe -m pip install -e . pytest
.\.venv\Scripts\pytest.exe -q
```

The test suite covers validation, cache isolation, parser fallback, empty page/slide preservation, missing numbered references, native image labels, pixel budgets, and supported Office assets.

## Status

This is an experimental research tool. Treat its output as retrieval evidence, not as an authoritative interpretation of a paper.