iso20022-evidence-pack-mcp

iso20022-evidence-pack-mcp：封印済み ISO 20022 監査証跡パック

完全にローカルで、閉じた世界で動作する Model Context Protocol (MCP) サーバーです。ISO 20022 の対応準備状況の調査結果、修正差分、シミュレートされた銀行の応答をまとめ、封印済みでエクスポート可能な監査証跡パックを作成します。これは iso20022-readiness-suite-mcp （調査結果を生成します）および ISO 20022 MCP Suite に含まれる iso20022-bank-profile-mcp の監査・認証版です。

設計上、改ざんを検知できます。 パックの封印は、パックの正規化された JSON に対する決定論的な SHA-256 ダイジェストです（digest フィールドを除外）。同一の内容を再封印すると同じダイジェストが生成され、いずれかのフィールドを変更すると検証に失敗するため、監査担当者は検知されていない変更を見つけられます。ネットワークに接続する機能も、サブサーバーも、XML もありません。すべてのツールは、渡された JSON 構造に対してローカルで決定論的な変換のみを行います。 v0.0.6、stdio、ストリーム可能 HTTP、SSE、認証付きストリーム可能 HTTPに対応。Ed25519 によるパック署名を含む 11 個のツールを備え、Python 3.10 以降に対応します。

目次

• 概要
• ISO 20022 MCP Suite
• インストール
• クイックスタート
• トランスポート — 1 つのコマンドラインから利用できる stdio、ストリーム可能 HTTP（2026-07-28 および 2025-11-25）、SSE、認証付き HTTP
• ツール
• HTTP トランスポートと認証
• 監査証跡パックの署名
• 例
• スイート内での位置づけ
• オープンコアとプレミアム
• 封印と署名
• iso20022-evidence-pack-mcp を使用すべきでない場合
• 開発
• セキュリティ
• ドキュメント
• ライセンス
• 貢献
• 謝辞

概要

Model Context Protocol（MCP）は、AI エージェントやアシスタントが外部ツールを一貫した方法で検出し、呼び出せるようにするオープンスタンダードです。 iso20022-evidence-pack-mcp は、ISO 20022 MCP Suite における監査／認証を担います。 iso20022-readiness-suite-mcp が生成する、検出結果を含む準備状況スコア、任意の修正結果、シミュレーションされた銀行の応答をまとめ、エクスポート、検証、コンプライアンスレポートとしての生成が可能な、強く型付けされた、評価済みの封印済みエビデンスパックを作成します。

EvidencePack は、型付けが緩やかな3つの入力を、自己記述型の1つのドキュメントにまとめます。入力は、準備状況の結果（メッセージタイプ、有効性、スコア、検出結果）、任意の修正結果（適用された修正、残存する検出結果）、およびシミュレーションされた銀行の応答（承認／却下のステータス）です。パックは準備状況スコアに基づいて A／B／C／F に評価され、封印されます。

重要なのは、この封印です。パックの正規化された JSON 形式（キーをソートし、区切り文字を詰め、digest フィールド自体は除外）から、決定論的な SHA-256 ダイジェストが計算されます。同じ内容を封印すれば、常に同じ値が得られます。これにより、パックの改ざんを検知できます。封印を再計算し、パックに含まれる値と比較することで、封印後にバイト単位で変更があったかどうかを監査担当者が確認できます。

すべてのツールは、型付けされた JSON シリアライズ可能なデータを返します。入力の不備、解析できない JSON、パックのスキーマに一致しない構造などのエラーが発生した場合は、クライアントのトランスポートに例外を送出するのではなく、{"error": ...} ペイロードを返します。

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

flowchart LR
    A["iso20022-readiness-suite-mcp<br/>(readiness + remediation + simulation)"] -->|JSON results| B["iso20022-evidence-pack-mcp<br/>(build + seal)"]
    B -->|sealed pack + digest| C["verify_seal<br/>(tamper check)"]
    B -->|markdown report| D["render_markdown<br/>(compliance report)"]

このサーバーは完全にローカルで、閉じた環境で動作します。状態を保持せず、ソケットを開かず、プロセスも起動しません。JSON を渡すと、封印済みのパックが返されます。

ISO 20022 MCP スイート

