Task402 Agent Evidence Tools

Task402 エージェント向けエビデンスツール

PDF、公開ウェブページ、OpenAPI コントラクト、Base チェーンデータから、エージェントに範囲を限定したエビデンスを提供します。ホスト型の 20 個のツールを備えた MCP サービス（https://task402.xyz/mcp）に接続できます。検出にローカルサーバー、API キー、ウォレットは必要ありません。有料の呼び出しでは、Base 上の x402 v2 USDC を使用します。MCP ホストに接続しただけでは、支払い署名者が自動的に付与されることはありません。

エージェントを接続する

Cursor の場合は、examples/cursor.mcp.json を .cursor/mcp.json にマージします。VS Code の場合は、examples/vscode.mcp.json を .vscode/mcp.json にマージします。その他の Streamable HTTP クライアントでは、次を使用できます。

{
  "mcpServers": {
    "task402": { "url": "https://task402.xyz/mcp" }
  }
}

接続を初期化し、tools/list を実行して実行可能なスキーマを確認します。Node.js 24 とこのリポジトリの依存関係がインストールされている場合、npm run discover を実行すると、公式 MCP SDK を通じて検出を行い、ツール名のみを出力します。有料ツールの呼び出しや支払いへの署名は行いません。

ホスト型の各ツールは、ツール固有の出力スキーマ、パラメーターの説明、MCP の安全性に関する注釈を提示します。そのためエージェントは、x402 の支払いを承認する前に、tools/list から結果の形式や再試行の動作を計画できます。

ツール	2026 年 10 月 12 日のライブ確認時の料金
generate_pdf	PDF 1 件あたり $0.01
web_evidence	HTTPS の公開ページ 1 件あたり $0.005
inspect_openapi	仕様 1 件あたり $0.001
plan_api_request、diff_openapi	呼び出し 1 回あたり $0.002
get_chain_balance、get_chain_transaction、get_erc20_balance	読み取り 1 回あたり $0.001
get_pdf_job	生成料金に含まれます。ジョブ機能が必要です
inspect_pdf、get_document_map、search_document、batch_search_document、prepare_document_context、extract_document_fields、read_document、verify_document_citation、compare_pdfs、validate_pdf_text、render_pdf_page_region	有料の PDF インデックス作成後に利用できます。ドキュメント機能が必要です

PDF のインデックス作成は、独立した REST 操作 POST /v1/documents（PDF 1 件あたり $0.01）です。バイナリのアップロードは MCP ツールではありません。生成した PDF のダウンロードも REST 専用です。支払いを承認する前に、現在の条件を/v1/pricingと支払いチャレンジで確認してください。ネイティブテキストを扱う PDF ツールは、OCR を提供せず、事実の真偽も検証しません。

チャレンジ、署名付きの再試行、結果を扱うワークフローについては、まずdocs/FIRST-PAID-CALL.mdを確認してください。リポジトリとリモート MCP メタデータの公開には、docs/PUBLISHING.mdを使用してください。

サービスアーキテクチャ

このプロジェクトでは、REST と MCP で共有される単一のサービスを通じて、Markdown をページ分割された PDF ファイルに変換します。ローカルランナーでは Playwright Chromium と SQLite を使用し、Cloudflare Worker アダプターでは Browser Run Quick Actions、D1、R2 を使用します。実際の決済フローでは、公式の x402 SDK ファシリテータークライアントを使用し、レンダリング前に検証を行い、PDF アーティファクトの保存後にのみ決済を確定します。

有料操作は、generate_pdf、ingest_document、web_evidence、OpenAPI の検査／計画／差分取得、および固定メソッドによる Base チェーンの読み取りです。インデックス作成後は、検索、引用、バッチ検索、制限付きコンテキストの準備、明示的なラベルによるフィールド照合も利用できます。ウェブエビデンスで取得できるのは、公開された HTTPS の HTML／テキストのみです。OpenAPI ツールが受け付けるのは、呼び出し元が指定した JSON とローカル参照のみです。チェーンツールがトランザクションに署名したり送信したりすることはありません。入力 HTML は実行されず、リモート画像などの外部リソースは省略またはブロックされます。また、生成された PDF にはハイパーリンクが保持されますが、レンダリング時にリンク先を取得することはありません。

