pain001-mcp
<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
<p align="center">
<img src="https://cloudcdn.pro/pain001/v1/logos/pain001.svg" alt="pain001-mcp logo" width="128" />
</p>
<h1 align="center">pain001-mcp</h1>
<p align="center">
Expose pain001 validation, generation and inspection as MCP tools.
</p>
<p align="center">
<a href="https://github.com/sebastienrousseau/pain001-mcp/actions"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/pain001-mcp/ci.yml?style=for-the-badge&logo=github" alt="Build" height="28" /></a>
<a href="https://pypi.org/project/pain001-mcp/"><img src="https://img.shields.io/pypi/v/pain001-mcp?style=for-the-badge&color=fc8d62&logo=python" alt="Registry" height="28" /></a>
<a href="https://sebastienrousseau.com/pain001-mcp/api.html"><img src="https://img.shields.io/badge/docs-manual-blue?style=for-the-badge&labelColor=555555&logo=readthedocs" alt="Docs" height="28" /></a>
<a href="https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/pain001-mcp"><img src="https://img.shields.io/ossf-scorecard/github.com/sebastienrousseau/pain001-mcp?style=for-the-badge&label=OpenSSF%20Scorecard&logo=openssf" alt="OpenSSF Scorecard" height="28" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue.svg?style=for-the-badge" alt="License: Apache-2.0 OR MIT" height="28" /></a>
<a href="https://github.com/sebastienrousseau/pain001-mcp/blob/main/docs/POLICIES.md"><img src="https://img.shields.io/badge/Python-3.11%2B-93450a.svg?style=for-the-badge&logo=python" alt="Python 3.11 or newer" height="28" /></a>
</p>
<p align="center">
<img src="https://raw.githubusercontent.com/sebastienrousseau/pain001-mcp/main/.github/demo.gif" alt="pain001-mcp --help, then examples/01_mcp_tools.py listing the registered tools, validating an IBAN and generating pain.001 XML" width="100%" />
</p>
---
## Contents
**Getting started**
- [Install](#install): PyPI and source
- [Requirements](#requirements): toolchain floor, platforms
- [Quick Start](#quick-start): use the installed companion
**The pain001-mcp ecosystem**
- [The pain001-mcp ecosystem](#the-pain001-mcp-ecosystem): core and this companion
**Library reference**
- [Capabilities at a glance](#capabilities-at-a-glance): the current surface by theme
- [Ecosystem comparison](#ecosystem-comparison): short matrix; full table at [`docs/COMPARISON.md`](docs/COMPARISON.md)
- [Benchmarks](#benchmarks): headline numbers; full table at [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md)
- [Features](#features): module-level capability list
- [Configuration](#configuration): core options
- [Examples](#examples): runnable example index
**Operational**
- [When not to use pain001-mcp](#when-not-to-use-pain001-mcp): limitations
- [Development](#development): make targets, fuzzing, CI
- [Security](#security): guarantees and compliance
- [Documentation](#documentation): all reference docs
- [Stability guarantees](#stability-guarantees): SemVer axis, output stability, minimum toolchain discipline
- [License](#license)
---
## Install
### As a Python library
```bash
python -m pip install pain001-mcp
```
> **Latest release: v0.0.90**: released with pain001 0.0.90. Requires
> pain001 0.0.90 and pain001-loader-mt101 0.0.90; the 30 MCP tools
> behave as they did in 0.0.89.
Test unreleased changes on this companion's `feat/v<next-version>` branch
against the matching core branch.
---
## Requirements
Python 3.11 or newer. CI tests 3.11–3.14 on Linux. See
[toolchain policy](docs/POLICIES.md); no distro-system-Python claim is made.
---
## Quick Start
```bash
pain001-mcp --help
pain001-mcp
```
The second command starts the stdio MCP server and waits for a client.
Configure your client to launch `pain001-mcp`. Use generated help for optional
HTTP/SSE transports; secure network access before exposing any listener.
---
## The pain001-mcp ecosystem
This independently installed companion delegates payment behavior to core.
Coordinated versioning does not imply branch changes have been released.
| Component | Purpose | Use case |
| :--- | :--- | :--- |
| [pain001](https://github.com/sebastienrousseau/pain001) | Generation and validation | Shared contracts and XML engine |
---
## Capabilities at a glance
| Area | Capability | Status |
| :--- | :--- | :--- |
| Integration | Payment validation and generation tools | Released; branch work is test-gated until it ships |
---
## Ecosystem comparison
This matrix describes the repository's scope, not an independently benchmarked
comparison with competitors.
| Project | Generate payment XML | Real settlement | Synthetic bank replies |
| :--- | :---: | :---: | :---: |
| **pain001-mcp** | Delegates to core | No | Not a bank service |
See [`docs/COMPARISON.md`](docs/COMPARISON.md) for the evidence and complete matrix.
---
## Benchmarks
CI smoke-runs benchmarks. No hardware-independent throughput or latency promise
is made; use the generated run report for measurements.
| Scenario | Result | Environment |
| :--- | ---: | :--- |
| Adapter operations | Run-specific | Python, hardware and dependency versions recorded per run |
See [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md) for methodology and full results.
---
## Features
The authoritative [tool catalogue](docs/tools.md) is generated from the server.
It covers validation, identifiers, generation, migration, bank-report parsing,
corpus access, review-only record fixes (`suggest_record_fix`) and the faces
(`list_faces`, `project_face`). Suggestions require review; financial
fields are refused, never guessed. Test unreleased tools with the matching core
feature branch. In-tree core MCP is a separate smaller surface.
---
## Configuration
Run `pain001-mcp --help` for transport, host and port options. Stdio is default.
See the [tool catalogue](docs/tools.md) for request shapes rather than a copied
tool count.
---
## Examples
Run the self-checking scripts under [examples/](https://github.com/sebastienrousseau/pain001-mcp/tree/main/examples). Tests cover valid
and malformed inputs and integration with the core contract.
---
## When not to use pain001-mcp
Not a bank, settlement engine or autonomous payment approver. Review outputs
before use. Transport support is not bank certification.
---
## Development
```bash
poetry install
poetry run make check
poetry run make security
poetry run python scripts/tool_catalogue.py --check
poetry run python scripts/render_readme.py --check
```
Coverage is gated at 100% line and branch. See [CONTRIBUTING.md](CONTRIBUTING.md)
and [DEVELOPMENT.md](DEVELOPMENT.md). README is generated from the canonical
layout and `docs/readme-values.json`; CI rejects drift.
---
## Security
Treat requests as untrusted. Protect HTTP listeners and avoid real secrets in
logs. Tools may read authorized input paths. Corrections never patch IBANs,
BICs, amounts or currencies.
Report vulnerabilities according to [`SECURITY.md`](SECURITY.md).
---
## Documentation
[What is pain.001?](https://pain001.com/pain-001/) · [User manual](https://sebastienrousseau.com/pain001-mcp/) · [API reference](https://sebastienrousseau.com/pain001-mcp/api.html) ·
[Developer guide](DEVELOPMENT.md) ·
[Family map](https://github.com/sebastienrousseau/pain001#the-pain001-ecosystem)
---
## Stability guarantees
Versions advance in coordinated `0.0.1` steps with core. The maintainer opens
releases; this iteration ships 0.0.90 with the family. Contract and output changes need
compatibility review. No stronger platform or stability guarantee is implied.
---
## License
Dual-licensed under [Apache-2.0](LICENSES/Apache-2.0.txt) OR [MIT](LICENSES/MIT.txt), at your
option. See [LICENSE](LICENSE). Dependencies retain their own licences.
<!-- mcp-name: io.github.sebastienrousseau/pain001-mcp -->
TDQS
Scored across 30 tools
Most tools target clearly distinct operations: record validation, scheme validation, XSD validation, full document checking, generation, parsing, corpus inspection, and projection. The main ambiguity is the validation/simulation/staging cluster—validate_records, validate_payment_scheme, simulate_payment_batch, stage_payment_batch, and check_payment_file overlap in purpose, although the descriptions do distinguish their roles.
All tool names use consistent snake_case and begin with a clear action verb such as list_, get_, validate_, generate_, parse_, stage_, or commit_. Variants and standard codes are handled predictably, e.g. generate_message_async and parse_camt053, with no mixed casing or vague names.
With 30 tools, the surface exceeds the typical well-scoped MCP range and the rubric's 25+ threshold. The advanced corpus, faces, migration, staging/clearing, and simulation tools are useful, but they make the server heavy; some could be split into sub-servers or collapsed into higher-level workflow tools.
Coverage across the ISO 20022 payment lifecycle is excellent: discovery, schema introspection, record and XML validation, generation, migration, parsing, corpus inspection, scheme validation, faces, MT101 conversion, and staged commit/clearing. No obvious dead ends exist for the stated pain.001-focused domain.