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_real ejecuta 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. Lee SECURITY.md antes 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: Cloakbox

Herramientas

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-mcp

Llama 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_demo

Escribe 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 command debe resolverse en el PATH que ve el cliente. Un cliente GUI puede no compartir el PATH de tu venv. Soluciones: usa uvx/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:

1. .obsify.json — un manifiesto de etiquetas que clasifica las rutas (public / confidential / restricted).

2. obsify.guard (se ejecuta como python -m obsify.guard) — un guardia PreToolUse que bloquea la lectura directa de un archivo etiquetado (salida 2) y redirige al asistente a scan_pii / make_synthetic_twin / run_on_real.

3. 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-md añ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.py

Doce 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_pii devolviendo 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.