omitly-mcp

# omitly-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
Omitly's **local, verifiable PDF redaction** to AI agents (Claude Code, Claude
Desktop, and any other MCP client).

> **Repository scope and licence — please read before opening a PR.**
>
> This repository is **source-available, not open source**. See [`LICENSE`](LICENSE):
> the code is published so you can read exactly what runs on your machine before
> you let it touch a confidential document. It is not licensed for reuse in other
> projects.
>
> It contains the MCP server and the compiled wasm detection bundle. The Omitly
> redaction engine, the tamper-evidence seal and the licensing implementation are
> **not** in this repository and are developed privately; this code calls the
> engine, it does not contain it.
>
> Development happens in a private repository and is mirrored here on release, so
> **pull requests cannot be merged**. Issues and security reports are very welcome
> — see [`SECURITY.md`](SECURITY.md).

The point of difference: an agent can redact a document **without uploading it
anywhere**. Redaction runs on-device through the Omitly engine and returns a
signed audit log proving the data was removed — the opposite of pasting a
confidential file into a chat model.

**Five of the eleven tools (`find_sensitive_regions`, `locate_text`,
`check_redaction`, `verify_redaction`, `extract_pdf_text`) work out of the
box — `npm install`, no Rust toolchain, no native binary, no desktop app.**
They run on a wasm-bindgen build of the same detector that powers the web
leak-checker at omitly.app, bundled directly in this package. `create_pdf`,
the two write tools (`redact_pdf`, `redact_by_entity`), and the two
seal-verification tools (`verify_seal`, `verify_document`) still need a
configured native engine — see "Build & run" below. Neither seal tool has a
wasm fallback yet: there is no wasm seal-verification path (tracked in
issue #113), so both always require the native engine, even though checking
a seal needs no licence.

## Tools

| Tool | What it does |
|------|--------------|
| `find_sensitive_regions` | Scans a PDF on-device and returns PII candidates — email/SSN/phone/card plus Australian identifiers (TFN, ABN, ACN, Medicare, Centrelink CRN, IHI, BSB; check-digit validated where a published algorithm exists) — with page + exact coordinates, so the agent selects by entity and never guesses geometry. Best-effort pattern matching, not a compliance assessment. Optional `regions` (`generic`/`us`/`au`) narrows the listed kinds. |
| `locate_text` | Resolves literal strings the model supplies (names, addresses — anything regex can't catch) to their page + coordinates. The model does the recognition; the engine does the geometry. |
| `check_redaction` | Audits an ALREADY-redacted PDF and reports whether sensitive text still survives underneath the redaction marks, in prior incremental-update revisions, metadata, AcroForm fields, or attachments — the "did my black boxes actually remove the data?" check, with a coverage report scoping what was inspected. Free tier (wasm) is EVALUATION-marked and capped to a monthly number of free checks; a configured licensed engine is not capped. |
| `extract_pdf_text` | Extracts a PDF's full text, page by page, PII-MASKED BY DEFAULT so raw sensitive values never flood the model's context window. Each page's `spans` report the CHAR offset (not byte offset) and kind of every masked value, so an agent can still reason about position without seeing the raw value. `masked: false` is a documented, explicit opt-in to raw text. Free, no licence, works out of the box on the bundled wasm engine — a native engine is preferred when available (also enables the `regions` filter; wasm ignores it and scans every pattern). Never renders pages to images. |
| `redact_by_entity` | One-shot: find + filter by kind (`email`/`ssn`/`phone`/`card`/`tfn`/`abn`/`acn`/`medicare`/`crn`/`ihi`/`bsb`) and/or `regions` + redact + verify. The "just scrub the obvious PII" shortcut. |
| `redact_pdf` | Removes the underlying data from given regions of a PDF, verifies nothing survives, writes the redacted file, and returns the audit log. |
| `verify_redaction` | Re-scans an already-redacted PDF and returns the verification verdict — the redaction-completeness check. |
| `verify_seal` | Cryptographically checks a PDF's embedded Omitly audit report and trailing Ed25519 tamper-evidence seal — the tamper-evidence check, distinct from `verify_redaction`. **Integrity, not identity:** the signing key is per-install and rides inside the file, so a valid seal means "unchanged since sealed by the holder of this key", never "produced by Omitly" — compare `sealFingerprint` out-of-band for origin. Requires a native engine; no wasm fallback exists. |
| `verify_document` | Recipient trust-verification (omitly#113): the same seal/report check as `verify_seal` — not a survivor re-scan — aimed at someone who *received* a PDF from someone else and wants to confirm it's authentic and unaltered, without paying or licensing anything. Free, no licence. Currently requires a native engine like `verify_seal` (no wasm seal-verification path yet). |
| `create_pdf` | Generates a clean PDF from Markdown/HTML on-device, rendered through a real browser engine so it looks printed — instead of writing a throwaway reportlab/LaTeX script. |
| `check_license` | Reports the current licence or trial state — tier, trial days left, the vendor-signed licensee name, which resolution step supplied the licence, and whether it is bound to this machine. Free, takes no arguments, reads no document, and is re-resolved on every call so buy → save licence → call again works without a restart. **Never returns the device fingerprint or the licence file's contents** — device binding is a yes/no. Requires a native engine: the wasm free tier has no licence concept. |

## PDF generation (`create_pdf`)

`create_pdf` is served by a **separate** binary, `omitly-pdf` (in
`crates/omitly-pdf`), kept apart from the redaction engine because generation is
a different trust model from verifiable redaction. It renders Markdown (or raw
HTML) through a headless Chromium-family browser (Chrome/Chromium/Edge/Brave;
override with `OMITLY_BROWSER_BIN`) — the same engine family the Omitly app's
webview uses, so output looks printed rather than script-generated. `omitly-pdf`
ships with the Omitly desktop application; its source is not in this repository.
Point `OMITLY_PDF_BIN` at the binary to enable this tool.

```jsonc
// stdin
{ "command": "create", "outputPath": "/abs/out.pdf",
  "source": "# Hello\n\nBody **markdown**", "format": "markdown", "title": "Hello" }
// stdout
{ "ok": true, "output": "/abs/out.pdf" }
```

Typical agent flows:
- Quick: **`redact_by_entity`** (find + redact + verify in one call).
- Careful: **`find_sensitive_regions` / `locate_text` → review → `redact_pdf` → `verify_redaction`**.
  Coordinates from `find`/`locate` drop straight into `redact` as its `regions` argument.

See [DEMO.md](./DEMO.md) for a full Claude Code walkthrough.

## Status

The MCP surface (eleven tools, schemas, transport), the native engine binary
(`crates/omitly-cli`, built as `omitly-redact`), and the bundled wasm engine
(`crates/leakcheck-wasm`, covering the four free tools without a native
binary) are all implemented and pass end-to-end tests. `find_sensitive_regions`
is a first-pass detector (ASCII patterns, per-show-operator matching): treat
its hits as *candidates for review*, not a completeness guarantee. An LLM can
always supply additional regions directly.

**Privacy of findings.** Detection results are returned with a **masked**
preview (e.g. `•••-••-6789`), never the raw value. The file isn't uploaded *and*
the secret detected inside it isn't sent back through the model — redaction is
driven entirely by page + coordinates, so the plaintext stays on the machine.

### Engine contract (implemented in `crates/omitly-cli`)

The server spawns `OMITLY_REDACT_BIN`, writes a JSON request to stdin, and reads
a JSON response from stdout. Any failure returns `{ "ok": false, "error": "..." }`
(the process still exits 0, so the caller reads `ok` rather than the exit code).

```jsonc
// stdin
{ "command": "find", "pdfPath": "..." }
// stdout
{ "ok": true, "count": 2, "regions": [
  { "page": 0, "x": 250.4, "y": 610.4, "width": 79.2, "height": 14.4, "kind": "ssn", "preview": "•••-••-6789" } ] }
// `preview` is masked — the raw value never leaves the process; redaction is driven by coordinates.
```

```jsonc
// stdin — "masked" omitted ⇒ true (the default); pass "masked": false for the
// documented raw-text opt-in. "regions" narrows detected kinds (generic
// kinds like email/card always apply).
{ "command": "extract_text", "pdfPath": "..." }
// stdout — "spans" offsets are CHAR (not byte) offsets into "text", valid
// against either the masked or the raw text of the same page (masking never
// changes a page's character count). A page that could not be decoded
// reports "contentDecoded": false with empty text/spans rather than being
// silently skipped.
{ "ok": true, "masked": true, "pages": [
  { "page": 0, "contentDecoded": true,
    "text": "Sensitive sample line: SSN •••-••-6789",
    "spans": [ { "kind": "ssn", "start": 24, "end": 35 } ] } ] }
```

```jsonc
// stdin
{ "command": "redact", "pdfPath": "...", "outputPath": "...",
  "regions": [{ "page": 0, "x": 72, "y": 700, "width": 200, "height": 14, "reason": "PII.SSN" }] }
// stdout — also writes "<outputPath>.audit.json" beside the file
{ "ok": true, "output": "...", "audit": { "verdict": "pass", "regions": [ ... ], "warnings": [], "metadataScrubbed": true } }
```

```jsonc
// stdin — recovers the redacted regions from "<pdfPath>.audit.json"
{ "command": "verify", "pdfPath": "..." }
// stdout — hiddenContent re-checks thumbnails / document actions / embedded
// files on the delivered bytes (omitly#171); any fail flips the verdict
{ "ok": true, "