配布メタデータ、変換の手引き、各チャネル向けの文案は docs/MARKETING.md と docs/LAUNCH-KIT.md にあります。LobeHub 向けの公開 MCP ディレクトリメタデータは、server.json、glama.json、lhm.plugin.json にあります。

エージェント、ディスカバリー、操作、デプロイ、オペレーター統計、セキュリティに関する詳細ガイドは、docs/AGENT-GUIDE.md です。

ホスト型 MCP サーバーを使用する

ローカルプロセスは不要です。Streamable HTTP エンドポイントを MCP 対応クライアントに追加します。

{
  "mcpServers": {
    "task402": {
      "type": "http",
      "url": "https://task402.xyz/mcp"
    }
  }
}

サーバーの検出に支払いは必要ありません。有料操作は x402 v2 チャレンジを返します。クライアントはネットワーク、USDC アセット、受取人、金額、リソース、タイムアウトを確認し、ウォレットで明示的な承認を得てから、署名済みの支払いを添えて同じリクエストを再試行する必要があります。Task402 が秘密鍵を受け取ったり、呼び出し元に代わってトランザクションに署名したり送信したりすることはありません。まず最初の有料呼び出しを試し、その後、署名者を注入する一連のフローについては examples/agent-flow.ts を参照してください。

含まれる機能

機能	料金	インターフェース
Markdown からページ番号付き PDF を生成	$0.01	REST, MCP
テキストをネイティブに含む PDF を 1 件インデックス化	$0.01	REST
検索、引用、比較、検証、マッピング、読み取り、フィールド抽出、コンテキスト準備、レンダリング	インデックス化後は料金に含まれます	REST, MCP
範囲を限定した公開ページのエビデンス	$0.005	REST, MCP
OpenAPI の検査、リクエストプラン、差分	$0.001–$0.002	REST, MCP
読み取り専用の Base 残高、トランザクション、ERC-20 データ	$0.001	REST, MCP

料金、制限、スキーマ、支払い条件は /v1/pricing で機械可読形式で提供されています。このサービスは、OCR、JavaScript によるページのレンダリング、任意の API の実行、トランザクションへの署名、PDF の視覚的・法的な変更箇所の比較には対応していません。

リモート MCP サーバーのメタデータのバージョンは、server.json に記載されている 0.3.2 です。2026-10-12 の監査時点では、公式 Registry で 0.2.0 が提供されていました。新しいメタデータの公開にはドメイン所有者の証明鍵が必要ですが、このワークスペースには意図的に保存していません。リリースが公開済みであると明言する前に、Registry の最新レコードを再確認してください。有料の REST および MCP チャレンジには x402 Bazaar の検出メタデータが含まれ、本番用ファシリテーターは https://facilitator.openx402.ai です。

公開されている検出ページは、https://task402.xyz/、/docs#first-paid-call、/llms.txt、/demo、/v1/tools、/openapi.json、/v1/pricing、/.well-known/x402.json、/.well-known/mcp/server-card.json、/.well-known/ai-plugin.json、/sitemap.xml から利用できます。これらにより、支払いや運営者の認証情報なしで、エージェントやディレクトリのクローラーが明確な入口を利用できます。Registry に公開すると、MCP Registry と同期するクライアントから見つけやすくなりますが、人為的なトラフィックが発生したり、呼び出しが保証されたりするわけではありません。

公開クイックスタートでは、引用の検証、PDF の改訂版の比較、モデル呼び出し前の PDF コンテキストの削減 に特化したワークフローを紹介しています。そのままコピーして使えるクライアントファイルは、examples/agent-flow.ts、examples/cursor.mcp.json、examples/vscode.mcp.json にあります。TypeScript のサンプルは、署名なしの生成およびインデックス化チャレンジを取得し、別途承認されたウォレットのペイロードに対する明示的な再試行メソッドを提供します。支払いへの署名や送信を自動で行うことはありません。

制御されたライブ決済を 1 回実行する準備ができたら、docs/TEST-TRANSACTION.md に従ってください。外部のウォレット署名者が必要で、秘密鍵を求めることはありません。

使い捨てのローカルテストウォレットを使う場合は、リポジトリに安全対策付きのターミナルヘルパーも含まれています：npm run test:live。署名前に Base/USDC のライブチャレンジを検証し、TASK402_CONFIRM=YES を必須とし、PDF をダウンロードします。また、支払いペイロードや権限情報を出力することはありません。セットアップとクリーンアップについては、テストガイドのターミナルのセクションを参照してください。

