Hiberden

hiberden-mcp: Servidor MCP de Hiberden

Expone el motor de archivo de Hiberden (hiberden-core) como herramientas del Model Context Protocol a través del transporte stdio (JSON-RPC 2.0 delimitado por nuevas líneas).

MCP es un estándar abierto y neutral respecto al proveedor, por lo que este único servidor se puede controlar desde cualquier cliente MCP: Claude Desktop / Claude Code, el SDK de Agents de OpenAI y el escritorio de ChatGPT, Gemini, Cursor, Windsurf y otros. No hay modelo ni clave de API en este proceso. El cliente aporta el LLM; este binario solo responde a llamadas de herramientas contra el catálogo local. En su modo predeterminado no realiza ninguna E/S de red.

Lectura y verificación por defecto

El servidor anuncia y responde a las herramientas de lectura/verificación a continuación por defecto, y nada muta la configuración. El único estado que cualquier herramienta predeterminada escribe es lo que verify_copy registra: el estado de la copia, su procedencia de verificación aprobada (qué algoritmo se ejecutó, cuándo tuvo éxito la última pasada completa) y una fila de registro de auditoría por cada verificación completada — y solo lo hace después de una lectura real desde el medio.

Las herramientas de escritura y eliminación (gestión de catálogo, destinos, políticas) SÍ están implementadas, pero detrás de un nivel de permisos persistido en el catálogo que por defecto es de solo lectura y solo se puede cambiar en la configuración de la aplicación de escritorio de Hiberden; una herramienta por encima del nivel activo no se anuncia ni se acepta. Ver docs/Hiberden_MCP_Command_Surface_and_Permission_Model.md (que reemplaza a docs/mcp/write-gate-design.md).

Herramientas de lectura y verificación (siempre activas)

Herramienta	Argumentos	Qué hace
list_projects	ninguno	Proyectos de nivel superior (contenedores). Para cada uno: nombre, política, recuento de archivos y un resumen de cuántos de sus archivos se encuentran en cada estado de cobertura.
list_archives	project_id?, collection_id?, name?	Los archivos (hojas realmente escritas en los medios). Para cada uno: proyecto, tamaño, SHA-256, cobertura 3-2-1 y estado por copia (destino + tipo + estado). Filtre por proyecto, Colección y/o una subcadena de nombre que no distinga mayúsculas y minúsculas.
list_collections	project_id	Las Colecciones dentro de un proyecto (nodos organizativos solo de catálogo): id, nombre, padre, recuento de archivos.
coverage_status	ninguno	Resumen 3-2-1 de toda la biblioteca: archivos totales más recuentos en no configurado, sin protección, en_progreso, en_riesgo y totalmente_cubierto.
archive_detail	archive_id	Detalle completo de un archivo: proyecto, tamaño, SHA-256, MD5 heredado (si se importó), cobertura y cada copia con su destino, tipo, estado, dirección y marcas de tiempo de escritura/verificación.
list_destinations	ninguno	Destinos configurados (Cinta, LocalFs, NAS, Nube) con id, ranura, tipo, nombre y estado habilitado/jubilado.
list_tapes	ninguno	Cintas: número de serie, etiqueta de volumen, uuid, capacidad, bytes usados, última hora de verificación y recuento de copias.
tape_detail	serial	Un cartucho por código de barras: etiqueta, capacidad, bytes usados, última verificación y los archivos almacenados en él.
recent_activity	limit?	Actividad de copias reciente, de más reciente a más antigua (20 por defecto): archivo de cada copia, destino, estado y marcas de tiempo de escritura/verificación.
find_file	query, limit?	Buscar un archivo por fragmento de nombre/ruta en todos los archivos, con el archivo y cada destino en el que está almacenado.
list_archive_files	archive_id, offset?, limit?	El manifiesto de archivos de un archivo del índice del catálogo (ruta, tamaño, SHA-256 por archivo), paginado. El habilitador de informes: listas de entregables listas para el cliente y manifiestos de suma de verificación del índice (una carga inicial única puede leer una copia local de un archivo preindexado). Los archivos sin índice construible (importaciones heredadas solo de cinta) informan indexed: false — manifiesto no disponible, no vacío.
list_jobs	limit?	Trabajos en segundo plano recientes (guardados, verificaciones, restauraciones), de más reciente a más antiguo: verbo, estado, archivo, destino, bytes, marcas de tiempo y el motivo de fallo registrado en filas fallidas/interrumpidas.
catalog_stats	ninguno	Resumen de inventario + capacidad en una sola llamada: recuentos, bytes archivados totales, copias por estado, destinos por tipo, capacidad de cinta frente a uso.
verify_copy	archive_id, destination_id, mode?	Vuelve a leer la copia de su medio y la compara con lo registrado. El mode: "full" predeterminado vuelve a calcular el hash SHA-256 más el BLAKE3 registrado y la firma almacenada cuando está presente, luego marca la copia como Verificada en caso de coincidencia, Fallida en caso de discrepancia o Perdida si el archivo ya no existe — la única pasada que puede promover. mode: "fast" es una relectura solo BLAKE3 que mantiene una copia ya Verificada o expone una discrepancia pero nunca promueve (sin hash rápido registrado, se recurre a una pasada completa, con el motivo indicado). Los resultados y las filas de auditoría nombran el algoritmo que se ejecutó.

