Obsify

Let an AI assistant work on sensitive files without their raw values ever entering the model's context.

obsify is a local, deterministicMCPserver. The frontier model reasons overshape— schemas, synthetic twins, masked feedback — while deterministic local code touches thesubstanceand returns only masked, aggregated results. No LLM calls, no network at runtime: detection is regex + checksums + dictionaries +Presidio's local NER.

Honest scope:run_on_realexecutes model-written code in abest-effortlocal sandbox and masks its outputbest-effort. It is not a jail. ReadSECURITY.mdbefore pointing it at anything you cannot afford to leak. Return aggregates.

Supported documents:PDF (text + tables; complex-table fallback viaobsify[tables]), Excel.xlsx/.xlsm, and Word.docx(paragraphs + tables). Unreadable or unsupported files are surfaced as explicit notes/blind spots, never silently dropped. (No OCR yet — scanned/image pages are flagged as low-coverage, not transcribed.)

Known-entity masking (optional).Supply a local.obsify.entitieslist of names to hide;scan_pii/redact_textdeterministically catch them — and the suffix/abbreviation variants NER misses (BRIGHTWATER HLDGS P/LforBrightwater Holdings Pty Ltd) — asKNOWN_ENTITY. The list stays local and never enters the model's context. Seedocs/known_entities.md.

Poke at all five tools live against synthetic data with the officialMCP Inspector:

python -m obsify.make_corpus --out ./corpus_demo npx @modelcontextprotocol/inspector obsify-mcp

Callscan_piion./corpus_demo/ledger.xlsxand confirm it returns types / counts / locations only — never values. Seedocs/verifying.md.

pip install "obsify[demo]" # reportlab, for the sample PDFs python -m obsify.make_corpus --out ./corpus_demo

It writes a multi-sheet Excel ledger (a numeric false-positive minefield), a PDF engagement letter (prose + trial-balance table), and a DOCX audit memo (paragraphs + vendor table). Great for kicking the tyres onscan_pii/make_synthetic_twinwithout touching real data.

Requires Python 3.11+. obsify speaks MCP overstdio— the client launches it as a local subprocess; nothing is hosted remotely. Register it with any MCP-capable client (Claude Desktop, Claude Code, Cursor, VS Code, …) by adding one block to that client's config.

{ "mcpServers": { "obsify": { "command": "uvx", "args": ["--from", "obsify", "obsify-mcp"] } } }

uvxfetches obsify from PyPI and runs it on demand — no permanent install. Onfirst run, obsify downloads the spaCy NER model (en_core_web_lg, ~560 MB) once and caches it; this fetches a public model and sends no user data (setOBSIFY_AUTO_DOWNLOAD=0to forbid it and install the model yourself). Later runs are instant and fully offline.

pipx install obsify # isolated, on PATH (or: pip install obsify)

Then point the client at the installed command:

{ "mcpServers": { "obsify": { "command": "obsify-mcp" } } }

Restart the client and the tools appear. Optional extras:obsify[tables](complex-table PDF fallback via camelot + Ghostscript),obsify[compute](pandas, handy insiderun_on_realcode).

PATH gotcha (the #1 cause of "server won't connect"):thecommandmust resolve on the PATH theclientsees. A GUI client may not share your venv's PATH. Fixes: useuvx/pipx(globally resolvable), or give an absolute path —"/path/to/.venv/bin/obsify-mcp"(macOS/Linux) or"C:\\path\\to\\.venv\\Scripts\\obsify-mcp.exe"(Windows).

From this repo (before it's on PyPI):

pip install "git+https://github.com/Formative-Sum41/obsify.git" # gets obsify-mcp + obsify`

The hard part of "help me, but don't read the confidential file" isdeciding when to protect. obsify moves that decision out of the model and into the environment:
- .obsify.json— a label manifest classifying paths (public/confidential/restricted).
- obsify.guard(run aspython -m obsify.guard) — a PreToolUse guard that blocks a direct read of a labelled file (exit 2) and redirects the assistant toscan_pii/make_synthetic_twin/run_on_real.
- A convention(inCLAUDE.md) so the assistantprefersobsify before it even hits the guard.

obsify init [--dir PATH] [--with-claude-md]

obsify initisnon-destructive by design— it owns exactly one file and hands you snippets for the rest:

- .obsify.json— obsify owns this; init writes it (never overwritten without--force).
- .claude/settings.json—yourfile: initprintsthe PreToolUse hook block to paste, never edits it (it runs code, so registering it is your call).
- CLAUDE.md—yourfile: the convention isopt-in. Default prints it;--with-claude-mdappends a marker-wrapped, idempotent block that never clobbers your content.

Full convention:docs/obsify_routing.md.

The harness earned its keep — it found real defects, which were then fixed:credit cards and phone numbers were being silently suppressed by the numeric-noise filter (now exempt via checksum validation / phone shape), and Medicare, IP, date-of-birth, AU passport and driver-licence had no recognizer (now added, checksum- or context-gated). Full method, numbers, and remaining documented gaps (SWIFT/BIC, non-DOB dates):eval/README.md.

pip install -e ".[dev]" pytest tests/ # or run any file directly: python tests/test_obsify.py

- mcp-protocol— launches the real server over stdio and speaks MCP to it (the same path a client like Claude uses): confirms all five tools register with valid schemas and that calls round-trip through JSON-RPC — includingscan_piireturningshape only, end to end.
- checksums— anchored to externally-published ABN/ACN/TFN worked examples (valid and corrupted), which breaks the generator↔validator circularity.
- obsify / twin / redaction— the privacy invariants: shape-only output, leak-free twins, and a fail-closed self-check.
- precision— the false-positive suppressors kill numeric-ledger noise while keeping real names.
- credentials— the anchored secret patterns catch cloud keys / tokens / JWTs / private-key blocks / connection strings, while keyword-anchored generics stay precise on prose (no entropy).
- routing— the guard's block/allow classification andobsify init's non-destructive contract.
- corpus— the synthetic PDF+Excel+DOCX corpus end to end: per-format detection, DOCX paragraph+table extraction, and shape-only output across every format.
- evaluation— the scored harness as a regression gate (recall, suppression, FP-torture, gaps).
- robustness— graceful degradation: corrupt/oversized/empty/nested/unsupported inputs never crash and are always surfaced as notes.
- model / variants— first-run model auto-download logic; variant normalization behindverify_value_free.

For interactive verification (MCP Inspector) and the live-client last-mile check, seedocs/verifying.md.

PRs welcome — seeCONTRIBUTING.mdfor setup, the merge bar, and the non-negotiable invariants (no LLM calls in the library, no runtime network, no real data, shape-not-substance). Security issues:SECURITY.md`(report privately).

MCP server that pseudonymizes PII before your LLM sees it and returns a cryptographically signed receipt for every response.