Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@pdf-form-proof fill the attached W-9 with my business info, then verify it's visible"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Fill a fillable PDF form, then prove every value actually shows on the page.
mcp-name: io.github.EssenceAlignment/pdf-form-proof
A PDF can hold a value in its data while the page a person sees, prints, or uploads shows nothing, or shows it cut off. Most form tools stop at "the field was set." This one keeps going: it renders the page, reads it back with OCR (optical character recognition, software that reads text from an image), and compares that with the text stored in the file. Each value comes back VISIBLE, INVISIBLE, RENDER-ONLY, or MISSING.
It works as an MCP server (MCP, the Model Context Protocol, is the plug-in standard that lets AI apps such as Claude call outside tools), as a Claude plugin, as a Gemini CLI extension, and as plain command-line tools.
Tool | What it does | Changes files? |
| Lists every fillable field: exact name, type, current value, required flag, and the values that check each checkbox or radio button | No |
| Fills fields by exact name and writes a new PDF. Refuses the whole fill if any name is not in the form. Never modifies the source, never overwrites an existing file. Returns the new file's SHA-256 and reads every text value back | Writes one new file |
| Renders a page, OCRs it, and gives each value a verdict. Can be limited to one region of the page so a copy of the value elsewhere cannot make it pass | No |
| SHA-256 fingerprint of a file, for a record of exactly what was produced | No |
Every tool carries MCP annotations: readOnlyHint and destructiveHint are set on all four.
Related MCP server: JustFill PDF Forms
Anyone who fills the same official PDFs again and again: small nonprofits and community organizations (vendor forms such as the IRS W-9, grant and funder forms, program intake and consent forms), operations staff, and builders who want an AI assistant to fill forms without hiding a partial or invisible fill.
You need Python 3.10 or newer and uv (https://docs.astral.sh/uv/). The verify
tool also needs two free programs:
macOS: brew install poppler tesseract
Debian or Ubuntu: sudo apt install poppler-utils tesseract-ocr
Add this to claude_desktop_config.json:
{
"mcpServers": {
"pdf-form-proof": {
"command": "uvx",
"args": ["pdf-form-proof"]
}
}
}Or install the .mcpb file from the latest GitHub release: double-click it, or
use Settings > Extensions > Advanced settings > Install Extension.
claude plugin marketplace add EssenceAlignment/pdf-form-proof
claude plugin install pdf-form-proof@pdf-form-proofgemini extensions install https://github.com/EssenceAlignment/pdf-form-proofuvx --from pdf-form-proof pdf-form-inspect form.pdf
uvx --from pdf-form-proof pdf-form-fill form.pdf filled.pdf values.json
uvx --from pdf-form-proof pdf-form-verify filled.pdf --require "Sample Community Food Bank"values.json maps exact field names (from pdf-form-inspect) to values:
{
"topmostSubform[0].Page1[0].f1_01[0]": "Sample Community Food Bank",
"topmostSubform[0].Page1[0].Boxes3a-b_ReadOrder[0].c1_1[0]": "/1"
}Text fields take a string. A checkbox or radio takes one of its on-state values (shown by inspect, for example "/1" or "/Yes"), or an empty string to clear it.
Exit codes: 0 success; 1 a finding (verify found a value that is not visible, or a fill could not be read back); 2 refused (unknown field names, a missing file, an existing output, or a tool such as tesseract failed).
$ pdf-form-verify filled.pdf --require "Sample Community Food Bank" --require "Sample Pantry Program"
PDF FORM PROOF - legibility check verdict: PASS
file: filled.pdf page 1 at 300 dpi scope: whole page
VALUE SOURCE TEXT RENDER VERDICT
Sample Community Food Bank required yes yes VISIBLE
Sample Pantry Program required yes yes VISIBLE
limit: legibility only; says nothing about whether values are correctAcroForm forms only. XFA-only forms (Adobe LiveCycle dynamic forms) are detected and refused, not filled.
finalize removes the XFA packet and the NeedAppearances flag so viewers draw
the values from their own appearance streams. It does not flatten the form;
fields stay editable.
Verify proves legibility, not correctness. It cannot tell you whether a value is the right answer for the form.
OCR can misread small, stylized, or handwritten-style fonts. A REFUSE verdict means "look at the page," not "the file is broken." A tool failure (missing poppler or tesseract, a render error) is reported as a tool failure, never as a finding about your document.
Signatures are not created. Signature fields are listed by inspect and left alone.
This tool fills forms. It does not give legal, tax, benefits, or other professional advice, and it does not decide what belongs in any field.
pdf-form-proof runs entirely on your own computer.
Data collection: none. It reads only the PDF files you name and writes only the output path you name.
Usage and storage: rendered page images are kept in ~/.cache/pdf-form-proof
only until the next verify run, which deletes them.
Third-party sharing: none. It makes no network calls and sends no telemetry.
Retention: nothing is retained beyond the files you create.
Contact: open an issue at https://github.com/EssenceAlignment/pdf-form-proof/issues
The fill engine and the visible-on-the-page check were built for a production document pipeline after a filled form passed every text-based check and was still returned because a value could not be seen on the page. The two rules that came out of that: never hide a partial fill, and check the page a person sees, not only the data in the file.
MIT. See LICENSE.
Fill an AcroForm PDF and write a NEW file (the source is never modified and an existing output is never overwritten). values maps exact field names to values: strings for text fields; an on-state such as "/1" or "/Yes" (or true) to check a box, "" or false to clear it. strict=true refuses the whole fill if any name is unknown. finalize=true removes the XFA packet and NeedAppearances flag so viewers render the values from their own appearance streams (fields stay editable; this is not flattening). Returns the output SHA-256 and a read-back of every text value.
| Name | Required | Description | Default |
|---|---|---|---|
| strict | No | ||
| values | Yes | ||
| finalize | No | ||
| output_path | Yes | ||
| source_pdf_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: discloses that the source is untouched, that an existing output will not be overwritten, what strict=true actually refuses, and precisely what finalize=true does (removes XFA packet and NeedAppearances, fields remain editable, not flattening). This resolves the main ambiguity of a mutate-in-place tool — whether it destroys the original or flattens the form — which the annotations alone (destructiveHint=false) would not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tightly packed sentences, front-loaded with the action and the safety guarantees, then field-value encoding rules, then the two flags, then return values. Parenthetical asides carry real content rather than boilerplate; nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the write-target safety model, the tricky free-form values encoding, both boolean flags, and the return payload (SHA-256 plus read-back of text values), so an agent knows both how to call it and what it can trust from the result. Nothing material is missing for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and a free-form `values` object (additionalProperties: true) plus nested checkbox semantics, the description carries the entire burden and does so: exact-field-name mapping, string vs on-state ('/1', '/Yes', true) vs clearing ('', false), strict behavior, and finalize behavior. This is information an agent cannot derive from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource: 'Fill an AcroForm PDF and write a NEW file.' It is clearly a distinct operation from pdf_form_inspect (reading form structure) and pdf_form_verify, but it never explicitly names or contrasts with those siblings, so differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical 'the source is never modified and an existing output is never overwritten' implies when this is safe to call and gives an implicit constraint (pick a fresh output path), but there is no explicit guidance on when to use this versus pdf_form_inspect or pdf_form_verify, nor stated prerequisites (e.g., inspecting first to get exact field names).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every fillable field in a PDF: exact name, type (text, button, choice, signature), current value, required flag, and for checkboxes/radios the on-state values that check them. Use the names exactly as returned when filling.
| Name | Required | Description | Default |
|---|---|---|---|
| pdf_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuine value by describing the exact shape of what is surfaced (types, current values, checkbox on-states), which is more than the annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste, and the enumeration of returned attributes comes first so the agent understands the payoff immediately. The usage tip is a compact trailing sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is not required and the description already characterizes the fields. It doesn't mention behavior for non-form PDFs or encrypted files, a minor gap for a read-only inspection tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single pdf_path parameter, so the description should ideally clarify expected path form. It only says "a PDF", leaving the format to inference. With one obvious required parameter, this is adequate but not compensating for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (list) and resource (fillable fields in a PDF) and enumerates exactly what is returned: name, type, current value, required flag, on-state values for checkboxes/radios. That detail distinguishes it from the sibling fill/verify tools without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use the names exactly as returned when filling" gives clear downstream context linking it to pdf_form_fill. It doesn't explicitly state when to prefer this over pdf_form_verify, but the inspect-vs-fill framing makes the intended position in the workflow clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render one page, OCR it, and compare with the PDF text layer. Each value gets a verdict: VISIBLE, INVISIBLE (in the file but not on the page), RENDER-ONLY, or MISSING. region is "page" or "x0,y0,x1,y1" as page fractions; with a region and auto=true every word the text layer places in that region must also be legible. A tool failure (missing poppler or tesseract, render error) returns REFUSE with the reason and makes no finding about the document. Proves legibility only, not correctness.
| Name | Required | Description | Default |
|---|---|---|---|
| dpi | No | ||
| auto | No | ||
| page | No | ||
| region | No | page | |
| values | No | ||
| pdf_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say read-only and non-destructive; the description adds what actually matters — that a missing binary or render error yields REFUSE with no finding rather than a false negative, and it defines the four verdict categories. The region+auto legibility rule is behavioral detail found nowhere in the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with the mechanism, then the verdict vocabulary, then the region/auto rule, then the failure and scope caveats. No restatement of the title or padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema covers the return shape, and the description still supplies what the schema cannot: verdict meanings, failure-mode semantics (REFUSE), and the correctness-vs-legibility limit. Nothing an agent needs to invoke or interpret this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the burden; it does explain the two non-obvious params well (region accepts 'page' or fractional x0,y0,x1,y1; auto requires every text-layer word in the region to be legible). dpi and the format of values are left unexplained, and 'page' is only implied by 'Render one page'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb chain (render, OCR, compare with text layer) on a specific resource (one PDF page), which no sibling does — pdf_form_fill writes, pdf_form_inspect reads metadata, pdf_sha256 hashes. The verdict taxonomy at the end makes the output shape unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The closing clause 'Proves legibility only, not correctness' gives a clear scope boundary that tells the agent when this tool's answer is not the one it needs. It never names a sibling or states a when-not-to-use case explicitly, so routing between verify/inspect/fill is left partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the SHA-256 digest of a file so the exact output can be recorded.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is fully covered. The description adds only the intended use (recording exact output) and says nothing about error behavior, hashing of missing/unreadable files, or digest encoding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence, front-loaded with the operation and result. Nothing is wasted, though it is arguably over-compressed for the amount of unstated context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With rich annotations and an output schema present, the definition is close to sufficient, but the meaning of 'path' — the only input — is left entirely unstated, which is the one thing an agent must get right to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'path' has 0% schema description coverage and the description adds no meaning: it does not state whether the path is absolute or relative, local-only, or what file types are accepted (the tool name suggests PDF, the description says 'a file').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: returns the SHA-256 digest of a file. The purpose is unambiguous and clearly disjoint from the pdf_form_* siblings, though it never explicitly contrasts itself with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The clause 'so the exact output can be recorded' implies an integrity/audit use case, but there is no explicit guidance on when to call this versus other verification steps, no prerequisites, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0pdf_form_fillpdf_form_inspectpdf_form_verifypdf_sha256Scored across 4 tools
Each tool targets a distinct verb on the PDF: inspect (read fields), fill (write new file), verify (render+OCR compare), and hash (record output). Boundaries are crisp, with no overlap, and the descriptions explicitly note scope limits (verify proves legibility, not correctness).
Consistent snake_case and a shared pdf_ prefix throughout. Minor deviation: pdf_sha256 breaks the pdf_form_* pattern and is a generic utility rather than a form operation, but it remains predictable and readable.
Four tools is lean but each earns its place in a tight fill-and-proof workflow with no redundancy. Slightly on the thin side for the implied scope, but well-scoped rather than padded.
Covers the full loop: enumerate fields, fill safely to a new file, verify rendering, and record the output digest. Minor gaps like batch/multi-file handling or field validation reporting are absent but workable given the narrow purpose.
Detect fillable fields in any PDF with AI, scans included, then fill and sign it.
Deterministic PDF tools for AI agents: inspect fields, fill forms, merge PDFs, invoices.
Make any PDF form fillable, fill it from data or documents, read it back, and fax the result.
Detect, review and fill existing PDF forms from JSON or Excel; reuse saved templates
