iso20022-readiness-suite-mcp

iso20022-readiness-suite-mcp：ISO 20022 対応状況確認・テストゲートウェイ

高レベルのオーケストレーションを行うModel Context Protocolサーバー — ホワイトラベルの ISO 20022 対応状況確認・テストゲートウェイです。 エージェントに対しては MCP サーバーとして、ISO 20022 MCP Suiteの基盤となるサーバーに対しては MCP クライアントとして機能します。これらを組み合わせて、対応状況のスコアリング、自動修正、クリアリングプロファイルの lint（CBPR+、SEPA_Instant、FedNow、Generic）、銀行応答のシミュレーションを実現します。エージェントが操作できる単一のゲートウェイから、「この支払いは準備できているか。できていないなら修正してほしい」という問いに答えられます。

2026年11月のマイルストーン。 主要なスキーム（CBPR+、HVPS+、T2、FedNow）が ISO 20022 の要件（特に構造化された郵便住所）を強化するにつれて、昨日は問題なかった支払いが明日には拒否される可能性があります。iso20022-readiness-suite-mcp は、エージェントの前段に単一の対応状況確認ゲートウェイを配置します。run_readiness_check はクリアリングプロファイルに照らしてペイロードを評価し、remediate_payload は準拠する形式を提案し、simulate_bank_response は銀行の応答をシミュレートします。v0.0.6、stdio（デフォルト）、ストリーミング可能な HTTP、SSE、または認証付きストリーミング可能な HTTP、4 つのツール、Python 3.10 以降に対応しています。

目次

• 概要
• ISO 20022 MCP Suite
• インストール
• クイックスタート
• トランスポート — stdio、ストリーミング可能な HTTP（2026-07-28 および 2025-11-25）、SSE、認証付き HTTP を 1 つのコマンドラインから利用できます
• ツール
• HTTP トランスポートと認証
• オーケストレーションとメタクライアントパターン
• オープンコアとプレミアム版
• iso20022-readiness-suite-mcp を使用すべきでない場合
• 開発
• セキュリティ
• ドキュメント
• ライセンス
• 貢献
• 謝辞

概要

Model Context Protocol（MCP）は、AI エージェントやアシスタントが外部ツールを一貫した方法で検出し、呼び出せるようにするオープン標準です。 iso20022-readiness-suite-mcp は、ISO 20022 MCP Suite のオーケストレーションの窓口です。外部のエージェントには4つの高レベルツールを提供し、その内部では MCP クライアントとして動作して、基盤となる Suite サーバーを stdio 経由で起動し、その結果を組み合わせます。これがメタクライアントパターンです。

主要な機能は、ワンショットのレディネスワークフローです。生の ISO 20022 ペイロードと対象のクリアリングプロファイルを渡すと、メッセージタイプを検出し、適切な基本バリデーターにルーティングして、プロファイルの市場慣行ルールに照らして検査し、検出事項とともに単一のレディネススコアを返します。さらに、リクエストに応じてペイロードを修正し、銀行がどのように応答するかをシミュレートします。

すべてのツールは、型付きで JSON にシリアライズ可能なデータを返します。不正な入力、解析できないペイロード、サブサーバーの欠落やエラーなど、どのような障害が発生した場合も、クライアントのトランスポートに例外を送出するのではなく、{"error": ...} ペイロードを返します。

• ウェブサイト： https://sebastienrousseau.github.io/iso20022-readiness-suite-mcp/
• ソースコード： https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp
• バグ報告： https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp/issues

flowchart TD
    A["MCP client<br/>(Claude Desktop, IDE, agent)"] -->|stdio| B["iso20022-readiness-suite-mcp<br/>(orchestration gateway)"]
    B -->|spawns over stdio via uvx| C["iso20022-mcp"]
    B -->|spawns over stdio via uvx| D["camt053-mcp"]
    B -->|spawns over stdio via uvx| E["pain001-mcp"]
    B -->|spawns over stdio via uvx| F["reconcile-mcp"]
    B -->|spawns over stdio via uvx| G["bankstatementparser-mcp"]
    B -->|spawns over stdio via uvx| H["structured-address-fix-mcp"]

ゲートウェイは、その上位にあるクライアントに対してはサーバーであり、その下位にある6つの基盤サーバーに対してはクライアントです。list_profiles と simulate_bank_response は完全にローカルで動作するため、基盤サーバーは不要です。一方、run_readiness_check と remediate_payload はサブサーバーにアクセスするため、それらがインストールされ、解決可能である必要があります（オーケストレーションとメタクライアントパターンを参照）。

ISO 20022 MCP Suite

