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.

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.

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.

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.

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: The raw MT942 interim transaction report text as a string.

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.

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).

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``).

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"``).

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.

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.

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.

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}``.

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.

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``).

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.

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``).

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"}``).

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.

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.

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.

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.

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.

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.