structured-address-fix-mcp

structured-address-fix-mcp：ISO 20022 郵便住所向け MCP サーバー

Model Context Protocol サーバーです。structured-address-fix ISO 20022 郵便住所ライブラリを AI エージェントやアシスタント向けのツールとして公開し、住所の形式を分類し、スキームのポリシーに照らして評価し、必要に応じて住所（または pacs.008／pain.001 メッセージ全体）を、2026年11月の移行要件に適合する構造化形式に修正します。お好みの MCP クライアントから利用できます。

2026年11月14日の期限。 この日、CBPR+、HVPS+、T2、CHAPS、Fedwireでは、完全に非構造化された郵便住所の受け付けが停止されます。債務者または債権者の住所が自由形式のテキストの場合、その支払いは拒否されます。structured-address-fix-mcp は、準備状況の確認と修正をエージェントの前に用意します。assess_message は問題のある当事者を示し、remediate_message は準拠した形式を提案し、get_cutover_date は拘束力のある日付を返します。v0.0.6、stdio、ストリーム可能な HTTP、SSE トランスポート、13 個のツール、Python 3.12 以降に対応しています。

目次

• 概要
• ISO 20022 MCP スイート
• インストール
• クイックスタート
• トランスポート — stdio、ストリーム可能な HTTP（2026-07-28 および 2025-11-25）、SSE を単一のコマンドラインから利用
• ツール
• ツールの使用方法
• 関連する MCP サーバー
• structured-address-fix-mcp を使用しない場合
• 開発
• セキュリティ
• ドキュメント
• ライセンス
• 貢献
• 謝辞

概要

Model Context Protocol（MCP）は、AI エージェントやアシスタントが外部ツールを共通の方法で検出し、呼び出せるようにするオープン標準です。 structured-address-fix-mcp は、structured-address-fix ライブラリをエージェント向けの第一級ツール群に変換する MCP サーバーです。アシスタントは、郵便住所、またはISO 20022 pacs.008／pain.001 メッセージ内のすべての住所付き当事者の情報を読み取り、会話から直接、2026年11月14日に必須となる構造化住所ルールに適合させることができます。

主な機能は、ワンショットで完了する修正ワークフローです。メッセージを評価し、期限到来時に拒否される住所を持つ当事者を特定して、変更内容の説明と信頼度スコアを付けた準拠形式を出力します。

すべてのツールは、CLI でも使用される単一の共有ファサード structured_address_fix.services を薄くラップした、型付きのラッパーです。そのため、すべてのインターフェースで同じ動作をします。ツールは JSON にシリアライズ可能なデータを返し、エラー時には例外を発生させず、{"error": ...} ペイロードを返します。

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

flowchart LR
    A["MCP client<br/>(Claude Desktop, IDE, agent)"] -->|stdio, streamable HTTP or SSE| B["structured-address-fix-mcp"]
    B -->|delegates to| C["structured_address_fix.services"]
    C -->|classify + assess + remediate| D["ISO 20022 postal addresses<br/>(pacs.008 / pain.001)"]

ISO 20022 MCP スイート

structured-address-fix-mcp は、ISO 20022 移行に対応する、連携可能でベンダー中立な MCP サーバー群における郵便住所のスペシャリストです。 依存関係のバージョン範囲はスイート全体で揃えているため、単一の Python 環境に各サーバーを問題なく共存させられます。まずは 1 つから始め、ワークフローの拡大に合わせて追加してください。

スイートには、ゲートウェイ iso20022-mcp （メッセージカタログ全体を対象とする統合 search／describe／validate／generate／parse メタツール）と、 acmt001-mcp（口座 管理）も含まれます。pacs008-mcp がメッセージの住所問題を リンティング するのに対し、 structured-address-fix-mcp はスキームごとのポリシーに基づいて住所そのものを 分類、評価、修正 するスペシャリストです。

インストール

structured-address-fix-mcp は macOS、Linux、Windows で動作し、 Python 3.12+ と pip が必要です。コアの structured-address-fix ライブラリと MCP SDK も自動的にインストールされます。

python -m pip install structured-address-fix-mcp

python -m venv venv
source venv/bin/activate        # macOS/Linux
venv\Scripts\activate           # Windows
python -m pip install -U structured-address-fix-mcp

クイックスタート

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

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

structured-address-fix-mcp

クライアントの設定に追加すれば、任意の MCP クライアント（Claude Desktop など）に登録できます：

