@cubiczan/finance-engines

Deterministic finance engines for AI agents: commodity margins, loan covenants, invoice audit, AP exceptions, and five-day close — as a TypeScript library and a licensed MCP server.

LLM agents are good at judgment and bad at arithmetic. This package gives them the arithmetic: pure, offline, fully deterministic engines that always return the same numbers for the same inputs — no network, no state, no hallucinated math. Use them directly from TypeScript/JavaScript, or hand them to any MCP-compatible agent (Claude Code, Claude Desktop, Cursor, custom agents) as a stdio tool server.

Commercial software. UNLICENSED — all rights reserved. Use requires a commercial agreement: sam@cubiczan.com. See LICENSE.md and PROVENANCE.md.

Engines

• Margin — index-linked product economics for commodity processors (e.g. battery recycling): revenue/margin per tonne from assay x payable x index price, inventory mark-to-market, shock-grid price sensitivity, breakeven prices, and config-driven contract structures (grade multiplier, discount + profit share, collar, assay payables).

• Covenant — loan covenant monitoring: parse a trial balance (Xero payload or plain records), compute EBITDA / DSCR / current ratio / leverage / liquidity, evaluate against covenant thresholds with headroom, and render a signable markdown compliance certificate.

• Audit — vendor-invoice anomaly detection for procure-to-pay: duplicate invoice numbers, entry lag, overdue-unpaid, amount outliers, unit-rate changes, new charge types, unexplained credits, inconsistent tax.

• Close — multi-ERP five-day-close readiness (source freeze, subledger cutoffs, reconciliation queue, evidence bundle, exception SLA, controller sign-off) plus an AP exception taxonomy with confidence and reason codes. Operator metrics: straight-through rate, synthetic double-handling minutes, stale-input rate, hours-to-close.

Related MCP server: ETL-D MCP Server

Quickstart — library

npm install @cubiczan/finance-engines

import {
  productEconomics, sensitivity, breakevenPrices, evaluateAllContracts,
  parseXeroTrialBalance, computeMetrics, evaluateCovenants, certificateMarkdown,
  runAllAuditRules, normalizeInvoiceNumber,
  classifyApExceptions, runFiveDayClose, assessCloseReadiness,
  defaultMarginConfig, defaultCovenantConfig,
} from "@cubiczan/finance-engines";

// Margins: bring your own config/prices, or use the bundled defaults
const prices = { LI2CO3: 12000, "LME-NI": 16000, "LME-CO": 34000, "LME-CU": 9600 };
const econ = productEconomics(defaultMarginConfig, prices);
const grid = sensitivity(defaultMarginConfig, prices, "black_mass");
const be = breakevenPrices(defaultMarginConfig, prices, "black_mass");
const contracts = evaluateAllContracts(defaultMarginConfig, prices);

// Covenants: trial balance -> metrics -> evaluation -> certificate
const tb = parseXeroTrialBalance(xeroTrialBalanceJson);
const metrics = computeMetrics(tb, defaultCovenantConfig);
const results = evaluateCovenants(metrics, defaultCovenantConfig);
const certificate = certificateMarkdown(results, metrics, "Q2 2026");

// Invoice audit: plain rows in, findings out
const findings = runAllAuditRules(invoiceRows, itemRows, { today: "2026-07-03" });
normalizeInvoiceNumber("#INV20481"); // -> "20481"

// AP exceptions + five-day close: see the cookbook below
const exceptions = classifyApExceptions(invoiceRows, itemRows);
const close = runFiveDayClose(closePayload); // period, now, freeze_at, sources, …

The engine core has zero runtime dependencies (the MCP SDK is only loaded by the server entry point).

UiPath can hand invoice rows, trial balances, or contract payloads to the same deterministic tools through the uipath_handoff MCP tool or directly into the library.

Procurement-profitability integration contract

The package exports a type-only boundary for callers that coordinate covenant checks, invoice audit, AP exceptions, and a five-day close:

import {
  type CovenantCheckInput,
  type InvoiceAuditInput,
  type APExceptionsInput,
  type FiveDayCloseInput,
  type ProcurementProfitabilityAdapter,
} from "@cubiczan/finance-engines";