iso20022-evidence-pack-mcp は、ISO 20022 への移行に向けて連携する、ベンダー中立な MCP サーバー群の監査・認証サーバーです。 依存関係の範囲はスイート全体で揃えているため、単一の Python 環境に各サーバーをまとめてインストールできます。

readiness suite が支払いの準備が整っているかを判断し、修正するのに対し、本サーバーは結果を認証し、その所見を封印済みの監査可能な成果物に変換します。

インストール

iso20022-evidence-pack-mcp は macOS、Linux、Windows で動作し、Python 3.10+ と pip が必要です。MCP SDK と pydantic のみを自動的にインストールし、その他の実行時依存関係はありません。

python -m pip install iso20022-evidence-pack-mcp

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

クイックスタート

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

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

iso20022-evidence-pack-mcp

クライアントの設定に追加すると、Claude Desktop などの任意の MCP クライアントに登録できます。

{
  "mcpServers": {
    "iso20022-evidence-pack": { "command": "iso20022-evidence-pack-mcp" }
  }
}

このコマンドは標準入力／標準出力で MCP 通信を行います。対話的に使用するのではなく、MCP クライアントから起動することを想定しています。これにより、エージェントは以下のツールを呼び出せるようになります。

トランスポートを使わず、FastMCP インスタンスを介して、プロセス内でツールを直接呼び出すこともできます。これは、エージェントが stdio 経由で受け取る内容を再現します。以下の例では、小さな readiness の結果から封印済みパックを作成し、封印の往復検証と、改ざん時に検証が失敗する様子を示します。

import asyncio
import json

from iso20022_evidence_pack_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 ""

    readiness = json.dumps({
        "message_type": "pacs.008.001.08",
        "is_valid": True,
        "readiness_score": 92,
        "structural_errors": [],
        "profile_findings": [],
    })

    # Fold the readiness result into a graded, sealed evidence pack.
    built = json.loads(await call("build_evidence_pack",
                                  {"readiness_content": readiness}))
    pack, digest = built["pack"], built["digest"]
    print(pack["grade"], digest)      # -> A sha256:01388e3dfbea7d21...

    # The seal round-trips: re-verifying the pack against its digest holds.
    ok = json.loads(await call("verify_seal", {
        "pack_content": json.dumps(pack),
        "expected_digest": digest,
    }))
    print(ok["verified"])             # -> True

    # Change any field and verification against the old digest fails.
    tampered = {**pack, "grade": "F"}
    bad = json.loads(await call("verify_seal", {
        "pack_content": json.dumps(tampered),
        "expected_digest": digest,
    }))
    print(bad["verified"])            # -> False


asyncio.run(main())

トランスポート

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

--host と --port で、streamable-http と sse のバインドアドレスを変更できます（デフォルトは 127.0.0.1 と 8000 です）。この 2 つにはそれぞれ認証機能がありません。ループバックにバインドするか、ルーティング可能なアドレスにバインドする前に、信頼できるゲートウェイの背後にサーバーを配置してください。認証が必要な場合は --transport http を使用します。すべてのリリースで、両方のプロトコル世代における Streamable HTTP と、MCP SDK クライアントを使用した SSE の動作を scout で検証しています。詳しくは ADR 0001 を参照してください。

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

ツール

すべてのツールは読み取り専用で、ローカルで実行され、冪等であり、閉じた世界を前提とします。JSON にシリアライズ可能なデータを返し、検証エラーまたは形式エラーが発生した場合は、例外を発生させる代わりに {"error": ...} ペイロードを返します。

• build_evidence_pack — 準備状況の結果（任意で修正結果、シミュレートした銀行レスポンス、自由形式のメタデータも指定可能）を、評価済みの封印済みエビデンスパックにまとめます。パック、そのダイジェスト、レンダリング済みの Markdown レポートを返します。
• seal_pack — エビデンスパックの決定論的な SHA-256 シールを計算します（生の JSON）。
• verify_seal — パックのシールを再計算し、指定されたダイジェストと比較します。
• render_markdown — エビデンスパックを Markdown のコンプライアンスレポートとしてレンダリングします。
• sign_pack — 演算子の Ed25519 キー（環境経由で設定）を使用して、パックの正規化バイト列に署名します。base64 形式の分離署名、PEM 公開鍵、key_id を返します。キーが設定されていない場合は EP_NO_SIGNING_KEY で失敗します。エビデンスパックの署名を参照してください。
• verify_pack_signature — 引数として渡された公開鍵を使用して、パックの正規化バイト列に対する分離 Ed25519 署名を検証します。verified と key_id を返します。