{
  "mcpServers": {
    "structured-address-fix": { "command": "structured-address-fix-mcp" }
  }
}

デフォルトでは、このコマンドは stdin/stdout を介して MCP と通信します。対話形式で使うのではなく、MCP クライアントから起動することを想定しています。共有デプロイメントまたは HTTP クライアントについては、トランスポートをご覧ください。エージェントは以下のツールを呼び出して、必要に応じて郵便住所を評価、修正できます。

トランスポート

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

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

{
  "mcpServers": {
    "structured-address-fix": { "url": "http://127.0.0.1:8000/mcp" }
  }
}

ツール

すべてのツールは共通の structured_address_fix.services レイヤーに処理を委譲するため、 CLI と同じ動作をします。ツールは JSON としてシリアライズ可能なデータを返します。ドメイン、検証、または値のエラーが発生した場合は、{"error": ...} ペイロードを返します。

• list_policies — 利用可能なすべての住所ポリシー（ルールブック）と、そのティア（例：cbpr-2026、sepa、hvps-plus、generic-structured）を一覧表示します
• classify_address — 郵便住所を構造化、ハイブリッド、または非構造化に分類します（簡易的な形式チェック）
• assess_address — 単一の住所をポリシーに照らして評価し、検出結果を返します
• assess_message — pacs.008 / pain.001 メッセージ内の住所があるすべての関係者をポリシーに照らして評価します
• remediate_address — 住所を準拠形式にするための修正案を提示し、修正前後の内容と信頼度スコア付きのパッチ操作を返します
• remediate_message — メッセージ内の住所があるすべての関係者を評価して修正します。必要に応じて操作を適用し、パッチ適用後の XML を返します
• preview_patch — メッセージに対して修正時に適用されるパッチ操作を返します（ドライラン）
• explain_finding — 検出コード（例：SAF001）の意味と解決方法を説明します
• get_cutover_date — 2026 年 11 月の拘束力のある構造化住所への切り替え日と、それを定めるスキームを返します
• normalize_country_code — 国名または国コードを ISO 3166-1 alpha-2 コードに変換します。英語名、現地の自称（Deutschland、España、Nippon）、一般的な別称（UK、USA、Holland、UAE）を受け付けます
• split_street_and_building — 通りの行を通り名、建物、建物内の区分に分割します。先頭に番号を置く形式（10 Downing Street）と、ヨーロッパ大陸の多くで使われる末尾に番号を置く形式の両方に対応します
• validate_postal_policy — 住所の post_code が国の形式ポリシーに適合するか検証します（米国の ZIP / ZIP+4、英国の英数字形式など）
• parse_address_libpostal — 自由形式の住所を ISO 20022 の郵便住所フィールドに解析します。オプションの postal extra がインストールされている場合は libpostal の統計的パーサーを使用し、それ以外の場合は決定論的なフォールバックを使用します

評価／修正ツール間で共通するオプションパラメーター：policy_id （デフォルトは cbpr-2026）、as_of（切り替えに関する文言を決定する YYYY-MM-DD 形式の日付。デフォルトは今日）、 および country_hint（住所に国情報がない場合に想定する ISO 3166-1 alpha-2 コード）。

ツールの使用

トランスポートを介さず、FastMCP インスタンスを通じてプロセス内で直接ツールを呼び出せます。 これは、エージェントが stdio 経由で受け取るものを再現します。このスニペットの実行可能なバージョンは examples/mcp_tools.py にあります。

import asyncio

from structured_address_fix_mcp import server

# A fully unstructured address: two free-text lines, no structured fields.
# At the 14 Nov 2026 cliff this form is rejected across the major schemes.
unstructured = {
    "address_lines": ["10 Downing St", "London SW1A 2AA"],
    "country": "GB",
}


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

    # When does the cliff bite?
    print(await call("get_cutover_date", {}))
    # -> {"date": "2026-11-14", "scheme": "SWIFT CBPR+ UG2026"}

    # What shape is this address in right now?
    print(await call("classify_address", {"address": unstructured}))
    # -> {"classification": "unstructured"}

    # Propose the compliant form, with each change explained.
    print(await call("remediate_address",
                     {"address": unstructured, "policy_id": "cbpr-2026"}))
    # -> {"policy_id": "cbpr-2026", "findings": [...], "suggestions": [...],
    #     "is_compliant_before": false, "is_compliant_after": true, ...}


