pdfproof-mcp

pdfproof-mcp is a framework-agnostic MCP server and Python engine for validating structured JSON, Excel, or CSV test data against PDF documents. It resolves records through an ordered, configurable hierarchy and returns deterministic evidence, structured results, and an HTML report.

The published distribution is named pdfproof-mcp; its Python import package is pdfproof.

The project is intentionally not a general PDF-to-Excel converter, browser automation tool, or LLM-based validation system.

Current status

The deterministic core and MCP integration are implemented. The approved architecture and implementation sequence are in PLAN.md.

Core guarantee

Each locator narrows only the candidates left by the preceding locator. The engine never searches an expected field across the entire document after a record has been resolved, and never silently selects among ambiguous candidates.

Test-data formats

JSON, multi-sheet Excel, and simple tabular CSV inputs normalize into the same test suite. Each user-defined record_id links its locators and validations, but is never an implicit PDF search key. See the test-data schema for the JSON example, Excel sheet design, CSV guidance, and the locator-versus-validation distinction. Canonical fields use stable machine keys with optional report labels; financial values use Decimal precision.

Usage modes

For batch testing, pass test_data_path pointing to JSON, Excel, or CSV. For interactive use, an AI host/client can convert a user request into direct structured test_data for the same validate_document tool. Both paths use one canonical model and one deterministic validation engine; the server does not parse natural language. See MCP usage.

MCP server

Start the stdio server from C:\pdfproof-mcp:

.venv\Scripts\python.exe -m pdfproof.server

The primary validate_document tool accepts exactly one of test_data_path (JSON, Excel, or CSV) and direct structured test_data (a TestSuite or TestRecord). Both use the same canonical input, PDF extraction, hierarchical resolution, validation, and HTML reporting path. See MCP documentation for the contract, examples, resources, and error handling.

Example file-driven call:

{"pdf_path": "sample_statement.pdf", "test_data_path": "sample_test_data.json"}

The server exposes pdf-validation://schema/json, pdf-validation://schema/excel, pdf-validation://schema/csv, pdf-validation://schema/tool-input, pdf-validation://examples, and pdf-validation://matching-rules as documentation resources.

The supplied sample_statement.pdf and sample_test_data.json are synthetic fixtures. Do not add real customer documents or identifiers to this repository.

Development

Requires Python 3.11 or newer. Once dependencies are installed, run:

pytest

Installation

Install the published distribution when available:

python -m pip install pdfproof-mcp

The distribution contains the complete PDFProof engine, CLI, and MCP server. Run CLI validation with:

pdfproof validate document.pdf test_data.json

Start the MCP server from an installed environment with:

python -m pdfproof.server

The package supports JSON, Excel, CSV, and direct structured MCP test data. The project has not been published to PyPI yet; the command above applies after a release is published.

License

MIT. See LICENSE.