agent-services-mcp

agent-services-mcp

既存の3つのサービスを検出可能なツールとして公開する、単一の薄い MCP（Model Context Protocol）サーバーです。AI エージェントや MCP 対応クライアントは、1つの接続を通じてサービスを見つけ、利用できます。

• provenance-receipts — コンテンツの出所を証明し、Ed25519 署名付きのレシートを返します。
• quality-gate — 公開済みのルーブリックに照らしてコンテンツの品質を評価し、Ed25519 署名付きのスコアレシートを返します。
• agent-action-audit — エージェントが実行したアクションの改ざん検知可能な監査レシートに署名します（エージェントの説明責任）。Ed25519 署名付きの監査レシートを返します。

これは薄いラッパーです。 すべてのツールは、基盤となる Worker に HTTP リクエストを転送し、そのレスポンスをそのまま返します。署名、スコアリング、決済のロジックを再実装することはありません。これらの処理は基盤となるサービスが担います。各サービスが何を証明するかについての誠実な説明は、ツールの説明にも反映されています。

クイックスタート — 約2分で最初の（無料の）呼び出し

npm install && npm run build
node examples/free-call.mjs       # connects to the LIVE services and calls a free tool

examples/free-call.mjs は、このサーバーに対して（稼働中のデプロイ先を指定した）MCP クライアントを実行し、get_quality_rubric と verify_audit を呼び出します。どちらも無料で、ウォレットは不要です。サーバーを MCP クライアント（Claude Desktop / Claude Code 形式）に接続する方法については、以下のMCP クライアントの接続を参照してください。

無料と有料の概要： verify_provenance、verify_quality、verify_audit、get_quality_rubric は無料です。certify_provenance、score_quality、audit_action は有料（Base 上での x402 USDC マイクロペイメント）です。2段階の決済フローと動作するサンプルについては、有料ツールの呼び出しを参照してください。

ラップ対象のサービスが証明すること（および証明しないこと）

• 出所： コンテンツが変更されていないこと（SHA-256 ハッシュ）と、レシートがサービスの鍵によって発行されたことを証明します。generator_metadata は呼び出し元の申告に基づくもので、特定のモデルが実行されたことではなく、あなたがそう申告したことを証明します。AI 検出ではなく、真実を保証するものでもありません。
• 品質： 公開済みのルーブリック（明瞭さ、完全性、内部整合性、明白な誤りがないこと）に照らした、再現可能なスコアです。絶対的な真実でも、外部基準でも、ファクトチェックでもありません。get_quality_rubric ツールでルーブリックを確認してください。
• 監査： アクションの記録が真正であること（サービスの鍵によって発行されたこと）と、発行後に改変されていないこと（改ざん検知可能）を証明します。action、actor_metadata、context は呼び出し元の申告に基づくもので、この記録をあなたが申告したことを証明しますが、エージェントの申告が真実であることは証明しません。説明責任と監査のためのツールであり、うそ発見器ではありません。

ツール

ツール	転送先	有料？	入力
certify_provenance	provenance-receipts POST /v1/certify	yes (x402)	content (string), generator_metadata (object, optional)
verify_provenance	provenance-receipts POST /v1/verify	no	content (string), receipt (object)
score_quality	quality-gate POST /v1/score	yes (x402)	content (string), rubric_version (string, optional), target_score (number 0–100, optional)
verify_quality	quality-gate POST /v1/verify	no	content (string), receipt (object)
get_quality_rubric	quality-gate GET /v1/rubric	no	none
audit_action	agent-action-audit POST /v1/audit	yes (x402)	action (string), actor_metadata (object), context (object, optional)
verify_audit	agent-action-audit POST /v1/verify	no	action (string), actor_metadata (object), context (object, optional), receipt (object)

詳細な説明と Zod の入出力スキーマについては、src/tools.ts を参照してください。 各ツールはサービスの生の JSON（ルーブリックの場合は Markdown）をテキストとして返します。また、 verify_* ツールと score_quality ツールは outputSchema も宣言し、 直接参照できる解析済みの structuredContent を返します（例：result.structuredContent.valid）。 2xx 以外のレスポンス（402 Payment Required を含む）は isError: true として通知され、本文も保持されます。402 の場合、ラッパーは支払い方法に関する簡潔で実行可能なメモを先頭に追加します。3 つの 有料 ツールは、ラッパー経由で支払いを完了するためのオプションの x_payment 入力（x402 の X-PAYMENT トークン）も受け付けます。有料ツールの呼び出しを参照してください。