iso20022-readiness-suite-mcp は、ISO 20022 移行向けに連携する、ベンダー中立な MCP サーバー群の上位に位置するオーケストレーションゲートウェイです。依存関係のバージョン範囲は Suite 全体で揃えてあるため、単一の Python 環境に各サーバーをまとめてインストールできます。必要な基盤サーバーをインストールし、このゲートウェイにそれらを組み合わせさせてください。

各基盤サーバーがそれぞれの役割を果たすのに対し、このゲートウェイはそれらを組み合わせます。ペイロードを検出して適切なバリデーターにルーティングし、クリアリングプロファイルに照らして検査し、レディネスをスコア化して修正し、銀行の応答をシミュレートします。これらすべてを4つのエージェントツールで利用できます。

インストール

iso20022-readiness-suite-mcp は macOS、Linux、Windows で動作し、Python 3.10+ と pip が必要です。MCP SDK、pydantic、defusedxml は自動的にインストールされます。

python -m pip install iso20022-readiness-suite-mcp

run_readiness_check と remediate_payload をエンドツーエンドで実行するには、基盤となるサーバーも解決可能にしてください。ゲートウェイは uvx でサーバーを起動するため、uv をインストールするだけで、インストール不要で起動できます。

python -m pip install uv        # provides the `uvx` launcher

python -m venv venv
source venv/bin/activate        # macOS/Linux
venv\Scripts\activate           # Windows
python -m pip install -U iso20022-readiness-suite-mcp

クイックスタート

10 分でインストールから MCP クライアントの設定、最初の会話まで進めるチュートリアルについては、docs/quickstart.md をご覧ください。

サーバーを stdio（デフォルトのトランスポート）で起動します。

iso20022-readiness-suite-mcp

MCP クライアント（Claude Desktop など）に登録するには、クライアントの設定に追加します。

{
  "mcpServers": {
    "iso20022-readiness-suite": { "command": "iso20022-readiness-suite-mcp" }
  }
}

このコマンドは stdin/stdout で MCP を使用します。対話形式で使うのではなく、MCP クライアントから起動することを想定しています。これにより、エージェントは以下のツールを呼び出せるようになります。

トランスポートを介さず、FastMCP インスタンスを通じてツールを直接プロセス内で呼び出すこともできます。これは、エージェントが stdio 経由で受け取る内容を再現します。2 つのローカルツール（list_profiles、simulate_bank_response）にはサブサーバーは不要です。

import asyncio

from iso20022_readiness_suite_mcp import server


async def main() -> None:
    async def call(name, args):
        result = await server.server.call_tool(name, args)
        # mcp 2.x returns a CallToolResult (read .content); 1.x
        # returns the content list, or a (content, meta) tuple.
        content = getattr(result, "content", None)
        if content is None:
            content = result[0] if isinstance(result, tuple) else result
        return content[0].text if content else ""

    # Which clearing profiles can I target? (fully local)
    print(await call("list_profiles", {}))
    # -> [{"profile_id": "CBPR+", ...}, {"profile_id": "SEPA_Instant", ...}, ...]

    # Mock how a bank would answer an initiation. (fully local)
    pacs008 = '<Document><CdtTrfTxInf><Amt Ccy="EUR">10</Amt></CdtTrfTxInf></Document>'
    print(await call("simulate_bank_response",
                     {"inbound_payload": pacs008, "desired_behavior": "ACCP"}))
    # -> {"status": "ACCP", "generated_response_type": "pacs.002.001.10", ...}


asyncio.run(main())

トランスポート

1 つのコマンドラインで、4 つのトランスポートを使用できます。

--host と --port は、streamable-http と sse のバインドアドレスを変更します（デフォルトは 127.0.0.1 と 8000 です）。この 2 つのトランスポートには独自の認証機能がありません。ループバックにバインドするか、ルーティング可能なアドレスにバインドする前に、信頼できるゲートウェイの背後にサーバーを配置してください。--transport http は認証付きのオプションです。外側のトランスポートにかかわらず、ゲートウェイはサブサーバーを引き続き stdio 経由で起動し、セッションをプールします。各リリースは、両方のプロトコル世代で scout を使った Streamable HTTP、および MCP SDK クライアントを使った SSE で検証されています。詳細は ADR 0001 をご覧ください。

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

ツール

すべてのツールは JSON シリアライズ可能なデータを返します。ドメインエラー、検証エラー、または サブサーバーエラーが発生した場合は、例外を送出するのではなく {"error": ...} ペイロードを返します。