MCP エージェントを正確に再現するには、npm run test:agent を使用してください。検出を実行し、構造化された x402 チャレンジを受け取り、公式 EVM クライアントを通じて署名し、_meta["x402/payment"] を使って再試行し、get_pdf_job でジョブを確認して、結果をダウンロードします。

ローカル開発

Node.js 24 以降を使用してください（Node 24.13 で検証済みです。ローカルの永続状態には node:sqlite を使用します）。このディレクトリから実行します。

npm ci
Copy-Item .dev.vars.example .dev.vars
npm run setup:browser
npm run dev

ローカルサーバーは 127.0.0.1:8787 のみでバインドされ、一致するループバック／localhost の Host authority（およびライブモードで設定されたパブリック authority）のみを受け付けます。ローカルのウェブエビデンスアダプターは、フェッチの前にすべてのホスト名を解決し、プライベート、ループバック、リンクローカル、および予約済みの DNS 宛先を拒否します。ホストされた Worker は、プラットフォームのエグレス境界と同じ URL チェックに依存します。サンプルの .dev.vars では、支払いを明示的に無効化する開発用バイパスが有効になっており、このバイパスは src/local.ts にのみ存在します。src/worker.ts は常にこのバイパスを拒否します。.dev.vars がない場合、サーバーは支払い未設定の状態で起動し、有料の生成はフェイルクローズします。ローカルのジョブとアーティファクトは .data/ に永続化され、Git では無視されます。

お使いのマシンで Playwright が指定バージョンの Chromium を見つけられない場合は、ローカルプロセスの起動前に、インストール済みの Chromium 実行ファイルを指定してください。

$env:BROWSER_EXECUTABLE_PATH = "C:\path\to\chrome.exe"
npm run dev

サンプル PDF を生成してダウンロードします。

$body = @{ title = "Quarterly Report"; markdown = "# Summary`n`n| Metric | Value |`n| --- | ---: |`n| Revenue | 42 |" } | ConvertTo-Json
$job = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8787/v1/pdf `
  -Headers @{ "Idempotency-Key" = "report-2026-q3-0001" } `
  -ContentType "application/json" -Body $body
$job | Format-List
Invoke-WebRequest -Uri $job.downloadUrl `
  -Headers @{ Authorization = "Bearer $($job.capability)" } `
  -OutFile .\report.pdf

この機能はベアラーシークレットを使用します。メモリ上に保持し、ログに記録せず、返されたステータス／ダウンロード URL にのみ送信してください。ステータスとダウンロードへのアクセスには、Authorization: Bearer <capability>（または X-Job-Capability）が必要です。ジョブ ID または冪等性キーだけではアクセスは許可されません。

API と制限

ルート	用途
GET /v1/pricing	操作、価格、支払いモード、サイズ／TTL 制限を機械可読形式で提供します
GET /.well-known/x402	周知のパスで同じディスカバリードキュメントを提供します
GET / and GET /docs	公開サービスの概要とエージェント向けクイックスタートを提供します
GET /llms.txt and GET /sitemap.xml	エージェントが読み取れる簡潔なメタデータと、クローラー向けの情報を提供します
POST /v1/pdf	PDF を生成します。Idempotency-Key が必要です。ライブモードでは x402 v2 PAYMENT-SIGNATURE を使用します
GET /v1/jobs/{jobId}	認可済みのジョブ状態を読み取ります
GET /v1/jobs/{jobId}/download	認可済みの完了済み PDF をダウンロードします
GET /v1/admin/stats	パスワードで保護されたツール統計の集計です。オプションで ?hours=24 を指定できます
GET /admin	保護された統計エンドポイントを表示するための、モバイル対応パスワードフォームです
POST /mcp	PDF、Web、OpenAPI、Base の読み取り専用ツールを備えた MCP Streamable HTTP エンドポイントです
POST /v1/documents	決定論的なネイティブテキスト操作向けの、有料の生 PDF インデックス作成です
GET /v1/documents/{documentId} and /map	ドキュメントのメタデータを確認するか、ページマップを読み取ります
POST /v1/documents/{documentId}/search, /batch-search, /context, /fields, /read, /citation, /validate	検索、引用付きコンテキストの作成、選択したページの読み取り、テキスト引用の検証、または明示された期待値の検証を行います
POST /v1/documents/compare	個別に認可された 2 つの PDF を、ページおよび正規化されたネイティブテキストで比較します
GET /v1/documents/{documentId}/pages/{page}/render	範囲を制限したページの切り抜きを PNG にレンダリングします
POST /v1/web/evidence	範囲を制限したテキスト、リンク、ソースハッシュ、プロンプトインジェクション警告を含む、有料の公開 HTTPS ページ抽出です
POST /v1/openapi/inspect	有料の OpenAPI 操作、パラメーター、リクエストボディ、セキュリティ、ローカル参照の検査です
POST /v1/openapi/request-plan and /v1/openapi/diff	有料の安全なリクエスト計画と決定論的な API コントラクト比較です。リクエストは実行されません
POST /v1/chain/balance, /v1/chain/transaction, /v1/chain/erc20-balance	有料の読み取り専用 Base RPC ユーティリティです。署名や資金移動は行いません

