proof

@toremlabs/proof-mcp

Proof は、AI が作成したコードの監査証跡です。エージェントが変更した内容、人が実際にレビューした内容、承認者を記録します。このパッケージは、その MCP サーバーです。

MCP 対応のあらゆるクライアント（Claude Desktop、Claude Code、Cursor、Windsurf、カスタムエージェント）に Proof ワークスペースを公開する Model Context Protocol（MCP）サーバーです。サーバーはユーザーの Proof アカウントにログインし、ウェブアプリと同じ Supabase プロジェクトと通信して、同じ RLS に従います。ウェブアプリと MCP は、1 つのクラウドワークスペースを利用する 2 つのフロントエンドです。

現在のバージョン：1.2.0。

誰かに代わって AI エージェントとしてこれをセットアップしていますか？代わりに llms-install.md をお読みください。同じ手順がエージェント向けに書かれており、 人間による対応が必要な手順も示されています。

インストール

npm install -g @toremlabs/proof-mcp
# or on demand without installing:
npx -y @toremlabs/proof-mcp

npm パッケージは @toremlabs/proof-mcp、インストールされるコマンドは proof-mcp なので、サブコマンドを直接実行できます。

npx -y @toremlabs/proof-mcp login

クイックスタート

1. このマシンを Proof アカウントにリンクする

npx -y @toremlabs/proof-mcp login

CLI にデバイスコードと、https://proof.toremlabs.com/device?code=XXXX-XXXX 形式のワンクリック URL が表示されます。ブラウザーで開き、まだサインインしていない場合はサインインして、デバイスを確認します。CLI はバックグラウンドでポーリングし、確認した時点で認証情報を ~/.proof/credentials.json に書き込みます（POSIX では chmod 600）。以降の MCP の実行では、何も表示されません。

ログインフローでは、3 つの Supabase Edge Functions mcp-device-init、mcp-device-grant、mcp-device-poll を使用します。

マシンのリンクを解除するには、npx -y @toremlabs/proof-mcp logout を実行するか、ウェブアプリの「Settings ▸ Connected devices」を開いてリモートで取り消します。

npx -y @toremlabs/proof-mcp whoami を実行すると、マシンが現在リンクされているアカウントを確認できます。

2. MCP クライアントを接続する

Claude Desktop。 macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%/Claude/claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "proof": { "command": "npx", "args": ["-y", "@toremlabs/proof-mcp"] }
  }
}

Claude Code / Cursor / Windsurf。 ワークスペースのルートに .mcp.json を配置します。

{
  "mcpServers": {
    "proof": { "command": "npx", "args": ["-y", "@toremlabs/proof-mcp"] }
  }
}

クライアントを再起動します。ツールメニューに Proof のツールが表示されます。

3. CLI サブコマンド

npx -y @toremlabs/proof-mcp whoami        # show the linked account + device
npx -y @toremlabs/proof-mcp logout        # delete the credentials file
npx -y @toremlabs/proof-mcp --help        # all options
npx -y @toremlabs/proof-mcp --no-realtime # boot the server with live sync off (persisted)
npx -y @toremlabs/proof-mcp --realtime    # re-enable live sync

ヘッドレスモード（CI、クラウドエージェント、一時コンテナ）

デバイスのペアリングでは、リフレッシュトークンがディスクに書き込まれます。個人用マシンでは問題なく機能しますが、一時的な環境（CI ランナー、クラウドエージェントのコンテナ、「Claude Code on the web」）では維持されません。実行のたびにファイルシステムが消去され、Supabase のリフレッシュトークンはローテーションにより 1 回しか使用できないため、設定に埋め込んだトークンは最初のセッション後に無効になります。

こうした環境では、ペアリングを省略し、アカウントのメールアドレスとパスワードを使って、サーバーが起動のたびに新たにサインインするようにします（パスワードは使用しても消費されないため、再ペアリングなしで継続して利用できます）。次の 3 つの環境変数を設定します。

[email protected]          # your Proof account email
PROOF_PASSWORD=your-account-password # secret — store it in a secrets manager
PROOF_ANON_KEY=sb_publishable_...    # project anon/publishable key (public, not a secret)
# optional: PROOF_SUPABASE_URL=...   # defaults to the production Proof project

PROOF_EMAIL と PROOF_PASSWORD が設定されている場合、これらは credentials.json より優先され、MCP サーバーは起動のたびに認証します。デバイスのリンクは必要ありません。要件：

