attest-mcp

attest-mcp

公式 MCP Registry に io.github.SPAZIO-GENESI/attest-mcp として掲載されています。

Spazio Genesi の証明サービスを提供する MCP サーバー および CLI です。MCP 対応の AI エージェント（Claude Code、Claude Desktop など）から、またはターミナル／CI パイプラインから直接、デジタル作品の証明、検証、存在確認を行えます。

プライバシーを完全に保護：ファイルのバイトデータがデバイスの外に出ることはありません。フィンガープリント（SHA-256）はディスクから読み込んでローカルで計算され、送信されるのはハッシュと任意のメタデータのみです。

📖 英語のドキュメント：attestazione.spaziogenesi.org/en — サイト、開発者向けドキュメント、プランと利用規約はすべて英語で利用できます。

できること

証明サービスは、ファイルの SHA-256 フィンガープリントにタイムスタンプを付与して署名（HMAC）し、署名付き PDF 証明書と、Bitcoin にアンカーされた OpenTimestamps 証明を生成できます。このサーバーはそのサービスを MCP ツールとして公開するため、エージェントはブラウザーを使わずに、ユーザーに代わって作品を証明・検証できます。

OpenTimestamps ラッパーだけではない理由

複数の MCP サーバーが、ハッシュを OpenTimestamps のカレンダーに送信できます。私たちが知る限り、完全な存在証明 — 署名付き PDF 証明書、認定された RFC 3161 タイムスタンプ、Bitcoin アンカー — を、ファイルのバイトデータを呼び出し元のマシンから外に出すことなく、無料で返すのはこれだけです。アカウントも、アップロードも、有料の公証チェーンも必要ありません。同じ組み合わせ（完全な証明書＋無料＋ローカルでのハッシュ計算）を備えた別の MCP サーバーをご存じでしたら、ぜひお知らせください。イシューを作成してください。

欧州の法務・規制環境に対応

Spazio Genesi はイタリアの非営利団体（ETS – Ente del Terzo Settore）です。このパッケージの基盤となる証明サービスは、EU の規制環境に後から適合させたものではなく、それを念頭に設計されています。

• GDPR を第一に、プライバシー・バイ・デザイン：ファイルそのものが当社のサーバーに届くことはありません。送信されるのは SHA-256 フィンガープリントと、宣言することを選択したメタデータのみです。
• EU 内でのデータ保管：証明書と証明は、EU の管轄下にある Cloudflare R2 に保管されます。
• 認定されたタイムスタンプ、単一の信頼点なし：各証明書には、AATL をルートとする機関（Adobe やほとんどの PDF リーダーから信頼されています）が発行する RFC 3161 タイムスタンプと、OpenTimestamps による独立した Bitcoin アンカーの両方が含まれます。
• eIDAS について誠実に説明：これは（現時点では）eIDAS 認定トラストサービスではありません。署名者の身元は現在セルフ署名であり、適格電子シールへのアップグレードは計画されていますが、未実装です。保証されることと保証されないことの詳細は、技術ホワイトペーパーをご覧ください。

プランと利用規約の全文：attestazione.spaziogenesi.org/en/condizioni。

インストール

Claude Desktop — コマンドを 1 つ実行するだけで、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"]
    }
  }
}

認証

基盤となるサービスに対応した、2つの認証方法があります。

1. API キー（パートナー連携用。Spazio Genesi が手動で発行します）： 環境変数 IMGAUTH_API_KEY を設定します。
2. デバイスフロー（個人利用／エージェント利用向け）：引数なしで authorize ツールを呼び出します。URL が返されるので、その URL を開き、本人確認ウィジェットで承認した後、返されたコードを指定して再度 authorize を呼び出します。セッショントークン（24 時間有効、証明 20 件分）は ~/.config/attest-mcp/credentials.json に保存され（対応環境では権限 600）、以降は自動的に使用されます。

どちらの方法でも、認証情報によって解除されるのは証明時のボット対策チェックのみです。サーバー側のタイムスタンプ、暗号署名、レート制限は変更されません。

ツール

ツール	機能
authorize	デバイスフローの認証を開始または続行します。
attest_file	ローカルファイルをハッシュ化（ストリーミング処理）して証明します。
get_certificate_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 はパッケージ内の 2 つ目の bin であり、引数なしの npx -y @spazio-genesi/attest-mcp は代わりに MCP サーバーを実行します。）

サイトにはない利点の 1 つは、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（標準出力に JSON オブジェクトを 1 つ出力。スクリプト向け）と --quiet（人間向けの必須ではない出力を減らす）が使用できます。エラーは標準エラー出力に送られます。CLI は MCP サーバーと同じく、認証情報（API キーまたはセッショントークン）を標準出力、標準エラー出力、--json の出力に決して表示しません。

終了コード（CI／スクリプト向けに安定した仕様です）：

コード	意味
0	成功／肯定的な結果
1	運用エラー（ネットワーク、認証、不正な入力）
2	否定的な検証結果（ハッシュ不一致、無効な署名）

認証方法は MCP サーバーと同じです。環境変数 IMGAUTH_API_KEY を使うか、sg-attest authorize（デバイスフロー）で保存したセッショントークンを使います。--key フラグはありません。コマンドラインに認証情報を指定するとシェルの履歴に残るため、代わりに環境変数（または CI シークレット）を使用してください。

CI でこの CLI を使ってビルド成果物を証明する GitHub Action は、関連リポジトリにあります：attest-action。

スタンドアロンバイナリ（Node 不要）

Node.js のないマシンや CI ランナーでは、リリースページからコンパイル済みの 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 の認証情報がまったくなくても同じ検証を実行できます。必要なのは、公開アテステーションの REST エンドポイント（この公開リポジトリでも、認証なしでアクセスできることを確認済み）と、Sigstore 独自の公開インフラストラクチャ（Rekor、Fulcio、TUF。こちらもアカウント不要）を使って署名を検証する sigstore ライブラリだけです。

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 で終了します（たとえば、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 パッケージであり、静的アセットがないため）が、ポリシーはプロジェクト全体を対象としています。

貢献

バグ報告と機能リクエスト：イシューを作成してください。プルリクエストも歓迎します。変更内容を絞り（PR ごとに変更は 1 つ）、npm test が通ることを確認し、説明では「何を」だけでなく「なぜ」を説明してください。テストポリシー：新しい機能を追加する PR では、test/ にその機能のテストを追加してください。npm run lint と npm test は、すべてのプッシュとプルリクエストで CI 上で実行されます。アテステーション契約そのもの（ハッシュ化、HMAC 検証、API サーフェス）に関わる変更については、まずイシューを作成してください。このクライアントは imgauth が所有する契約を反映しているため、変更は契約との互換性を保つ必要があります。

ライセンス

MIT — LICENSE を参照してください。このサービス自体（imgauth）は AGPL-3.0 です。