structured-address-fix-mcp 0.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- structured_address_fix_mcp-0.0.1/LICENSE +189 -0
- structured_address_fix_mcp-0.0.1/PKG-INFO +359 -0
- structured_address_fix_mcp-0.0.1/README.md +337 -0
- structured_address_fix_mcp-0.0.1/pyproject.toml +134 -0
- structured_address_fix_mcp-0.0.1/structured_address_fix_mcp/__init__.py +24 -0
- structured_address_fix_mcp-0.0.1/structured_address_fix_mcp/explanations.py +87 -0
- structured_address_fix_mcp-0.0.1/structured_address_fix_mcp/server.py +382 -0
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work.
|
|
38
|
+
|
|
39
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
40
|
+
form, that is based on (or derived from) the Work and for which the
|
|
41
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
42
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
43
|
+
of this License, Derivative Works shall not include works that remain
|
|
44
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
45
|
+
the Work and Derivative Works thereof.
|
|
46
|
+
|
|
47
|
+
"Contribution" shall mean any work of authorship, including
|
|
48
|
+
the original version of the Work and any modifications or additions
|
|
49
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
50
|
+
submitted to the Licensor for inclusion in the Work by the copyright owner
|
|
51
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
52
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
53
|
+
means any form of electronic, verbal, or written communication sent
|
|
54
|
+
to the Licensor or its representatives, including but not limited to
|
|
55
|
+
communication on electronic mailing lists, source code control systems,
|
|
56
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
57
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
58
|
+
excluding communication that is conspicuously marked or otherwise
|
|
59
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
60
|
+
|
|
61
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
62
|
+
on behalf of whom a Contribution has been received by the Licensor and
|
|
63
|
+
subsequently incorporated within the Work.
|
|
64
|
+
|
|
65
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
66
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
67
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
68
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
69
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
70
|
+
Work and such Derivative Works in Source or Object form.
|
|
71
|
+
|
|
72
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
73
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
74
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
75
|
+
(except as stated in this section) patent license to make, have made,
|
|
76
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
77
|
+
where such license applies only to those patent claims licensable
|
|
78
|
+
by such Contributor that are necessarily infringed by their
|
|
79
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
80
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
81
|
+
institute patent litigation against any entity (including a
|
|
82
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
83
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
84
|
+
or contributory patent infringement, then any patent licenses
|
|
85
|
+
granted to You under this License for that Work shall terminate
|
|
86
|
+
as of the date such litigation is filed.
|
|
87
|
+
|
|
88
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
89
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
90
|
+
modifications, and in Source or Object form, provided that You
|
|
91
|
+
meet the following conditions:
|
|
92
|
+
|
|
93
|
+
(a) You must give any other recipients of the Work or
|
|
94
|
+
Derivative Works a copy of this License; and
|
|
95
|
+
|
|
96
|
+
(b) You must cause any modified files to carry prominent notices
|
|
97
|
+
stating that You changed the files; and
|
|
98
|
+
|
|
99
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
100
|
+
that You distribute, all copyright, patent, trademark, and
|
|
101
|
+
attribution notices from the Source form of the Work,
|
|
102
|
+
excluding those notices that do not pertain to any part of
|
|
103
|
+
the Derivative Works; and
|
|
104
|
+
|
|
105
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
106
|
+
distribution, then any Derivative Works that You distribute must
|
|
107
|
+
include a readable copy of the attribution notices contained
|
|
108
|
+
within such NOTICE file, excluding any notices that do not
|
|
109
|
+
pertain to any part of the Derivative Works, in at least one
|
|
110
|
+
of the following places: within a NOTICE text file distributed
|
|
111
|
+
as part of the Derivative Works; within the Source form or
|
|
112
|
+
documentation, if provided along with the Derivative Works; or,
|
|
113
|
+
within a display generated by the Derivative Works, if and
|
|
114
|
+
wherever such third-party notices normally appear. The contents
|
|
115
|
+
of the NOTICE file are for informational purposes only and
|
|
116
|
+
do not modify the License. You may add Your own attribution
|
|
117
|
+
notices within Derivative Works that You distribute, alongside
|
|
118
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
119
|
+
that such additional attribution notices cannot be construed
|
|
120
|
+
as modifying the License.
|
|
121
|
+
|
|
122
|
+
You may add Your own copyright statement to Your modifications and
|
|
123
|
+
may provide additional or different license terms and conditions
|
|
124
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
125
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
126
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
127
|
+
the conditions stated in this License.
|
|
128
|
+
|
|
129
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
130
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
131
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
132
|
+
this License, without any additional terms or conditions.
|
|
133
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
134
|
+
the terms of any separate license agreement you may have executed
|
|
135
|
+
with Licensor regarding such Contributions.
|
|
136
|
+
|
|
137
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
138
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
139
|
+
except as required for reasonable and customary use in describing the
|
|
140
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
141
|
+
|
|
142
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
143
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
144
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
145
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
146
|
+
implied, including, without limitation, any warranties or conditions
|
|
147
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
148
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
149
|
+
appropriateness of using or redistributing the Work and assume any
|
|
150
|
+
risks associated with Your exercise of permissions under this License.
|
|
151
|
+
|
|
152
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
153
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
154
|
+
unless required by applicable law (such as deliberate and grossly
|
|
155
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
156
|
+
liable to You for damages, including any direct, indirect, special,
|
|
157
|
+
incidental, or consequential damages of any character arising as a
|
|
158
|
+
result of this License or out of the use or inability to use the
|
|
159
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
160
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
161
|
+
other commercial damages or losses), even if such Contributor
|
|
162
|
+
has been advised of the possibility of such damages.
|
|
163
|
+
|
|
164
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
165
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
166
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
167
|
+
or other liability obligations and/or rights consistent with this
|
|
168
|
+
License. However, in accepting such obligations, You may act only
|
|
169
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
170
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
171
|
+
defend, and hold each Contributor harmless for any liability
|
|
172
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
173
|
+
of your accepting any such warranty or additional liability.
|
|
174
|
+
|
|
175
|
+
END OF TERMS AND CONDITIONS
|
|
176
|
+
|
|
177
|
+
Copyright 2023-2026 Sebastien Rousseau
|
|
178
|
+
|
|
179
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
180
|
+
you may not use this file except in compliance with the License.
|
|
181
|
+
You may obtain a copy of the License at
|
|
182
|
+
|
|
183
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
184
|
+
|
|
185
|
+
Unless required by applicable law or agreed to in writing, software
|
|
186
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
187
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
188
|
+
See the License for the specific language governing permissions and
|
|
189
|
+
limitations under the License.
|
|
@@ -0,0 +1,359 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: structured-address-fix-mcp
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Summary: Model Context Protocol (MCP) server exposing the structured-address-fix ISO 20022 address-remediation library as agent tools.
|
|
5
|
+
License: Apache-2.0
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Keywords: iso20022,cbpr,mcp,postal-address,pacs008,payments
|
|
8
|
+
Author: Sebastien Rousseau
|
|
9
|
+
Author-email: sebastian.rousseau@gmail.com
|
|
10
|
+
Requires-Python: >=3.12,<4.0
|
|
11
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
16
|
+
Requires-Dist: mcp (>=1.28.1)
|
|
17
|
+
Requires-Dist: structured-address-fix (>=0.0.1,<1)
|
|
18
|
+
Project-URL: Homepage, https://sebastienrousseau.github.io/structured-address-fix/
|
|
19
|
+
Project-URL: Repository, https://github.com/sebastienrousseau/structured-address-fix-mcp
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
|
|
22
|
+
# structured-address-fix-mcp: An MCP Server for ISO 20022 Postal Addresses
|
|
23
|
+
|
|
24
|
+
[![PyPI Version][pypi-badge]][07]
|
|
25
|
+
[![Python Versions][python-versions-badge]][07]
|
|
26
|
+
[![License][license-badge]][01]
|
|
27
|
+
[![Tests][tests-badge]][tests-url]
|
|
28
|
+
[![Quality][quality-badge]][quality-url]
|
|
29
|
+
[![OpenSSF Scorecard][scorecard-badge]][scorecard-url]
|
|
30
|
+
[![Documentation][docs-badge]][docs-url]
|
|
31
|
+
|
|
32
|
+
**A [Model Context Protocol][mcp] server that exposes the
|
|
33
|
+
[`structured-address-fix`][core] ISO 20022 postal-address library as tools for
|
|
34
|
+
AI agents and assistants** — classify an address's shape, assess it against a
|
|
35
|
+
scheme policy, and remediate it (or a whole pacs.008 / pain.001 message) into
|
|
36
|
+
the structured form the November 2026 cutover requires, all from your
|
|
37
|
+
favourite MCP client.
|
|
38
|
+
|
|
39
|
+
> **The 14 November 2026 cliff.** On that date CBPR+, HVPS+, T2, CHAPS, and
|
|
40
|
+
> Fedwire stop accepting fully unstructured postal addresses: a payment whose
|
|
41
|
+
> debtor/creditor address is a free-text blob is rejected. `structured-address-fix-mcp`
|
|
42
|
+
> puts the readiness check and the fix in front of your agent — `assess_message`
|
|
43
|
+
> flags the offending parties, `remediate_message` proposes the compliant form,
|
|
44
|
+
> and `get_cutover_date` reports the binding date. **v0.0.1**, stdio transport,
|
|
45
|
+
> 9 tools, Python 3.12+.
|
|
46
|
+
|
|
47
|
+
## Contents
|
|
48
|
+
|
|
49
|
+
- [Overview](#overview)
|
|
50
|
+
- [The ISO 20022 MCP Suite](#the-iso-20022-mcp-suite)
|
|
51
|
+
- [Install](#install)
|
|
52
|
+
- [Quick Start](#quick-start)
|
|
53
|
+
- [Tools](#tools)
|
|
54
|
+
- [Using the tools](#using-the-tools)
|
|
55
|
+
- [Related MCP Servers](#related-mcp-servers)
|
|
56
|
+
- [When not to use structured-address-fix-mcp](#when-not-to-use-structured-address-fix-mcp)
|
|
57
|
+
- [Development](#development)
|
|
58
|
+
- [Security](#security)
|
|
59
|
+
- [Documentation](#documentation)
|
|
60
|
+
- [License](#license)
|
|
61
|
+
- [Contributing](#contributing)
|
|
62
|
+
- [Acknowledgements](#acknowledgements)
|
|
63
|
+
|
|
64
|
+
## Overview
|
|
65
|
+
|
|
66
|
+
The [Model Context Protocol][mcp] (MCP) is an open standard that lets AI agents
|
|
67
|
+
and assistants discover and call external tools in a uniform way.
|
|
68
|
+
**structured-address-fix-mcp** is an MCP server that turns the
|
|
69
|
+
[`structured-address-fix`][core] library into a set of first-class agent tools,
|
|
70
|
+
so an assistant can read a postal address — or every addressed party in an
|
|
71
|
+
**ISO 20022 `pacs.008` / `pain.001` message** — and bring it into line with the
|
|
72
|
+
structured-address rules that become mandatory on **14 November 2026**,
|
|
73
|
+
directly from a conversation.
|
|
74
|
+
|
|
75
|
+
The headline capability is the one-shot remediation workflow: assess a message,
|
|
76
|
+
find the parties whose addresses will be rejected at the cliff, and emit the
|
|
77
|
+
compliant form with each change explained and confidence-scored.
|
|
78
|
+
|
|
79
|
+
Every tool is a thin, typed wrapper over `structured_address_fix.services` —
|
|
80
|
+
the single shared facade also used by the CLI — so all interfaces behave
|
|
81
|
+
identically. Tools return JSON-serialisable data; on an error they return an
|
|
82
|
+
`{"error": ...}` payload rather than raising.
|
|
83
|
+
|
|
84
|
+
- **Website:** <https://sebastienrousseau.github.io/structured-address-fix/>
|
|
85
|
+
- **Source code:** <https://github.com/sebastienrousseau/structured-address-fix-mcp>
|
|
86
|
+
- **Bug reports:** <https://github.com/sebastienrousseau/structured-address-fix-mcp/issues>
|
|
87
|
+
|
|
88
|
+
```mermaid
|
|
89
|
+
flowchart LR
|
|
90
|
+
A["MCP client<br/>(Claude Desktop, IDE, agent)"] -->|stdio| B["structured-address-fix-mcp"]
|
|
91
|
+
B -->|delegates to| C["structured_address_fix.services"]
|
|
92
|
+
C -->|classify + assess + remediate| D["ISO 20022 postal addresses<br/>(pacs.008 / pain.001)"]
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## The ISO 20022 MCP Suite
|
|
96
|
+
|
|
97
|
+
`structured-address-fix-mcp` is the **postal-address specialist** in a set of
|
|
98
|
+
coordinated, vendor-neutral MCP servers for the ISO 20022 migration.
|
|
99
|
+
Dependency ranges are kept aligned across the suite, so the servers co-install
|
|
100
|
+
cleanly in a single Python environment: start with one, add the rest as your
|
|
101
|
+
workflow grows.
|
|
102
|
+
|
|
103
|
+
| Server | Scope | Install | Use it when |
|
|
104
|
+
|------|------|------|------|
|
|
105
|
+
| [`structured-address-fix-mcp`](#install) | ISO 20022 postal-address classification, assessment, and remediation for the Nov 2026 structured-address cliff | `pip install structured-address-fix-mcp` | You need to get debtor/creditor addresses cliff-ready — **this package** |
|
|
106
|
+
| [`pacs008-mcp`](https://github.com/sebastienrousseau/pacs008-mcp) | Generate, validate, parse & scheme-check ISO 20022 pacs.008 FI-to-FI credit transfers, with Nov-2026 address linting | `pip install pacs008-mcp` | You work with pacs.008 messages end to end |
|
|
107
|
+
| [`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` | You originate outbound payment files |
|
|
108
|
+
| [`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` | You work with bank-to-customer statements |
|
|
109
|
+
|
|
110
|
+
The suite also includes the [`iso20022-mcp`](https://github.com/sebastienrousseau/iso20022-mcp)
|
|
111
|
+
gateway (unified `search` / `describe` / `validate` / `generate` / `parse`
|
|
112
|
+
meta-tools across the whole message catalogue) and
|
|
113
|
+
[`acmt001-mcp`](https://github.com/sebastienrousseau/acmt001-mcp) (account
|
|
114
|
+
management). Where `pacs008-mcp` *lints* a message for address problems,
|
|
115
|
+
`structured-address-fix-mcp` is the specialist that *classifies, assesses, and
|
|
116
|
+
fixes* the addresses themselves against per-scheme policies.
|
|
117
|
+
|
|
118
|
+
## Install
|
|
119
|
+
|
|
120
|
+
**structured-address-fix-mcp** runs on macOS, Linux, and Windows and requires
|
|
121
|
+
**Python 3.12+** and **pip**. It pulls in the core `structured-address-fix`
|
|
122
|
+
library and the MCP SDK automatically.
|
|
123
|
+
|
|
124
|
+
```sh
|
|
125
|
+
python -m pip install structured-address-fix-mcp
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
<details>
|
|
129
|
+
<summary>Using an isolated virtual environment (recommended)</summary>
|
|
130
|
+
|
|
131
|
+
```sh
|
|
132
|
+
python -m venv venv
|
|
133
|
+
source venv/bin/activate # macOS/Linux
|
|
134
|
+
venv\Scripts\activate # Windows
|
|
135
|
+
python -m pip install -U structured-address-fix-mcp
|
|
136
|
+
```
|
|
137
|
+
</details>
|
|
138
|
+
|
|
139
|
+
## Quick Start
|
|
140
|
+
|
|
141
|
+
For the 10-minute install → MCP client config → first conversation
|
|
142
|
+
tutorial, see [`docs/quickstart.md`](docs/quickstart.md).
|
|
143
|
+
|
|
144
|
+
Launch the server over stdio (the FastMCP default transport):
|
|
145
|
+
|
|
146
|
+
```sh
|
|
147
|
+
structured-address-fix-mcp
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Register it with any MCP client (e.g. Claude Desktop) by adding it to the
|
|
151
|
+
client's configuration:
|
|
152
|
+
|
|
153
|
+
```json
|
|
154
|
+
{
|
|
155
|
+
"mcpServers": {
|
|
156
|
+
"structured-address-fix": { "command": "structured-address-fix-mcp" }
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
The command speaks MCP on stdin/stdout — it is meant to be launched by an
|
|
162
|
+
MCP client, not used interactively. The agent can then call the tools below
|
|
163
|
+
to assess and remediate postal addresses on demand.
|
|
164
|
+
|
|
165
|
+
## Tools
|
|
166
|
+
|
|
167
|
+
All tools delegate to the shared `structured_address_fix.services` layer, so
|
|
168
|
+
they behave identically to the CLI. Tools return JSON-serialisable data; on a
|
|
169
|
+
domain, validation, or value error they return an `{"error": ...}` payload.
|
|
170
|
+
|
|
171
|
+
- `list_policies` — List every available address policy (rulebook) with its tier (e.g. `cbpr-2026`, `sepa`, `hvps-plus`, `generic-structured`)
|
|
172
|
+
- `classify_address` — Classify a postal address as structured, hybrid, or unstructured (a quick shape check)
|
|
173
|
+
- `assess_address` — Score a single address against a policy and return its findings
|
|
174
|
+
- `assess_message` — Assess every addressed party in a pacs.008 / pain.001 message against a policy
|
|
175
|
+
- `remediate_address` — Propose the compliant form of an address, with the before/after and confidence-scored patch operations
|
|
176
|
+
- `remediate_message` — Assess and remediate every addressed party in a message; optionally apply the operations and return the patched XML
|
|
177
|
+
- `preview_patch` — Return the patch operations remediation would apply to a message (a dry run)
|
|
178
|
+
- `explain_finding` — Explain what a finding code (e.g. `SAF001`) means and how to resolve it
|
|
179
|
+
- `get_cutover_date` — Return the binding November 2026 structured-address cutover date and the scheme that sets it
|
|
180
|
+
|
|
181
|
+
Optional parameters shared across the assessment/remediation tools: `policy_id`
|
|
182
|
+
(defaults to `cbpr-2026`), `as_of` (an `YYYY-MM-DD` date that decides the cliff
|
|
183
|
+
wording; defaults to today), and `country_hint` (an ISO 3166-1 alpha-2 code to
|
|
184
|
+
assume when an address carries no country of its own).
|
|
185
|
+
|
|
186
|
+
## Using the tools
|
|
187
|
+
|
|
188
|
+
You can invoke the tools in-process — without a transport — straight through the
|
|
189
|
+
FastMCP instance. This mirrors what an agent receives over stdio. The runnable
|
|
190
|
+
version of this snippet lives in [`examples/mcp_tools.py`](examples/mcp_tools.py).
|
|
191
|
+
|
|
192
|
+
```python
|
|
193
|
+
import asyncio
|
|
194
|
+
|
|
195
|
+
from structured_address_fix_mcp import server
|
|
196
|
+
|
|
197
|
+
# A fully unstructured address: two free-text lines, no structured fields.
|
|
198
|
+
# At the 14 Nov 2026 cliff this form is rejected across the major schemes.
|
|
199
|
+
unstructured = {
|
|
200
|
+
"address_lines": ["10 Downing St", "London SW1A 2AA"],
|
|
201
|
+
"country": "GB",
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
async def main() -> None:
|
|
206
|
+
async def call(name, args):
|
|
207
|
+
result = await server.server.call_tool(name, args)
|
|
208
|
+
content = result[0] if isinstance(result, tuple) else result
|
|
209
|
+
return content[0].text if content else ""
|
|
210
|
+
|
|
211
|
+
# When does the cliff bite?
|
|
212
|
+
print(await call("get_cutover_date", {}))
|
|
213
|
+
# -> {"date": "2026-11-14", "scheme": "SWIFT CBPR+ UG2026"}
|
|
214
|
+
|
|
215
|
+
# What shape is this address in right now?
|
|
216
|
+
print(await call("classify_address", {"address": unstructured}))
|
|
217
|
+
# -> {"classification": "unstructured"}
|
|
218
|
+
|
|
219
|
+
# Propose the compliant form, with each change explained.
|
|
220
|
+
print(await call("remediate_address",
|
|
221
|
+
{"address": unstructured, "policy_id": "cbpr-2026"}))
|
|
222
|
+
# -> {"policy_id": "cbpr-2026", "findings": [...], "suggestions": [...],
|
|
223
|
+
# "is_compliant_before": false, "is_compliant_after": true, ...}
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
asyncio.run(main())
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Run it directly:
|
|
230
|
+
|
|
231
|
+
```sh
|
|
232
|
+
python examples/mcp_tools.py
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
## Related MCP Servers
|
|
236
|
+
|
|
237
|
+
Part of the **ISO 20022 MCP Suite** — open-source, Apache-2.0 licensed MCP
|
|
238
|
+
servers for banking and financial-services AI agents:
|
|
239
|
+
|
|
240
|
+
| Server | Purpose |
|
|
241
|
+
|---|---|
|
|
242
|
+
| [`pacs008-mcp`](https://github.com/sebastienrousseau/pacs008-mcp) | Generate, validate, parse & scheme-check ISO 20022 pacs.008 FI-to-FI credit transfers + Nov-2026 address linting |
|
|
243
|
+
| [`pain001-mcp`](https://github.com/sebastienrousseau/pain001-mcp) | Generate & validate ISO 20022 pain.001 payment files (v03–v12, pain.008, SEPA) with rulebook checks |
|
|
244
|
+
| [`camt053-mcp`](https://github.com/sebastienrousseau/camt053-mcp) | Parse, validate, filter & reverse ISO 20022 camt.05x bank statements; MT94x migration; CBPR+ readiness |
|
|
245
|
+
| [`acmt001-mcp`](https://github.com/sebastienrousseau/acmt001-mcp) | Generate & validate ISO 20022 acmt account-management messages |
|
|
246
|
+
| [`iso20022-mcp`](https://github.com/sebastienrousseau/iso20022-mcp) | Unified gateway: `search` / `describe` / `validate` / `generate` / `parse` across the pain · pacs · camt · acmt families |
|
|
247
|
+
|
|
248
|
+
## When not to use structured-address-fix-mcp
|
|
249
|
+
|
|
250
|
+
- **You have no MCP client.** This server only makes sense paired with an
|
|
251
|
+
MCP-aware host (Claude Desktop, the IDE plugins, an agent framework). For
|
|
252
|
+
scripted / CI use, the `structured-address-fix` CLI covers the same ground
|
|
253
|
+
without the stdio protocol overhead.
|
|
254
|
+
- **You need a long-lived network service.** v0.1 speaks **stdio only** —
|
|
255
|
+
one process per operator, launched by the client, no network surface. An
|
|
256
|
+
HTTP/OAuth transport for shared, multi-tenant deployments is on the
|
|
257
|
+
[roadmap](ROADMAP.md), not in this release.
|
|
258
|
+
- **You need streaming responses.** Tool calls return whole values, not
|
|
259
|
+
streams. Large messages are assessed and remediated in one call, not
|
|
260
|
+
chunked over multiple responses.
|
|
261
|
+
- **You need to *build* the pacs.008 / pain.001 message.** Out of scope; this
|
|
262
|
+
server fixes the addresses inside a message. Use
|
|
263
|
+
[`pacs008-mcp`](https://github.com/sebastienrousseau/pacs008-mcp) or
|
|
264
|
+
[`pain001-mcp`](https://github.com/sebastienrousseau/pain001-mcp) to
|
|
265
|
+
generate and validate the message itself.
|
|
266
|
+
|
|
267
|
+
## Development
|
|
268
|
+
|
|
269
|
+
**structured-address-fix-mcp** uses [Poetry](https://python-poetry.org/) and
|
|
270
|
+
[mise](https://mise.jdx.dev/).
|
|
271
|
+
|
|
272
|
+
```bash
|
|
273
|
+
git clone https://github.com/sebastienrousseau/structured-address-fix-mcp.git && cd structured-address-fix-mcp
|
|
274
|
+
mise install
|
|
275
|
+
poetry install
|
|
276
|
+
poetry shell
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
> **Note:** the server depends on the core `structured-address-fix` library.
|
|
280
|
+
> Until it is published to PyPI, the dev dependency group installs it from the
|
|
281
|
+
> sibling checkout (`../structured-address-fix`); see
|
|
282
|
+
> [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
|
283
|
+
|
|
284
|
+
A `Makefile` orchestrates the quality gates (kept in lockstep with CI):
|
|
285
|
+
|
|
286
|
+
```bash
|
|
287
|
+
make check # all gates (REQUIRED before commit): lint + type-check + test + examples
|
|
288
|
+
make test # pytest
|
|
289
|
+
make lint # ruff + black
|
|
290
|
+
make type-check # mypy --strict
|
|
291
|
+
make security # bandit
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
## Security
|
|
295
|
+
|
|
296
|
+
`structured-address-fix-mcp` is a thin wrapper — every tool delegates to
|
|
297
|
+
`structured_address_fix.services`, where the defence-in-depth for XML parsing
|
|
298
|
+
(defusedxml) lives. Tools catch the documented domain, validation, and value
|
|
299
|
+
errors and return an `{"error": ...}` envelope per the suite convention; they
|
|
300
|
+
never propagate raw exceptions to the MCP client. Reporting practice, supported
|
|
301
|
+
versions, and the full supply-chain posture (SLSA L3 provenance, PEP 740
|
|
302
|
+
attestations, SBOMs, and the NIST SP 800-218 SSDF practice mapping) are
|
|
303
|
+
documented in [`SECURITY.md`](SECURITY.md). Vulnerabilities go via GitHub
|
|
304
|
+
Private Vulnerability Reporting, not public issues.
|
|
305
|
+
|
|
306
|
+
## Documentation
|
|
307
|
+
|
|
308
|
+
- [`README.md`](README.md) — this file
|
|
309
|
+
- [`CHANGELOG.md`](CHANGELOG.md) — release notes
|
|
310
|
+
- [`SECURITY.md`](SECURITY.md) — disclosure + supported versions
|
|
311
|
+
- [`SUPPORT.md`](SUPPORT.md) — how to get help
|
|
312
|
+
- [`ROADMAP.md`](ROADMAP.md) — what's next (HTTP/OAuth transport, observability, entitlement gating)
|
|
313
|
+
- [`MAINTAINERS.md`](MAINTAINERS.md) — who can merge
|
|
314
|
+
- [`docs/quickstart.md`](docs/quickstart.md) — 10-minute install → first conversation
|
|
315
|
+
- [`docs/deployment-cookbook.md`](docs/deployment-cookbook.md) — stdio client configs (Claude Desktop, Cursor, containers)
|
|
316
|
+
- [`examples/`](examples/) — runnable scripts
|
|
317
|
+
- [`glama.json`](glama.json) — Glama directory manifest
|
|
318
|
+
|
|
319
|
+
---
|
|
320
|
+
|
|
321
|
+
## MCP Registry
|
|
322
|
+
|
|
323
|
+
`mcp-name: io.github.sebastienrousseau/structured-address-fix-mcp`
|
|
324
|
+
|
|
325
|
+
---
|
|
326
|
+
|
|
327
|
+
## License
|
|
328
|
+
|
|
329
|
+
Licensed under the [Apache License, Version 2.0][01]. Any contribution submitted
|
|
330
|
+
for inclusion shall be licensed as above, without additional terms.
|
|
331
|
+
|
|
332
|
+
## Contributing
|
|
333
|
+
|
|
334
|
+
Contributions are welcome — see the [contributing instructions][04]. Thanks to
|
|
335
|
+
all [contributors][05].
|
|
336
|
+
|
|
337
|
+
## Acknowledgements
|
|
338
|
+
|
|
339
|
+
Built on the [`structured-address-fix`][core] ISO 20022 postal-address library
|
|
340
|
+
and the [Model Context Protocol][mcp] Python SDK.
|
|
341
|
+
|
|
342
|
+
[01]: https://opensource.org/license/apache-2-0/
|
|
343
|
+
[04]: https://github.com/sebastienrousseau/structured-address-fix-mcp/blob/main/CONTRIBUTING.md
|
|
344
|
+
[05]: https://github.com/sebastienrousseau/structured-address-fix-mcp/graphs/contributors
|
|
345
|
+
[07]: https://pypi.org/project/structured-address-fix-mcp/
|
|
346
|
+
[core]: https://github.com/sebastienrousseau/structured-address-fix
|
|
347
|
+
[mcp]: https://modelcontextprotocol.io
|
|
348
|
+
[docs-badge]: https://img.shields.io/badge/Docs-structured--address--fix-blue?style=for-the-badge
|
|
349
|
+
[docs-url]: https://sebastienrousseau.github.io/structured-address-fix/
|
|
350
|
+
[license-badge]: https://img.shields.io/pypi/l/structured-address-fix-mcp?style=for-the-badge
|
|
351
|
+
[pypi-badge]: https://img.shields.io/pypi/v/structured-address-fix-mcp?style=for-the-badge
|
|
352
|
+
[python-versions-badge]: https://img.shields.io/pypi/pyversions/structured-address-fix-mcp.svg?style=for-the-badge
|
|
353
|
+
[quality-badge]: https://img.shields.io/github/actions/workflow/status/sebastienrousseau/structured-address-fix-mcp/ci.yml?branch=main&label=Quality&style=for-the-badge
|
|
354
|
+
[quality-url]: https://github.com/sebastienrousseau/structured-address-fix-mcp/actions/workflows/ci.yml
|
|
355
|
+
[scorecard-badge]: https://api.scorecard.dev/projects/github.com/sebastienrousseau/structured-address-fix-mcp/badge?style=for-the-badge
|
|
356
|
+
[scorecard-url]: https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/structured-address-fix-mcp
|
|
357
|
+
[tests-badge]: https://img.shields.io/github/actions/workflow/status/sebastienrousseau/structured-address-fix-mcp/ci.yml?branch=main&label=Tests&style=for-the-badge
|
|
358
|
+
[tests-url]: https://github.com/sebastienrousseau/structured-address-fix-mcp/actions/workflows/ci.yml
|
|
359
|
+
|