Skip to main content
Glama

obsify

Lassen Sie einen KI-Assistenten an sensiblen Dateien arbeiten, ohne dass deren Rohwerte jemals in den Kontext des Modells gelangen.

obsify ist ein lokaler, deterministischer MCP-Server. Das Frontier-Modell denkt über die Struktur nach – Schemata, synthetische Zwillinge, maskiertes Feedback – während deterministischer lokaler Code die Substanz berührt und nur maskierte, aggregierte Ergebnisse zurückgibt. Keine LLM-Aufrufe, kein Netzwerk zur Laufzeit: Erkennung erfolgt per Regex + Prüfsummen + Wörterbücher + Presidio's lokalem NER.

Es wird mit australischer Entitätsunterstützung (ABN / ACN / TFN, prüfsummenvalidiert) und einer labelgesteuerten Routing-Ebene ausgeliefert, die „Wann sollte der Assistent Rohdaten vermeiden“ zu einer deterministischen, erzwungenen Entscheidung und nicht zu einer Ermessensentscheidung macht.

Ehrlicher Geltungsbereich: run_on_real führt modellgeschriebenen Code in einer Best-Effort-lokalen Sandbox aus und maskiert dessen Ausgabe Best-Effort. Es ist kein Gefängnis. Lesen Sie SECURITY.md, bevor Sie es auf etwas richten, dessen Verlust Sie sich nicht leisten können. Geben Sie Aggregate zurück.

Warum

Die Einspeisung vertraulicher Dokumente in ein gehostetes LLM bedeutet, dass die Substanz Ihre Grenzen verlässt. Die üblichen Antworten sind „Verwenden Sie das LLM nicht“ oder „Vertrauen Sie dem Anbieter.“ obsify geht einen dritten Weg — Compute-to-Data: Bringen Sie den Code zu den Daten, nicht die Daten zum Modell.

  • Das Modell sieht das Schema einer Tabelle, nicht ihre Zeilen.

  • Das Modell entwickelt anhand eines synthetischen Zwillings (gefälschte Werte, echte Struktur).

  • Der Analysecode des Modells wird lokal ausgeführt; nur maskierte, aggregierte Ausgabe wird zurückgegeben.

Das Denken des Frontier-Modells bleibt erhalten. Nur seine Augen auf Rohwerte werden entfernt.

Related MCP server: taskvault

Werkzeuge

Werkzeug

Was es tut

Rückgabe

scan_pii(path)

Durchsucht eine Datei/einen Ordner nach PII

Typen, Orte, Anzahlen — niemals Werte

make_synthetic_twin(path, out)

Originalgetreue Fälschung einer Excel-Arbeitsmappe

Schema-Zusammenfassung; Zwilling nach out geschrieben (Werte gefälscht, leak-verifiziert)

run_on_real(code, data_path)

Compute-to-Data: Führen Sie Ihren Code lokal gegen die echte Datei aus (gebunden an DATA_PATH)

Nur PII-maskierte, größenbegrenzte stdout/stderr — Aggregate zurückgeben

redact_text(text)

Maskiert PII in einem String zu <TYPE>-Token

Der geschwärzte String

verify_value_free(text, terms)

Fail-Closed-Prüfung, dass text keines von terms (oder deren Varianten) preisgibt

{"value_free": bool}

Unterstützte Dokumente: PDF (Text + Tabellen; komplexe Tabellen-Fallback via obsify[tables]), Excel .xlsx/.xlsm und Word .docx (Absätze + Tabellen). Nicht lesbare oder nicht unterstützte Dateien werden als explizite Hinweise/blinde Flecken ausgewiesen, niemals stillschweigend verworfen. (Noch keine OCR — gescannte/Bild- Seiten werden als abdeckungsarm gekennzeichnet, nicht transkribiert.)

Maskierung bekannter Entitäten (optional). Stellen Sie eine lokale .obsify.entities-Liste mit zu verbergenden Namen bereit; scan_pii / redact_text fangen sie deterministisch ab – sowie die Suffix-/Abkürzungsvarianten, die NER übersieht (BRIGHTWATER HLDGS P/L für Brightwater Holdings Pty Ltd) – als KNOWN_ENTITY. Die Liste bleibt lokal und gelangt niemals in den Kontext des Modells. Siehe docs/known_entities.md.

Demo

Testen Sie alle fünf Werkzeuge live gegen synthetische Daten mit dem offiziellen MCP Inspector:

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

