Skip to main content
Glama

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: taskvault

Herramientas

Herramienta

Qué hace

Devuelve

scan_pii(path)

Escanea un archivo/carpeta en busca de PII

Tipos, ubicaciones, recuentos — nunca valores

make_synthetic_twin(path, out)

Falso fiel de un libro de Excel

Resumen del esquema; gemelo escrito en out (valores falsos, verificación de fugas)

run_on_real(code, data_path)

Compute-to-data: ejecuta tu código localmente contra el archivo real (vinculado a DATA_PATH)

Solo stdout/stderr enmascarados de PII y con límite de tamaño — devuelve agregados

redact_text(text)

Enmascara PII en una cadena a tokens <TYPE>

La cadena redactada

verify_value_free(text, terms)

Verificación de cierre por fallo de que text no filtra ninguno de terms (o sus variantes)

{"value_free": bool}

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.

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