verify_copy es el diferenciador: es una prueba del medio real, no una marca almacenada. Identifique la copia por archive_id + destination_id. Funciona para copias en disco y NAS y para copias en cinta (el cartucho se monta y se lee de vuelta). La verificación de lectura en la nube (S3) se ejecuta en la aplicación de escritorio de Hiberden, no aquí: para una copia en la nube, la herramienta devuelve un mensaje claro de que la copia se verificó en el escritorio, no aquí, por lo que no ha pasado ni fallado. Ese mensaje es un resultado de no intentado, no un fallo de verificación.

Agregar archivos (escribir bytes), guardar y restaurar no están expuestos aquí. Las herramientas de configuración de catálogo, destino y política existen detrás del nivel de permisos descrito anteriormente; en el nivel de solo lectura predeterminado no se anuncian ni se aceptan.

Selección de catálogo

El servidor lee el catálogo único compartido por la aplicación de escritorio, la CLI y este servidor. Resolución de ruta:

1. La variable de entorno HIBERDEN_DB, si está configurada.
2. De lo contrario, %LOCALAPPDATA%\Hiberden\catalog.db en Windows, o ~/.hiberden/catalog.db en Linux.

El catálogo se abre de nuevo en cada llamada de herramienta (sub-milisegundo) en lugar de mantenerse durante la vida del proceso. Con el modo WAL y un tiempo de espera de ocupado, la aplicación de escritorio y este servidor pueden ejecutarse contra el mismo catalog.db al mismo tiempo sin un riesgo de bloqueo multiproceso.

Todos los diagnósticos van a stderr. stdout transporta el canal JSON-RPC; cualquier cosa escrita en stdout que no sea un mensaje JSON-RPC corrompe la secuencia.

Kit Linux sin cabeza

Los binarios de Linux se publican en la página de lanzamientos y en cdn.hiberden.app. Están compilados en Ubuntu 22.04, por lo que se ejecutan en Ubuntu 22.04+, Debian 12+ y equivalentes; verificados en debian:bookworm-slim y ubuntu:22.04.

curl -fsSLO https://cdn.hiberden.app/downloads/hiberden-cli-linux-x86_64
curl -fsSLO https://cdn.hiberden.app/downloads/hiberden-cli-linux-x86_64.sha256
sha256sum -c hiberden-cli-linux-x86_64.sha256      # verify before running it
chmod +x hiberden-cli-linux-x86_64
./hiberden-cli-linux-x86_64 --version

hiberden-mcp-linux-x86_64 es el mismo conector que la compilación de Windows. La CLI (hiberden) cataloga y archiva sin servidor de visualización y sin red — todo el propósito del kit es que una máquina aislada o sin cabeza pueda ejecutarlo.

Linux alcanzó disponibilidad general el 2026-08-11 en la versión 1.3.1, junto con Windows. Qué cubre y qué no cubre, con precisión:

• Escribir un nuevo archivo requiere una licencia. Leer sus datos de vuelta nunca la requiere, con licencia o no. Los kits publicados antes de GA no tienen restricciones y siguen así; la elegibilidad se aplica desde el primer kit posterior a GA en adelante. Nada de lo que archive ahora se vuelve ilegible más tarde: el formato y el catálogo son idénticos en todas las plataformas.
• La aplicación de escritorio también se ejecuta en Linux, como un .deb y .AppImage firmados desde hiberden.app/linux. Una beta de macOS para Apple Silicon está en hiberden.app/download.
• La cinta en Linux no está probada en hardware. El backend apunta a la implementación de LTFS de código abierto y nunca se ha ejecutado contra una unidad en ninguna plataforma. Use HIBERDEN_TAPE_FAKE=1 para ejercitar los flujos sin una.
• Los archivos están firmados por una identidad Ed25519 por instalación almacenada en ~/.hiberden/keys/ (solo propietario). Es el mismo modelo de custodia que los llaveros del sistema operativo en otras plataformas, y no más fuerte: no está respaldado por hardware.

Configuración

El binario se autoinstala en clientes MCP conocidos:

hiberden-mcp install          # auto-detect Claude Desktop / Cursor / Windsurf and write their config
hiberden-mcp install --print  # print a paste-ready snippet instead of touching anything
hiberden-mcp uninstall        # remove the hiberden entry from detected clients
hiberden-mcp help             # show usage

install escribe (o actualiza) una entrada mcpServers.hiberden que apunta a este ejecutable. Es de configuración cero para el catálogo: la entrada solo fija HIBERDEN_DB cuando ya lo tiene configurado en su entorno; de lo contrario, se basa en la ruta %LOCALAPPDATA%\Hiberden\catalog.db predeterminada.

Configuración manual

Para conectarlo manualmente, agregue esto a la configuración de su cliente (Claude Desktop: claude_desktop_config.json; Claude Code: .mcp.json; Cursor / Windsurf usan la misma forma mcpServers). command es la ruta al ejecutable. env es opcional: incluya HIBERDEN_DB solo si su catálogo se encuentra en un lugar distinto de la ruta predeterminada.

{
  "mcpServers": {
    "hiberden": {
      "command": "C:/path/to/hiberden-mcp.exe",
      "env": { "HIBERDEN_DB": "C:/path/to/catalog.db" }
    }
  }
}

Prueba de humo (sin necesidad de cliente)

Esto envía tres solicitudes (initialize, list tools, read coverage) directamente al binario:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"coverage_status","arguments":{}}}' \
  | HIBERDEN_DB=path/to/catalog.db hiberden-mcp

Seguridad

• Solo local y de dominio cerrado. El servidor es solo de lectura + verificación y realiza cero E/S de red; el único estado que escribe es el estado de copia que verify_copy sella después de una lectura. Nunca envía datos a Hiberden ni a terceros.
• No hay clave de API ni LLM almacenados en el binario, por lo que no hay nada que robar allí.
• verify_copy proporciona el estado físico real: vuelve a leer y vuelve a calcular el hash del medio real, por lo que incluso un asistente manipulado no puede fabricar un "Verificado".
• Las anotaciones de herramientas (readOnlyHint, destructiveHint, etc.) son sugerencias, no garantías. La inyección de prompts es un problema sin resolver en toda la industria. La arquitectura aquí es conservadora por diseño; eso no es una afirmación de inmunidad.

Privacidad

El servidor se ejecuta completamente en su propia máquina, no tiene cuenta ni clave de API, y en su modo predeterminado de lectura y verificación realiza cero E/S de red — nunca envía su catálogo ni sus archivos a Hiberden ni a terceros. El único estado que cualquier herramienta predeterminada escribe es el estado de copia que verify_copy sella después de una lectura real. Los detalles completos (qué lee el servidor, qué nunca hace, el papel del cliente de IA separado y el manejo de credenciales) están en PRIVACY.md, alojado en https://hiberden.app/mcp/privacy.

Advertencia sobre cintas

El soporte de cintas está en beta y no se ha validado en hardware de cinta física en esta implementación. El diseño nunca habla SCSI directamente y trata la cinta como un sistema de archivos a través de las herramientas LTFS, por lo que cualquier cinta que las herramientas LTFS puedan montar debería funcionar por construcción. Esa es una propiedad arquitectónica, no una matriz de hardware probada. No lea estas notas como una garantía para ninguna unidad o generación específica.

Para probar sin una unidad, el backend de cinta puede ejecutarse contra un backend simulado: configure HIBERDEN_TAPE_FAKE=1 (y opcionalmente HIBERDEN_TAPE_FAKE_ROOT=<dir> para apuntar a un directorio que represente el volumen montado).