• list_profiles — 利用可能なクリアリングプロファイル（CBPR+、SEPA_Instant、FedNow、Generic）と、それぞれの市場慣行およびルールを一覧表示します。完全にローカルで動作し、サブサーバーは必要ありません。
• run_readiness_check — ISO 20022 ペイロードを検出、構造検証、プロファイルリンティングし、対象のクリアリングプロファイルに対する準備状況をスコアリングします。基盤となるサブサーバーに接続します。
• remediate_payload — クリアリングプロファイルに基づき、自動修正（例：2026年11月の住所構造化の修正）を適用し、structured-address-fix-mcp に委譲します。基盤となるサブサーバーに接続します。
• simulate_bank_response — インバウンド開始に対する銀行の ACCP／RJCT／PDNG 応答を模した pacs.002 ステータスレポートを生成します（RJCT では理由コードが必要です）。完全にローカルで動作し、サブサーバーは必要ありません。

到達可能性。 run_readiness_check と remediate_payload は uvx 経由で 基盤となるサーバーを stdio で起動するため、これら2つのツールが正常に動作するには、 サーバーがインストール済みで、名前解決可能である必要があります。list_profiles と simulate_bank_response は完全にローカルで処理するため、単独で常に動作します。

HTTP トランスポートと認証

デフォルトでは、ゲートウェイは stdio で通信します。ローカルの MCP クライアントが オペレーターごとに1つのプロセスを起動し、ネットワークへの露出はなく、認証も不要です。

iso20022-readiness-suite-mcp                 # stdio (default)

認証なしのスイートの --transport streamable-http および --transport sse については、トランスポートで説明しています。 共有型のマルチテナント環境向けに、ゲートウェイは認証付きの streamable-HTTP トランスポートも提供します。デフォルトの --bind はループバックのみ （127.0.0.1:8080）です。公開するには、明示的に --bind=0.0.0.0:8080 を指定します。

iso20022-readiness-suite-mcp --transport=http --bind=0.0.0.0:8080

HTTP トランスポートでは認証が必須です。認証を設定せずに起動すると拒否されます。 2つのモードがあり、上から順に強力です。

OAuth 2.1 リソースサーバー（RFC 9728）— 本番環境向け。
ISO20022_READINESS_OAUTH_* 環境変数を設定すると、サーバーは Authorization: Bearer <jwt> を認可サーバーの JWKS に照らして検証します。

JWT の署名（JWKS。未知の kid が検出された場合は鍵をローテーションして検証）、 iss／aud／exp／nbf、および必須スコープを検証します。RFC 9728 の 保護リソースメタデータは、認証なしで /.well-known/oauth-protected-resource に提供されます。 拒否されたリクエストには 401（insufficient_scope の場合は 403）を返し、 そのメタデータを指す WWW-Authenticate チャレンジを含めます。

静的ベアラートークン — 開発モード専用。 OAuth 変数が設定されていない場合は、 代わりに ISO20022_READINESS_TOKEN の単一の共有シークレットを受け付けます （hmac.compare_digest で比較します）。これは明示的に開発モード専用です。共有シークレットは1つで、 有効期限もスコープもありません。OAuth も設定されている場合は無視されます。

ISO20022_READINESS_TOKEN=s3cret \
  iso20022-readiness-suite-mcp --transport=http --bind=127.0.0.1:8080

HTTP 呼び出し元は任意で X-MCP-Tenant ヘッダーを送信できます。このヘッダーは リクエストごとのテナントコンテキストに転送されます。また、認証済みトークンのスコープも ツールに公開されるため、ツールコードはトランスポートごとに分岐せずに動作を制御できます。 詳しい設定については、docs/transport.md を参照してください。

オーケストレーションとメタクライアントパターン

ゲートウェイは、オーケストレーションの「クライアントでもあるサーバー」という側面を実装しています。オーケストレーターは SubServerInvoker プロトコルのみに依存し、本番環境用の StdioSubServerInvoker は基盤となるサーバーを標準入出力経由で起動し、ツールを1つ呼び出してからセッションを終了します。サーバーが見つからない、起動エラー、ツールエラーなど、あらゆる失敗は型付きの ToolOutcome としてデータで返され、呼び出し元との境界を越えて例外が送出されることはありません。

デフォルトでは、各基盤サーバーはインストール不要の uvx コマンドで起動します。

コマンドのマップはデプロイごとに上書きできるため、ゲートウェイの接続先を uvx ではなく、ローカルにインストールしたコンソールスクリプト、固定された仮想環境、またはリモートで起動するプロセスに指定できます。パターンの詳細と、ローカルまたはリモートのサブサーバーを指定する方法については、docs/orchestration.md をご覧ください。

オープンコアとプレミアム

ゲートウェイはオープンコアです。基本の検証ワークフローと汎用スキームプロファイルはオープンソースで、常に利用できます。上位プランの機関固有の機能は商用アドオンで、同じプロファイルエンジンとオーケストレーションの接続点に組み込めます（プロファイルエンジンには、実行時に読み込まれるルールパック用の register() フックがすでに用意されています）。

