iso20022-evidence-pack-mcp

# iso20022-evidence-pack-mcp: Sealed ISO 20022 Audit Evidence Packs

[![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 fully local, closed-world [Model Context Protocol (MCP)][mcp] server** that
compiles ISO 20022 readiness findings, remediation diffs, and simulated bank
responses into one **sealed, exportable audit evidence pack**. It is the audit
and certification sibling of
[`iso20022-readiness-suite-mcp`](https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp)
(which produces those findings) and
[`iso20022-bank-profile-mcp`](https://github.com/sebastienrousseau/iso20022-bank-profile-mcp)
in the [ISO 20022 MCP Suite](#the-iso-20022-mcp-suite).

> **Tamper-evident by construction.** The pack's seal is a deterministic
> SHA-256 digest over the pack's canonical JSON (the `digest` field excluded).
> Re-sealing identical content yields the identical digest, and changing any
> field breaks verification — so an auditor can detect undetected change. There
> is **no network surface, no sub-servers, and no XML**: every tool is a pure,
> local, deterministic transform over the JSON structures it is handed.
> **v0.0.2**, stdio transport (plus an optional authenticated HTTP transport),
> 6 tools including Ed25519 pack signing, 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)
- [Signing evidence packs](#signing-evidence-packs)
- [Examples](#examples)
- [How it fits the suite](#how-it-fits-the-suite)
- [Open-core vs premium](#open-core-vs-premium)
- [Seal vs signature](#seal-vs-signature)
- [When not to use iso20022-evidence-pack-mcp](#when-not-to-use-iso20022-evidence-pack-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-evidence-pack-mcp** is the audit/certification end of the ISO 20022
MCP Suite: it takes the results that
[`iso20022-readiness-suite-mcp`](https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp)
produces — a readiness score with findings, an optional remediation result,
and any simulated bank responses — and folds them into one strongly-typed,
graded, **sealed** evidence pack that can be exported, verified, and rendered
as a compliance report.

An `EvidencePack` folds three loosely-typed inputs into one self-describing
document: a **readiness result** (message type, validity, score, findings), an
optional **remediation result** (fixes applied, residual findings), and any
**simulated bank responses** (accepted / rejected statuses). The pack is graded
(A / B / C / F from the readiness score) and sealed.

The seal is the point: it is a deterministic SHA-256 digest computed over the
pack's canonical JSON form (sorted keys, tight separators, with the `digest`
field itself excluded). Sealing the same content always yields the same value,
which is exactly what makes the pack **tamper-evident** — recomputing the seal
and comparing it to the one carried in the pack tells an auditor whether any
byte changed since it was sealed.

Every tool returns typed, JSON-serialisable data; on any failure — bad input,
unparseable JSON, a shape that does not match the pack schema — it returns an
`{"error": ...}` payload rather than raising into the client transport.

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

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

The server is fully local and closed-world: it holds no state, opens no
sockets, and spawns no processes. You hand it JSON, it hands you a sealed pack.

## The ISO 20022 MCP Suite

`iso20022-evidence-pack-mcp` is the **audit and certification** server 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.

| Server | Scope | Install |
|------|------|------|
| [`iso20022-readiness-suite-mcp`](https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp) | Orchestration gateway: readiness scoring, remediation, clearing-profile linting, and bank-response simulation — the results this server folds in | `pip install iso20022-readiness-suite-mcp` |
| [`iso20022-bank-profile-mcp`](https://github.com/sebastienrousseau/iso20022-bank-profile-mcp) | Manage and serve bank-specific clearing profiles / rule packs as a first-class server | `pip install iso20022-bank-profile-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` |
| [`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` |

Where the readiness suite decides *whether a payment is ready and fixes it*,
**this server certifies the outcome**: it turns those findings into a sealed,
auditable artifact.

## Install

**iso20022-evidence-pack-mcp** runs on macOS, Linux, and Windows and requires
**Python 3.10+** and **pip**. It pulls in only the MCP SDK and `pydantic`
automatically — there are no other runtime dependencies.

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

<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-evidence-pack-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-evidence-pack-mcp
```

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

```json
{
  "mcpServers": {
    "iso20022-evidence-pack": { "command": "iso20022-evidence-pack-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 example below builds a sealed pack from a small readiness result, then
shows the seal round-tripping (and breaking on tamper):

```python
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"])