io.github.sebastienrousseau/camt053-mcp

Check a camt.053 statement against the CBPR+ Nov 2026 acceptance rules. Use this to audit a statement for the business-rule changes (schema version, structured postal addresses) enforced from the Nov 2026 cutover. For plain XSD schema validity use ``validate_statement`` instead; for just the cutover date use ``get_cbpr_cutover_date``. A coordinated CBPR+ / Fedwire / CHAPS / T2 cutover lands on **14-16 November 2026**: unstructured-only postal addresses get rejected, ``camt.110/111`` exceptions and investigations become mandatory, and T2S R2026.NOV upgrades camt.053 / 054 to schema revision MR2026. This tool walks the supplied payload and reports every issue that will fail the Nov 2026 acceptance rules: * **Schema version** vs the CBPR+ current set (``camt.053.001.08`` / ``camt.053.001.13``); ``.02``-``.07`` are flagged as deprecated warnings; unknown / non-camt.053 namespaces as errors. * **Postal addresses**: every ``<PstlAdr>`` is classified as fully structured, hybrid, or **unstructured-only** (``<AdrLine>`` without ``<TwnNm>`` + ``<Ctry>`` siblings, the Nov 2026 reject case). Returns a dictionary ``{"cbpr_ready": bool, "schema_version": str | None, "checked_at": ISO-8601 UTC, "cutover_date": "2026-11-16", "issues": [...], "summary": {...}}``. ``cbpr_ready`` is ``True`` iff no ``severity="error"`` issue was raised. An ``{"error": ...}`` envelope is returned instead if the XML is malformed or refused by the hardened pre-flight (DOCTYPE / ENTITY / oversized payload). Args: xml: The raw camt.05x statement XML as a string.

Return a curated payments-rulebook citation for a single clause. Use this to quote one specific rule (with its canonical source URL) once you know the ``scheme``/``version``/``clause``. To discover which clauses exist first, call ``list_rulebook_clauses``. Looks up one well-known rule across the SEPA, CBPR+, and HVPS+ rulebooks and returns a short summary together with the canonical source URL so an agent can quote the rule and the operator can verify it against the official document. The registry is a curated convenience layer, not a verbatim reproduction of copyrighted text. Always defer to ``source_url`` for authoritative wording before relying on a citation for compliance or contractual decisions; the returned ``disclaimer`` field repeats this for the calling agent. Args: scheme: One of ``"SEPA"``, ``"CBPR+"``, or ``"HVPS+"`` (case sensitive). version: The rulebook version (e.g. ``"2025"`` or ``"2026"``). clause: A kebab-case clause identifier from ``list_rulebook_clauses``. Returns: A citation dict ``{"scheme", "version", "clause", "title", "summary", "source_url", "as_of", "disclaimer"}`` or an ``{"error": ...}`` payload if the citation is not in the registry.

