obsify
obsify
Permite que un asistente de IA trabaje con archivos sensibles sin que sus valores brutos entren nunca en el contexto del modelo.
obsify es un servidor local y determinista del MCP. El modelo de frontera razona sobre la forma — esquemas, gemelos sintéticos, retroalimentación enmascarada — mientras que el código local determinista toca la sustancia y devuelve solo resultados enmascarados y agregados. Sin llamadas a LLM, sin red en tiempo de ejecución: la detección se basa en expresiones regulares, sumas de verificación, diccionarios y el NER local de Presidio.
Viene con soporte para entidades australianas (ABN / ACN / TFN, validados por suma de verificación) y una capa de enrutamiento basada en etiquetas que convierte "¿cuándo debe evitar el asistente los datos brutos?" en una decisión determinista y forzada, no en un juicio subjetivo.
Alcance honesto:
run_on_realejecuta código escrito por el modelo en un entorno aislado local de buena fe y enmascara su salida de buena fe. No es una cárcel. LeeSECURITY.mdantes de apuntarlo a algo que no puedas permitirte filtrar. Devuelve agregados.
Por qué
Alimentar documentos confidenciales a un LLM alojado significa que la sustancia sale de tu perímetro. Las respuestas habituales son "no uses el LLM" o "confía en el proveedor". obsify toma un tercer camino — compute-to-data: lleva el código a los datos, no los datos al modelo.
El modelo ve el esquema de una hoja de cálculo, no sus filas.
El modelo desarrolla contra un gemelo sintético (valores falsos, estructura real).
El código de análisis del modelo se ejecuta localmente; solo la salida enmascarada y agregada regresa.
El razonamiento del modelo de frontera se conserva. Solo se eliminan sus ojos sobre los valores brutos.
Related MCP server: taskvault
Herramientas
Herramienta | Qué hace | Devuelve |
| Escanea un archivo/carpeta en busca de PII | Tipos, ubicaciones, recuentos — nunca valores |
| Falso fiel de un libro de Excel | Resumen del esquema; gemelo escrito en |
| Compute-to-data: ejecuta tu código localmente contra el archivo real (vinculado a | Solo stdout/stderr enmascarados de PII y con límite de tamaño — devuelve agregados |
| Enmascara PII en una cadena a tokens | La cadena redactada |
| Verificación de cierre por fallo de que |
|
Documentos compatibles: PDF (texto + tablas; tabla compleja alternativa mediante obsify[tables]), Excel .xlsx/.xlsm y Word .docx (párrafos + tablas). Los archivos ilegibles o no compatibles se muestran como notas explícitas/puntos ciegos, nunca se omiten en silencio. (Aún no hay OCR — las páginas escaneadas/con imágenes se marcan como de baja cobertura, no se transcriben.)
Enmascaramiento de entidades conocidas (opcional). Proporciona una lista local .obsify.entities de nombres a ocultar; scan_pii / redact_text los detectan determinísticamente — así como las variantes de sufijo/abreviatura que NER omite (BRIGHTWATER HLDGS P/L por Brightwater Holdings Pty Ltd) — como KNOWN_ENTITY. La lista permanece local y nunca entra en el contexto del modelo. Consulta docs/known_entities.md.
Demostración
Prueba las cinco herramientas en vivo contra datos sintéticos con el MCP Inspector oficial:
python -m obsify.make_corpus --out ./corpus_demo
npx @modelcontextprotocol/inspector obsify-mcpLlama a scan_pii en ./corpus_demo/ledger.xlsx y confirma que devuelve solo tipos, recuentos y ubicaciones — nunca valores. Consulta docs/verifying.md.
Pruébalo — corpus sintético
Genera un corpus falso pero realista (todo sintético; ABN/ACN/TFN son válidos por suma de verificación) que abarque los tres formatos, y luego apunta una herramienta a él:
pip install "obsify[demo]" # reportlab, for the sample PDFs
python -m obsify.make_corpus --out ./corpus_demoEscribe un libro de Excel de varias hojas (un campo minado de falsos positivos numéricos), una carta de compromiso PDF (prosa + tabla de saldos de comprobación) y un memo de auditoría DOCX (párrafos + tabla de proveedores). Ideal para probar scan_pii / make_synthetic_twin sin tocar datos reales.
Instalación y ejecución como servidor MCP
Requiere Python 3.11+. obsify habla MCP a través de stdio — el cliente lo lanza como un subproceso local; nada se aloja de forma remota. Regístralo con cualquier cliente compatible con MCP (Claude Desktop, Claude Code, Cursor, VS Code, …) añadiendo un bloque a la configuración de ese cliente.
Recomendado — instalación cero mediante uvx:
{ "mcpServers": { "obsify": { "command": "uvx", "args": ["obsify-mcp"] } } }uvx obtiene obsify de PyPI y lo ejecuta bajo demanda — sin instalación permanente. En la primera ejecución, obsify descarga el modelo NER de spaCy (en_core_web_lg, ~560 MB) una vez y lo almacena en caché; esto descarga un modelo público y no envía datos de usuario (establece OBSIFY_AUTO_DOWNLOAD=0 para prohibirlo e instalar el modelo tú mismo). Las ejecuciones posteriores son instantáneas y completamente fuera de línea.
O instálalo (pip / pipx):
pipx install obsify # isolated, on PATH (or: pip install obsify)Luego apunta el cliente al comando instalado:
{ "mcpServers": { "obsify": { "command": "obsify-mcp" } } }Reinicia el cliente y las herramientas aparecen. Extras opcionales: obsify[tables] (alternativa para tablas complejas en PDF mediante camelot + Ghostscript), obsify[compute] (pandas, útil dentro del código de run_on_real).
Problema con PATH (la causa #1 de "el servidor no se conecta"): el
commanddebe resolverse en el PATH que ve el cliente. Un cliente GUI puede no compartir el PATH de tu venv. Soluciones: usauvx/pipx(resoluble globalmente), o proporciona una ruta absoluta —"/path/to/.venv/bin/obsify-mcp"(macOS/Linux) o"C:\\path\\.venv\\Scripts\\obsify-mcp.exe"(Windows).
Desde este repositorio (antes de que esté en PyPI):
pip install "git+https://github.com/Formative-Sum41/obsify.git" # gets `obsify-mcp` + `obsify`La capa de enrutamiento — determinista, no un juicio subjetivo
La parte difícil de "ayúdame, pero no leas el archivo confidencial" es decidir cuándo proteger. obsify saca esa decisión del modelo y la pone en el entorno:
.obsify.json— un manifiesto de etiquetas que clasifica las rutas (public/confidential/restricted).obsify.guard(se ejecuta comopython -m obsify.guard) — un guardia PreToolUse que bloquea la lectura directa de un archivo etiquetado (salida 2) y redirige al asistente ascan_pii/make_synthetic_twin/run_on_real.Una convención (en
CLAUDE.md) para que el asistente prefiera obsify incluso antes de toparse con el guardia.
Configúralo con un solo comando:
obsify init [--dir PATH] [--with-claude-md]obsify init es no destructivo por diseño — posee exactamente un archivo y te proporciona fragmentos para el resto:
.obsify.json— obsify posee esto; init lo escribe (nunca se sobrescribe sin--force)..claude/settings.json— tu archivo: init imprime el bloque del hook PreToolUse para pegar, nunca lo edita (ejecuta código, por lo que registrarlo es tu decisión).CLAUDE.md— tu archivo: la convención es opt-in. Por defecto lo imprime;--with-claude-mdañade un bloque envuelto en marcadores e idempotente que nunca sobrescribe tu contenido.
Convención completa: docs/obsify_routing.md.
Cómo la detección se mantiene precisa
Identificadores validados por suma de verificación. Los candidatos ABN/ACN/TFN se proponen mediante expresiones regulares y se confirman con sus sumas de verificación oficiales, por lo que un número aleatorio nunca se reporta como identificador.
IDs con contexto requerido. Un número desnudo solo se acepta como ABN/ACN/TFN cuando una palabra etiqueta ("TFN", "ABN", "BSB", …) está cerca — esto elimina la avalancha de falsos positivos de ID de diario secuencial en libros numéricos.
Supresión de letras / NER con dígitos. Los números puros, cantidades, fechas y códigos alfanuméricos no se marcan como nombres/orgs; los nombres reales, correos electrónicos y direcciones (que llevan letras) no se ven afectados. La PII validada sin letras sigue exenta: IDs con suma de verificación (ABN/ACN/TFN/Medicare), tarjetas Luhn, IPs válidas, cuentas adyacentes a BSB y teléfonos (mediante contexto o forma de teléfono) — mientras que un punto decimal sigue marcando una cantidad, no un teléfono.
Precisión medida
obsify incluye un harness de evaluación puntuado (eval/ — corpus sintético etiquetado + clave de respuestas + puntuador contra el detector de envío, más una verificación cruzada independiente de terceros). Titular en el corpus sintético: 100% de recall en elementos esperados detectables, 0 falsos positivos en una hoja de tortura de FP numéricos (con un guardia de números agrupados), IDs con puerta de contexto desnudos correctamente suprimidos. Verificación cruzada independiente vs Microsoft presidio-research: EMAIL/IBAN 100%, PERSON 94%.
El harness se ganó su lugar — encontró defectos reales, que luego se corrigieron: las tarjetas de crédito y los números de teléfono estaban siendo suprimidos en silencio por el filtro de ruido numérico (ahora exentos mediante validación de suma de verificación / forma de teléfono), y Medicare, IP, fecha de nacimiento, pasaporte australiano y licencia de conducir no tenían reconocedor (ahora añadidos, con puerta de suma de verificación o contexto). Método completo, números y brechas documentadas restantes (SWIFT/BIC, fechas no DOB): eval/README.md.
Pruebas
pip install -e ".[dev]"
pytest tests/ # or run any file directly: python tests/test_obsify.pyDoce suites (73 pruebas), ejecutadas en CI en Linux + Windows / Python 3.11 + 3.12:
mcp-protocol — lanza el servidor real sobre stdio y habla MCP con él (el mismo camino que un cliente como Claude): confirma que las cinco herramientas se registran con esquemas válidos y que las llamadas hacen un viaje de ida y vuelta a través de JSON-RPC — incluyendo
scan_piidevolviendo solo forma, de extremo a extremo.checksums — anclado a ejemplos trabajados de ABN/ACN/TFN publicados externamente (válidos y corruptos), lo que rompe la circularidad generador↔validador.
obsify / gemelo / redacción — los invariantes de privacidad: salida solo de forma, gemelos sin fugas y una autocomprobación de cierre por fallo.
precision — los supresores de falsos positivos eliminan el ruido del libro numérico mientras mantienen los nombres reales.
routing — la clasificación de bloqueo/permiso del guardia y el contrato no destructivo de
obsify init.corpus — el corpus sintético PDF+Excel+DOCX de extremo a extremo: detección por formato, extracción de párrafos+tablas de DOCX y salida solo de forma en cada formato.
evaluation — el harness puntuado como puerta de regresión (recall, supresión, tortura de FP, brechas).
robustness — degradación elegante: entradas corruptas/demasiado grandes/vacías/anidadas/no compatibles nunca fallan y siempre se muestran como notas.
model / variants — lógica de descarga automática del modelo en primera ejecución; normalización de variantes detrás de
verify_value_free.
Para verificación interactiva (MCP Inspector) y la comprobación de última milla con cliente en vivo, consulta docs/verifying.md.
Licencia
MIT — consulta LICENSE.
Available Tools
5 toolsmake_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
Scored across 5 tools
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.
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.
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).
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
Related MCP Connectors
Governed access to sensitive data, secrets and APIs for AI agents. A signed proof for each decision.
Deterministic runtime safety for AI agents: scan PII, gate tool actions, verify LLM output.
300+ deterministic data utilities for AI agents: validate, normalize, parse, match, redact.
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceLet 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
- AlicenseNot gradedqualityBmaintenanceEnables 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.2AGPL 3.0
- FlicenseNot gradedqualityNot gradedmaintenanceEnables 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.-
- AlicenseNot gradedqualityBmaintenanceEnables 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.1MIT