Hiberden

hiberden-mcp：Hiberden MCP 服务

通过 stdio 传输协议（以换行符分隔的 JSON-RPC 2.0），将 Hiberden 归档引擎（hiberden-core）作为 Model Context Protocol 工具提供。

MCP 是一项开放且不受供应商限制的标准，因此任何 MCP 客户端都可以驱动此服务：Claude Desktop / Claude Code、OpenAI's Agents SDK 和 ChatGPT 桌面版、Gemini、Cursor、Windsurf 等。本进程不包含模型，也不需要 API 密钥。大模型由客户端提供；此二进制文件只会针对本地目录响应工具调用。在默认模式下，它不会执行任何网络 I/O。

默认执行读取和验证

默认情况下，服务会公布并响应以下读取和验证工具，不会修改任何配置。默认工具唯一会写入的状态是 verify_copy 记录的内容：副本的状态、验证通过的来源信息（运行的算法、最近一次完整验证通过的时间），以及每次完成验证对应的一条审计日志记录；而且只有在确实从介质读回数据后才会写入这些内容。

写入和删除工具（目录管理、目标位置、策略）已实现，但受目录持久化的权限等级控制，该等级默认为只读，且只能在 Hiberden 桌面应用的设置中更改；高于当前权限等级的工具既不会公布，也不会被接受。请参阅 docs/Hiberden_MCP_Command_Surface_and_Permission_Model.md（该文档取代 docs/mcp/write-gate-design.md）。

读取与验证工具（始终启用）

工具	参数	功能
list_projects	无	顶层项目（容器）。每个项目包括：名称、策略、归档数量，以及各覆盖状态下归档数量的汇总。
list_archives	project_id?、collection_id?、name?	归档（实际写入介质的叶节点）。每个归档包括：项目、大小、SHA-256、3-2-1 覆盖情况，以及每个副本的状态（目标位置 + 类型 + 状态）。可按项目、Collection 和／或不区分大小写的名称子串筛选。
list_collections	project_id	一个项目内的 Collection（仅用于编目整理的节点）：ID、名称、父级、归档数量。
coverage_status	无	全库 3-2-1 覆盖情况汇总：归档总数，以及未配置、未受保护、进行中、有风险和完全覆盖的数量。
archive_detail	archive_id	单个归档的完整详情：项目、大小、SHA-256、旧版 MD5（如为导入归档）、覆盖情况，以及每个副本的目标位置、类型、状态、地址和写入／验证时间戳。
list_destinations	无	已配置的目标位置（Tape、LocalFs、NAS、Cloud），包括 ID、槽位、类型、名称，以及启用／已退役状态。
list_tapes	无	磁带：序列号、卷标、uuid、容量、已用字节数、上次验证时间和副本数量。
tape_detail	serial	按条码标识的单盒磁带：标签、容量、已用字节数、上次验证时间，以及存储在其中的归档。
recent_activity	limit?	最近的副本活动，按时间从新到旧排列（默认 20 条）：每个副本的归档、目标位置、状态，以及写入／验证时间戳。
find_file	query、limit?	跨所有归档按文件名／路径片段查找文件，并列出其所在的归档和每个存储目标位置。
list_archive_files	archive_id、offset?、limit?	根据目录索引获取单个归档的文件清单（路径、大小、每个文件的 SHA-256），支持分页。可生成报告：从索引生成客户端可用的交付文件列表和校验和清单（首次回填时可能会读取预先建立索引的归档的本地副本）。无法建立索引的归档（仅从旧版磁带导入）会返回 indexed: false——表示清单不可用，而非清单为空。
list_jobs	limit?	最近的后台作业（保存、验证、还原），按时间从新到旧排列：操作、状态、归档、目标位置、字节数、时间戳，以及失败／中断作业记录的失败原因。
catalog_stats	无	一次调用即可汇总库存和容量：数量、归档总字节数、按状态划分的副本数量、按类型划分的目标位置，以及磁带容量与使用情况。
verify_copy	archive_id、destination_id、mode?	从介质重新读取副本并与记录内容比较。默认 mode: "full" 会重新计算 SHA-256，并在存在记录值时重新计算已记录的 BLAKE3 和存储的签名；匹配时将副本标记为已验证，不匹配时标记为失败，文件不存在时标记为缺失——这是唯一可提升副本状态的验证方式。mode: "fast" 仅重新读取 BLAKE3，可维持已有的已验证状态，或发现不匹配，但绝不会提升状态（没有已记录的快速校验哈希时会回退到完整验证，并说明原因）。结果和审计记录会注明所用算法。

verify_copy 是差异化功能：它依据实际介质提供证明，而非依赖存储的标记。使用 archive_id + destination_id 标识副本。它适用于磁盘和 NAS 副本，也适用于磁带副本（会装载磁带并读回数据）。Cloud（S3）读回验证在 Hiberden 桌面应用中运行，而非在此处运行：对于云副本，该工具会明确提示副本已在桌面应用中检查，而非在此处检查，因此该副本既未通过验证，也未验证失败。此提示表示未尝试验证，并非验证失败。

此处不提供添加归档（写入字节）、保存和还原功能。 目录、目标位置和策略配置工具受上述权限级别限制；在默认的只读级别下，这些工具既不会公开，也不会接受调用。

目录选择

服务会读取桌面应用、命令行和此服务共用的单个目录。路径解析规则如下：

1. 如果设置了 HIBERDEN_DB 环境变量，则使用该变量。
2. 否则，在 Windows 上使用 %LOCALAPPDATA%\Hiberden\catalog.db，在 Linux 上使用 ~/.hiberden/catalog.db。