既定の制限は、リクエストボディが 256 KiB、正規化された Markdown が 240 KiB、タイトルが 160 文字、Markdown が 20,000 行、PDF 出力が 20 MiB、アーティファクトの有効期間が 24 時間、レンダリングの期限が 90 秒です。PDF は A4 レイアウトを使用し、表のヘッダーを繰り返し、可能な場合は行を分割せず、ページ番号を含めます。Cloudflare では 1 時間に 1 回、ローカルプロセスでは起動時と 1 時間ごとにクリーンアップが実行されます。クリーンアップのバッチには上限があります。有効期限が切れたケイパビリティは直ちに使用できなくなりますが、物理的な削除には追加のバッチが必要になる場合があります。決済の確定状況が不明な場合、運営者による照合に備えてアーティファクトは保持されます。

ローカルでの PDF 検査と取得

デプロイされた Worker は、隔離された Cloudflare Container パーサーを通じて、決定論的な PDF ドキュメント操作を公開します。Worker はケイパビリティ、D1 メタデータ、R2 のソース／インデックスオブジェクト、検証、クリーンアップを管理します。Container は、外部インターネットへのアクセスを無効にした状態で、ネイティブの PDF.js 抽出と範囲を制限したページレンダリングを行います。ローカル開発では、引き続き Node.js パーサーを通じて同じ操作を直接実行します。

呼び出し元が生成した冪等性キーと、別途用意した高エントロピーの復旧シークレットを使用して、生の PDF をアップロードします（復旧シークレットによって、そのキーの使用範囲が呼び出し元に限定されます）。返されたケイパビリティと復旧シークレットは呼び出し元のシークレットストアに保存してください。サーバーが復旧シークレットを返すことはありません。応答を受信できなかった場合に同じアップロードを復旧する目的に限り、両方のキーを再利用してください。冪等性キーだけでは、既存のドキュメントケイパビリティを取得できません。

$recovery = [Convert]::ToHexString([Security.Cryptography.RandomNumberGenerator]::GetBytes(32)).ToLowerInvariant()
$doc = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8787/v1/documents `
  -Headers @{ "Idempotency-Key" = "research-pdf-2026-0001"; "X-Document-Recovery-Key" = $recovery; "X-File-Name" = "research.pdf" } `
  -ContentType "application/pdf" -InFile .\research.pdf
$headers = @{ Authorization = "Bearer $($doc.capability)" }
Invoke-RestMethod -Uri $doc.inspectUrl -Headers $headers
Invoke-RestMethod -Method Post -Uri "$($doc.inspectUrl)/search" -Headers $headers `
  -ContentType "application/json" -Body '{"query":"revenue","limit":5}'
Invoke-RestMethod -Method Post -Uri "$($doc.inspectUrl)/read" -Headers $headers `
  -ContentType "application/json" -Body '{"pages":[1,2]}'

返される capability はベアラーシークレットです。非公開に保ち、返された URL に対して Authorization ヘッダーでのみ送信してください。バイナリのアップロードは最大 20 MiB、100 ページまでです。解析では、メタデータ、ページラベルとサイズ、ブックマーク、正規化されたバウンディングボックスを含むネイティブテキストブロック、フォームフィールドの名前・種類・値、注釈数、埋め込み添付ファイルのファイル名・サイズを含む、上限のあるローカルインデックスを構築します。インデックスの上限は 8 MiB、テキストブロック 50,000 件です。GET .../map?page=1 は、そのページに配置されたブロックを最大 500 件返します。デフォルトのマップでは、簡潔なページ概要が返されます。ソース PDF のバイトデータと抽出したインデックスは .data/document-objects/ および .data/documents.sqlite に永続的に保存され、有効期限が切れると削除されます。デフォルトの保持期間は 24 時間です（DOCUMENT_TTL_SECONDS で最大 7 日間まで延長できます）。

