io.github.sebastienrousseau/reconcile-mcp

Explain the match score between one expected and one observed record. Purpose: Scores a single transaction pair across reference, amount, date, and name signals, returning individual signal weights and an explanation even for pairs below threshold. When to use: - When tuning scoring weights, tolerances, or debugging match decisions. - When explaining match confidence for human review or exception handling. When NOT to use: - Do NOT use for entire batches; use reconcile instead. - Do NOT use for cross-currency conversions without a known FX rate; use match_amounts_with_fx_drift. Behavioral transparency: Pure, deterministic, side-effect-free, read-only calculation without external dependencies.

List built-in sandbox reconciliation scenarios and magic references. Purpose: Returns the catalog of deterministic test-mode scenarios and synthetic magic references to demonstrate reconciliation outcomes without production data. When to use: - When discovering available test scenarios (e.g. clean_match, month_end, fx_drift). - When testing agent decision-making workflows with zero setup. When NOT to use: - Do NOT use for production reconciliation batches. Behavioral transparency: Static catalogue retrieval; read-only and instantaneous.

Load expected and observed record inputs for a named sandbox scenario. Purpose: Retrieves the test-mode expected and observed fixture records for a named scenario so they can be inspected, customized, or passed to reconcile. When to use: - When reviewing fixture data prior to executing reconciliation runs. - When creating custom variations of standard reconciliation scenarios. When NOT to use: - Do NOT use if you want to run and reconcile the scenario in one step; use run_sandbox_scenario. - Do NOT use with non-existent scenario names. Behavioral transparency: Deterministic dictionary lookup; read-only with no side effects.

Compare two amounts in different currencies within an FX drift tolerance. Purpose: Converts currency amounts using a provided exchange rate and verifies if the percentage difference falls within an acceptable tolerance window using exact decimal arithmetic. When to use: - When reconciling cross-currency payments with conversion timing or rate variance. - When evaluating FX tolerance bounds on cross-border transactions. When NOT to use: - Do NOT use for same-currency comparisons where standard tolerance applies; use reconcile. - Do NOT use with non-positive FX rates. Behavioral transparency: Pure mathematical calculation; read-only and idempotent.

Score two counterparty names using Jaro-Winkler string similarity. Purpose: Computes similarity in [0, 1] between two company or individual names, tolerating typographical variations and legal suffix abbreviations (e.g. 'Corp' vs 'Corporation Inc'). When to use: - When verifying whether two counterparty or entity names represent the same party. - When evaluating name similarity thresholds for automated matching rules. When NOT to use: - Do NOT use for full multi-signal transaction matching; use reconcile or explain_match. - Do NOT use with non-string inputs. Behavioral transparency: Pure, deterministic string calculation; read-only and idempotent.

Convert parsed camt.053 statement entries into canonical observed records. Purpose: Adapts parsed ISO 20022 camt.053 bank statement documents or entry lists into canonical observed records ready for the reconcile engine. When to use: - When ingesting parsed bank statements before calling reconcile. - When transforming bank booking entries into uniform id, amount, date, and counterparty fields. When NOT to use: - Do NOT use for payment initiation orders (pain.001); use normalize_pain001 instead. - Do NOT pass raw unparsed XML text; parse or deserialize first. Behavioral transparency: Pure, deterministic, read-only data normalization.

Convert parsed pain.001 payment instructions into canonical expected records. Purpose: Adapts parsed ISO 20022 pain.001 credit transfer documents or transaction lists into canonical expected records ready for the reconcile engine. When to use: - When ingesting parsed pain.001 files before calling reconcile. - When mapping diverse payment field structures into uniform id, amount, and reference fields. When NOT to use: - Do NOT use for bank statement entries (camt.053); use normalize_camt053 instead. - Do NOT pass raw unparsed XML text; parse or deserialize to a dictionary or list first. Behavioral transparency: Pure, deterministic, read-only data normalization.

Reconcile expected payments against observed bank-statement entries. Purpose: Matches expected payment instructions (e.g. from pain.001) against observed bank transactions (e.g. from camt.053) and produces an explainable reconciliation report covering exact matches, short/over adjustments, split settlements (one-to-many), batch credits (many-to-one), and unmatched residuals. When to use: - When performing multi-transaction cash reconciliation between ledgers and statements. - When transparent per-match confidence scores and reason breakdowns are required for audit. When NOT to use: - Do NOT use for raw, unparsed XML files; normalize input documents first using normalize_pain001 or normalize_camt053. - Do NOT use for single-pair tuning analysis; use explain_match instead. - Do NOT use for unconstrained combinatorial invoice subsets; use reconcile_many_to_many. Behavioral transparency: Pure, deterministic, side-effect-free, read-only calculation without network or disk access.

Match statement deposits to disjoint subsets of invoices via subset-sum ILP. Purpose: Solves bounded subset-sum as an integer linear program (ILP) to pair statement deposits against matching combinations of outstanding invoice records. When to use: - When customer deposits consolidate multiple invoices or split remittances. - When one-to-one or one-to-many heuristics leave unmatched aggregates. When NOT to use: - Do NOT use for straightforward 1:1 or 1:N reconciliation where reconcile is sufficient and faster. - Do NOT use without the optional ilp extra installed (pip install reconcile-mcp[ilp]). Behavioral transparency: Deterministic ILP optimization; read-only and idempotent.

Load a named sandbox scenario and immediately return its reconciliation report. Purpose: One-call execution that loads built-in fixture records and executes the reconciliation pipeline, returning a complete explainable match report. When to use: - When performing quick verification, smoke tests, or initial agent demonstrations. - When verifying tolerance tuning against standard test cases. When NOT to use: - Do NOT use with live production data. - Do NOT use when custom expected or observed records must be supplied; use reconcile instead. Behavioral transparency: Deterministic, in-memory execution; read-only and idempotent.