設定

3 つのサービス URL は環境変数で設定できます（シークレットではなく、ベース URL のみです）。

環境変数	本番（デプロイ済み）	ローカル開発時のフォールバック
PROVENANCE_URL	https://provenance-receipts.gpmiddleton71.workers.dev	http://localhost:8787
QUALITY_GATE_URL	https://quality-gate.gpmiddleton71.workers.dev	http://localhost:8788
AUDIT_URL	https://agent-action-audit.gpmiddleton71.workers.dev	http://localhost:8789

.env.example と以下のクライアント設定は、本番デプロイを参照しています。環境変数が設定されていない場合、サーバーはローカルの wrangler dev 用に localhost にフォールバックします（Workers のデフォルトは :8787 なので、競合を避けるため、quality-gate は :8788、agent-action-audit は :8789 で実行してください）。

本番サービスでは、有料ツール（certify_provenance、 score_quality、audit_action）には x402 が必要です。このラッパーはリクエストを転送しますが、ウォレットは保持しないため、 X-PAYMENT がない場合は 402（支払い要件）が返され、isError として通知されます。無料ツールは通常どおり使用できます。

有料ツールの呼び出し（x402）

3 つの有料ツールでは、x402 のマイクロペイメント（Base メインネット上の USDC）が必要です。ラッパーはウォレットを保持していないため、ユーザーに代わって支払いを行うことはありません。そのため、支払いは次の 2 段階で行います。

1. x_payment を指定せずにツールを呼び出します。 x402 の支払い要件（ネットワーク、アセット、金額、payTo）を本文に含む 402 が返されます。ラッパーは、次に何をすればよいかを説明する 1 行のメモを先頭に追加します。
2. それらの要件を使い、x402 クライアントと残高のあるウォレットで x402 の X-PAYMENT トークンを作成してから、そのトークンを x_payment 入力に指定して、もう一度ツールを呼び出します。 ラッパーはこれを X-PAYMENT ヘッダーとして転送します。基盤サービスが検証・決済を行い、署名済みのレシートを返します。

実際に動作する有料呼び出しを行う最も簡単な方法は、基盤サービスに対して x402 クライアントに直接決済させることです。

npm install x402-fetch
BUYER_PRIVATE_KEY=0x...  node examples/paid-call.mjs

examples/paid-call.mjs は、x402-fetch と使い捨ての Base メインネットウォレット（少額の実際の USDC を保有）を使って、audit_action の支払いと呼び出しを行います。約 0.01 USDC が購入者からサービスの payTo に移動します。ガス代は不要です（ファシリテーターがガス代を支払います）。実際のお金を使います。数セントだけを入れた使い捨てキーを使用してください。 certify_provenance と score_quality も同様です。

クイックスタート（ローカル）

# 1. Build the MCP server
npm install
npm run build            # -> dist/index.js

# 2. In separate terminals, run the three services (free; payments off)
#    (provenance-receipts) npm run dev                 # http://localhost:8787
#    (quality-gate)        npx wrangler dev --port 8788 # http://localhost:8788
#    (agent-action-audit)  npx wrangler dev --port 8789 # http://localhost:8789

# 3a. Smoke-test the free tool paths through an MCP stdio client
node scripts/test-client.mjs

# 3b. (optional, costs ~$0.012) prove the paid score_quality path end-to-end
node scripts/test-score.mjs

# 3c. Smoke-test the wrapper against the LIVE deployed services (free — the
#     paid tools return a forwarded 402; no payment, no scoring call)
node scripts/test-live.mjs

scripts/test-client.mjs は無料ツールをローカルでテストします。scripts/test-score.mjs は score_quality を通じて Anthropic のスコアリングを実際に 1 回呼び出します。 scripts/test-live.mjs はラッパーの接続先をデプロイ済みの workers.dev URL に設定し、無料ツールが動作することと、有料ツールが x402 の 402 を転送することを確認します。