Classify one statement entry into a category via MCP LLM Sampling. Use this when you want a semantic, model-driven label for an entry (payroll, fee, refund, …) rather than a deterministic rule match. Because it delegates an LLM completion to the client it is open-world and non-idempotent; for the fixed candidate categories it chooses from, call ``list_classify_entry_categories`` first. Uses the **MCP Sampling** protocol primitive: the server (this process) asks the *client* (the agent's host application) to perform an LLM completion on the server's behalf, then receives the model's structured response. Keeps every LLM call in the operator's existing model contract (privacy, billing, audit). The model is asked to choose exactly one category from ``categories`` (or :data:`camt053_mcp.classify.DEFAULT_CATEGORIES` if ``None`` is passed) and return a structured ``{category, confidence, explanation}`` payload. Clients that do not support Sampling will get an ``{"error": "..."}`` envelope and can fall back to a rules-only classifier. Args: ctx: The MCPServer Context (auto-injected; provides ``session.create_message``). entry: A statement entry dict (the shape returned by ``parse_statement`` / ``list_entries``). categories: The candidate categories. ``None`` uses the built-in default list (12 common payment buckets). Returns: ``{"category", "confidence", "explanation"}`` on success or ``{"error": "..."}`` on Sampling failure / malformed model response / out-of-vocabulary category.

Convert a legacy SWIFT MT940 statement into a camt.053 structure. Use this as the Phase-1 migration wedge: SWIFT MT940 customer statements retire in **November 2028**, so this tool bridges the gap by turning raw MT940 text into the same JSON-serialisable camt.053 document shape that ``parse_statement`` returns (group header plus statements, each with its account, balances, and entries). Downstream tools (``list_entries``, ``filter_entries``, ``classify_entry``, ``export_journal``) then work on the result unchanged. Wraps the ``camt053-loader-mt940`` library's ``parse_mt940``; the MT parsing itself is delegated (no MT grammar is reimplemented here). The resulting ``ParsedDocument`` is serialised with the same ``to_dict()`` the server's other parse tools use, so agents get a consistent structure. Nothing is read from or written to disk. Returns the converted document as a JSON-serialisable dict, or an ``{"error": ...}`` payload if the MT940 text cannot be parsed (e.g. a missing ``:20:`` reference or a malformed balance / statement line). Args: mt940_text: The raw MT940 statement text as a string.

Convert a legacy SWIFT MT942 interim report into a camt.052 structure. Use this as the Phase-1 migration wedge for intraday reporting: SWIFT MT94x messages retire in **November 2028**, so this tool bridges the gap by turning raw MT942 *Interim Transaction Report* text into the same JSON-serialisable camt.052 (Bank-to-Customer Account **Report**) document shape the server's parse tools return (group header plus statements, each with its account, balances, and entries). MT942 is the intraday sibling of MT940: where MT940 maps to camt.053 (end-of-day statement), MT942 maps to camt.052, so the resulting ``message_type`` is ``camt.052.001.08``. Downstream tools (``list_entries``, ``filter_entries``, ``classify_entry``, ``export_journal``) then work on the result unchanged. Wraps the ``camt053-loader-mt942`` library's ``parse_mt942``; the MT parsing itself is delegated (no MT grammar is reimplemented here). The resulting ``ParsedDocument`` is serialised with the same ``to_dict()`` the server's other parse tools use, so agents get a consistent structure. Nothing is read from or written to disk. **Documented model limitation.** The ``camt053`` typed model is camt.053-statement-oriented: it has no dedicated field for camt.052's floor-limit (``<Lmt>``) or transaction-summary (``<TxsSummry>``) blocks. Rather than drop that data, the loader surfaces it on the balance list using clearly proprietary ``type_code`` values so consumers can recognise and filter them: ``:34F:`` floor limits become ``FLIMD`` / ``FLIMC`` balances, and ``:90D:`` / ``:90C:`` entry-count summaries become ``SUMD:<count>`` / ``SUMC:<count>`` balances (the ISO ``NbOfNtries`` count is encoded after the colon; the sum is the balance ``amount``). See the loader's README. Returns the converted document as a JSON-serialisable dict, or an ``{"error": ...}`` payload if the MT942 text cannot be parsed (e.g. a missing ``:20:`` reference or a malformed floor-limit / summary / statement line). Args: mt942_text…

Screen a camt.05x statement for deterministic, rule-based anomalies. Use this as a fast, explainable first pass over an incoming statement before deeper review or reversal. It applies three fixed heuristics over the parsed entry list (see ``list_entries``) and never calls out to a model or the network, so the same statement always yields the same result: * **Duplicate references** (severity ``HIGH``) -- two or more entries share an end-to-end id (or, absent one, an entry reference), a classic double-payment signal. * **Unusual fee deductions** (severity ``MEDIUM``) -- a fee/charge debit whose amount exceeds a fixed fraction (25%) of the largest ordinary transaction amount on the statement. * **Velocity spikes** (severity ``LOW``/``MEDIUM``) -- a booking-date window whose entry count runs far above the statement's median per-window count. Returns ``{"anomalies": [{"type", "severity", "detail", "entry_refs"}], "checked_entries": <int>}``; ``anomalies`` is empty for a clean statement. Returns an ``{"error": ...}`` payload instead if the XML cannot be parsed. Args: statement_xml: The raw statement XML as a string.

Export a camt.053 statement as accounting-platform journal-entry payloads. Use this to reshape a statement's booked entries into ready-to-POST Xero or QuickBooks payloads (the tool builds the payloads only; it does not call any external API or write files). To discover the valid ``target`` values first, call ``list_export_journal_targets``. Parses the supplied statement and re-shapes every booked entry into a target-specific journal-entry payload ready for direct POST to the accounting platform's REST API. Supported targets (see ``camt053_mcp.export_journal.SUPPORTED_TARGETS``): * ``"xero"`` - returns a list of Xero ``BankTransactions`` payloads. Each entry maps to ``{Type, Reference, Date, BankAccount, Contact, LineAmountTypes, CurrencyCode, LineItems}``; CRDT entries become ``Type=RECEIVE`` and DBIT entries ``Type=SPEND``. * ``"qbo"`` - returns a list of QuickBooks Online ``JournalEntry`` payloads. Each entry produces a balanced two-line journal (one to the bank account, one to a clearing account; sign flipped on debit entries). Operator-specific values (account codes, contact identifiers, realm IDs) appear as ``"OPERATOR_FILL"`` placeholders so the operator knows exactly what still needs wiring. The response's ``placeholder_count`` field reports the total. NetSuite + SAP S/4HANA targets are tracked as a follow-up in #17. Args: xml: The raw camt.053 statement XML as a string. target: One of ``"xero"`` or ``"qbo"`` (default ``"xero"``). Returns: ``{"target", "entries", "placeholder_count", "placeholder_field"}`` on success, or ``{"error": ...}`` on failure (unsupported target / malformed XML / parse refusal).

List only the statement entries carrying a given return reason code. Use this to preview exactly which entries a reversal would touch before calling ``generate_reversal`` with the same ``reason_code``. For every entry regardless of reason code use ``list_entries`` instead. When ``limit`` is ``None`` (the default) the full list of matching entries is returned, preserving the behaviour expected by existing callers. When ``limit`` is given, a paginated envelope ``{"total", "offset", "limit", "entries"}`` is returned instead, exposing the ``offset:offset + limit`` slice. A negative ``offset`` or ``limit`` yields an ``{"error": ...}`` payload. Args: xml: The raw statement XML as a string. reason_code: The ISO external return reason to match (default ``"AC04"`` Closed Account). offset: The zero-based index of the first entry to return (paginated mode only; default ``0``). limit: The maximum number of entries to return, or ``None`` for the full list (default ``None``).

Generate a validated camt.053.001.14 reversal document from a statement. This is the headline one-shot workflow: pass an incoming statement and a return-reason code and get back the reversal XML (nothing is written to disk). Preview which entries will be reversed first with ``filter_entries`` using the same ``reason_code``. This is the headline one-shot workflow: parse the incoming camt.053, pick the entries with the requested return reason (e.g. AC04 Closed Account), and emit a validated camt.053.001.14 reversal statement. Returns the validated XML document as a string, or an ``{"error": ...}`` payload (serialized) if generation fails. Args: xml: The raw incoming statement XML as a string. reason_code: The ISO external return reason to reverse (default ``"AC04"``).

Return the official CBPR+ / Nov 2026 cutover date as ISO 8601. Use this to quote the enforcement date directly, without parsing a document. To actually audit a statement against the rules that take effect on that date, call ``check_cbpr_readiness`` instead. The cutover (``2026-11-16``) is the date after which the rules checked by ``check_cbpr_readiness`` are enforced by the major clearing systems; payments that fail will be rejected at receive-time. Surfaced as a discrete tool so agents can quote it directly without having to call a readiness check first.

Return the full JSON Schema for a message type's flat input record. Use this to learn every field, its type, and its constraints before assembling records, or to drive a form/UI. For just the required-field names use ``get_required_fields``; to actually check records against this schema use ``validate_records``. Args: message_type: A supported ISO 20022 camt.05x message type.

List only the required input field names for a camt message type. Use this for a quick checklist of the mandatory columns before building reversing-entry records. When you need full type/format constraints (not just which fields are required), call ``get_input_schema`` instead. Args: message_type: A supported ISO 20022 camt.05x message type.

Return the multi-tenant scoping context of the current call. Use this to confirm which tenant/account scope the server attributes the session to. On the streamable-HTTP transport (D7, #42) the ``tenant`` field carries the value of the optional ``Camt053-Account`` request header the caller sent; over stdio (or when the caller sent no header) it is ``None``. The same value is stamped as the ``scope`` on the server's audit log, so an agent can verify its calls are attributed to the right tenant. The lookup is read-only and deterministic for a given request: nothing is validated or mutated, and no external system is touched. Args: ctx: The MCPServer Context (auto-injected; carries the underlying HTTP request, when there is one). Returns: ``{"service": "camt053-mcp", "tenant": str | None}``.

List the default candidate categories the ``classify_entry`` tool uses. Use this to quote the built-in category vocabulary to a user before running the LLM classifier. This is a static list lookup (no model call); to actually classify an entry, call ``classify_entry``. Operators can override the list per call; this tool exposes the default the prompt template ships with so an agent can quote them to the user before invoking the classifier.

List every booked entry across all statements in a camt.05x document. Use this to get the flat, paginable entry list from a statement. To keep only the entries carrying a given return-reason code use ``filter_entries``; for the full nested document structure use ``parse_statement``. When ``limit`` is ``None`` (the default) the full list of entries is returned. When ``limit`` is given, a paginated envelope ``{"total", "offset", "limit", "entries"}`` is returned instead, exposing the ``offset:offset + limit`` slice. A negative ``offset`` or ``limit`` yields an ``{"error": ...}`` payload. Args: xml: The raw statement XML as a string. offset: The zero-based index of the first entry to return (paginated mode only; default ``0``). limit: The maximum number of entries to return, or ``None`` for the full list (default ``None``).

List the accounting-platform targets the ``export_journal`` tool supports. Use this to tell a user which ``target`` values ``export_journal`` accepts before invoking it. This lists export destinations only; for the LLM classifier's category vocabulary use ``list_classify_entry_categories``. Returns the sorted list of valid ``target`` arguments accepted by ``export_journal`` (``["qbo", "xero"]`` today). NetSuite and SAP S/4HANA support is a tracked follow-up.

List every supported ISO 20022 camt.05x message type and its name. Use this first, before any validation or generation call, to discover the exact ``message_type`` strings this server accepts. For the return-reason codes rather than message types, call ``list_return_reasons`` instead. Returns a list of ``{"message_type": ..., "name": ...}`` dictionaries, one per supported message type (e.g. ``camt.053.001.14``).

List every known ISO external return reason code with its name. Use this to discover the ``reason_code`` values that ``filter_entries`` and ``generate_reversal`` accept (e.g. ``AC04`` Closed Account). For the supported message types rather than reason codes, use ``list_message_types``. Returns a list of ``{"code": ..., "name": ...}`` dictionaries (e.g. ``{"code": "AC04", "name": "Closed Account Number"}``).

List the curated rulebook clauses the server can cite, optionally filtered. Use this to browse the citation registry and pick a ``clause`` id; then pass that id to ``cite_rulebook`` to fetch the full summary and source URL. Returns the full registry, optionally filtered by ``scheme`` and / or ``version``. Use the resulting ``clause`` values as input to ``cite_rulebook``. Args: scheme: Restrict to one scheme (e.g. ``"SEPA"``). ``None`` returns all schemes. version: Restrict to one version (e.g. ``"2026"``). ``None`` returns all versions.

Parse an incoming camt.05x statement XML string into structured data. Use this to turn a raw statement into a navigable dict (header, statements, accounts, balances, entries). To pull just the flat entry list use ``list_entries``; to only check the document is schema-valid use ``validate_statement``. Returns the parsed document as a JSON-serialisable dict (group header plus statements, each with its account, balances, and entries), or an ``{"error": ...}`` payload if the XML cannot be parsed. Args: xml: The raw statement XML as a string.

Search the curated rulebook clauses by lexical-vector similarity. Use this when you know *what* a rule is about but not its exact ``scheme``/``version``/``clause`` id: describe it in natural language and get back the closest curated clauses, each with a similarity ``score``. Then pass the winning ``scheme``/``version``/``clause`` to ``cite_rulebook`` for the full citation, or browse everything with ``list_rulebook_clauses``. Retrieval is a **deterministic lexical-vector cosine** search over the same curated SEPA / CBPR+ / HVPS+ summaries that back ``cite_rulebook`` (no external, copyrighted, or auth-gated rulebook text is indexed). Each clause and the query are hashed into a fixed 256-dimension term-frequency vector (whole words plus character 3/4-grams, BLAKE2b-bucketed so results are reproducible across processes) and ranked by cosine distance with ``sqlite-vec``. It is offline and does **not** use a large neural embedding model, so the same query always yields the same ranking and no model download or network call happens at query time. ``sqlite-vec`` ships in the optional ``[vector]`` extra and is imported lazily; when it is not installed this returns a graceful ``{"error": ...}`` payload asking the operator to ``pip install 'camt053-mcp[vector]'`` rather than failing to import. Args: query: The natural-language search string. top_k: The maximum number of clauses to return (default ``5``, clamped to the corpus size). Returns: ``{"query", "top_k", "returned", "method", "results", "disclaimer"}`` where ``results`` is the ranked list of clause dicts (each with an added ``score``), or an ``{"error": ...}`` payload on a bad argument or a missing ``[vector]`` extra.

Validate a single financial identifier (IBAN, BIC, or LEI). Use this for a one-off identifier check with a clear pass/fail. To validate identifiers embedded across a whole batch of records, prefer ``validate_records`` rather than calling this per field. Returns ``{"kind": str, "value": str, "valid": bool}``. Args: kind: One of ``"iban"``, ``"bic"``, or ``"lei"`` (case-insensitive). value: The identifier value to check.

Validate flat records against a message type's input JSON Schema. Use this on in-memory reversing-entry records to catch structural/type errors per row before generation. To validate a whole camt.05x *document* (XML) against its XSD instead, use ``validate_statement``. Returns a report ``{"valid": bool, "total": int, "valid_count": int, "errors": [...]}``. Args: message_type: A supported ISO 20022 camt.05x message type. records: One or more flat reversing-entry records to validate.

Validate an incoming camt.05x statement XML against its XSD schema. Use this to confirm a document is well-formed and schema-valid before processing it. This checks XSD conformance only; for the Nov 2026 CBPR+ business rules use ``check_cbpr_readiness``, and to extract the data use ``parse_statement``. Detects the document's message type, validates it against the matching ISO 20022 schema, and returns a report ``{"valid": bool, "message_type": str, "errors": [...]}``. A well-formed but schema-invalid document yields ``valid=False`` with a populated ``errors`` list (and the detected ``message_type``); a valid one yields ``valid=True`` with no errors. Returns an ``{"error": ...}`` payload instead if the XML cannot be parsed (e.g. it is malformed or is not a camt ``Document``). Args: xml: The raw statement XML as a string.