ap2-iso20022

ap2-iso20022：エージェント決済の委任 → 電信送金に有効な ISO 20022

AP2（Google の Agent Payments Protocol）および x402 （Coinbase の HTTP-402）の委任を、ISO 20022 の pain.001 / pacs.008 レコードに変換します。 支出上限、有効期限、認可のガードレールを備え、MCP サーバーとして動作します。 これらのエージェント決済プロトコルは決済を認可します。このライブラリは、その認可を実際に決済を完了させる銀行レールのメッセージに変換します。カードネットワークやステーブルコインでは対応できないレールです。

最新リリース：v0.0.7：stdio、ストリーマブル HTTP、SSE 経由で利用できる 11 個の MCP ツール。純粋な Python（依存関係は mcp のみ）、ブランチカバレッジ 100％、Python 3.10 以降に対応しています。出力はそのまま pain001 / pacs008 に渡して、電信送金に有効な XML を生成できます。 ISO 20022 MCP suite の一部です。

---

理由

署名済みの AP2 委任（または x402 決済認可）を持つエージェントは、支払いが許可されていることを証明できます。しかし、これらのプロトコルは、銀行が資金を移動するために必要な pain.001 を生成しません。ap2-iso20022 は、その欠けている工程を担います。また、資金の移動は重大な結果を伴うため、変換と検証のみを行います。ISO レコードの生成と送信は意図的に別の工程とし、実際の決済は明示的なガード付きの手順として扱います。

インストール

pip install ap2-iso20022
# or run the MCP server without installing:
uvx --from ap2-iso20022 ap2-iso20022-mcp

MCP クライアントの設定例（Claude Desktop）：

{
  "mcpServers": {
    "ap2-iso20022": {
      "command": "ap2-iso20022-mcp"
    }
  }
}

トランスポート

1 つのコマンドラインで 3 種類のトランスポートを利用できます。

コマンド	トランスポート	エンドポイント	プロトコルのリビジョン
ap2-iso20022-mcp	stdio	クライアントがプロセスを起動	2026-07-28、2025-11-25
ap2-iso20022-mcp --transport streamable-http	ストリーマブル HTTP	http://127.0.0.1:8000/mcp	同じエンドポイントで 2026-07-28（ステートレス、server/discover）と 2025-11-25（initialize、Mcp-Session-Id）に対応します。レスポンスはサーバー送信イベントとしてストリーミングされ、GET でサーバーからクライアントへのストリームを開きます
ap2-iso20022-mcp --transport sse	HTTP+SSE（2024-11-05）	http://127.0.0.1:8000/sse および /messages/	古いトランスポートを引き続き想定しているクライアント向けです

--host と --port でバインドアドレスを変更できます（デフォルトは 127.0.0.1 と 8000 です）。HTTP トランスポートには独自の認証機能がありません。ループバックにバインドするか、ルーティング可能なアドレスにバインドする前に、信頼できるゲートウェイの背後にサーバーを配置してください。すべてのリリースは、両方のプロトコル世代でストリーマブル HTTP を使用し、scout で検証しています。また、MCP SDK クライアントで SSE も検証しています。詳しくは ADR 0001 をご覧ください。

{
  "mcpServers": {
    "ap2-iso20022": { "url": "http://127.0.0.1:8000/mcp" }
  }
}

フロー：正規化 → ガードレール → 変換

from ap2_iso20022 import bridge

# 1. Normalise the protocol payload into a canonical mandate.
mandate = bridge.from_ap2({
    "intent_id": "AP2-CoffeeRun-7",
    "payer": "Alice's Shopping Agent",
    "payer_account": "DE89370400440532013000",
    "merchant_name": "Blue Bottle Coffee",
    "payee_account": "GB29NWBK60161331926819",
    "amount": "12.50", "currency": "EUR", "memo": "oat latte",
    "spending_limit": "50.00",
    "signature": "eyJ...", "signature_type": "jws",
})

# 2. Guardrail before it becomes a payment.
check = bridge.check_mandate(mandate, as_of="2026-03-02T09:00:00")
assert check["ok"]          # required fields ok, within cap, not expired, signed

# 3. Convert to a pain.001 record that feeds pain001 -> wire-valid XML.
record = bridge.to_pain001(mandate)   # exact pain001 field names + JSON number amounts

ツール

• normalize_ap2 — AP2 委任ペイロード → 正規化された委任。
• normalize_x402 — x402 決済ペイロード → 正規化された委任。
• check_mandate — ガードレール：必須フィールド、支出上限、有効期限（as_of を使用）、認可証明。
• to_pain001 — 正規化された委任 → pain.001 レコード（顧客信用振替）。
• to_pacs008 — 正規化された委任 → pacs.008 レコード（金融機関間）。

出力フィールドの名前と型は pain001 / pacs008 が期待するものと一致しており、 それぞれの JSON スキーマに対して検証済みです。そのため、to_pain001(mandate) → pain001 generate_message とつなぐだけで、追加の接続コードなしに XSD 準拠の pain.001 を生成できます。

ガードレール

check_mandate は {ok, violations, warnings} を返します。

• 必須フィールド — 支払人／受取人の名前と口座、金額、通貨
• 支出上限 — 上限が設定されている場合、amount <= max_amount
• 有効期限 — as_of を渡すと、有効期限切れの委任を拒否します
• 認可証明 — proof_type / proof_value がない場合に警告します

資金を移動することはありません。委任に基づいて安全に処理できるかどうかを通知します。

スイート

ベンダーに依存しない、Python ネイティブな ISO 20022 MCP サーバー群の一部です。

• iso20022-mcp — 各ファミリーを統合するゲートウェイです。
• pain001-mcp · pacs008-mcp — このブリッジに渡す XML を生成します。
• reconcile-mcp — 明細書と支払いを照合します。
• camt-exceptions — E&I メッセージ（キャンセル、調査）を扱います。

開発

git clone https://github.com/sebastienrousseau/ap2-iso20022
cd ap2-iso20022
python -m venv .venv && . .venv/bin/activate
pip install -e . && pip install pytest pytest-cov ruff black mypy
pytest                      # 100% branch coverage gate
ruff check ap2_iso20022 tests && black --check ap2_iso20022 tests && mypy ap2_iso20022

ライセンス

Apache License, Version 2.0（LICENSE）の下でライセンスされています。

---

mcp-name: io.github.sebastienrousseau/ap2-iso20022