Hiberden

hiberden-mcp: Servidor MCP do Hiberden

Expõe o mecanismo de arquivamento do Hiberden (hiberden-core) como ferramentas do Model Context Protocol sobre o transporte stdio (JSON-RPC 2.0 delimitado por nova linha).

MCP é um padrão aberto e neutro entre fornecedores, então este único servidor pode ser controlado por qualquer cliente MCP: Claude Desktop / Claude Code, o SDK de Agentes da OpenAI e o ChatGPT desktop, Gemini, Cursor, Windsurf e outros. Não há modelo nem chave de API neste processo. O cliente traz o LLM; este binário apenas responde a chamadas de ferramentas contra o catálogo local. No seu modo padrão, ele não realiza nenhuma E/S de rede.

Leitura + verificação por padrão

O servidor anuncia e responde às ferramentas de leitura/verificação abaixo por padrão, e nada altera a configuração. O único estado que qualquer ferramenta padrão grava é o que verify_copy registra: o status da cópia, sua proveniência de verificação aprovada (qual algoritmo foi executado, quando a última passagem completa foi bem-sucedida) e uma linha de log de auditoria para cada verificação concluída — e isso só acontece após uma leitura real do meio.

As ferramentas de gravação e exclusão (gerenciamento de catálogo, destinos, políticas) ESTÃO implementadas, mas atrás de um nível de permissão persistido no catálogo que por padrão é somente leitura e só pode ser alterado nas configurações do aplicativo desktop do Hiberden; uma ferramenta acima do nível ativo não é anunciada nem aceita. Consulte docs/Hiberden_MCP_Command_Surface_and_Permission_Model.md (que substitui docs/mcp/write-gate-design.md).

Ferramentas de leitura + verificação (sempre ativas)

Ferramenta	Argumentos	O que faz
list_projects	nenhum	Projetos de nível superior (contêineres). Para cada um: nome, política, contagem de arquivos e um resumo de quantos de seus arquivos estão em cada estado de cobertura.
list_archives	project_id?, collection_id?, name?	Os arquivos (folhas realmente gravadas na mídia). Para cada um: projeto, tamanho, SHA-256, cobertura 3-2-1 e status por cópia (destino + tipo + status). Filtre por projeto, Coleção e/ou uma substring de nome sem diferenciar maiúsculas de minúsculas.
list_collections	project_id	As Coleções dentro de um projeto (nós organizacionais somente de catálogo): id, nome, pai, contagem de arquivos.
coverage_status	nenhum	Resumo 3-2-1 de toda a biblioteca: total de arquivos mais contagens em não configurado, desprotegido, em_andamento, em_risco e totalmente_coberto.
archive_detail	archive_id	Detalhes completos de um arquivo: projeto, tamanho, SHA-256, MD5 legado (se importado), cobertura e cada cópia com seu destino, tipo, status, endereço e carimbos de data/hora de gravação/verificação.
list_destinations	nenhum	Destinos configurados (Fita, LocalFs, NAS, Nuvem) com id, slot, tipo, nome e estado habilitado/desativado.
list_tapes	nenhum	Fitas: número de série, rótulo do volume, uuid, capacidade, bytes usados, última hora de verificação e contagem de cópias.
tape_detail	serial	Um cartucho por código de barras: rótulo, capacidade, bytes usados, última verificação e os arquivos armazenados nele.
recent_activity	limit?	Atividade recente de cópias, das mais novas para as mais antigas (padrão 20): arquivo de cada cópia, destino, status e carimbos de data/hora de gravação/verificação.
find_file	query, limit?	Encontre um arquivo por fragmento de nome/caminho em todos os arquivos, com o arquivo e cada destino em que ele está armazenado.
list_archive_files	archive_id, offset?, limit?	O manifesto de arquivos de um arquivo do índice do catálogo (caminho, tamanho, SHA-256 por arquivo), paginado. O habilitador de relatórios: listas de entregáveis prontas para o cliente e manifestos de soma de verificação do índice (um preenchimento único pode ler uma cópia local de um arquivo pré-indexado). Arquivos sem índice construível (importações legadas somente de fita) relatam indexed: false — manifesto indisponível, não vazio.
list_jobs	limit?	Trabalhos em segundo plano recentes (salvamentos, verificações, restaurações), dos mais novos para os mais antigos: verbo, estado, arquivo, destino, bytes, carimbos de data/hora e o motivo de falha registrado em linhas com falha/interrompidas.
catalog_stats	nenhum	Inventário em uma chamada + resumo de capacidade: contagens, total de bytes arquivados, cópias por status, destinos por tipo, capacidade de fita vs. uso.
verify_copy	archive_id, destination_id, mode?	Relê a cópia do seu meio e a compara com o que foi registrado. O padrão mode: "full" recalcula o hash SHA-256 mais o BLAKE3 registrado e a assinatura armazenada quando presente, e então marca a cópia como Verificada em caso de correspondência, Falhou em caso de divergência ou Ausente se o arquivo não existir — a única passagem que pode promover. mode: "fast" é uma releitura somente BLAKE3 que sustenta uma cópia já Verificada ou expõe uma divergência, mas nunca promove (sem hash rápido registrado, cai para uma passagem completa, com o motivo informado). Resultados e linhas de auditoria nomeiam o algoritmo que foi executado.