Rufen Sie scan_pii für ./corpus_demo/ledger.xlsx auf und bestätigen Sie, dass es nur Typen / Anzahlen / Orte zurückgibt – niemals Werte. Siehe docs/verifying.md.

Testen Sie es – synthetisches Korpus

Generieren Sie ein gefälschtes, aber realistisches Korpus (alles synthetisch; ABN/ACN/TFN sind prüfsummenvalidiert), das alle drei Formate umfasst, und richten Sie dann ein Werkzeug darauf:

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

Es schreibt eine mehrblättrige Excel-Tabelle (ein numerisches False-Positive-Minenfeld), ein PDF-Anschreiben (Prosatext + Probebilanz-Tabelle) und ein DOCX-Prüfvermerk (Absätze + Lieferantentabelle). Großartig, um die Reifen von scan_pii / make_synthetic_twin zu testen, ohne echte Daten zu berühren.

Installation und Ausführung als MCP-Server

Erfordert Python 3.11+. obsify spricht MCP über stdio – der Client startet es als lokalen Unterprozess; nichts wird remote gehostet. Registrieren Sie es bei jedem MCP-fähigen Client (Claude Desktop, Claude Code, Cursor, VS Code, …), indem Sie einen Block zur Konfiguration dieses Clients hinzufügen.

Empfohlen – Installation ohne Installation via uvx:

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

uvx holt obsify von PyPI und führt es bei Bedarf aus – keine dauerhafte Installation. Beim ersten Start laden Sie das spaCy NER-Modell (en_core_web_lg, ~560 MB) einmal herunter und zwischenspeichern es; dies holt ein öffentliches Modell und sendet keine Benutzerdaten (setzen Sie OBSIFY_AUTO_DOWNLOAD=0, um es zu verbieten und das Modell selbst zu installieren). Spätere Ausführungen sind sofort und vollständig offline.

Oder installieren Sie es (pip / pipx):

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

Dann weisen Sie den Client auf den installierten Befehl:

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

Starten Sie den Client neu und die Werkzeuge erscheinen. Optionale Extras: obsify[tables] (komplexe Tabellen-PDF- Fallback via camelot + Ghostscript), obsify[compute] (pandas, praktisch innerhalb von run_on_real-Code).

PATH-Falle (Hauptgrund Nr. 1 für „Server verbindet nicht“): Der command muss im PATH aufgelöst werden können, den der Client sieht. Ein GUI-Client teilt möglicherweise nicht den PATH Ihrer venv. Lösungen: Verwenden Sie uvx/pipx (global auflösbar) oder geben Sie einen absoluten Pfad an – "/pfad/zu/.venv/bin/obsify-mcp" (macOS/Linux) oder "C:\\pfad\zu\\.venv\\Scripts\\obsify-mcp.exe" (Windows).

Aus diesem Repository (bevor es auf PyPI ist):

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

Die Routing-Ebene – deterministisch, keine Ermessensentscheidung

Der schwierige Teil von „Hilf mir, aber lies die vertrauliche Datei nicht“ ist die Entscheidung, wann geschützt werden muss. obsify verlagert diese Entscheidung aus dem Modell in die Umgebung:

  1. .obsify.json – ein Label-Manifest, das Pfade klassifiziert (public / confidential / restricted).

  2. obsify.guard (ausgeführt als python -m obsify.guard) – ein PreToolUse-Guard, der das direkte Lesen einer gelabelten Datei blockiert (Exit 2) und den Assistenten an scan_pii / make_synthetic_twin / run_on_real weiterleitet.

  3. Eine Konvention (in CLAUDE.md), sodass der Assistent obsify bevorzugt, bevor er überhaupt auf den Guard trifft.

Richten Sie es mit einem Befehl ein:

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

obsify init ist von Grund auf nicht destruktiv – es besitzt genau eine Datei und gibt Ihnen Schnipsel für den Rest:

  • .obsify.json – obsify besitzt dies; init schreibt es (niemals ohne --force überschrieben).

  • .claude/settings.json – Ihre Datei: init gibt den PreToolUse-Hook-Block zum Einfügen aus, bearbeitet ihn nie (da er Code ausführt, ist die Registrierung Ihre Entscheidung).

  • CLAUDE.md – Ihre Datei: die Konvention ist opt-in. Standardmäßig wird sie ausgegeben; --with-claude-md hängt einen markierungsumschlossenen, idempotenten Block an, der Ihren Inhalt niemals überschreibt.