デプロイ済みのパーサー Container が設定されている場合、MCP エンドポイントに inspect_pdf、get_document_map、search_document、batch_search_document、prepare_document_context、extract_document_fields、read_document、verify_document_citation、compare_pdfs、validate_pdf_text、render_pdf_page_region が追加されます。MCP ではバイナリコンテンツをアップロードしません。最初に REST でアップロードし、その後、ドキュメント ID と capability をツールに渡してください。

検索では、空白を正規化した後、大文字と小文字を区別せずに完全一致で照合します。読み取りは最大 10 ページ、出力文字数 32,000 文字までです。引用チェックで確認できるのは、正規化されたテキストが指定ページに存在することのみです。近傍のテキストブロックとそのバウンディングボックスが返されますが、内容の真偽や視覚的な読み取り順序は確認されません。比較では、ページ単位の正規化テキストの変更が報告されます。画像、視覚的な差異、メタデータ、署名の違いは調査されません。検証で確認されるのは、パーサーで読み取り可能かどうか、オプションのページ数、必須テキストのみです。ページの切り抜きには正規化されたページ比率が使われ、ラスターピクセル数 400 万、PNG 出力 4 MiB に制限されます。

OCR、表構造の抽出・クエリ、フォームへの入力、添付ファイルのダウンロード、PDF/A 適合性テスト、暗号学的署名の検証には対応していません。ネイティブテキストが少ない場合は警告として報告され、スキャンされたページに推測したテキストが追加されることはありません。PDF リンクはテキストとして保持され、取得されることはありません。PDF の署名マーカーはメタデータとしてのみ提示され、信頼性や有効性は検証されません。

ネイティブ PDF の解析とレンダリングは、分離されたパーサー Container 内で実行されます。Worker は一度に 1 つのパーサータスクのみを受け付け、起動・処理の期限を 60 秒に設定し、タスクごとに Container を破棄してプロセスとファイルシステムの状態をリセットします。同時にアップロードまたはレンダリングを行うと 503 が返されるため、同じ復旧キー／冪等性キーを使って少し待ってから再試行してください。アップロード、ページ、テキスト、インデックス、出力、インスタンスメモリにも上限が適用されます。Container には外部インターネットへのアクセス権がなく、決済シークレットや capability シークレットも渡されません。OCR、視覚的な意味の比較、PDF/A 適合性、暗号学的署名の検証には引き続き対応しておらず、検証ツールで明示的に報告されます。

冪等性キーはライブモードでは検証済みの支払者ごとに適用され、正規化された入力および決済ペイロードにひも付けられます。異なるコンテンツまたは決済で再利用すると 409 が返されます。また、EVM ネットワーク／アセット／支払者／認可 nonce を使って、同一の決済認可の重複が拒否されます。決済リプレイ防止用のトゥームストーンは、成果物と認可の両方の有効期限が切れた後、少なくとも 30 日間保持されます。同じ完了済みリクエストであれば、ジョブの有効期間中、レンダリングや決済処理を再度行わずに元の capability を取得できます。

REST クライアントは、402 応答と標準の PAYMENT-REQUIRED ヘッダーで x402 v2 の条件を受け取ります。MCP クライアントは、isError: true のツール結果として同じ PaymentRequired オブジェクトを受け取り、決済情報を params._meta["x402/payment"] で送信します。決済済みのツール結果には _meta["x402/payment-response"] が含まれます。

保護されたウォレットを使用する MCP クライアント

examples/mcp-client.ts では、公式の MCP SDK Streamable HTTP クライアントと x402 MCP トランスポートフィールドを紹介しています。呼び出し元から ApprovedWallet アダプターを受け取り、秘密鍵フィールド、環境変数のキー、署名の実装は含まれていません。このアダプターは、ハードウェアウォレット、HSM、KMS、または個別にサンドボックス化されたウォレットサービスで実装してください。署名を行う前に、署名者が想定されるネットワーク、USDC アセット、送信先、金額の上限、ノンスのポリシーを適用するようにしてください。MCP クライアントやリポジトリに長期間有効な秘密鍵を追加しないでください。

