🎯 Precision PDF MCP Server (precision-pdf-mcp)

Pixel-Perfect PDF Form and Worksheet Filling for AI Coding Agents.
Powered by Hybrid Vector-Raster Geometry, Set-of-Marks (SoM), and Virtual Excel Grounding.

---

💡 Why Precision PDF?

Filling assignment worksheets, tax forms, and scanned PDF workbooks has always been a painful failure mode for Large Language Models (LLMs):

• ❌ The "Floating Text" Bug: LLMs guess raw (x, y) floats, causing answers to float aimlessly above or below lines.
• ❌ The "Collision" Bug: Answers smash directly into printed text (e.g., Heis going, Parentsmust, 1)wear).
• ❌ The "Scanned PDF" Blindspot: Most PDF tools rely only on vector drawings. Scanned workbooks have 0 vector lines, leaving AI completely blind.
• ❌ Multi-Line Truncation: Long answers get crammed into line 1 or truncated because the agent doesn't realize two lines are printed for that question.

Precision PDF solves this once and for all.

---

🚀 Key Innovations

[ Input PDF: Digital or Scanned Workbook ]
                    │
                    ▼
  ┌─────────────────────────────────────────────────────────┐
  │ 1. Tri-Layer Hybrid Detector                            │
  │    • Vector Lines & Rects (pdfplumber)                  │
  │    • In-Memory Morphological Line Scanner (NumPy)       │
  │      Detects physical lines in scanned images in RAM!   │
  │    • Text Anchors & Gap Numbers (1), 2., He_________)   │
  └─────────────────────────┬───────────────────────────────┘
                            │
                            ▼
  ┌─────────────────────────────────────────────────────────┐
  │ 2. Context Guards & Smart Layout                        │
  │    • Padding Guard: Auto +6pt..+10pt margin after       │
  │      printed subjects (He, You, Jenny...)               │
  │    • Multi-Line Grouping: Detects stacked lines & auto- │
  │      wraps long sentences at natural word boundaries    │
  │    • Auto-Scale Font: Scales down font to prevent crash │
  └─────────────────────────┬───────────────────────────────┘
                            │
                            ▼
  ┌─────────────────────────────────────────────────────────┐
  │ 3. Virtual Excel Matrix & Set-of-Marks (Agent View)     │
  │    • Renders Top Columns (A, B, C...) & Rows (1, 2, 3)  │
  │    • Badges targets: [S01], [S02], [S03]...             │
  │    • STRICTLY VIRTUAL: Only for the agent to inspect!   │
  └─────────────────────────┬───────────────────────────────┘
                            │
                            ▼
  ┌─────────────────────────────────────────────────────────┐
  │ 4. Clean Vector Injection (Output PDF)                  │
  │    • Baseline Snapped: Text rests 1.2pt above line      │
  │    • Centered in Boxes: Dead-center horizontally & vert │
  │    • Crisp Circles / Underlines: Vector option markers  │
  │    • ZERO GRID POLLUTION: Output PDF is 100% clean!     │
  └─────────────────────────────────────────────────────────┘

---

📦 Installation & Quickstart

Method 1: Instant Run with uvx (Recommended)

No installation required. Run directly in Claude Desktop or Cursor via uvx:

uvx precision-pdf-mcp

Method 2: Install via pip

pip install precision-pdf-mcp

Method 3: From Source (Local Development)

git clone https://github.com/zuan412/precision-pdf-mcp.git
cd precision-pdf-mcp
pip install -e .

---

🛠️ MCP Client Configuration

1. Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "precision-pdf": {
      "command": "uvx",
      "args": ["precision-pdf-mcp"]
    }
  }
}

2. Cursor IDE

Add to Cursor Settings -> MCP Servers (~/.cursor/mcp.json):

{
  "mcpServers": {
    "precision-pdf": {
      "command": "uvx",
      "args": ["precision-pdf-mcp"]
    }
  }
}

3. Antigravity / Gemini CLI / Windsurf / Cline

In your mcp_config.json:

{
  "mcpServers": {
    "precision-pdf": {
      "command": "python",
      "args": ["-m", "precision_pdf"]
    }
  }
}

---

🧰 Available MCP Tools

hpe_inspect_virtual_grid

Generates a temporary Virtual Excel Matrix inspector image with Set-of-Marks badges ([S01], [S02]...) and returns a JSON catalog of detected slots.

• Arguments:
  • pdf_path (string, required): Absolute path to the PDF.
  • page_number (int, required): 1-based page number.
  • dpi (int, optional, default: 150): Image resolution.
• Returns:
  • inspector_image_path: Path to the image for agent visual inspection.
  • slots: Dictionary of slots containing grid address (e.g. Col D, Row 14), type, baseline, and width.

hpe_fill_slots

Injects answers directly into the target PDF using Slot IDs.

• Arguments:
  • pdf_path (string, required): Absolute path to the PDF.
  • page_number (int, required): 1-based page number.
  • slot_answers_json (string, required): JSON string of answers.
    • Slot map: {"S01": "must have left", "S02": "could do"}
    • Multi-line wrap: {"S03": ["first line text", "second line text"]}
    • Option circle: {"circle_option": "A"}
    • Option underline: {"underline_option": "Shall"}
  • output_path (string, optional): Output PDF path. If omitted, safely updates in-place.
• Guarantees:
  • 100% baseline snap (rests naturally on the printed line).
  • Zero grid pollution (no rulers or badges in final output).

hpe_render_clean_verify

Renders the final, clean PDF page to an image for visual QA verification.

• Arguments:
  • pdf_path (string, required): Path to the completed PDF.
  • page_number (int, required): 1-based page number.
  • dpi (int, optional, default: 150): Output DPI.

---

🧪 Testing

Run the included unit test suite:

python -m unittest discover -s tests

---

🛡️ Zero Disk Pollution & Safety Guarantee

Precision PDF is engineered to run in memory:

• All morphological line detection and raster scanning execute in RAM via NumPy arrays and io.BytesIO.
• Temporary inspector previews use OS-standard tempfile.gettempdir()/precision_pdf or the $PRECISION_PDF_TEMP_DIR environment variable.
• Stdio JSON-RPC communication is 100% isolated: all logs, warnings, and internal debug outputs route strictly to sys.stderr.

---

📄 License

MIT License. See LICENSE for details. Built with ❤️ for the AI agent pair-programming community.