const adapter: ProcurementProfitabilityAdapter = {
  checkCovenant: (input: CovenantCheckInput) => {
    // Call parse/compute/evaluate/certificate from this package here.
    return callerOwnedCovenantResult(input);
  },
  auditInvoices: (input: InvoiceAuditInput) => callerOwnedInvoiceAudit(input),
  reviewAPExceptions: (input: APExceptionsInput) => callerOwnedAPReview(input),
  assessFiveDayClose: (input: FiveDayCloseInput) => callerOwnedCloseReview(input),
};

CovenantCheckInput/Output and InvoiceAuditInput/Output use the package's existing typed engine rows and results. APExceptions* and FiveDayClose* describe caller-owned workflow data; this package does not persist, fetch, or resolve those records. Every contract carries provenance.invocation: "dependency" to make that boundary explicit. This example is an integration contract only: callers must have a commercial license and must depend on this package rather than copy its internals. See LICENSE.md and PROVENANCE.md.

Quickstart — MCP server

The package ships a stdio MCP server as the finance-engines-mcp binary.

# Claude Code
claude mcp add finance-engines -- npx -y @cubiczan/finance-engines finance-engines-mcp
# or, with the package installed:
claude mcp add finance-engines -- finance-engines-mcp

Or in a generic MCP client config:

{
  "mcpServers": {
    "finance-engines": {
      "command": "npx",
      "args": ["-y", "@cubiczan/finance-engines", "finance-engines-mcp"]
    }
  }
}

All tools are deterministic and offline. Where config/prices are optional, bundled sample defaults apply — supply your own to price your own book.

MCP tools

Development

npm install
npm run build          # tsc -> dist/
npm test               # builds, then runs all suites + MCP smoke test (node --test)
npm run example:close  # multi-ERP five-day close fixture

The test suites mirror the donor Python test suites number-for-number (same fixtures, same hand-computed expectations), proving the ports equivalent.

Cookbook — five-day close + AP exceptions

PE-style close pressure (multiple ERPs, five-day clock, AP exceptions killing straight-through rate) is the operator problem this example is built against. The engines stay offline and deterministic; they do not talk to NetSuite, SAP, or Xero.

npm run example:close
# or, after a build:
node examples/five-day-close/run.mjs

The fixture (examples/five-day-close/fixture.json) is a synthetic June 2026 close across three ERPs:

It walks the six gates — source freeze, subledger cutoffs, reconciliation queue, evidence bundle, exception SLA, controller sign-off — and classifies the AP corpus (duplicates reuse normalizeInvoiceNumber; plus missing / mismatched PO, missing receipt, wrong legal entity, tax review, ownerless approval).

Library equivalent:

import { readFileSync } from "node:fs";
import { runFiveDayClose, classifyApExceptions, apExceptionTaxonomy } from "@cubiczan/finance-engines";

const payload = JSON.parse(readFileSync("examples/five-day-close/fixture.json", "utf8"));
const report = runFiveDayClose(payload);
// report.gates, report.metrics, report.exceptions, report.covenant, report.signoff_ready

Pass the same payload to MCP tools five_day_close / close_readiness ({ "close": { …payload } }) or classify_ap_exceptions.

Illustrative vs production

Deterministic engine (this package)

• Gate status, stale flags, coverage, hours-to-close, exception codes / reason codes / confidence, and the four operator metrics — given the same payload, every run returns the same JSON.

• Duplicate detection is the existing audit normalizer, not a second scheme.

• Covenant flash, when a trial balance is supplied, is the existing covenant engine (same certificate markdown).

Illustrative only (do not treat as measured ops data)

• Every timestamp in the fixture (now, freeze_at, extract times, SLA clocks). Production should inject real freeze/extract/sign-off times.

• Double-handling minutes — a published synthetic table (DEFAULT_HANDLING_MINUTES + retouch minutes), not stopwatch data.

• Entity names, checksums, invoice amounts, and the mid-close “blocked” story (stale Xero extract, open intercompany rec, past-SLA exceptions, DSCR breach).

• No ERP connector, OCR, workflow engine, or system of record. Straight- through rate here is exception-free invoices / invoices, not OCR capture rate.

Taxonomy: docs/ap-exceptions.md.
Gates and metrics: docs/five-day-close.md.

Copyright (c) 2026 Shyam Desigan (Cubiczan). All rights reserved.