この例では、未払いの呼び出しでチャレンジを取得し、注入された署名者にペイロードを要求して、_meta["x402/payment"] を付けて再試行した後、認証済みのダウンロード用ジョブ機能を返します。これは最小限の正常系の例です。本番環境のクライアントでは、冪等性キーと正確な署名済み決済ペイロードを安全に保存して同じリクエストを再試行できるようにし、決済が不確定な場合に返される復旧情報も保持してください。ローカル開発用のバイパスでは、チェーン上の決済は作成も決済もされません。x402 のエンドツーエンドの送金には、適切に設定されたテストウォレットとテストネットのファシリテーターを使用してください。

Cloudflare へのデプロイ

Worker のエントリーポイントは src/worker.ts です。チェックイン済みの wrangler.toml には、本番環境用の D1、R2、Browser Run、パーサー Durable Object／Container のバインディングが含まれています。別のアカウントにデプロイする場合は、それらのリソース識別子を置き換え、対応するリソースをプロビジョニングしてください。パーサーイメージのビルドには、Docker エンジンが実行中であり、Docker CLI が PATH 上にある必要があります。Cloudflare アカウントを使用してリソースをプロビジョニングします。

npx wrangler login
npx wrangler d1 create x402-docs-mvp
npx wrangler r2 bucket create x402-docs-mvp

Wrangler が出力した D1 の database_id を wrangler.toml にコピーし、チェックイン済みのスキーマを適用します。

npx wrangler d1 migrations apply x402-docs-mvp --remote

統計エンドポイントは、マイグレーション 0002_tool_stats.sql の tool_stats_daily テーブルを使用します。トラフィックを受け付ける前に、そのパスワードを Worker シークレットとして設定してください。

npx wrangler secret put STATS_PASSWORD
npx wrangler secret put DOCUMENT_CONTAINER_TOKEN

アカウントで Browser Run を有効にし、wrangler.toml の [browser] バインディングを維持してください。このプロジェクトは、ドキュメントに記載されている BROWSER.quickAction("pdf", ...) API を呼び出します。Browser Run は Workers Paid アカウントで利用できますが、Paid プランで費用が必ず5ドル以下に抑えられるわけではありません。Browser Run、D1、R2、Worker の使用により従量課金が発生する場合があります。デプロイ前に Cloudflare の最新の課金／価格情報を確認し、アカウントの予算／アラートを設定してください。

Worker 側のプレビューでは、Browser Run Quick Actions を使用するために npx wrangler dev --remote が必要です（ローカルの wrangler dev は quickAction を実装していません）。通常の npm run dev コマンドは引き続き完全にローカルで実行され、代わりに Playwright Chromium を使用します。

ダッシュボードまたは Wrangler の変数を使って、シークレットではない Worker 変数を設定します。

PAYMENTS_MODE=live
PUBLIC_BASE_URL=https://task402.xyz
PRICE_USD=0.01
PRICE_DOCUMENT_USD=0.01
PRICE_WEB_EVIDENCE_USD=0.005
PRICE_OPENAPI_USD=0.001
PRICE_CHAIN_USD=0.001
X402_NETWORK=eip155:8453
X402_ASSET=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
X402_PAY_TO=0xAEA6fDF13ca10aD6B906884ffAcBb58a0e9E144A
X402_FACILITATOR_URL=https://facilitator.openx402.ai
MCP_ALLOWED_ORIGINS=https://<your-approved-mcp-client-origin>

Worker のデプロイでは STATS_PASSWORD が必須で、20～256文字でなければなりません。エントロピーの高い一意のランダムシークレットを使用してください。これは支払い認証情報ではないため、ウォレットやファシリテーターのシークレットとは別に保管してください。DOCUMENT_CONTAINER_TOKEN は、Worker とパーサー Container の間でのみ使用する別の内部シークレットです。保護された運用者向けルートは GET /v1/admin/stats です。スマートフォンからアクセスする場合は、モバイルページ /admin を開いてください。docs/AGENT-GUIDE.md を参照してください。

