Metadata-Version: 2.5
Name: pdfproof-mcp
Version: 0.1.0
Summary: Deterministic PDF document validation with traceable evidence.
Author: pdfproof-mcp contributors
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: mcp<2,>=1.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: pdfplumber>=0.11
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: pymupdf>=1.24
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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](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](docs/test-data-schema.md) 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](docs/mcp-usage.md).

## MCP server

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

```text
.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](docs/mcp.md) for the contract, examples, resources, and error handling.

Example file-driven call:

```json
{"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:

```text
pytest
```

## Installation

Install the published distribution when available:

```text
python -m pip install pdfproof-mcp
```

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

```text
pdfproof validate document.pdf test_data.json
```

Start the MCP server from an installed environment with:

```text
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](LICENSE).
