Agaveis/hiberden-mcp

Exposes the Hiberden archive engine (hiberden-core) as Model Context
Protocol tools over the stdio transport
(newline-delimited JSON-RPC 2.0).
MCP is an open, vendor-neutral standard, so this one server is drivable from any
MCP client: Claude Desktop / Claude Code, OpenAI's Agents SDK and ChatGPT
desktop, Gemini, Cursor, Windsurf, and others. There is no model and no API key
in this process. The client brings the LLM; this binary only answers tool calls
against the local catalog. In its default mode it performs no network I/O.
Read + verify by default
The server advertises and answers the read/verify tools below by default, and
nothing mutates configuration. The only state any default tool ever writes
is what verify_copy records: the copy's status, its verify-pass provenance
(which algorithm ran, when the last full pass succeeded), and an audit-log
row for each completed verify — and it only does that after a genuine
read-back from the medium.
Write and delete tools (catalog management, destinations, policies) ARE
implemented, but behind a catalog-persisted permission tier that defaults to
read-only and is only changeable in the Hiberden desktop app's settings; a
tool above the active tier is neither advertised nor accepted. See
docs/Hiberden_MCP_Command_Surface_and_Permission_Model.md (which supersedes
docs/mcp/write-gate-design.md).
Read + verify tools (always on)
| Tool | Args | What it does |
|------|------|--------------|
| list_projects | none | Top-level projects (containers). For each: name, policy, archive count, and a roll-up of how many of its archives sit in each coverage state. |
| list_archives | project_id?, collection_id?, name? | The archives (leaves actually written to media). For each: project, size, SHA-256, 3-2-1 coverage, and per-copy status (destination + kind + status). Narrow by project, Collection, and/or a case-insensitive name substring. |
| list_collections | project_id | The Collections inside one project (catalog-only organizational nodes): id, name, parent, archive count. |
| coverage_status | none | Library-wide 3-2-1 roll-up: total archives plus counts in unconfigured, unprotected, in_progress, at_risk, and fully_covered. |
| archive_detail | archive_id | Full detail for one archive: project, size, SHA-256, legacy MD5 (if imported), coverage, and every copy with its destination, kind, status, address, and written/verified timestamps. |
| list_destinations | none | Configured destinations (Tape, LocalFs, NAS, Cloud) with id, slot, kind, name, and enabled/retired state. |
| list_tapes | none | Tapes: serial, volume label, uuid, capacity, used bytes, last verified time, and copy count. |
| tape_detail | serial | One cartridge by barcode: label, capacity, used bytes, last verified, and the archives stored on it. |
| recent_activity | limit? | Recent copy activity, newest first (default 20): each copy's archive, destination, status, and write/verify timestamps. |
| find_file | query, limit? | Find a file by name/path fragment across every archive, with the archive and every destination it is stored in. |
| list_archive_files | archive_id, offset?, limit? | The file manifest of one archive from the catalog index (path, size, per-file SHA-256), paginated. The report enabler: client-ready deliverable lists and checksum manifests from the index (a one-time backfill may read a local copy of a pre-index archive). Archives with no buildable index (legacy tape-only imports) report indexed: false — manifest unavailable, not empty. |
| list_jobs | limit? | Recent background jobs (saves, verifies, restores), newest first: verb, state, archive, destination, bytes, timestamps, and the recorded failure reason on failed/interrupted rows. |
| catalog_stats | none | One-call inventory + capacity roll-up: counts, total archived bytes, copies by status, destinations by kind, tape capacity vs. use. |