HTTP トランスポートと認証

サーバーはデフォルトで stdio を使用します。ローカルの MCP クライアントが起動し、オペレーターごとに 1 つのプロセスとして動作するため、ネットワークに公開されず、認証も必要ありません。共有型のマルチテナント環境では、v0.0.2 でオプションのストリーム可能な HTTP トランスポートが追加されました。

iso20022-evidence-pack-mcp --transport=http --bind=127.0.0.1:8080

--bind のデフォルトはループバックアドレス 127.0.0.1:8080 です。そのため、サーバーを公開する設定（例：--bind=0.0.0.0:8080）は明示的なオプトインとなります。認証を設定せずに HTTP トランスポートを起動することは拒否され、認証なしのエンドポイントが提供されることはありません。 認証方式は、強度の高い順に次のとおりです。

• OAuth 2.1 リソースサーバー（RFC 9728） — ISO20022_EVIDENCE_PACK_OAUTH_* 変数を設定します。

  変数	必須	意味
  ISO20022_EVIDENCE_PACK_OAUTH_ISSUER	はい	認可サーバーの発行者です。JWT の iss は、この値と完全に一致する必要があります。
  ISO20022_EVIDENCE_PACK_OAUTH_AUDIENCE	はい	このサーバーの正規リソース URI（RFC 8707）です。JWT の aud にこの値が含まれている必要があります。
  ISO20022_EVIDENCE_PACK_OAUTH_JWKS_URL	いいえ	JWKS ドキュメントの URL です（デフォルトは <issuer>/.well-known/jwks.json）。
  ISO20022_EVIDENCE_PACK_OAUTH_SCOPES	いいえ	すべてのトークンに必要なスコープを、スペース区切りで指定します。

  すべてのリクエストで Authorization: Bearer <jwt> を提示する必要があります。JWT は JWKS に照らして検証されます（iss／aud／exp／nbf および必要なスコープ）。保護対象リソースのメタデータは /.well-known/oauth-protected-resource で提供されます。認証に失敗した場合は WWW-Authenticate チャレンジを伴う 401（スコープ不足の場合は 403）が返されます。

• 静的な開発モードのベアラートークン — ISO20022_EVIDENCE_PACK_TOKEN に空でないシークレットを設定します。この場合、すべてのリクエストで Authorization: Bearer <secret> を送信する必要があります。これは有効期限もスコープもない単一の共有シークレットです。本番環境では OAuth 2.1 を使用してください。

HTTP の呼び出し元は、オプションで X-MCP-Tenant ヘッダーを送信できます。このヘッダーは、マルチテナントのスコープ設定に使えるよう、ツールから参照可能なリクエストコンテキストに引き継がれます。HTTP トランスポートでは追加の依存関係（pyjwt[crypto]、httpx、starlette、uvicorn）が必要ですが、デフォルトの stdio トランスポートではいずれも不要です。詳しくは docs/transport.md を参照してください。

エビデンスパックへの署名

パックのシールは完全性、つまり内容が変更されていないことを証明します。署名は真正性、つまり特定の鍵がその内容を保証していることを証明します。v0.0.2 では、2 つのツールを通じて Ed25519 署名が追加されました。

• sign_pack は、パックの正規バイト列に署名します。これは、digest フィールドを除いた、シールがダイジェストを計算するものとまったく同じシリアライズです。署名はシール対象の内容を対象とするため、digest フィールドだけが変更されても有効なままですが、シール対象のフィールドが 1 つでも変更されると無効になります。このツールは、base64 形式のデタッチド署名、algorithm の値 "ed25519"、PEM 形式の公開鍵、および key_id（ed25519:<16 hex>）を返します。
• verify_pack_signature は、ツール引数として渡された公開鍵を使って、パックの正規バイト列に対するデタッチド署名を検証します。公開鍵はツールの境界を越えて安全に渡せます。このツールは verified と key_id を返します。

