attest-mcp

attest-mcp

已列入 官方 MCP 注册表，名称为 io.github.SPAZIO-GENESI/attest-mcp。

适用于 Spazio Genesi 认证服务的 MCP 服务和 CLI——可通过任何支持 MCP 的 AI Agent（Claude Code、Claude Desktop 等），或直接从终端 / CI 流水线认证、验证并检查数字作品是否存在。

充分保护隐私：文件字节永远不会离开你的设备。指纹（SHA-256）在本地计算，并从磁盘流式读取——只会发送哈希值和可选元数据。

📖 英文文档：attestazione.spaziogenesi.org/en ——网站、开发者文档以及服务等级 / 条款均提供英文版本。

功能

认证服务会为文件的 SHA-256 指纹添加时间戳并进行签名（HMAC），还可生成签名 PDF 证书以及锚定在 Bitcoin 上的 OpenTimestamps 证明。本服务将这些功能作为 MCP 工具提供，让 Agent 无需浏览器即可代表你认证和验证作品。

为什么选择它，而不只是 OpenTimestamps 封装

有几个 MCP 服务可以将哈希值提交到 OpenTimestamps 日历。据我们所知，这是唯一一个能返回完整存在性证明的服务——包括签名 PDF 证书、受认可的 RFC 3161 时间戳和 Bitcoin 锚定，而且免费，文件字节也绝不会离开调用者的设备。无需账户，无需上传，也无需付费公证链。如果你知道还有其他 MCP 服务具备同样的组合（完整证书 + 免费 + 本地哈希计算），我们很乐意了解——请提交 issue。

专为欧洲法律和监管环境打造

Spazio Genesi 是一家意大利非营利组织（ETS – 第三部门实体）。此软件包背后的认证服务在设计时就考虑了欧盟监管环境，而非事后才为其调整：

• GDPR 优先，隐私保护融入设计：文件本身绝不会到达我们的服务器——只会发送其 SHA-256 指纹（以及你选择声明的任何元数据）。
• 欧盟数据驻留：证书和证明归档在受欧盟司法管辖的 Cloudflare R2 中。
• 受认可的时间戳，不依赖单一信任来源：每份证书都包含来自以 AATL 为根的机构的 RFC 3161 时间戳（受 Adobe 和大多数 PDF 阅读器信任），以及通过 OpenTimestamps 独立锚定的 Bitcoin 时间戳。
• 如实说明 eIDAS 状态：此服务目前尚未获得 eIDAS 合格信任服务资质——签署者身份目前为自签名，合格电子印章则是计划中的升级项目，尚未实现。有关各项保障内容及其限制的完整、坦诚说明，请参阅技术白皮书。

完整的服务等级和条款：attestazione.spaziogenesi.org/en/condizioni。

安装

Claude Desktop——一条命令，无需手动编辑 JSON：

npx -y @spazio-genesi/attest-mcp-setup

此命令会查找你的 claude_desktop_config.json（Windows/macOS/Linux），添加 attest-mcp 条目，并先备份原始文件。如果现有文件不是有效 JSON，命令会拒绝进行任何修改——绝不会猜测。之后请重启 Claude Desktop。若要移除该配置，请添加 --uninstall。若要预览而不写入文件，请添加 --dry-run。

Claude Code：

claude mcp add attest-mcp -- npx -y @spazio-genesi/attest-mcp

手动配置 / 其他客户端——将以下内容添加到 MCP 客户端的配置中：

{
  "mcpServers": {
    "attest-mcp": {
      "command": "npx",
      "args": ["-y", "@spazio-genesi/attest-mcp"]
    }
  }
}

身份验证

两种身份验证方式，与底层服务保持一致：

1. API 密钥（用于合作伙伴集成，由 Spazio Genesi 手动签发）： 设置 IMGAUTH_API_KEY 环境变量。
2. 设备流程（用于个人/Agent）：不带参数调用 authorize 工具。它会返回一个 URL——打开该 URL，通过人工验证小组件完成批准，然后使用返回的代码再次调用 authorize。会话令牌（24 小时，20 次证明）将保存到 ~/.config/attest-mcp/credentials.json（在支持的平台上，权限设为 600），之后会自动使用。

无论采用哪种方式，凭据都只用于通过证明时的反机器人检查——服务端时间戳、加密签名和速率限制均不变。

工具

工具	功能
authorize	开始或继续设备流程授权。
attest_file	对本地文件进行哈希计算（流式处理）并生成证明。
get_certificate_pdf	生成新的签名 PDF，或从磁盘恢复已归档的 PDF。
verify_file	对本地文件进行哈希计算，并将其与声明的哈希值和签名进行核对。
verify_certificate	无需本地文件即可验证证书签名。
check_anchor	检查/下载 OpenTimestamps（Bitcoin）证明。
service_status	显示证明服务的红绿灯状态。

