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 (which produces those findings) and iso20022-bank-profile-mcp in 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
• The ISO 20022 MCP Suite
• Install
• Quick Start
• Tools
• HTTP transport & authentication
• Signing evidence packs
• Examples
• How it fits the suite
• Open-core vs premium
• Seal vs signature
• When not to use iso20022-evidence-pack-mcp
• Development
• Security
• Documentation
• License
• Contributing
• 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 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

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.

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.

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

Quick Start

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

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

iso20022-evidence-pack-mcp

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

{
  "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):

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