asyncio.run(main())

直接実行します。

python examples/mcp_tools.py

関連する MCP サーバー

ISO 20022 MCP Suite の一部です。銀行および金融サービスの AI エージェント向けの、Apache-2.0 ライセンスのオープンソース MCP サーバーです。

structured-address-fix-mcp を使用しないケース

• MCP クライアントを使用していない場合。 このサーバーは、MCP 対応ホスト（Claude Desktop、IDE プラグイン、エージェントフレームワーク）と組み合わせて初めて役立ちます。スクリプト実行や CI では、structured-address-fix CLI を使えば、stdio プロトコルのオーバーヘッドなしで同じ処理を行えます。
• 認証付きのマルチテナントサービスが必要な場合。 HTTP トランスポート（トランスポート）には独自の認証機能がなく、デフォルトでループバックにバインドされます。信頼できるゲートウェイの背後に配置してください。OAuth 2.1 リソースサーバー認証とテナントのスコープ設定はロードマップに記載されており、このリリースには含まれません。
• ストリーミングレスポンスが必要な場合。 ツール呼び出しはストリームではなく、値全体を返します。大きなメッセージも複数のレスポンスに分割せず、1 回の呼び出しで評価し、修正します。
• pacs.008 / pain.001 メッセージを作成する必要がある場合。 これは対象範囲外です。このサーバーはメッセージ内の住所を修正します。メッセージ自体の生成と検証には、pacs008-mcp または pain001-mcp を使用してください。

開発

structured-address-fix-mcp は Poetry と mise を使用します。

git clone https://github.com/sebastienrousseau/structured-address-fix-mcp.git && cd structured-address-fix-mcp
mise install
poetry install
poetry shell

注記： このサーバーはコアの structured-address-fix ライブラリに依存しています。 PyPI に公開されるまでは、開発用依存関係グループで、隣接するチェックアウト（../structured-address-fix）からインストールします。詳しくは CONTRIBUTING.md を参照してください。

Makefile が CI と足並みをそろえた品質ゲートを実行します。

make check        # all gates (REQUIRED before commit): lint + type-check + test + examples
make test         # pytest
make lint         # ruff + black
make type-check   # mypy --strict
make security     # bandit

セキュリティ

structured-address-fix-mcp は薄いラッパーであり、すべてのツールは structured_address_fix.services に処理を委譲します。XML 解析の多層防御（defusedxml）はここに実装されています。ツールは、文書化されたドメインエラー、検証エラー、値エラーを捕捉し、スイートの規約に従って {"error": ...} エンベロープを返します。MCP クライアントに未加工の例外を伝播させることはありません。報告手順、サポート対象バージョン、サプライチェーン対策の全容（SLSA L3 の来歴、PEP 740 の証明書、SBOM、NIST SP 800-218 SSDF のプラクティスマッピング）は SECURITY.md に記載されています。脆弱性は公開 Issue ではなく、GitHub Private Vulnerability Reporting から報告してください。

ドキュメント

• README.md — このファイル
• CHANGELOG.md — リリースノート
• SECURITY.md — 脆弱性の開示とサポート対象バージョン
• SUPPORT.md — サポートを受ける方法
• ROADMAP.md — 今後の予定（HTTP トランスポートでの OAuth、可観測性、利用資格の制御）
• MAINTAINERS.md — マージ権限を持つ人
• docs/quickstart.md — 10 分でインストールして最初の会話を始める
• docs/deployment-cookbook.md — クライアント設定（Claude Desktop、Cursor、コンテナー）と HTTP トランスポート
• docs/adr/ — アーキテクチャ決定記録
• ARCHITECTURE.md — コードベースの構成
• RELEASING.md — リリースの作成方法
• examples/ — 実行可能なスクリプト
• glama.json — Glama ディレクトリのマニフェスト

MCP レジストリ

mcp-name: io.github.sebastienrousseau/structured-address-fix-mcp

ライセンス

Apache License, Version 2.0 に基づいてライセンスされています。採用のために提出されたすべてのコントリビューションも、追加条件なしで上記と同じライセンスの対象となります。

コントリビューション

コントリビューションを歓迎します。コントリビューションの手順をご覧ください。コントリビューターの皆さんに感謝します。

謝辞

structured-address-fix ISO 20022 郵便住所ライブラリと、Model Context Protocol Python SDK を基盤に構築されています。