CLI（sg-attest）

同一软件包，无需单独安装。CLI 是与 MCP 服务并列的一个 bin，共享相同的哈希计算/API/配置代码——同样充分保护隐私（本地流式计算哈希，文件字节绝不会发送），并使用相同的凭据。

npx -y -p @spazio-genesi/attest-mcp sg-attest attest ./work.png
npx -y -p @spazio-genesi/attest-mcp sg-attest verify ./work.png --hash <sha256>

（必须使用 -p：sg-attest 是该软件包的辅助 bin，而直接运行 npx -y @spazio-genesi/attest-mcp 会启动 MCP 服务。）

相比网站，它有一项优势：没有 1 GB 上限。浏览器受 WebCrypto 限制（会将整个文件加载到内存）；而此 CLI 在 Node 上从磁盘流式读取，因此可以为任意大小的文件生成证明。

命令	功能	凭据
attest <file> [--title --author --year --note] [--pdf <out>]	在本地计算哈希（流式处理）→ 生成证明 → 打印指纹、证明和 HMAC。不归档任何内容；若未指定 --pdf，则不会创建 /c/<hash> 页面。只有使用 --pdf <out> 才会生成签名证书并打印验证链接	是
verify <file> [--hash <sha256>]	在本地计算哈希；指定 --hash 时会进行比较（不同时退出码为 2）；还会报告归档/锚定状态	否
verify-cert --hash --attestazione --hmac [--titolo --autore --anno --note]	验证证书的 HMAC 签名，无需本地文件	否
cert <hash> [-o <file.pdf>]	恢复已归档的证书	否
anchor <hash> [-o <file.ots>]	检查/下载 OpenTimestamps（Bitcoin）证明	否
status	显示服务的红绿灯状态	否
authorize	设备流程：打印待批准的 URL、轮询并保存令牌	—
--version / --help	版本（来自 package.json）和用法说明	—

每条命令都接受 --json（在 stdout 输出一个 JSON 对象，供脚本使用）和 --quiet（减少非必要的面向用户的输出）。错误会输出到 stderr；CLI 绝不会将凭据（API 密钥或会话令牌）打印到 stdout、stderr 或 --json 输出中——与 MCP 服务遵循相同的安全原则。

退出码（稳定契约，适用于 CI/脚本）：

代码	含义
0	成功/肯定结果
1	操作错误（网络、身份验证、输入错误）
2	否定的验证结果（哈希不匹配、签名无效）

身份验证方式与 MCP 服务相同：使用 IMGAUTH_API_KEY 环境变量，或使用通过 sg-attest authorize（设备流程）保存的会话令牌。没有 --key 标志——命令行中的凭据会留在 shell 历史记录中；请改用环境变量（或 CI 密钥）。

一个使用此 CLI 在 CI 中为构建产物生成证明的 GitHub Action，位于配套代码库 attest-action 中。

独立二进制文件（无需 Node）

对于没有 Node.js 的机器或 CI 运行器，可从 Releases 页面下载预编译的 sg-attest 可执行文件——命令相同、行为相同，无需安装。

OS	架构	文件
Linux	x64	sg-attest-linux-x64
Linux	arm64	sg-attest-linux-arm64
macOS	Intel	sg-attest-macos-x64
macOS	Apple Silicon	sg-attest-macos-arm64
Windows	x64	sg-attest-windows-x64.exe
Windows	ARM64	sg-attest-windows-arm64.exe

每个版本还包含 SHA256SUMS.txt。运行前请验证下载文件：

sha256sum -c SHA256SUMS.txt --ignore-missing   # Linux/macOS

(Get-FileHash .\sg-attest-windows-x64.exe -Algorithm SHA256).Hash   # compare by eye to SHA256SUMS.txt

⚠️ 这些二进制文件未经代码签名：首次运行时，Windows SmartScreen 或 macOS Gatekeeper 可能会显示“未知发布者”警告。 在此期间，上方校验和可保证文件完整性——该二进制文件由 GitHub Actions 直接从此仓库的源代码构建并发布，未经过人工上传。

用法与通过 npm 安装的 CLI 相同，只需直接调用该文件：

chmod +x ./sg-attest-linux-x64          # Linux/macOS only
./sg-attest-linux-x64 attest ./work.png --pdf cert.pdf
./sg-attest-linux-x64 status

npx/npm 仍是主要分发渠道（也是 attest-action 在 CI 中使用的方式）——这些二进制文件是额外的渠道，而非替代方案。

构建来源证明（SLSA/in-toto）