MCP クライアントへの接続（stdio）

このサーバーは stdio（stdin/stdout）経由で MCP を使用します。任意の MCP クライアントがサブプロセスとして起動します。Claude Desktop / Claude Code 形式の mcpServers 設定例：

{
  "mcpServers": {
    "agent-services": {
      "command": "node",
      "args": ["C:\\Users\\Gareth\\agent-services-mcp\\dist\\index.js"],
      "env": {
        "PROVENANCE_URL": "https://provenance-receipts.gpmiddleton71.workers.dev",
        "QUALITY_GATE_URL": "https://quality-gate.gpmiddleton71.workers.dev",
        "AUDIT_URL": "https://agent-action-audit.gpmiddleton71.workers.dev"
      }
    }
  }
}

• まず npm run build を実行して、dist/index.js が存在することを確認してください。
• クライアントは接続後、tools/list を呼び出します（上記の 7 つのツールが表示されます）。ツールは tools/call 経由で呼び出されます。
• ツールの呼び出し時に、基盤サービスが設定済みの URL でアクセス可能である必要があります。
• ログは stderr に出力されます。stdout は MCP プロトコル専用です。

プログラムから接続する場合は、SDK の Client と StdioClientTransport を使用します（command: "node"、args: ["dist/index.js"]）。scripts/test-client.mjs を参照してください。

x402 決済（ここでは処理せず転送）

有料エンドポイント（/v1/certify、/v1/score、/v1/audit）は、基盤サービス上で x402 によって保護されています。このラッパーはリクエストを転送するだけで、ウォレットは保持しません。サービスで決済が有効になっていて、有効な X-PAYMENT が指定されていない場合、支払い要件を含む 402 が返されます。ラッパーは、要件の本文をそのまま保持し、これを isError として返します。決済（x402 承認への署名）は、基盤サービスに対してクライアントが行う必要があります。x402 の詳細については、各サービスの README.md / docs/API.md を参照してください。Base Sepolia テストネットのみ対応しています。メインネットには対応していません。

レシートの独立した検証

certify_provenance、score_quality、audit_action が返すレシートには Ed25519 署名が付いており、これらのサービスを信頼せずに検証できます。コンテンツまたはレコードを再ハッシュし、サービスの公開鍵に照らして署名を確認してください。各サービスには、実行可能な独立した検証ツールと手順が付属しています。以下を参照してください。 provenance-receipts/docs/VERIFYING.md、 quality-gate/docs/VERIFYING.md、 および agent-action-audit の docs/VERIFYING.md。

ビルド状況

• ステップ 1 — 骨組みとツール定義（src/tools.ts）
• ステップ 2 — ツールハンドラー（HTTP 転送）とローカルのスモークテスト
• ステップ 3 — README：概要、ツール、および MCP クライアントの接続方法
• 稼働中 — デプロイ済みのサービスに接続（*.gpmiddleton71.workers.dev） scripts/test-live.mjs でエンドツーエンドの検証済みです。無料ツールは動作し、有料ツールは x402 の 402 を転送します。

7 つすべてのツールパスを稼働中のデプロイ先に対して検証済みです（ラッパー経由で有料の score_quality を エンドツーエンドで 1 回呼び出したものを含む）。有料ツール（certify_provenance、score_quality、audit_action）は x402 の 402 を転送します。

スタック

• 公式 MCP SDK：@modelcontextprotocol/sdk v1.29.0（TypeScript）、stdio トランスポート、zod 入力スキーマ。
• Node ESM + TypeScript（tsc → dist/）。

プロジェクト構成

agent-services-mcp/
├── src/
│   ├── index.ts     # MCP server: registers tools, forwards HTTP, stdio transport
│   └── tools.ts     # the 7 tool definitions (names, descriptions, Zod schemas)
├── scripts/
│   ├── test-client.mjs  # MCP stdio client — free tool smoke test (local)
│   ├── test-score.mjs   # MCP stdio client — one paid score_quality e2e check
│   └── test-live.mjs    # MCP stdio client — against the live deployed services
├── package.json
├── tsconfig.json
├── .gitignore
└── .env.example     # PROVENANCE_URL, QUALITY_GATE_URL, AUDIT_URL