Vollständige Konvention: docs/obsify_routing.md.

Wie die Erkennung präzise bleibt

  • Prüfsummenvalidierte Identifikatoren. ABN/ACN/TFN-Kandidaten werden per Regex vorgeschlagen und durch ihre offiziellen Prüfsummen bestätigt, sodass eine zufällige Zahl niemals als Identifikator gemeldet wird.

  • Kontextabhängige IDs. Eine bloße Zahl wird nur dann als ABN/ACN/TFN akzeptiert, wenn ein Label-Wort („TFN“, „ABN“, „BSB“, …) in der Nähe ist – dies unterdrückt die False-Positive-Flut durch sequenzielle Journal-IDs in numerischen Tabellen.

  • Buchstabenlose / NER-mit-Ziffern-Unterdrückung. Reine Zahlen, Beträge, Daten und alphanumerische Codes werden nicht als Namen/Organisationen gekennzeichnet; echte Namen, E-Mails und Adressen (die Buchstaben enthalten) sind nicht betroffen. Validierte buchstabenlose PII bleibt ausgenommen: Prüfsummen-IDs (ABN/ACN/TFN/Medicare), Luhn-Karten, gültige IPs, BSB-bezogene Konten und Telefone (via Kontext oder Telefonform) – während ein Dezimalpunkt immer noch einen Betrag und kein Telefon kennzeichnet.

Gemessene Genauigkeit

obsify wird mit einem bewerteten Evaluierungs-Framework ausgeliefert (eval/ – beschriftetes synthetisches Korpus + Antwortschlüssel + Bewerter gegen den ausgelieferten Detektor, plus eine unabhängige Drittanbieter-Kreuzprüfung). Überschrift auf dem synthetischen Korpus: 100 % Recall bei erwarteten Erkennungselementen, 0 False Positives auf einer numerischen FP-Foltertabelle (mit einer gruppierten Zahlensperre), bloße kontextabhängige IDs korrekt unterdrückt. Unabhängige Kreuzprüfung vs. Microsoft presidio-research: EMAIL/IBAN 100 %, PERSON 94 %.

Das Framework hat sich bezahlt gemacht – es fand echte Fehler, die dann behoben wurden: Kreditkarten und Telefonnummern wurden stillschweigend durch den numerischen Rauschfilter unterdrückt (jetzt ausgenommen via Prüfsummen- validierung / Telefonform), und Medicare, IP, Geburtsdatum, AU-Pass und Führerschein hatten keinen Erkenner (jetzt hinzugefügt, prüfsummen- oder kontextabhängig). Vollständige Methode, Zahlen und verbleibende dokumentierte Lücken (SWIFT/BIC, Nicht-Geburtsdaten): eval/README.md.

Tests

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

Zwölf Suiten (73 Tests), ausgeführt in CI unter Linux + Windows / Python 3.11 + 3.12:

  • mcp-protocol – startet den echten Server über stdio und spricht MCP mit ihm (derselbe Weg, den ein Client wie Claude verwendet): bestätigt, dass alle fünf Werkzeuge mit gültigen Schemata registriert sind und dass Aufrufe durch JSON-RPC hin und zurück gehen – einschließlich scan_pii, das nur die Struktur, Ende-zu-Ende zurückgibt.

  • checksums – verankert an extern veröffentlichten ABN/ACN/TFN-Arbeitsbeispielen (gültig und korrupt), was die Generator↔Validator-Zirkularität durchbricht.

  • obsify / twin / redaction – die Datenschutzinvarianten: nur Strukturausgabe, leak-freie Zwillinge und eine Fail-Closed-Selbstprüfung.

  • precision – die False-Positive-Unterdrücker töten numerisches Tabellenrauschen, während echte Namen erhalten bleiben.

  • routing – die Block-/Erlaubnis-Klassifizierung des Guards und der nicht-destruktive Vertrag von obsify init.

  • corpus – das synthetische PDF+Excel+DOCX-Korpus Ende-zu-Ende: formatbezogene Erkennung, DOCX- Absatz+Tabellen-Extraktion und nur Strukturausgabe über jedes Format.

  • evaluation – das bewertete Framework als Regressionstor (Recall, Unterdrückung, FP-Folter, Lücken).

  • robustness – Graceful Degradation: korrupte/überdimensionierte/leere/verschachtelte/nicht unterstützte Eingaben stürzen nie ab und werden immer als Hinweise ausgewiesen.

  • model / variants – Logik zum automatischen Herunterladen des Modells beim ersten Start; Variantennormalisierung hinter verify_value_free.