上方校验和能回答“此文件是否完整？”——但无法说明 这些字节从何而来。自 v0.4.2 起，每个版本还附带一份经过签名的构建来源证明 （actions/attest-build-provenance，release-binaries.yml 中的 release 作业）：这是一个加密证明，表明该文件由此仓库自己的工作流，从特定 提交和标签构建而成，并非人工上传或事后替换。

GitHub CLI 可以验证此证明，但 gh attestation verify 即使面对公开仓库也需要经过 身份验证的 gh 会话（已确认：未登录时会报错“please run gh auth login”）——如果验证的目的在于让任何人无需任何设置即可执行，这确实是个缺口：

gh attestation verify sg-attest-linux-x64 --repo SPAZIO-GENESI/attest-mcp

scripts/verify-provenance.mjs 可以执行相同的验证，完全不需要 GitHub 凭据——它只使用公开的 attestations REST 端点（已确认无需身份验证即可访问，即使面对公开仓库也是如此）和 sigstore 库。该库会根据 Sigstore 自己的公共基础设施（Rekor、Fulcio、TUF）检查签名（这些服务同样无需账户）：

git clone https://github.com/SPAZIO-GENESI/attest-mcp
cd attest-mcp && npm install
node scripts/verify-provenance.mjs ./sg-attest-linux-x64 \
  --repo SPAZIO-GENESI/attest-mcp --tag v0.4.2

成功时退出码为 0；如果文件与工作流实际构建的任何文件都不匹配，则退出码为 1（例如，哪怕只更改一个字节，摘要也会改变，因此用于查找证明的键本身也不再匹配任何证明）。

配置

环境变量	默认值	用途
IMGAUTH_API_KEY	—	API 密钥凭据，可绕过设备授权流程。
IMGAUTH_BASE_URL	https://imgauth.spaziogenesi.org	用于本地开发的覆盖值（http://localhost:8787）。
IMGAUTH_CERT_PAGE_BASE	https://attestazione.spaziogenesi.org	永久证书页面基础 URL 的覆盖值。

故障排除

如果客户端报告 “Server disconnected”，请先检查日志：此服务会将诊断信息写入 stderr，MCP 客户端会捕获这些信息。在 Claude Desktop 中，日志位于 %APPDATA%\Claude\logs\mcp-server-attest-mcp.log（Windows）或 ~/Library/Logs/Claude/mcp-server-attest-mcp.log（macOS）。

每个生命周期事件都应对应一行日志：

[attest-mcp 2026-07-21T11:14:12.948Z] v0.2.2 ready on stdio (node v22.22.2, pid 32316)
[attest-mcp 2026-07-21T11:14:12.965Z] exiting (code 0)

• exiting (code 0) — 正常关闭：客户端关闭了 stdin。笔记本电脑从睡眠中唤醒或客户端重启后出现此情况是正常的；只需重启客户端即可重新连接。
• fatal: … 后跟 exiting (code 1) — 发生了实际崩溃，堆栈跟踪位于前一行。请附上相关信息提交问题。
• 完全没有 ready 行 — 进程未能启动：请检查 node 是否在 PATH 中，以及版本是否至少为 v18（node --version）。

stdout 承载 JSON-RPC 协议，绝不用于记录日志。

已知限制

证书 PDF 及其文本为意大利语（Spazio Genesi 是一家意大利非营利组织，且证书是一份面向法律用途的文件）。MCP 工具描述和本 README 使用英语，面向国际受众。

开发

npm install
npm test          # unit tests (hash vectors, CLI argument parsing)
IMGAUTH_BASE_URL=http://localhost:8787 npm start   # MCP server against a local `wrangler dev`
IMGAUTH_BASE_URL=http://localhost:8787 node src/cli.js status   # CLI against the same

test/cli-smoke.local.mjs 是一个仅供本地使用的测试脚本（npm test 不会运行它），用于针对隔离的 wrangler dev imgauth 实例，端到端测试每条 sg-attest 命令 — 所需环境变量请参阅该文件顶部的注释。

安全

报告漏洞 → /sicurezza/（负责任披露政策，为善意研究提供安全港）— 此仓库没有自己的 security.txt（这是 npm 软件包，没有静态资源），但该政策适用于整个项目。

贡献

Bug 报告和功能请求：提交问题。 欢迎提交拉取请求 — 请保持改动聚焦（每个 PR 只包含一项改动），确保 npm test 通过，并在描述中说明“为什么”，而不只是“做了什么”。测试政策：任何新增功能的 PR 都应在 test/ 下添加相应测试；每次推送和拉取请求都会在 CI 中运行 npm run lint 和 npm test。如果改动涉及证明合约本身（哈希计算、HMAC 验证、API 接口），请先提交问题：此客户端映射的是由 imgauth 所维护的合约，因此改动必须保持兼容。

许可证

MIT — 参见 LICENSE。这是证明服务的客户端；服务本身（imgauth）采用 AGPL-3.0 许可证。