{
  "markdown": "# iso20022-readiness-suite-mcp: The ISO 20022 Readiness & Testing Gateway\n\n[![PyPI Version][pypi-badge]][07]\n[![Python Versions][python-versions-badge]][07]\n[![License][license-badge]][01]\n[![Tests][tests-badge]][tests-url]\n[![Quality][quality-badge]][quality-url]\n[![OpenSSF Scorecard][scorecard-badge]][scorecard-url]\n[![Documentation][docs-badge]][docs-url]\n\n**A high-level orchestration [Model Context Protocol][mcp] server — the\nWhite-Label ISO 20022 Readiness & Testing Gateway.** It is an MCP *server* to\nyour agent and an MCP *client* to the foundational servers of the\n[ISO 20022 MCP Suite](#the-iso-20022-mcp-suite). It composes them into\nreadiness scoring, automated remediation, clearing-profile linting (CBPR+,\nSEPA_Instant, FedNow, Generic), and bank-response simulation — one gateway an\nagent can drive to answer \"is this payment ready, and if not, fix it\".\n\n> **The November 2026 milestones.** As the major schemes (CBPR+, HVPS+, T2,\n> FedNow) tighten their ISO 20022 requirements — structured postal addresses\n> chief among them — a payment that was fine yesterday can be rejected\n> tomorrow. `iso20022-readiness-suite-mcp` puts a single readiness gateway in\n> front of your agent: `run_readiness_check` scores a payload against a\n> clearing profile, `remediate_payload` proposes the compliant form, and\n> `simulate_bank_response` mocks how a bank would answer. **v0.0.2**, stdio\n> (default) or streamable HTTP, 4 tools, Python 3.10+.\n\n## Contents\n\n- [Overview](#overview)\n- [The ISO 20022 MCP Suite](#the-iso-20022-mcp-suite)\n- [Install](#install)\n- [Quick Start](#quick-start)\n- [Tools](#tools)\n- [HTTP transport & authentication](#http-transport--authentication)\n- [Orchestration & the meta-client pattern](#orchestration--the-meta-client-pattern)\n- [Open-core vs premium](#open-core-vs-premium)\n- [When not to use iso20022-readiness-suite-mcp](#when-not-to-use-iso20022-readiness-suite-mcp)\n- [Development](#development)\n- [Security](#security)\n- [Documentation](#documentation)\n- [License](#license)\n- [Contributing](#contributing)\n- [Acknowledgements](#acknowledgements)\n\n## Overview\n\nThe [Model Context Protocol][mcp] (MCP) is an open standard that lets AI agents\nand assistants discover and call external tools in a uniform way.\n**iso20022-readiness-suite-mcp** is the orchestration front door of the ISO\n20022 MCP Suite: it presents four high-level tools to the outer agent, and\nunderneath it acts as an MCP *client* that spawns the foundational suite\nservers over stdio and composes their results — the **meta-client pattern**.\n\nThe headline capability is the one-shot readiness workflow: hand it a raw ISO\n20022 payload and a target clearing profile, and it detects the message type,\nroutes it to the correct base validator, lints it against the profile's\nmarket-practice rules, and returns a single readiness score with the\nfindings — then, on request, remediates the payload and simulates how a bank\nwould respond.\n\nEvery tool returns typed, JSON-serialisable data; on any failure — a bad\ninput, an unparseable payload, a missing or erroring sub-server — it returns\nan `{\"error\": ...}` payload rather than raising into the client transport.\n\n- **Website:** <https://sebastienrousseau.github.io/iso20022-readiness-suite-mcp/>\n- **Source code:** <https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp>\n- **Bug reports:** <https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp/issues>\n\n```mermaid\nflowchart TD\n    A[\"MCP client<br/>(Claude Desktop, IDE, agent)\"] -->|stdio| B[\"iso20022-readiness-suite-mcp<br/>(orchestration gateway)\"]\n    B -->|spawns over stdio via uvx| C[\"iso20022-mcp\"]\n    B -->|spawns over stdio via uvx| D[\"camt053-mcp\"]\n    B -->|spawns over stdio via uvx| E[\"pain001-mcp\"]\n    B -->|spawns over stdio via uvx| F[\"reconcile-mcp\"]\n    B -->|spawns over stdio via uvx| G[\"bankstatementparser-mcp\"]\n    B -->|spawns over stdio via uvx| H[\"structured-address-fix-mcp\"]\n```\n\nThe gateway *is a server* to the client above it and *a client* to the six\nfoundational servers below it. `list_profiles` and `simulate_bank_response`\nare fully local and need none of them; `run_readiness_check` and\n`remediate_payload` reach the sub-servers and therefore require them to be\ninstalled and resolvable (see\n[Orchestration & the meta-client pattern](#orchestration--the-meta-client-pattern)).\n\n## The ISO 20022 MCP Suite\n\n`iso20022-readiness-suite-mcp` is the **orchestration gateway** that sits on\ntop of a set of coordinated, vendor-neutral MCP servers for the ISO 20022\nmigration. Dependency ranges are kept aligned across the suite, so the servers\nco-install cleanly in a single Python environment: install the foundational\nservers you need, then let this gateway compose them.\n\n| Server | Scope | Install |\n|------|------|------|\n| [`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` |\n| [`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` |\n| [`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` |\n| [`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` |\n| [`bankstatementparser-mcp`](https://github.com/sebastienrousseau/bankstatementparser-mcp) | Parse bank statements (MT940/MT942 and camt) into structured, agent-friendly data | `pip install bankstatementparser-mcp` |\n| [`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` |\n\nWhere each foundational server does one job well, **this gateway** composes\nthem: it detects and routes a payload to the right validator, lints it against\na clearing profile, scores its readiness, remediates it, and simulates the\nbank's answer — all behind four agent tools.\n\n## Install\n\n**iso20022-readiness-suite-mcp** runs on macOS, Linux, and Windows and\nrequires **Python 3.10+** and **pip**. It pulls in the MCP SDK, `pydantic`,\nand `defusedxml` automatically.\n\n```sh\npython -m pip install iso20022-readiness-suite-mcp\n```\n\nTo exercise `run_readiness_check` and `remediate_payload` end to end, also\nmake the foundational servers resolvable — the gateway launches them with\n`uvx`, so installing [`uv`](https://docs.astral.sh/uv/) is enough for a\nzero-install spawn:\n\n```sh\npython -m pip install uv        # provides the `uvx` launcher\n```\n\n<details>\n<summary>Using an isolated virtual environment (recommended)</summary>\n\n```sh\npython -m venv venv\nsource venv/bin/activate        # macOS/Linux\nvenv\\Scripts\\activate           # Windows\npython -m pip install -U iso20022-readiness-suite-mcp\n```\n</details>\n\n## Quick Start\n\nFor the 10-minute install → MCP client config → first conversation tutorial,\nsee [`docs/quickstart.md`](docs/quickstart.md).\n\nLaunch the server over stdio (the FastMCP default transport):\n\n```sh\niso20022-readiness-suite-mcp\n```\n\nRegister it with any MCP client (e.g. Claude Desktop) by adding it to the\nclient's configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"iso20022-readiness-suite\": { \"command\": \"iso20022-readiness-suite-mcp\" }\n  }\n}\n```\n\nThe command speaks MCP on stdin/stdout — it is meant to be launched by an MCP\nclient, not used interactively. The agent can then call the tools below.\n\nYou can also invoke the tools in-process — without a transport — straight\nthrough the FastMCP instance. This mirrors what an agent receives over stdio.\nThe two local tools (`list_profiles`, `simulate_bank_response`) need no\nsub-servers:\n\n```python\nimport asyncio\n\nfrom iso20022_readiness_suite_mcp import server\n\n\nasync def main() -> None:\n    async def call(name, args):\n        result = await server.server.call_tool(name, args)\n        # mcp 2.x returns a CallToolResult (read .content); 1.x\n        # returns the content list, or a (content, meta) tuple.\n        content = getattr(result, \"content\", None)\n        if content is None:\n            content = result[0] if isinstance(result, tuple) else result\n        return content[0].text if content else \"\"\n\n    # Which clearing profiles can I target? (fully local)\n    print(await call(\"list_profiles\", {}))\n    # -> [{\"profile_id\": \"CBPR+\", ...}, {\"profile_id\": \"SEPA_Instant\", ...}, ...]\n\n    # Mock how a bank would answer an initiation. (fully local)\n    pacs008 = '<Document><CdtTrfTxInf><Amt Ccy=\"EUR\">10</Amt></CdtTrfTxInf></Document>'\n    print(await call(\"simulate_bank_response\",\n                     {\"inbound_payload\": pacs008, \"desired_behavior\": \"ACCP\"}))\n    # -> {\"status\": \"ACCP\", \"generated_response_type\": \"pacs.002.001.10\", ...}\n\n\nasyncio.run(main())\n```\n\n## Tools\n\nAll tools return JSON-serialisable data; on a domain, validation, or\nsub-server error they return an `{\"error\": ...}` payload rather than raising.\n\n- `list_profiles` — List the available clearing profiles (CBPR+, SEPA_Instant, FedNow, Generic) with their market practice and rules. Fully local; no sub-servers needed.\n- `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.\n- `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.\n- `simulate_bank_response` — Emit a pacs.002 status report mocking a bank's ACCP / RJCT / PDNG response to an inbound initiation (a reason code is required for RJCT). Fully local; no sub-servers needed.\n\n> **Reachability.** `run_readiness_check` and `remediate_payload` spawn the\n> underlying servers over stdio via `uvx`, so those servers must be\n> installed / resolvable for the two tools to succeed. `list_profiles` and\n> `simulate_bank_response` compute purely locally and always work standalone.\n\n## HTTP transport & authentication\n\nBy default the gateway speaks **stdio** — launched by a local MCP client, one\nprocess per operator, with no network surface and **no authentication needed**:\n\n```sh\niso20022-readiness-suite-mcp                 # stdio (default)\n```\n\nFor shared, multi-tenant deployments it also offers an **optional\nstreamable-HTTP transport**. The default `--bind` is loopback-only\n(`127.0.0.1:8080`); expose it explicitly with `--bind=0.0.0.0:8080`:\n\n```sh\niso20022-readiness-suite-mcp --transport=http --bind=0.0.0.0:8080\n```\n\nThe HTTP transport **requires authentication** — starting it with none\nconfigured is refused. Two modes apply, strongest first.\n\n**OAuth 2.1 resource server (RFC 9728) — production.** Set the\n`ISO20022_READINESS_OAUTH_*` environment variables and the server validates\n`Authorization: Bearer <jwt>` against your authorization server's JWKS:\n\n| Variable | Required | Meaning |\n|---|---|---|\n| `ISO20022_READINESS_OAUTH_ISSUER` | yes | Authorization server issuer; the JWT `iss` must match it exactly. |\n| `ISO20022_READINESS_OAUTH_AUDIENCE` | yes | This server's canonical resource URI (RFC 8707); the JWT `aud` must contain it. |\n| `ISO20022_READINESS_OAUTH_JWKS_URL` | no | JWKS document URL (default `<issuer>/.well-known/jwks.json`). |\n| `ISO20022_READINESS_OAUTH_SCOPES` | no | Space-separated scopes every token must carry. |\n\nJWTs are checked for signature (JWKS, with key rotation on an unknown `kid`),\n`iss` / `aud` / `exp` / `nbf`, and the required scopes. The RFC 9728\nprotected-resource metadata is served unauthenticated at\n`/.well-known/oauth-protected-resource`. Rejections return `401` (`403` for\n`insufficient_scope`) with a `WWW-Authenticate` challenge pointing at that\nmetadata.\n\n**Static bearer token — dev mode only.** When no OAuth variables are set, a\nsingle shared secret in `ISO20022_READINESS_TOKEN` is accepted instead\n(compared with `hmac.compare_digest`). This is explicitly dev-mode — one shared\nsecret, no expiry, no scopes — and is ignored when OAuth is also configured:\n\n```sh\nISO20022_READINESS_TOKEN=s3cret \\\n  iso20022-readiness-suite-mcp --transport=http --bind=127.0.0.1:8080\n```\n\nHTTP callers may send an optional `X-MCP-Tenant` header, forwarded into a\nper-request tenant context; the authenticated token's scopes are exposed to\ntools too, so tool code can scope behaviour without branching on the transport.\nSee [`docs/transport.md`](docs/transport.md) for the full setup.\n\n## Orchestration & the meta-client pattern\n\nThe gateway implements the \"server that is also a client\" half of the\norchestration: an orchestrator depends only on a `SubServerInvoker` protocol,\nand the production `StdioSubServerInvoker` spins up an underlying server over\nstdio, calls one tool, and tears the session down. Every failure — a missing\nserver, a spawn error, a tool error — is returned as data (a typed\n`ToolOutcome`), never raised across the caller boundary.\n\nBy default each foundational server is launched with a zero-install `uvx`\ncommand:\n\n| Sub-server | Default launch command |\n|---|---|\n| `iso20022-mcp` | `uvx iso20022-mcp` |\n| `camt053-mcp` | `uvx camt053-mcp` |\n| `pain001-mcp` | `uvx pain001-mcp` |\n| `reconcile-mcp` | `uvx reconcile-mcp` |\n| `bankstatementparser-mcp` | `uvx bankstatementparser-mcp` |\n| `structured-address-fix-mcp` | `uvx structured-address-fix-mcp` |\n\nThe command map is overridable per deployment, so you can point the gateway at\nlocally installed console scripts, a pinned virtualenv, or a remote-launched\nprocess instead of `uvx`. See [`docs/orchestration.md`](docs/orchestration.md)\nfor the full pattern and how to point it at local or remote sub-servers.\n\n## Open-core vs premium\n\nThe gateway is **open core**: the baseline validation workflows and the\ngeneric scheme profiles are open source and always available. Higher-tier,\ninstitution-specific capabilities are commercial add-ons that plug into the\nsame profile-engine and orchestration seams (the profile engine already\nexposes a `register()` hook for runtime-loaded rule packs).\n\n| Capability | Tier |\n|---|---|\n| Basic Validation Workflows | **Open Source** |\n| Generic Scheme Profiles (CBPR+, SEPA_Instant, FedNow, Generic) | **Open Source** |\n| Advanced Proprietary Rule Packs | **Paid** |\n| White-Label Portals | **Paid** |\n| Stateful Persistence Logs | **Paid** |\n\nThe paid tiers are on the [roadmap](ROADMAP.md) (premium rule-pack entitlement\ngating, plus the sister `iso20022-bank-profile-mcp` and\n`iso20022-evidence-pack-mcp` servers), not in this release. Nothing in the\nopen-source tier is time-limited or feature-gated.\n\n## When not to use iso20022-readiness-suite-mcp\n\n- **You have no MCP client.** This server only makes sense paired with an\n  MCP-aware host (Claude Desktop, the IDE plugins, an agent framework).\n- **You only need one message operation.** If you just want to validate a\n  pain.001 or parse a camt.053, call the relevant foundational server\n  directly — the gateway's value is *composing* them.\n- **You need `run_readiness_check` / `remediate_payload` without the\n  sub-servers.** Those two tools require the foundational servers to be\n  resolvable (via `uvx` or an overridden command map). If you cannot install\n  them, you are limited to `list_profiles` and `simulate_bank_response`.\n- **You need a long-lived network service.** stdio (the default) is one\n  process per operator, launched by the client, with no network surface. For\n  shared, multi-tenant deployments use the optional streamable-HTTP transport\n  (`--transport=http`, with OAuth 2.1 or a dev-mode token) — see\n  [HTTP transport & authentication](#http-transport--authentication).\n- **You need streaming responses.** Tool calls return whole values, not\n  streams.\n\n## Development\n\n**iso20022-readiness-suite-mcp** uses [Poetry](https://python-poetry.org/) and\n[mise](https://mise.jdx.dev/).\n\n```bash\ngit clone https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp.git && cd iso20022-readiness-suite-mcp\nmise install\npoetry install\npoetry shell\n```\n\n> **Note:** the test suite injects a fake sub-server invoker, so you do **not**\n> need the foundational servers installed to run the tests — only to exercise\n> `run_readiness_check` / `remediate_payload` against real servers. See\n> [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\nA `Makefile` orchestrates the quality gates (kept in lockstep with CI):\n\n```bash\nmake check        # all gates (REQUIRED before commit): lint + type-check + test\nmake test         # pytest (100% line + branch coverage)\nmake lint         # ruff + black\nmake type-check   # mypy --strict\nmake security     # bandit\n```\n\n## Security\n\n`iso20022-readiness-suite-mcp` returns errors as data — every tool catches the\ndocumented domain, validation, and value errors (and every sub-server failure)\nand returns an `{\"error\": ...}` envelope; it never propagates raw exceptions\nto the MCP client. XML payloads reached through the clearing-profile engine\nare parsed with `defusedxml` only (no XXE / billion-laughs). Reporting\npractice, supported versions, the meta-client attack surface, and the full\nsupply-chain posture (SLSA L3 provenance, PEP 740 attestations, SBOMs, and the\nNIST SP 800-218 SSDF practice mapping) are documented in\n[`SECURITY.md`](SECURITY.md). Vulnerabilities go via GitHub Private\nVulnerability Reporting, not public issues.\n\n## Documentation\n\n- [`README.md`](README.md) — this file\n- [`CHANGELOG.md`](CHANGELOG.md) — release notes\n- [`SECURITY.md`](SECURITY.md) — disclosure + supported versions\n- [`SUPPORT.md`](SUPPORT.md) — how to get help\n- [`ROADMAP.md`](ROADMAP.md) — what's next (sister servers, premium rule-pack entitlement)\n- [`MAINTAINERS.md`](MAINTAINERS.md) — who can merge\n- [`docs/quickstart.md`](docs/quickstart.md) — 10-minute install → first conversation\n- [`docs/transport.md`](docs/transport.md) — the HTTP transport and OAuth 2.1 (RFC 9728) auth setup\n- [`docs/orchestration.md`](docs/orchestration.md) — the meta-client pattern and pointing the gateway at local/remote sub-servers\n- [`docs/profiles.md`](docs/profiles.md) — the clearing profiles and how premium rule packs plug in\n- [`glama.json`](glama.json) — Glama directory manifest\n\n---\n\n## MCP Registry\n\n`mcp-name: io.github.sebastienrousseau/iso20022-readiness-suite-mcp`\n\n---\n\n## License\n\nLicensed under the [Apache License, Version 2.0][01]. Any contribution submitted\nfor inclusion shall be licensed as above, without additional terms.\n\n## Contributing\n\nContributions are welcome — see the [contributing instructions][04]. Thanks to\nall [contributors][05].\n\n## Acknowledgements\n\nBuilt on the foundational servers of the ISO 20022 MCP Suite and the\n[Model Context Protocol][mcp] Python SDK.\n\n[01]: https://opensource.org/license/apache-2-0/\n[04]: https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp/blob/main/CONTRIBUTING.md\n[05]: https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp/graphs/contributors\n[07]: https://pypi.org/project/iso20022-readiness-suite-mcp/\n[mcp]: https://modelcontextprotocol.io\n[docs-badge]: https://img.shields.io/badge/Docs-iso20022--readiness--suite-blue?style=for-the-badge\n[docs-url]: https://sebastienrousseau.github.io/iso20022-readiness-suite-mcp/\n[license-badge]: https://img.shields.io/pypi/l/iso20022-readiness-suite-mcp?style=for-the-badge\n[pypi-badge]: https://img.shields.io/pypi/v/iso20022-readiness-suite-mcp?style=for-the-badge\n[python-versions-badge]: https://img.shields.io/pypi/pyversions/iso20022-readiness-suite-mcp.svg?style=for-the-badge\n[quality-badge]: https://img.shields.io/github/actions/workflow/status/sebastienrousseau/iso20022-readiness-suite-mcp/ci.yml?branch=main&label=Quality&style=for-the-badge\n[quality-url]: https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp/actions/workflows/ci.yml\n[scorecard-badge]: https://api.scorecard.dev/projects/github.com/sebastienrousseau/iso20022-readiness-suite-mcp/badge?style=for-the-badge\n[scorecard-url]: https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/iso20022-readiness-suite-mcp\n[tests-badge]: https://img.shields.io/github/actions/workflow/status/sebastienrousseau/iso20022-readiness-suite-mcp/ci.yml?branch=main&label=Tests&style=for-the-badge\n[tests-url]: https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp/actions/workflows/ci.yml\n",
  "bytes": 20689,
  "sha": "13c0b1ffb3da8716fee428aece892fd5f0613e6cf2c05cf6fd3f23aa8a024a17",
  "repo_slug": "sebastienrousseau/iso20022-readiness-suite-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sebastienrousseau_iso20022_rea_0b9f79a6/readme"
}