• Supabase プロジェクトでメールアドレスとパスワードによるサインインが有効になっており、アカウントにパスワードが設定されている必要があります（パスワードレスまたはマジックリンクのみのアカウントでは、先にパスワードを追加する必要があります）。
• PROOF_PASSWORD はシークレットとして扱ってください。環境変数を利用者に公開せざるを得ない環境では、専用アカウントの使用をおすすめします。

旧環境変数名。 以前、サーバーは Heuresis として提供されていたため、各変数では旧名称の HEURESIS_*（HEURESIS_EMAIL、HEURESIS_SNAPSHOT、…）も使用できます。両方が設定されている場合は PROOF_* 名が優先されます。古い ~/.heuresis/ ディレクトリでペアリングしたマシンも引き続き動作します。読み取り時には旧ディレクトリも参照し、次回の書き込み時に ~/.proof/ へ移行します。

ライブ同期

MCP がクラウドモードで起動すると、Supabase Realtime を介してワークスペースをサブスクライブし、nodes、edges、projects、または ideas の行が変更されるたびにクライアントに通知します。ウェブアプリで加えた編集は 手動で更新しなくてもエージェントの表示に反映され、MCP に接続されたクライアントからの書き込みも、 同じように他の接続中のクライアントに届きます。サブスクリプションを無効にするには --no-realtime を渡してください（通知が多すぎる場合や、クライアントがすべての 通知をログに記録する場合に便利です）。この設定は ~/.proof/config.json に保存されるため、 フラグを渡す必要があるのは一度だけです。

ツール

ツールは合計 53 個です。クラウドワークスペースに対するデータツールが 49 個、 ウェブアプリと同じアイデア創出オペレーターを実行するオペレーターツールが 4 個です。

読み取り。 get_workspace_summary、list_projects、get_project_graph、 get_subtree、list_concepts、list_edges、get_concept、search_concepts、 find_concepts、find_orphans、list_recent_decisions。エージェントのセッションの多くは、 get_workspace_summary または list_projects から始まります。

コンセプトの書き込み。 add_concept、update_concept、bulk_add_concepts、 set_parent、link_concepts、add_kref、validate_concept、set_standing、 archive_concept、unarchive_concept、star_concept、remove_concept、 remove_concepts。

アイデアとプロジェクトの書き込み。 create_idea、rename_idea、recolor_idea、 set_idea_members、add_to_idea、delete_idea、create_project、 update_project、delete_project。

エージェントの実行と引き継ぎ。 list_agent_runs、get_agent_run、 update_agent_run、list_pending_handoffs、claim_handoff。

エビデンス、証明、レビュー。 add_evidence、add_challenge、record_proof、 get_concept_proof、list_proofs、list_verification_records、 get_verification_record、submit_review_summary。

コンセプトを対象とするすべての書き込みでは、origin='mcp' を設定した行が public.provenance に記録されるため、ウェブアプリのセッションログで、どの画面とどの デバイスから変更されたかを確認できます。アイデア、プロジェクト、またはエージェント実行レベルの書き込みでは記録されません。 provenance の行はノード（node_id NOT NULL）にひも付けられますが、これらの操作には ひも付け先となる単一のコンセプトがないためです。

オペレーター（4 個）。 run_operator（Branch / Matrix / ASIT / TRIZ / Combine / Free / Contradiction による候補の生成）、run_operator_and_commit（同じ処理に加えて、 結果を 1 回のラウンドトリップでコミット）、expand_concept（再帰的な Branch。 展開は幾何級数的に増えるため、上限は深さ × 幅ではなく、実行するモデル呼び出し数で 決まります）、および get_run（以前のオペレーター実行を取得）。

ツールの入力形式は、ウェブアプリの src/agent/tools.ts にある対応ツールと同じです。 そのため、両方の画面を使うエージェントには一貫したインターフェースが提供されます。

スナップショットモード（読み取り専用）

認証情報がなくても、サーバーはディスク上の JSON ワークスペースエクスポートを読み取り、 読み取り専用のツールセット（get_workspace_summary、list_projects、 search_concepts、get_concept、get_subtree、get_project_graph、 list_recent_decisions）を公開できます。PROOF_SNAPSHOT にファイルを指定してください。

export PROOF_SNAPSHOT="/absolute/path/to/your-export.json"
npx @toremlabs/proof-mcp

ウェブアプリの Settings → Workspace → Export からワークスペースをエクスポートできます。このモードは オフラインまたは読み取り専用で使うための便宜的なもので、基本の利用方法はクラウドモードです。

ライセンス

AGPL-3.0-or-later。