English Français العربية

io.github.eternal-roman/ledger

Official registry AI and agents

Exact-decimal double-entry for agents. Call MCP tools; do not do money math in tokens.

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package @eternal-roman/ledger-mcp
Claude Code 
claude mcp add ledger -- npx -y @eternal-roman/ledger-mcp@0.19.1
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "ledger": {
            "command": "npx",
            "args": [
                "-y",
                "@eternal-roman/ledger-mcp@0.19.1"
            ]
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. Ledger
  2. For agents
  3. Why this exists
  4. Install (library)
  5. Layers on the kernel
  6. Verify
  7. Docs
  8. License
  9. Disclaimer

Ledger

Agents do not do money math in tokens.

Exact-decimal double-entry kernel + MCP. Fail-closed. Audit-hashed. Deterministic.

Money.from · validateEntry · Ledger.apply. Invalid entries are rejected, never posted.

For agents

Do not add, split, convert, or balance amounts yourself. Call the kernel.

npx -y @eternal-roman/ledger-mcp
{
  "mcpServers": {
    "ledger": { "command": "npx", "args": ["-y", "@eternal-roman/ledger-mcp"] }
  }
}

Then:

  1. Read ledger://canon/rules and ledger://canon/workflow.
  2. Compute with money_compute. Validate with entry_validate. Post with ledger_post.
  3. Prove with ledger_verify_equation + ledger_audit_hash. Never invent an audit hash.
  4. Ground treatments with cite_lookup. Bundle proof with artifact_make.

Rules live in AGENTS.md. Protocol: docs/CORE-PROTOCOL.md. Machine index: llms.txt. Full tool list: mcp/.

Host plugins (Grok and compatible) load /ledger-verify, /ledger-audit, /ledger-cite, /ledger-reconcile, /ledger-sim, /ledger-review from this repo. Copy AGENTS.md or skills/ledger/SKILL.md if the host has no plugin loader.

Why this exists

Token-level arithmetic is indifferent to scale, balance, and currency. The kernel is not.

FailureKernel
Float drift / sub-scaleMoney.from rejects
Unbalanced entryvalidateEntry + Ledger.apply reject
Silent currency mixPer-currency; FX must be explicit
Tamper / non-reproSHA-256 auditHash (ledger-audit-v2) + determinism harness
Ungrounded treatmentStarter IFRS/GAAP graph via cite_lookup
Exact moneyDouble-entryImmutable + audit hashDeterministicNo DBAgent / MCP
Ledgeryeskernelyesyesyesyes
dinero.jsyes———yes—
medicipartialyes——MongoDB—
Formance / TigerBeetleyesyesyespartialservice—

Install (library)

npm install @eternal-roman/ledger
import { Money, Account, AccountType, createBalancedEntry, emptyLedger, validateEntry } from '@eternal-roman/ledger';

const cash = new Account('1000', 'Cash', AccountType.Asset);
const equity = new Account('3000', 'Owner Equity', AccountType.Equity);

const contribution = createBalancedEntry(
  'cap-001', '2026-06-21', cash, equity,
  Money.from('10000', 'USD'), 'Initial capital'
);

if (!validateEntry(contribution).ok) throw new Error('Invariant violation');

const ledger = emptyLedger().apply(contribution).ledger;
ledger.balance(cash).toString(); // "10000.00 USD"

ESM and CommonJS. Kernel-only import: @eternal-roman/ledger/core.

Mechanical check (no LLM):

npx ledger-verify --scan .
npx ledger-verify --prove entries.json

Layers on the kernel

All of these emit validated JournalEntrys. None reimplement money.

  • Trading / custody — fillToEntries, deposits, withdrawals, taker/maker fees
  • Portfolio — FIFO/LIFO/HIFO lots, realized/unrealized P&L, valuePortfolio
  • Investing — time- and money-weighted returns, allocation, planRebalance
  • Crypto transfers — one-shot or two-phase in-transit + network fees
  • IFRS 16 lessee — PV liability, ROU, full schedule, golden-master to the cent
  • Close / FX / depreciation / cash flow / reconcile — period locks, CTA, schedules, direct-method cash flow

Asset scales (BTC=8, ETH=18, …) are installed with installAssetScales(defaultAssetRegistry()). Fiat is unchanged. See examples/.

Verify

npm test
npm run verify        # determinism harness
npm run verify:full   # build + typecheck + tests + versions + MCP smoke
npm run eval          # unguarded vs kernel benchmark

Docs

DocFor
AGENTS.mdAgent contract
llms.txtMachine-readable map
docs/CORE-PROTOCOL.mdZero-Skip protocol
docs/SUCCESS-CHECKLIST.mdPre-ship checklist
docs/ANTI-PATTERNS.mdWhat the kernel rejects
docs/SCOPE-AND-LAYERS.mdWhat ships today
mcp/README.mdMCP tools, resources, prompts
CONTRIBUTING.mdDeveloping this repo

Python kernel port: reference-implementations/python/ (same invariants; install an asset-scale resolver for non-fiat).

License

MIT. See LICENSE.

Disclaimer

Deterministic primitives and verification tools. Not financial, tax, legal, or accounting advice. You are responsible for inputs, assumptions, rates, jurisdiction, and compliance. Tests and benchmarks are due diligence, not a certification. See LICENSE.

Frequently asked questions

What is io.github.eternal-roman/ledger?

Exact-decimal double-entry for agents. Call MCP tools; do not do money math in tokens.

How do I install io.github.eternal-roman/ledger?

It runs on your machine. In Claude Code: claude mcp add ledger -- npx -y @eternal-roman/ledger-mcp@0.19.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.eternal-roman/ledger need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is io.github.eternal-roman/ledger open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.eternal-roman/ledger?

It is published by eternal-roman. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.