{"_id":"@cubiczan/finance-engines","name":"@cubiczan/finance-engines","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@cubiczan/finance-engines","version":"0.1.0","description":"Deterministic finance engines for AI agents: commodity margins, loan covenants, invoice audit - as a TypeScript library and a licensed MCP server.","license":"UNLICENSED","author":{"name":"Shyam Desigan","email":"sam@cubiczan.com","url":"Cubiczan"},"type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"bin":{"finance-engines-mcp":"dist/mcp-server.js"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.json","prepack":"npm run build","test":"npm run build && node --test test/*.test.mjs"},"engines":{"node":">=18.17"},"keywords":["finance","mcp","margin","covenant","invoice-audit","deterministic","agents"],"dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","zod":"^3.23.8"},"devDependencies":{"@types/node":"^22.10.0","typescript":"^5.5.4"},"gitHead":"4224caf8f3463dad875a97b8a9bd21cf416c8175","_id":"@cubiczan/finance-engines@0.1.0","_nodeVersion":"26.0.0","_npmVersion":"12.0.2","dist":{"integrity":"sha512-/dPAzK/Y4cgnJTNRlpW+p8N8imdWmmTbPVqE0eCnSl/f0wB9oUrmcQzy+O8o6HQ9UHsLMb8orpbQSifiU5ixYA==","shasum":"b729fa961c652a391d4ed8c8eeb04262edbb19bc","tarball":"https://registry.npmjs.org/@cubiczan/finance-engines/-/finance-engines-0.1.0.tgz","fileCount":23,"unpackedSize":78228,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAbITL1OLU5jQF6hT0ayKOzgDQWwV6xGw16h3zivCtLUAiBfEAJMJcOTMlNUYj2KG8m58yMePhTzZk6szqSLezhRcw=="}]},"_npmUser":{"name":"cubiczan","email":"icohangar@gmail.com"},"directories":{},"maintainers":[{"name":"cubiczan","email":"icohangar@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/finance-engines_0.1.0_1788432937204_0.9321924849655445"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-03T10:55:36.989Z","0.1.0":"2026-09-03T10:55:37.352Z","modified":"2026-09-03T10:55:37.623Z"},"maintainers":[{"name":"cubiczan","email":"icohangar@gmail.com"}],"description":"Deterministic finance engines for AI agents: commodity margins, loan covenants, invoice audit - as a TypeScript library and a licensed MCP server.","keywords":["finance","mcp","margin","covenant","invoice-audit","deterministic","agents"],"author":{"name":"Shyam Desigan","email":"sam@cubiczan.com","url":"Cubiczan"},"license":"UNLICENSED","readme":"# @cubiczan/finance-engines\n\n**Deterministic finance engines for AI agents: commodity margins, loan\ncovenants, invoice audit — as a TypeScript library and a licensed MCP\nserver.**\n\nLLM agents are good at judgment and bad at arithmetic. This package gives them\nthe arithmetic: three pure, offline, fully deterministic engines that always\nreturn the same numbers for the same inputs — no network, no state, no\nhallucinated math. Use them directly from TypeScript/JavaScript, or hand them\nto any MCP-compatible agent (Claude Code, Claude Desktop, Cursor, custom\nagents) as a stdio tool server.\n\n> **Commercial software.** `UNLICENSED` — all rights reserved. Use requires a\n> commercial agreement: **sam@cubiczan.com**. See [LICENSE.md](./LICENSE.md)\n> and [PROVENANCE.md](./PROVENANCE.md).\n\n## Engines\n\n- **Margin** — index-linked product economics for commodity processors (e.g.\n  battery recycling): revenue/margin per tonne from assay x payable x index\n  price, inventory mark-to-market, shock-grid price sensitivity, breakeven\n  prices, and config-driven contract structures (grade multiplier, discount +\n  profit share, collar, assay payables).\n- **Covenant** — loan covenant monitoring: parse a trial balance (Xero payload\n  or plain records), compute EBITDA / DSCR / current ratio / leverage /\n  liquidity, evaluate against covenant thresholds with headroom, and render a\n  signable markdown compliance certificate.\n- **Audit** — vendor-invoice anomaly detection for procure-to-pay: duplicate\n  invoice numbers, entry lag, overdue-unpaid, amount outliers, unit-rate\n  changes, new charge types, unexplained credits, inconsistent tax.\n\n## Quickstart — library\n\n```bash\nnpm install @cubiczan/finance-engines\n```\n\n```ts\nimport {\n  productEconomics, sensitivity, breakevenPrices, evaluateAllContracts,\n  parseXeroTrialBalance, computeMetrics, evaluateCovenants, certificateMarkdown,\n  runAllAuditRules, normalizeInvoiceNumber,\n  defaultMarginConfig, defaultCovenantConfig,\n} from \"@cubiczan/finance-engines\";\n\n// Margins: bring your own config/prices, or use the bundled defaults\nconst prices = { LI2CO3: 12000, \"LME-NI\": 16000, \"LME-CO\": 34000, \"LME-CU\": 9600 };\nconst econ = productEconomics(defaultMarginConfig, prices);\nconst grid = sensitivity(defaultMarginConfig, prices, \"black_mass\");\nconst be = breakevenPrices(defaultMarginConfig, prices, \"black_mass\");\nconst contracts = evaluateAllContracts(defaultMarginConfig, prices);\n\n// Covenants: trial balance -> metrics -> evaluation -> certificate\nconst tb = parseXeroTrialBalance(xeroTrialBalanceJson);\nconst metrics = computeMetrics(tb, defaultCovenantConfig);\nconst results = evaluateCovenants(metrics, defaultCovenantConfig);\nconst certificate = certificateMarkdown(results, metrics, \"Q2 2026\");\n\n// Invoice audit: plain rows in, findings out\nconst findings = runAllAuditRules(invoiceRows, itemRows, { today: \"2026-07-03\" });\nnormalizeInvoiceNumber(\"#INV20481\"); // -> \"20481\"\n```\n\nThe engine core has **zero runtime dependencies** (the MCP SDK is only loaded\nby the server entry point).\n\n## Quickstart — MCP server\n\nThe package ships a stdio MCP server as the `finance-engines-mcp` binary.\n\n```bash\n# Claude Code\nclaude mcp add finance-engines -- npx -y @cubiczan/finance-engines finance-engines-mcp\n# or, with the package installed:\nclaude mcp add finance-engines -- finance-engines-mcp\n```\n\nOr in a generic MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"finance-engines\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cubiczan/finance-engines\", \"finance-engines-mcp\"]\n    }\n  }\n}\n```\n\nAll tools are deterministic and offline. Where `config`/`prices` are optional,\nbundled sample defaults apply — supply your own to price your own book.\n\n## MCP tools\n\n| Tool | Engine | What it does |\n|---|---|---|\n| `product_margins` | margin | Revenue, cost, and margin per MT per product, with metal contributions and inventory mark |\n| `price_sensitivity` | margin | Margin/MT scenario grid under uniform and per-metal price shocks |\n| `breakeven` | margin | Implied per-metal index prices at which a product's margin hits zero |\n| `evaluate_contracts` | margin | Evaluate grade-multiplier / profit-share / collar / assay-payables contract structures at spot |\n| `parse_trial_balance` | covenant | Flatten a Xero Reports/TrialBalance payload into netted section balances |\n| `compute_covenant_metrics` | covenant | EBITDA, DSCR, current ratio, leverage, liquidity, etc. from a trial balance |\n| `evaluate_covenants` | covenant | Test metrics against covenant thresholds with % headroom |\n| `compliance_certificate` | covenant | End-to-end signable markdown covenant certificate for a period |\n| `audit_invoices` | audit | Run all eight invoice anomaly rules over supplied invoice/item rows |\n| `normalize_invoice_number` | audit | Canonicalize an invoice number for duplicate detection |\n\n## Development\n\n```bash\nnpm install\nnpm run build   # tsc -> dist/\nnpm test        # builds, then runs all ported suites + MCP smoke test (node --test)\n```\n\nThe test suites mirror the donor Python test suites number-for-number (same\nfixtures, same hand-computed expectations), proving the ports equivalent.\n\n---\n\nCopyright (c) 2026 Shyam Desigan (Cubiczan). All rights reserved.\n","readmeFilename":"README.md","_rev":"1-7e1a0ca1ddaebe5fc6986006b0cc40db"}