iso20022-readiness-suite-mcp

# iso20022-readiness-suite-mcp: The ISO 20022 Readiness & Testing Gateway

[![PyPI Version][pypi-badge]][07]
[![Python Versions][python-versions-badge]][07]
[![License][license-badge]][01]
[![Tests][tests-badge]][tests-url]
[![Quality][quality-badge]][quality-url]
[![OpenSSF Scorecard][scorecard-badge]][scorecard-url]
[![Documentation][docs-badge]][docs-url]

**A high-level orchestration [Model Context Protocol][mcp] server — the
White-Label ISO 20022 Readiness & Testing Gateway.** It is an MCP *server* to
your agent and an MCP *client* to the foundational servers of the
[ISO 20022 MCP Suite](#the-iso-20022-mcp-suite). It composes them into
readiness scoring, automated remediation, clearing-profile linting (CBPR+,
SEPA_Instant, FedNow, Generic), and bank-response simulation — one gateway an
agent can drive to answer "is this payment ready, and if not, fix it".

> **The November 2026 milestones.** As the major schemes (CBPR+, HVPS+, T2,
> FedNow) tighten their ISO 20022 requirements — structured postal addresses
> chief among them — a payment that was fine yesterday can be rejected
> tomorrow. `iso20022-readiness-suite-mcp` puts a single readiness gateway in
> front of your agent: `run_readiness_check` scores a payload against a
> clearing profile, `remediate_payload` proposes the compliant form, and
> `simulate_bank_response` mocks how a bank would answer. **v0.0.2**, stdio
> (default) or streamable HTTP, 4 tools, Python 3.10+.

## Contents

- [Overview](#overview)
- [The ISO 20022 MCP Suite](#the-iso-20022-mcp-suite)
- [Install](#install)
- [Quick Start](#quick-start)
- [Tools](#tools)
- [HTTP transport & authentication](#http-transport--authentication)
- [Orchestration & the meta-client pattern](#orchestration--the-meta-client-pattern)
- [Open-core vs premium](#open-core-vs-premium)
- [When not to use iso20022-readiness-suite-mcp](#when-not-to-use-iso20022-readiness-suite-mcp)
- [Development](#development)
- [Security](#security)
- [Documentation](#documentation)
- [License](#license)
- [Contributing](#contributing)
- [Acknowledgements](#acknowledgements)

## Overview

The [Model Context Protocol][mcp] (MCP) is an open standard that lets AI agents
and assistants discover and call external tools in a uniform way.
**iso20022-readiness-suite-mcp** is the orchestration front door of the ISO
20022 MCP Suite: it presents four high-level tools to the outer agent, and
underneath it acts as an MCP *client* that spawns the foundational suite
servers over stdio and composes their results — the **meta-client pattern**.

The headline capability is the one-shot readiness workflow: hand it a raw ISO
20022 payload and a target clearing profile, and it detects the message type,
routes it to the correct base validator, lints it against the profile's
market-practice rules, and returns a single readiness score with the
findings — then, on request, remediates the payload and simulates how a bank
would respond.

Every tool returns typed, JSON-serialisable data; on any failure — a bad
input, an unparseable payload, a missing or erroring sub-server — it returns
an `{"error": ...}` payload rather than raising into the client transport.

- **Website:** <https://sebastienrousseau.github.io/iso20022-readiness-suite-mcp/>
- **Source code:** <https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp>
- **Bug reports:** <https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp/issues>

```mermaid
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"]
```

The gateway *is a server* to the client above it and *a client* to the six
foundational servers below it. `list_profiles` and `simulate_bank_response`
are fully local and need none of them; `run_readiness_check` and
`remediate_payload` reach the sub-servers and therefore require them to be
installed and resolvable (see
[Orchestration & the meta-client pattern](#orchestration--the-meta-client-pattern)).

## The ISO 20022 MCP Suite

`iso20022-readiness-suite-mcp` is the **orchestration gateway** that sits on
top of a set of coordinated, vendor-neutral MCP servers for the ISO 20022
migration. Dependency ranges are kept aligned across the suite, so the servers
co-install cleanly in a single Python environment: install the foundational
servers you need, then let this gateway compose them.

| Server | Scope | Install |
|------|------|------|
| [`iso20022-mcp`](https://github.com/sebastienrousseau/iso20022-mcp) | Unified gateway meta-tools (`search` / `describe` / `validate` / `generate` / `parse`) across the ISO 20022 message catalogue | `pip install iso20022-mcp` |
| [`camt053-mcp`](https://github.com/sebastienrousseau/camt053-mcp) | ISO 20022 camt.05x bank statements: parse, validate, filter, reverse; MT94x migration; CBPR+ readiness | `pip install camt053-mcp` |
| [`pain001-mcp`](https://github.com/sebastienrousseau/pain001-mcp) | Generate & validate ISO 20022 pain.001 payment-initiation files (v03–v12, pain.008, SEPA) with rulebook checks | `pip install pain001-mcp` |
| [`reconcile-mcp`](https://github.com/sebastienrousseau/reconcile-mcp) | Reconcile ISO 20022 payments and statements; match initiations to their bank-side outcomes | `pip install reconcile-mcp` |
| [`bankstatementparser-mcp`](https://github.com/sebastienrousseau/bankstatementparser-mcp) | Parse bank statements (MT940/MT942 and camt) into structured, agent-friendly data | `pip install bankstatementparser-mcp` |
| [`structured-address-fix-mcp`](https://github.com/sebastienrousseau/structured-address-fix-mcp) | ISO 20022 postal-address classification, assessment, and remediation for the Nov 2026 structured-address cliff | `pip install structured-address-fix-mcp` |

Where each foundational server does one job well, **this gateway** composes
them: it detects and routes a payload to the right validator, lints it against
a clearing profile, scores its readiness, remediates it, and simulates the
bank's answer — all behind four agent tools.

## Install

**iso20022-readiness-suite-mcp** runs on macOS, Linux, and Windows and
requires **Python 3.10+** and **pip**. It pulls in the MCP SDK, `pydantic`,
and `defusedxml` automatically.

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

To exercise `run_readiness_check` and `remediate_payload` end to end, also
make the foundational servers resolvable — the gateway launches them with
`uvx`, so installing [`uv`](https://docs.astral.sh/uv/) is enough for a
zero-install spawn:

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

<details>
<summary>Using an isolated virtual environment (recommended)</summary>

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

## Quick Start

For the 10-minute install → MCP client config → first conversation tutorial,
see [`docs/quickstart.md`](docs/quickstart.md).

Launch the server over stdio (the FastMCP default transport):

```sh
iso20022-readiness-suite-mcp
```

Register it with any MCP client (e.g. Claude Desktop) by adding it to the
client's configuration:

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

The command speaks MCP on stdin/stdout — it is meant to be launched by an MCP
client, not used interactively. The agent can then call the tools below.

You can also invoke the tools in-process — without a transport — straight
through the FastMCP instance. This mirrors what an agent receives over stdio.
The two local tools (`list_profiles`, `simulate_bank_response`) need no
sub-servers:

```python
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())
```

## Tools

All tools return JSON-serialisable data; on a domain, validation, or
sub-server error they return an `{"error": ...}` payload rather than raising.

- `list_profiles` — List the available clearing profiles (CBPR+, SEPA_Instant, FedNow, Generic) with their market practice and rules. Fully local; no sub-servers needed.
- `run_readiness_check` — Detect, structurally validate, profile-lint, and score an ISO 20022 payload's readiness against a target clearing profile. Reaches the foundational sub-servers.
- `remediate_payload` — Apply automated remediation (e.g. the Nov 2026 structured-address fixes) driven by a clearing profile, delegating to `structured-address-fix-mcp`. Reaches the foundational sub-servers.
- `simulate_bank_response` — Emit a pacs.002 status report mocking a bank's ACCP / RJCT / PDNG response to an in