Ed25519 の秘密鍵は、起動時にオペレーターが環境変数を通じて設定します。

• ISO20022_EVIDENCE_PACK_SIGNING_KEY — PEM 秘密鍵を直接指定する場合、または
• ISO20022_EVIDENCE_PACK_SIGNING_KEY_FILE — PEM 鍵ファイルへのパスを指定する場合です。

秘密鍵が MCP ツールの境界を越えることはありません。 サーバーが秘密鍵を生成したり永続化したりすることはありません。鍵素材はオペレーターが生成して管理し、できれば HSM/KMS を使用してください。鍵が設定されていない場合、sign_pack は EP_NO_SIGNING_KEY を返します。不正な鍵または署名の場合は EP_INVALID_INPUT を返します。

オペレーターが提供した鍵による署名は、現在利用できます。鍵不要の署名（sigstore）および検証用のトラストルートを用いる PKI 署名は、引き続きロードマップの項目です。

例

実行可能で自己完結した例は、examples/ にあります。各スクリプトは公開ツールを直接実行し、ネットワークやサブサーバーを必要としません。

python examples/01_build_full_pack.py

全例の一覧は examples/README.md をご覧ください。または、make examples を実行するとすべて実行できます。

スイート内での位置付け

レディネススイートとエビデンスパックサーバーは、2 段階のパイプラインを構成します。

1. レディネス → 結果。 iso20022-readiness-suite-mcp は、run_readiness_check（スコア＋指摘事項）、remediate_payload （自動修正）、simulate_bank_response（モックの pacs.002 結果）を実行します。 それぞれ型付き JSON を返します。
2. 結果 → 封印済みパック。 ここで、これらの JSON 結果を build_evidence_pack に渡します。結果は正規化されて厳密に型付けされたパックになり、 レディネススコア（A/B/C/F）が評価され、全体が決定論的な SHA-256 ダイジェストで 封印されます。後から verify_seal を実行するとパックが変更されていないことを 証明でき、render_markdown を使うと人が読めるコンプライアンスレポートに 変換できます。

封印は決定論的であるため、同じ入力からは常に同じダイジェストが生成されます。 そのため、今日作成したパックを次の四半期に再度封印しても、同一のパックであること、 あるいは同一ではないことを確実に証明できます。2 つのサーバーは疎結合です。 レディネススイートは封印について何も知らず、このサーバーは指摘事項がどのように 生成されたかを何も知りません。指摘事項をまとめて証明するだけです。

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

このサーバーはオープンコアです。パックの構築、封印、検証、レンダリングは オープンソースで、常に利用できます。改ざんの証拠を残すパックを、真正性を検証可能な 永続保存済みの成果物にする上位ティアの機能は、ロードマップに記載された 商用アドオンです。

オープンソースティアの機能に、期限や機能制限はありません。封印とレポートは 現在、すべて完全に機能します。

封印と署名の違い

封印は整合性ダイジェストであり、暗号署名ではありません。 パックが封印後に 変更されていないこと（改ざんの証拠）を証明しますが、誰がパックを作成したか （真正性）は証明しません。パックを構築できる人なら誰でも有効な封印を計算できるため、 封印はチェックサムであり、出所の証明ではありません。

真正性、つまりパックを特定の鍵に結び付ける機能を封印に追加するのが、 sign_pack / verify_pack_signature です。 パックの正規バイト列に対する Ed25519 署名により、オペレーター鍵の保有者が そのコンテンツを作成したことを証明できます。封印と署名は相互に補完するもので、 封印は整合性を、署名は真正性を示します。ただし、署名の信頼性は公開鍵の来歴を どの程度信頼できるかに左右されます。キーレス（sigstore）/ PKI 署名と 検証用トラストルートは、引き続きロードマップ上の項目です （ROADMAP.md を参照）。署名鍵を設定していない場合は、 封印済みでも署名されていないパックは整合性のみが確認されたものとして扱ってください。 すでに信頼しているチャネル経由で送信・保存し、署名済みのものとして表示しないでください。 脅威モデルに関する詳細は SECURITY.md をご覧ください。

iso20022-evidence-pack-mcpを使用しない場合