verify_copy é o diferencial: é uma prova do meio real, não um sinalizador armazenado. Identifique a cópia por archive_id + destination_id. Funciona para cópias em disco e NAS e para cópias em fita (o cartucho é montado e lido de volta). A verificação de leitura de nuvem (S3) é executada no aplicativo desktop do Hiberden, não aqui: para uma cópia em nuvem, a ferramenta retorna uma mensagem clara de que a cópia foi verificada no desktop, não aqui, então ela não passou nem falhou. Essa mensagem é um resultado de não tentativa, não uma falha de verificação.

Adicionar arquivos (gravar bytes), salvar e restaurar não são expostos aqui. As ferramentas de configuração de catálogo, destino e política existem atrás do nível de permissão descrito acima; no nível padrão somente leitura, elas não são anunciadas nem aceitas.

Seleção de catálogo

O servidor lê o único catálogo compartilhado pelo aplicativo desktop, a CLI e este servidor. Resolução de caminho:

1. A variável de ambiente HIBERDEN_DB, se definida.
2. Caso contrário, %LOCALAPPDATA%\Hiberden\catalog.db no Windows, ou ~/.hiberden/catalog.db no Linux.

O catálogo é aberto novamente a cada chamada de ferramenta (sub-milissegundo) em vez de ser mantido durante toda a vida do processo. Com o modo WAL e um tempo limite de ocupação, o aplicativo desktop e este servidor podem ser executados contra o mesmo catalog.db ao mesmo tempo sem um risco de bloqueio entre processos.

Todos os diagnósticos vão para o stderr. O stdout carrega o canal JSON-RPC; qualquer coisa gravada no stdout que não seja uma mensagem JSON-RPC corrompe o fluxo.

Kit Linux sem cabeça

Os binários Linux são publicados na página de releases e em cdn.hiberden.app. Eles são compilados no Ubuntu 22.04, então são executados no Ubuntu 22.04+, Debian 12+ e equivalentes; verificados em debian:bookworm-slim e 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 é o mesmo conector da compilação Windows. A CLI (hiberden) cataloga e arquiva sem servidor de exibição e sem rede — todo o objetivo do kit é que uma máquina isolada ou sem cabeça possa executá-lo.

O Linux atingiu disponibilidade geral em 11/08/2026 na versão 1.3.1, junto com o Windows. O que isso cobre e não cobre, precisamente:

• Gravar um novo arquivo exige uma licença. Ler seus dados de volta nunca exige, com ou sem licença. Kits publicados antes do GA não têm restrição e permanecem assim; o direito se aplica a partir do primeiro kit pós-GA em diante. Nada que você arquivar agora se tornará ilegível depois: o formato e o catálogo são idênticos em todas as plataformas.
• O aplicativo desktop também é executado no Linux, como um .deb e .AppImage assinados em hiberden.app/linux. Um beta para macOS para Apple Silicon está em hiberden.app/download.
• Fita no Linux não é comprovada em hardware. O backend tem como alvo a implementação de código aberto do LTFS e nunca foi executado contra uma unidade em nenhuma plataforma. Use HIBERDEN_TAPE_FAKE=1 para exercitar os fluxos sem uma.
• Os arquivos são assinados por uma identidade Ed25519 por instalação armazenada em ~/.hiberden/keys/ (somente proprietário). É o mesmo modelo de custódia dos chaveiros do sistema operacional em outras plataformas, e não é mais forte: não é respaldado por hardware.

Configuração

O binário se autoinstala em clientes MCP conhecidos:

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 grava (ou atualiza) uma entrada mcpServers.hiberden apontando para este executável. É zero-configuração para o catálogo: a entrada só fixa HIBERDEN_DB quando você já a definiu no seu ambiente; caso contrário, ela depende do caminho padrão %LOCALAPPDATA%\Hiberden\catalog.db.

Configuração manual

Para conectá-lo manualmente, adicione isto à configuração do seu cliente (Claude Desktop: claude_desktop_config.json; Claude Code: .mcp.json; Cursor / Windsurf usam o mesmo formato mcpServers). command é o caminho para o executável. env é opcional: inclua HIBERDEN_DB somente se o seu catálogo estiver em um local diferente do caminho padrão.

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

Teste rápido (sem cliente necessário)

Isto envia três solicitações (inicializar, listar ferramentas, ler cobertura) diretamente para o binário:

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

Segurança

• Somente local e domínio fechado. O servidor é somente leitura + verificação e realiza zero E/S de rede; o único estado que ele grava é o status da cópia verify_copy registra após uma leitura. Ele nunca envia dados para o Hiberden ou terceiros.
• Nenhuma chave de API e nenhum LLM são armazenados no binário, então não há nada para roubar ali.
• verify_copy fornece o estado físico real: ele relê e recalcula o hash do meio real, então mesmo um assistente manipulado não pode fabricar um "Verificado".
• Anotações de ferramentas (readOnlyHint, destructiveHint e assim por diante) são dicas, não garantias. Injeção de prompt é um problema não resolvido em toda a indústria. A arquitetura aqui é conservadora por design; isso não é uma alegação de imunidade.

Privacidade

O servidor é executado inteiramente na sua própria máquina, não mantém conta nem chave de API e, no seu modo padrão de leitura e verificação, realiza zero E/S de rede — ele nunca envia seu catálogo ou seus arquivos para o Hiberden ou terceiros. O único estado que qualquer ferramenta padrão grava é o status da cópia verify_copy registra após uma leitura real. Detalhes completos (o que o servidor lê, o que ele nunca faz, o papel do cliente de IA separado e o tratamento de credenciais) estão em PRIVACY.md, hospedado em https://hiberden.app/mcp/privacy.

Ressalva sobre fita

O suporte a fita está em beta e não foi validado em hardware de fita física nesta implementação. O design nunca fala SCSI diretamente e trata a fita como um sistema de arquivos por meio das ferramentas LTFS, então qualquer fita que as ferramentas LTFS possam montar deve funcionar por construção. Isso é uma propriedade arquitetural, não uma matriz de hardware testada. Não leia estas notas como uma garantia para qualquer unidade ou geração específica.

Para testes sem uma unidade, o backend de fita pode ser executado contra um backend falso: defina HIBERDEN_TAPE_FAKE=1 (e opcionalmente HIBERDEN_TAPE_FAKE_ROOT=<dir> para apontar para um diretório que represente o volume montado).