デプロイ済みの設定では、Base メインネットの USDC（eip155:8453）と https://facilitator.openx402.ai を使用します。公開される対応機能のレスポンスでは、Base メインネットの exact EVM 支払いと discovery 拡張が通知されます。これにより、クライアントが支払い拡張をエコーすると Bazaar でカタログ化できるようになります。ファシリテーターは支払いに関わる依存先として扱ってください。本番トラフィックを変更する前に、その可用性、利用規約、対応ネットワーク、discovery の動作、決済の動作を確認してください。このサービスは PRICE_USD を小数点以下6桁の USDC 単位に変換します。

機能用の HMAC シークレットを設定し、ファシリテーターで必要な場合は、そのベアラートークンも Worker シークレットとして設定します。32文字以上のランダムシークレットを生成し、TOML ファイルにコミットしたり貼り付けたりしないでください。

npx wrangler secret put CAPABILITY_SECRET
npx wrangler secret put X402_FACILITATOR_BEARER_TOKEN

認証を必要としないファシリテーターでは、ファシリテータートークンは任意です。ローカルチェックを実行した後、デプロイするか決める前にデプロイバンドルを確認してください。

npm ci
npm run typecheck
npm test
npm run deploy:dry-run
# npx wrangler deploy   # explicit operator action after reviewing account config and costs

このリポジトリには、ウォレット認証情報やファシリテーターのシークレットは含まれていません。チェックイン済みの Wrangler 設定には、このプロジェクトに必要なデプロイ用リソース識別子が含まれています。別のアカウントにデプロイする場合は、これらを置き換えてください。Worker には有効な支払い設定が必要で、設定がない場合はフェイルクローズします。開発用のバイパス機能はありません。Worker の PUBLIC_BASE_URL には、パス、認証情報、クエリ、フラグメントを含まない、信頼できる HTTPS オリジンを正確に設定してください。これにより、呼び出し元が制御する Host ヘッダーを信頼せずに、MCP の結果に絶対URLのステータス／ダウンロードリンクが含まれるようになります。ファシリテーターの URL にはパスを含められますが、HTTPS を使用し、URL 認証情報、クエリ、フラグメントを含めてはなりません。

決済の復旧

決済がタイムアウトするか、ファシリテーターから保留中／不明確な結果が返された場合、ジョブは settlement_unknown になります。レスポンスにはジョブ ID とケイパビリティが含まれるため、ステータスを引き続き確認できます。サービスは生成済み PDF を保持し、同じ認可情報を使って決済を自動的に再試行することはありません。運用担当者が対応する前に、ファシリテーターの取引ステータスと対象ネットワークを確認してください。同じ認可情報を再送信しないでください。タイムアウトは、レスポンスが失われていても、チェーントランザクションが受理されたことを意味する場合があります。この MVP には照合／管理者向けエンドポイントが含まれていないため、運用担当者はファシリテーター／ネットワークと照合し、監査可能な運用プロセスを通じて結果を記録する必要があります。

チェック

npm test では、入力制限、HTML／スクリプト／URL のサニタイズ、決済の冪等性とリプレイ処理、不確定および確定的なファシリテーターの結果、実際の PDF 解析、ケイパビリティで制限されたドキュメントの復旧、地図／検索／読み取り／引用／比較／検証、上限付きの切り抜き描画、有効期限切れのクリーンアップ、公式 MCP SDK の初期化／一覧表示／ツール呼び出しを検証します。短い表、および長い表／長いトークンのフィクスチャを使い、ローカルの Chromium で PDF 生成とページ分割の表示もテストしました。これらのテストでは、実際のブロックチェーン決済の送信や、アカウント固有の Cloudflare バインディングの検証は行いません。

配布準備状況

チェックイン済みのディレクトリメタデータは server.json、glama.json、lhm.plugin.json にあり、ディスカバリーの根拠と公開チェックリストは docs/DISTRIBUTION-AUDIT.md にあります。ディレクトリで利用可能だと表明する前に、ライブの MCP Registry レコード、ファシリテーターの Bazaar リソース、サードパーティの掲載 URL が、現在の /v1/pricing コントラクトと一致することを確認してください。これらのファイルは申請の準備を整えるものであり、外部ディレクトリへの掲載には、それぞれの公開者またはリポジトリのワークフローが別途必要です。

エージェントは、最新の料金には /v1/pricing、REST スキーマには /openapi.json、実行可能な入力スキーマには MCP tools/list を優先して使用してください。公開されている /docs、/llms.txt、/sitemap.xml のページには意図的に認証情報が含まれていないため、クローラーは決済前にサービスを把握できます。