Für interaktive Verifizierung (MCP Inspector) und die letzte Meile des Live-Clients siehe docs/verifying.md.

Lizenz

MIT – siehe LICENSE.

Available Tools

5 tools
make_synthetic_twinA

Generate a SYNTHETIC TWIN of a real Excel workbook at path, written to out. Schema (sheets, headers, column types, true row counts) is preserved; every data value is freshly FAKED — no real value is copied. Reason and write your analysis code against the twin; then run it on the real file with run_on_real. Returns the schema summary (safe shape).

Inputs: out (required), path (required), cap_rows.

redact_textA

Return text with detected PII replaced by placeholders (e.g. <AU_TFN>, ). Deterministic; checksum-validated identifiers and context/precision rules apply so bare numbers are not over-masked.

entities is an optional PATH to a local .obsify.entities file of KNOWN names to hide; matches (incl. variants) are masked as <KNOWN_ENTITY>. If omitted, a nearby .obsify.entities is auto-used.

Inputs: text (required), entities. Returns: result

run_on_realA

COMPUTE-TO-DATA: execute your Python code LOCALLY against the real file at data_path (bound to the variable DATA_PATH in your code); the returned output is size-capped and best-effort PII-masked. The data never enters your context; substance never leaves. Return AGGREGATES (counts/sums/summaries) via print() — output masking is defense-in-depth, NOT a guarantee (NER can miss a name in a raw record), so never print raw records or identifiers. The masking field carries this caveat with the result. Network is disabled and a timeout applies.

Inputs: code (required), data_path (required), timeout.

scan_piiA

Scan a file or folder for PII and return TYPES + LOCATIONS + COUNTS only — never the detected values. Safe to surface to an LLM: it learns what PII exists and where, without the substance entering context. Recurses into subfolders; skips unreadable files and caps very large sheets, reporting both as notes.

entities is an optional PATH to a local .obsify.entities file (one name per line) of KNOWN names to hide; matches (incl. suffix/abbreviation variants) are reported as KNOWN_ENTITY. If omitted, a nearby .obsify.entities is auto-used. The names are read locally and never returned.

Inputs: path (required), entities, max_cells.

verify_value_freeA

Fail-closed check that text contains NONE of terms (nor their suffix-normalized / distinctive-token variants). Returns {"value_free": bool} with zero detail on what matched — for verifying an artifact before it leaves the perimeter.

Inputs: text (required), terms (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose: make_synthetic_twin creates a fake dataset, run_on_real executes code against real data, scan_pii identifies PII locations, redact_text masks PII in text, and verify_value_free checks for forbidden terms. No two tools overlap in what they accomplish.

    Naming Consistency4/5

    Most tools follow a verb_noun pattern (make_synthetic_twin, scan_pii, redact_text, verify_value_free), but run_on_real breaks the pattern with a prepositional phrase. The style is consistent (all snake_case, verbs first) but the deviation is noticeable.

    Tool Count4/5

    With 5 tools, the count is well-scoped for a focused PII-handling server. Each tool covers a necessary step in the workflow, and the count is within the typical 3-15 range, though a few additional helpers could be justified (e.g., a check for twin accuracy).

    Completeness4/5

    The tool surface covers the core lifecycle: protect data (scan, redact, verify) and enable safe analysis (twin, run on real). Minor gaps exist, such as no tool to validate the synthetic twin's fidelity against the real file, and verify_value_free lacks a positive counterpart, but agents can work around these.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Let LLMs analyze sensitive data safely by querying a tokenized, join-preserving copy of the database, with fail-closed PII scanning and provable numeric equivalence.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to access only task-relevant data with secrets hidden and personal details pseudonymized, while enforcing destination policies to prevent data leakage even under prompt injection.
      2
      AGPL 3.0
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables agents to encrypt and sanitize sensitive data such as credentials, credit card numbers, and addresses locally before dispatching prompts to cloud LLMs, then rehydrate the masked values client-side. It runs deterministically with zero external dependencies over MCP JSON-RPC stdio, so no plaintext PII leaves the user's machine.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding assistants to audit datasets against DAMA-DMBOK quality dimensions, sanitize PII, generate differential-privacy synthetic twins, compress prompt context, and export dbt schema tests and interactive HTML reports. It supports development against sensitive data with zero real records exposed to external LLMs.
      1
      MIT