有料プランはロードマップに記載されており（プレミアムルールパックの利用権限管理に加え、関連する iso20022-bank-profile-mcp および iso20022-evidence-pack-mcp サーバー）、今回のリリースには含まれていません。オープンソースプランの機能に、利用期限や機能制限はありません。

iso20022-readiness-suite-mcp を使用しない場合

• MCP クライアントをお持ちでない場合。 このサーバーは、MCP 対応ホスト（Claude Desktop、IDE プラグイン、エージェントフレームワーク）と組み合わせる場合にのみ意味があります。
• メッセージ操作を1つだけ必要とする場合。 pain.001 の検証や camt.053 の解析だけが必要なら、該当する基盤サーバーを直接呼び出してください。ゲートウェイの価値は、これらを組み合わせることにあります。
• サブサーバーなしで run_readiness_check / remediate_payload を使う必要がある場合。 これら2つのツールを使うには、基盤サーバーを解決できる必要があります（uvx または上書きしたコマンドマップ経由）。インストールできない場合は、list_profiles と simulate_bank_response のみ利用できます。
• 長時間稼働するネットワークサービスが必要な場合。 デフォルトの標準入出力方式では、クライアントがオペレーターごとに1つのプロセスを起動するため、ネットワークへの公開はありません。認証なしで --transport streamable-http と --transport sse を使うと、--host/--port で待ち受けます（トランスポートをご覧ください）。共有型のマルチテナントデプロイには、認証付きの Streamable HTTP トランスポート（--transport=http、OAuth 2.1 または開発モードのトークンを使用）を使ってください。HTTP トランスポートと認証をご覧ください。
• ストリーミング応答が必要な場合。 ツール呼び出しはストリームではなく、値全体を返します。

開発

iso20022-readiness-suite-mcp は Poetry と mise を使用します。

git clone https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp.git && cd iso20022-readiness-suite-mcp
mise install
poetry install
poetry shell

注記： テストスイートでは偽のサブサーバー呼び出し元を注入するため、テストの実行に基盤サーバーをインストールする必要はありません。実サーバーに対して run_readiness_check / remediate_payload を試す場合にのみ必要です。CONTRIBUTING.md をご覧ください。

Makefile で品質チェックを実行します（CI と常に同期しています）。

make check        # all gates (REQUIRED before commit): lint + type-check + test
make test         # pytest (100% line + branch coverage)
make lint         # ruff + black
make type-check   # mypy --strict
make security     # bandit

セキュリティ

iso20022-readiness-suite-mcp はエラーをデータとして返します。すべてのツールは、文書化されたドメインエラー、検証エラー、値エラー、およびすべてのサブサーバーの障害を捕捉し、{"error": ...} エンベロープを返します。MCP クライアントに生の例外を伝播させることはありません。クリアリングプロファイルエンジンを介して取得する XML ペイロードの解析には defusedxml のみを使用し、XXE や billion-laughs 攻撃を防ぎます。報告の実施方法、サポート対象バージョン、メタクライアントの攻撃対象領域、およびサプライチェーン全体のセキュリティ対策（SLSA L3 の来歴情報、PEP 740 の証明書、SBOM、NIST SP 800-218 SSDF の実践項目への対応付け）については、SECURITY.md に記載しています。脆弱性の報告には、公開 issue ではなく GitHub の非公開脆弱性報告機能をご利用ください。

ドキュメント

• README.md — このファイル
• CHANGELOG.md — リリースノート
• ARCHITECTURE.md — モジュール構成とゲートウェイの設計判断
• RELEASING.md — リリースに値する変更とリリースの手順
• SECURITY.md — 脆弱性の開示とサポート対象バージョン
• SUPPORT.md — サポートを受ける方法
• ROADMAP.md — 今後の予定（姉妹サーバー、プレミアムルールパックの利用権）
• MAINTAINERS.md — マージ権限を持つメンテナー
• docs/adr/ — アーキテクチャ決定記録
• docs/quickstart.md — 10 分でインストールから最初の対話まで
• docs/transport.md — HTTP トランスポートと OAuth 2.1（RFC 9728）認証の設定
• docs/orchestration.md — メタクライアントパターンと、ローカル／リモートのサブサーバーをゲートウェイに接続する方法
• docs/profiles.md — クリアリングプロファイルとプレミアムルールパックの組み込み方法
• glama.json — Glama ディレクトリのマニフェスト

MCP Registry

mcp-name: io.github.sebastienrousseau/iso20022-readiness-suite-mcp

ライセンス

Apache License, Version 2.0 に基づいてライセンスされています。採用を目的として提出された貢献は、追加条件なしで上記と同じ条件でライセンスされます。

貢献

貢献を歓迎します。貢献ガイドラインをご覧ください。貢献者の皆様に感謝します。

謝辞

ISO 20022 MCP Suite の基盤サーバーと、Model Context Protocol Python SDK を基に構築されています。