每次调用工具时都会重新打开目录（耗时不到 1 毫秒），而不是在进程整个生命周期内一直保持打开。启用 WAL 模式并设置忙碌超时后，桌面应用和此服务可以同时使用同一个 catalog.db，不会有多进程锁定风险。

所有诊断信息都写入 stderr。stdout 承载 JSON-RPC 通道；任何非 JSON-RPC 消息写入 stdout 都会破坏数据流。

Linux 无头套件

Linux 二进制文件发布在 releases 页面和 cdn.hiberden.app。它们基于 Ubuntu 22.04 构建，因此可在 Ubuntu 22.04+、Debian 12+ 及同类系统上运行；已在 debian:bookworm-slim 和 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 与 Windows 版使用相同的连接器。CLI（hiberden）无需显示服务器或网络即可编目和归档——这套工具的核心目的，就是让隔离网络或无头机器也能运行。

Linux 版于 2026-08-11 随 1.3.1 版与 Windows 版一同正式发布。以下是准确的适用范围说明：

• 创建新归档需要许可证。 读取自己的数据不需要许可证。GA 之前发布的套件不受此限制，今后也会继续如此；从第一个 GA 之后的套件起，才需要授权。现在归档的内容以后不会变得无法读取：所有平台使用相同的格式和目录。
• 桌面应用也可在 Linux 上运行，可从 hiberden.app/linux 下载带签名的 .deb 和 .AppImage。适用于 Apple Silicon 的 macOS 版本可从 hiberden.app/download 下载。
• Linux 上的磁带功能尚未经过硬件验证。 后端面向开源 LTFS 实现，但从未在任何平台上连接磁带驱动器运行过。可使用 HIBERDEN_TAPE_FAKE=1，在不连接驱动器的情况下测试相关流程。
• 归档使用每次安装专属的 Ed25519 身份进行签名，该身份存储在 ~/.hiberden/keys/ 下（仅所有者可访问）。它与其他平台的操作系统密钥环采用相同的密钥保管模式，安全性也没有更高：它不受硬件保护。

设置

该二进制文件可自动安装到已知的 MCP 客户端中：

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 会写入（或更新）一个指向此可执行文件的 mcpServers.hiberden 条目。目录无需配置：如果环境中已设置 HIBERDEN_DB，该条目只会固定此变量；否则会使用默认路径 %LOCALAPPDATA%\Hiberden\catalog.db。

手动配置

如需手动接入，请将以下内容添加到客户端的配置中（Claude Desktop：claude_desktop_config.json；Claude Code：.mcp.json；Cursor / Windsurf 使用相同的 mcpServers 格式）。command 是可执行文件的路径。env 为可选项：只有当目录存放在默认路径以外的位置时，才需要包含 HIBERDEN_DB。

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

冒烟测试（无需客户端）

此命令会将三个请求（初始化、列出工具、读取覆盖范围）直接传入二进制文件：

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

容器映像

Docker Hub 上的映像 agaveis/hiberden-mcp 是运行在 debian:bookworm-slim 容器中的同一个连接器二进制文件。映像不包含目录：它会启动并报告自身信息，提供只读工具，但没有可供回答问题的归档内容。这不是运行 Hiberden 的方式。如需实际使用，请从 https://hiberden.app 安装 Hiberden。

该映像的用途是让 MCP 目录能够在 Linux 沙箱中与连接器执行自检握手（初始化，然后调用 tools/list），也让任何人都能在无需安装的情况下查看其提供的工具。

如需让它访问实际目录，请挂载目录并设置 HIBERDEN_DB：

docker run --rm -i -v /var/lib/hiberden:/cat -e HIBERDEN_DB=/cat/catalog.db agaveis/hiberden-mcp

连接器以只读模式打开该目录，但 verify 会写入状态；连接器绝不会读取操作系统密钥环。

安全性

• 仅在本地和封闭域中运行。服务仅负责读取和验证，不执行任何网络 I/O；唯一写入的状态是读取后由 verify_copy 写入的副本状态。它绝不会向 Hiberden 或任何第三方发送数据。
• 二进制文件中不存储 API 密钥或大模型，因此其中没有可被窃取的内容。
• verify_copy 提供真实的物理状态：它会重新读取并重新计算实际介质的哈希，因此即使助手受到操纵，也无法伪造“已验证”状态。
• 工具注释（readOnlyHint、destructiveHint 等）只是提示，而非保证。提示词注入是整个行业尚未解决的问题。这里的架构经过保守设计，但这并不意味着能够免受此类问题影响。

隐私

服务完全运行在你自己的机器上，不持有任何账户或 API 密钥，并且在默认的读取和验证模式下不执行任何网络 I/O——它绝不会向 Hiberden 或任何第三方发送你的目录或文件。默认工具写入的唯一状态，是在实际读取后由 verify_copy 写入的副本状态。完整详情（服务会读取什么、绝不会执行什么、单独的 AI 客户端所起的作用，以及凭据处理方式）请参阅托管于 https://hiberden.app/mcp/privacy 的 PRIVACY.md。

磁带注意事项

此实现尚未在实体磁带硬件上验证磁带支持。该设计不会直接与 SCSI 通信，而是通过 LTFS 工具将磁带视为文件系统，因此原则上，LTFS 工具能够挂载的任何磁带都应该可以使用。这是架构特性，并非经过测试的硬件兼容性清单。请勿将这些说明视为对任何特定驱动器或代际的保证。

无需驱动器即可进行测试：磁带后端可使用假后端运行： 设置 HIBERDEN_TAPE_FAKE=1（也可选择设置 HIBERDEN_TAPE_FAKE_ROOT=<dir>，指向一个模拟已挂载卷的目录）。

网站： https://hiberden.app

项目列表和源代码： https://github.com/Agaveis/hiberden-mcp

由亚利桑那州斯科茨代尔的 AgaveIS 构建并维护。