omitly-mcp 0.0.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,34 @@
+Omitly MCP server — Proprietary License
+Copyright (c) 2026 Innisfallen Pty Ltd. All rights reserved.
+
+This software is provided to let AI agents and MCP clients use Omitly's
+local, on-device PDF tools: free functionality (detection, leak checking,
+verification, document generation) at no charge, and paid functionality
+(verifiable redaction and any other features gated by an Omitly licence)
+subject to a valid, current Omitly licence.
+
+Permission is granted to install and use this package to:
+  (a) use the free functionality for any lawful purpose; and
+  (b) use the paid functionality only while you hold a valid Omitly licence
+      issued by Innisfallen and in accordance with the Omitly Terms of
+      Service at https://omitly.app.
+
+You may NOT, except to the extent permitted by applicable law that cannot be
+excluded by agreement:
+  - copy, modify, or create derivative works of this software;
+  - reverse engineer, decompile, or disassemble it, or attempt to derive the
+    source of the closed components or engine;
+  - redistribute, sublicense, sell, rent, or lease it;
+  - circumvent, disable, or interfere with the licence gating or any
+    usage metering; or
+  - remove or alter any proprietary notices.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+For commercial licensing terms, contact hello@omitly.app.

package/README.md

@@ -0,0 +1,235 @@
+# 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).
+
+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.
+
+**Four of the seven tools (`find_sensitive_regions`, `locate_text`,
+`check_redaction`, `verify_redaction`) 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` and the two
+write tools (`redact_pdf`, `redact_by_entity`) still need a configured
+native engine — see "Build & run" below.
+
+## 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. |
+| `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. |
+| `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. |
+
+## 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. Build it and
+point `OMITLY_PDF_BIN` at the binary:
+
+```bash
+cargo build -p omitly-pdf --release   # → target/release/omitly-pdf
+```
+
+```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 (seven 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
+{ "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, "verdict": "pass", "regions": [ ... ], "metadataScrubbed": true,
+  "hiddenContent": [ { "class": "thumbnails", "verification": { "result": "pass" } }, ... ] }
+```
+
+## Build & run
+
+**Free tools only (find_sensitive_regions, locate_text, check_redaction,
+verify_redaction) — no native engine needed:**
+
+```bash
+cd omitly-mcp
+npm install    # published releases ship the wasm build already bundled
+npm run build  # local/dev only: also runs wasm-pack (needs Rust + wasm-pack)
+node dist/index.js
+```
+
+`npm install omitly-mcp` from the registry gets a package with `wasm/`
+already built — a published install never needs Rust. Building **from
+source** (this repo) does need `wasm-pack` (`cargo install wasm-pack`) and
+the `wasm32-unknown-unknown` target, since `npm run build` regenerates the
+wasm bundle from `../crates/leakcheck-wasm` via `npm run build:wasm`.
+
+**Everything, including `create_pdf` and the two write tools
+(`redact_pdf`, `redact_by_entity`):**
+
+```bash
+# 1. Build the local engine binaries (from the repo root)
+cargo build -p omitly-cli -p omitly-pdf --release   # → target/release/{omitly-redact,omitly-pdf}
+
+# 2. Build and start the MCP server
+cd omitly-mcp
+npm install
+npm run build
+OMITLY_ENGINE_DIR=/abs/path/to/target/release node dist/index.js
+```
+
+One env var covers both binaries: `OMITLY_ENGINE_DIR` is the directory holding
+`omitly-redact` and `omitly-pdf`. Per-binary overrides (`OMITLY_REDACT_BIN`,
+`OMITLY_PDF_BIN`) win over the directory when set. When `OMITLY_ENGINE_DIR`
+(or `OMITLY_REDACT_BIN`) isn't set, `find_sensitive_regions`, `locate_text`,
+and `check_redaction` transparently use the bundled wasm engine instead —
+same detector, no native binary. `verify_redaction` does too, but with a
+narrower check: without a native engine there's no `<path>.audit.json`
+sidecar to verify specific regions against, so it falls back to a general
+re-scan of the whole file (still useful — a non-empty result still means the
+file isn't clean — just not the same rigor as the sidecar-based check).
+
+`find`/`redact` need `qpdf` for the redaction pipeline (`QPDF_BIN` overrides the
+PATH lookup). `find` alone (native or wasm) is read-only and works without it.
+
+## Access control
+
+Every path in a tool call comes from the model, so the server confines all
+reads and writes to one allowed directory:
+
+- **`OMITLY_ALLOWED_DIR`** — set it in the MCP config (recommended). Without
+  it, the directory the server was started in is used.
+- Symlinks are resolved before the check, so a link inside the root pointing
+  outside it is refused.
+- Outputs **never overwrite an existing file** (or its `.audit.json` sidecar);
+  the agent is asked to pick a fresh name instead.
+- **`OMITLY_ENGINE_TIMEOUT_MS`** (default 120000) — a wedged engine process is
+  killed at the deadline instead of hanging the agent's tool call.
+
+These are guardrails against confused-deputy mistakes, not a sandbox against a
+hostile local user — see `docs/THREAT-MODEL.md`.
+
+## Licensing
+
+`redact_pdf`/`redact_by_entity` are the write surface, enforced **inside the
+engine binary** (not in this server, and not bypassable by the bundled wasm
+fallback — wasm never touches these two tools): a Pro or Personal licence
+(`OMITLY_LICENSE_FILE`, or the Omitly desktop app's activated licence on the
+same machine) runs unmarked; otherwise the shared 14-day trial applies and
+the audit output is permanently marked as evaluation output. The redaction
+itself is never degraded, and licence checks never touch the network.
+`find_sensitive_regions`, `locate_text`, `check_redaction`, and
+`verify_redaction` are free forever — the wasm build backing them has no
+licence logic at all, because there's nothing to gate.
+
+## Register with Claude Code
+
+```bash
+claude mcp add omitly -- env \
+  OMITLY_ENGINE_DIR=/path/to/engine-dir \
+  OMITLY_ALLOWED_DIR=/path/agents/may/touch \
+  node /abs/path/to/omitly-mcp/dist/index.js
+```
+
+Or in Claude Desktop's `claude_desktop_config.json`:
+
+```jsonc
+{
+  "mcpServers": {
+    "omitly": {
+      "command": "node",
+      "args": ["/abs/path/to/omitly-mcp/dist/index.js"],
+      "env": {
+        "OMITLY_ENGINE_DIR": "/path/to/engine-dir",
+        "OMITLY_ALLOWED_DIR": "/path/agents/may/touch"
+      }
+    }
+  }
+}
+```
+
+## One-click install for Claude Desktop (MCPB, free tier only)
+
+`mcpb/` packages the four free/diagnosis tools (`check_redaction`,
+`find_sensitive_regions`, `locate_text`, `verify_redaction`) — never the write
+tools — as a self-contained [MCPB](https://github.com/anthropics/mcpb) `.mcpb`
+extension: no Node/npm/Rust toolchain on the end user's machine, just
+"Install Extension…" in Claude Desktop. This is a deliberately smaller,
+separate server (`mcpb/server/index.js`) from `dist/index.js` above, so the
+bundle can never expose `redact_pdf`/`redact_by_entity`/`create_pdf` even by
+accident.
+
+```bash
+npm run mcpb:pack   # build:wasm + copy into mcpb/wasm + npm install + mcpb pack
+                     # → dist-mcpb/omitly-leak-check.mcpb
+```
+
+`mcpb:pack` needs the same Rust + wasm-pack toolchain as `npm run build`
+(builds the shared wasm detector once, then copies it into `mcpb/` — see
+`mcpb/scripts/copy-wasm.mjs`). The packed `.mcpb` itself needs nothing but
+Node, already bundled inside Claude Desktop.
+
+**Not signed** (`mcpb sign` needs a code-signing cert we don't have yet — same
+gate as desktop app signing). `mcpb info` on the packed file confirms
+`WARNING: Not signed`. Whether Claude Desktop's "Install Extension…" flow
+blocks or just warns on an unsigned `.mcpb` has NOT been confirmed against the
+real Desktop app in this change (no Desktop GUI in this environment) — that
+check is still open, tracked in omitly#225.