• MCP クライアントがありません。 このサーバーは、MCP 対応のホスト（Claude Desktop、IDE プラグイン、エージェントフレームワーク）と組み合わせて初めて意味を持ちます。
• 準備状況の評価結果そのものが必要です。 このサーバーは結果を認証しますが、結果を生成するものではありません。まず iso20022-readiness-suite-mcp を実行してスコアを算出し、修正し、シミュレーションしてから、その出力をここに取り込んでください。
• 公開の信頼ルートに対する、鍵なし／PKI 署名が必要です。 シールは改ざん検知用ダイジェストであり、署名ではありません（シールと署名の違いを参照）。オペレーターが提供する鍵を使った Ed25519 署名は v0.0.2 で提供されます（エビデンスパックへの署名を参照）が、鍵なし（sigstore）／信頼ルートによる検証を行う PKI 署名は、引き続きロードマップに記載されています。
• 依存関係ゼロのネットワークサービスが必要です。 デフォルトのトランスポートはstdioです。オペレーターごとに 1 つのプロセスをクライアントが起動し、ネットワークへの公開面はありません。共有のマルチテナント環境向けに、認証付き HTTP トランスポート（OAuth 2.1／RFC 9728）が v0.0.2 で提供されます（HTTP トランスポートと認証を参照）が、追加の依存関係が必要で、明示的に有効化する必要があります。
• ストリーミング応答が必要です。 ツール呼び出しが返すのはストリームではなく、値全体です。

開発

iso20022-evidence-pack-mcp は Poetry と mise を使用します。

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

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
make examples     # run every examples/*.py end to end

セキュリティ

iso20022-evidence-pack-mcp はエラーをデータとして返します。各ツールは、文書化された検証エラーと値エラーをすべて捕捉し、{"error": ...} のエンベロープを返します。生の例外が MCP クライアントに伝播することはありません。デフォルトの stdio トランスポートでは、サーバーにネットワークへの公開面はなく、サブプロセスを起動せず、XML も解析しません。攻撃者が到達できる領域は、標準ライブラリで解析し、pydantic モデルに照らして検証する JSON のみです。オプションの HTTP トランスポートはデフォルトで無効です。有効にする場合は、OAuth 2.1（RFC 9728）または静的な開発モードのベアラートークンがないと起動しません（HTTP トランスポートと認証を参照）。パックのシールは改ざん検知用ダイジェストであり、署名ではありません。Ed25519 署名（sign_pack）を追加すると、さらに真正性を確保できます（シールと署名の違いを参照）。報告の実務、サポート対象バージョン、シールの脅威モデルに関する注記、およびサプライチェーン対策の全容（SLSA L3 の来歴情報、PEP 740 の証明、SBOM、NIST SP 800-218 SSDF の実践項目との対応付け）は、SECURITY.md に記載されています。脆弱性の報告には、公開 issue ではなく GitHub の非公開脆弱性報告機能を使用してください。

ドキュメント

• README.md — このファイル
• CHANGELOG.md — リリースノート
• SECURITY.md — 脆弱性の開示 + サポート対象バージョン + シールの脅威モデル
• SUPPORT.md — サポートを受ける方法
• ROADMAP.md — 今後の予定（鍵なし／PKI 署名、長期保存、プレミアム利用権）
• MAINTAINERS.md — マージできる担当者
• ARCHITECTURE.md — モジュール構成、トランスポート、拡張ポイント
• RELEASING.md — リリースの基準とリリース方法
• docs/adr/ — アーキテクチャ決定記録
• docs/quickstart.md — インストールから最初の会話まで 10 分
• docs/evidence-packs.md — パックのスキーマ、SHA-256 シーリングモデル、Ed25519 署名、準備状況からエビデンスへのパイプライン
• docs/transport.md — オプションの HTTP トランスポートと OAuth 2.1（RFC 9728）認証
• glama.json — Glama ディレクトリのマニフェスト

MCP Registry

mcp-name: io.github.sebastienrousseau/iso20022-evidence-pack-mcp

ライセンス

Apache License, Version 2.0の下でライセンスされています。採用のために提出された貢献は、追加条件なしに、上記と同じライセンスの下でライセンスされるものとします。

貢献

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

謝辞

ISO 20022 MCP Suite のサーバーおよび Model Context Protocol Python SDK とともに構築されました。