# io.github.eternal-roman/ledger (npm · @eternal-roman/ledger-mcp)

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

- Trust score: 69/100 (medium)
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-18

## Components

- npm · `@eternal-roman/ledger-mcp`: 69/100 (this document), [markdown](https://verifymcp.io/servers/eternal-roman-ledger/eternal-roman-ledger-mcp.md), [page](https://verifymcp.io/servers/eternal-roman-ledger/eternal-roman-ledger-mcp)

## Channel facts

- Registry: `npm`
- Package: `@eternal-roman/ledger-mcp`
- Version: `0.19.1`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-18.

- **Supply Chain Security**: 98/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - No install/post-install scripts declared.
  - 30 of 98 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 48/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 3 days ago).
  - Publishes a security disclosure policy (SECURITY.md).
- **Schema Quality & AI Usability**: 84/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (good).
  - Tool/resource definitions use about 2047 tokens (~89/item across 23 items; 20 tools + 3 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 81/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 44% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### Claude

```bash
claude mcp add eternal-roman-ledger -- npx -y @eternal-roman/ledger-mcp
```

### Codex

```bash
codex mcp add eternal-roman-ledger -- npx -y @eternal-roman/ledger-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "eternal-roman-ledger": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@eternal-roman/ledger-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add eternal-roman-ledger --command npx --arg -y --arg @eternal-roman/ledger-mcp
```

### Hermes

```yaml
mcp_servers:
  eternal-roman-ledger:
    command: "npx"
    args: ["-y", "@eternal-roman/ledger-mcp"]
```

### Other

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

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-14 (score 69)

First indexed and scored.

## MCP tools (20)

### `money_compute` (~151 tokens)

Exact money arithmetic

Perform EXACT decimal money arithmetic with the kernel (decimal.js, never floats). Use this for every monetary calculation instead of computing in your own tokens. Ops: add, sub (same currency), mul, div (money x scalar), allocate (split by ratios, remainder to last), convert (via FX rate), compare.

Input parameters:

- `a` (object, required)
- `b`: Second operand for add/sub/compare
- `op` (string, required)
- `rate` (object): FX rate for convert
- `ratios` (array): Ratios for allocate
- `roundingMode` (string): Rounding for mul/div/convert
- `scalar` (string): Scalar for mul/div, as a decimal string

### `entry_validate` (~67 tokens)

Validate a journal entry

Run the kernel invariant check on a proposed journal entry: balanced debits=credits per currency, >=2 lines, positive amounts, no sub-scale precision, valid ISO date, no silent currency mix. Returns { ok, violations[] }. Always validate before posting.

Input parameters:

- `entry` (object, required)

### `ledger_post` (~94 tokens)

Post an entry to a ledger

Validate and apply a journal entry to a (serialized) ledger, returning the new ledger JSON plus its audit hash. The kernel refuses unbalanced state: an invalid entry is NOT posted and its violations are returned instead. Omit "ledger" to start from empty.

Input parameters:

- `entry` (object, required)
- `ledger` (object): Serialized ledger (Ledger.toJSON shape). Strict shape for MCP; kernel fromJSON does final validation.

### `ledger_balance` (~103 tokens)

Account balance

Net balance for an account in a serialized ledger, per its normal balance side. Pass "currency" for multi-currency accounts (otherwise fails closed). Returns all currencies via balancesByCurrency too.

Input parameters:

- `accountCode` (string, required)
- `asOf` (string): Optional as-of date YYYY-MM-DD
- `currency` (string)
- `ledger` (object): Serialized ledger (Ledger.toJSON shape). Strict shape for MCP; kernel fromJSON does final validation.

### `ledger_trial_balance` (~52 tokens)

Trial balance

Every account in a serialized ledger with its current net balance (one row per currency).

Input parameters:

- `ledger` (object): Serialized ledger (Ledger.toJSON shape). Strict shape for MCP; kernel fromJSON does final validation.

### `ledger_verify_equation` (~62 tokens)

Verify accounting equation

Verify Assets + Expenses = Liabilities + Equity + Income (per currency) holds for a serialized ledger. Returns { balanced }.

Input parameters:

- `ledger` (object): Serialized ledger (Ledger.toJSON shape). Strict shape for MCP; kernel fromJSON does final validation.

### `ledger_audit_hash` (~68 tokens)

Audit hash

Compute the tamper-evident SHA-256 audit-hash chain for a serialized ledger. Any change to any field or line ordering yields a different hash.

Input parameters:

- `ledger` (object): Serialized ledger (Ledger.toJSON shape). Strict shape for MCP; kernel fromJSON does final validation.

### `ledger_verify_determinism` (~71 tokens)

Verify determinism

Rebuild a serialized ledger twice and confirm the two runs are byte-for-byte identical via their audit hashes AND that the fundamental equation holds. Returns { ok, hash }.

Input parameters:

- `ledger` (object): Serialized ledger (Ledger.toJSON shape). Strict shape for MCP; kernel fromJSON does final validation.

### `trace_run` (~64 tokens)

Trace a sequence of entries

Replay a sequence of journal entries on a fresh ledger, capturing balances, the fundamental equation, and an audit-hash prefix at every step. This is the agent-facing audit trail. Fails closed with the offending step if any entry is invalid.

Input parameters:

- `entries` (array, required)

### `cite_lookup` (~80 tokens)

Look up accounting citations

Retrieve matching IFRS/GAAP facts and citations from the kernel knowledge graph for a query (e.g. "revenue recognition", "lease", "cost basis"). Use to ground claims in canon rather than asserting from memory.

Input parameters:

- `asOf` (string)
- `levers` (object): Optional dimension filters
- `query` (string, required)

### `artifact_make` (~314 tokens)

Build a canonical financial artifact

Assemble a Canonical Financial Artifact (scope, assumptions, citations, kernel plan, proof, reproducibility, auditHash) — the structured proof bundle a financial answer should carry. Every field is required and auditHash is verified, not just format-checked: it must be a digest a kernel call (ledger_post / ledger_audit_hash / ledger_verify_determinism / trace_run) actually returned in this session, or one this tool can recompute from the serialized `ledger` you pass alongside it. A fabricated value — even a well-formed one — is rejected. Validates that the kernel plan references core primitives; errors otherwise.

Input parameters:

- `assumptions` (array, required)
- `auditHash` (string, required): The exact auditHash string returned by a prior ledger_post / ledger_audit_hash / ledger_verify_determinism / trace_run call in this session — proves the claim instead of asserting it.
- `citations` (array, required): Real canon/kernel references (e.g. GAAP/IFRS cites from cite_lookup, or "core:double-entry"). Never defaulted.
- `kernelPlan` (string, required): The actual primitives used, e.g. "Money.from + createEntry + Ledger.apply + validateEntry"
- `ledger` (object): Optional: the serialized ledger the auditHash belongs to. If provided, the hash is recomputed from it and compared — useful when the hash was produced outside this server process.
- `proof` (string, required)
- `reproducibility` (string, required)
- `scope` (string, required)

### `periods_create_lock` (~37 tokens)

Create a period lock (hard close)

Create an immutable PeriodLock fact for use with guarded posting. effectiveDate <= lockDate will be rejected.

Input parameters:

- `lock` (object, required)

### `periods_guarded_post` (~79 tokens)

Guarded ledger post (respects period locks)

Like ledger_post but rejects entries whose effectiveDate falls on or before any provided period lock. Returns the same shape. Always kernel-verified.

Input parameters:

- `entry` (object, required)
- `ledger` (object): Serialized ledger (Ledger.toJSON shape). Strict shape for MCP; kernel fromJSON does final validation.
- `periodLocks` (array)

### `closing_generate_entries` (~89 tokens)

Generate closing entries to Retained Earnings

Given a (serialized) ledger snapshot and close date, returns balanced JournalEntry[] that close Income/Expense to RE using the kernel. All entries are pre-validated. Kernel verified.

Input parameters:

- `closeDate` (string, required)
- `ledger` (object): Serialized ledger (Ledger.toJSON shape). Strict shape for MCP; kernel fromJSON does final validation.
- `retainedEarnings` (object)

### `fx_compute_translation` (~91 tokens)

FX translation + CTA

Translate ledger balances at asOf using provided rates into reportingCurrency. Returns holdings, translated totals, and the exact CTA plug amount. Always kernel-verified for balance.

Input parameters:

- `asOf` (string, required)
- `ledger` (object): Serialized ledger (Ledger.toJSON shape). Strict shape for MCP; kernel fromJSON does final validation.
- `rates` (object, required)
- `reportingCurrency` (string, required)

### `depreciation_build_schedule` (~98 tokens)

Build depreciation / amortization schedule

Exact straight-line (allocate) or declining balance schedule. Input cost/salvage/life/method. Returns periods with exact Money amounts as strings. Kernel-allocate based.

Input parameters:

- `commencementDate` (string, required)
- `cost` (object, required)
- `decliningRate` (string)
- `id` (string, required)
- `method` (string, required)
- `salvage` (object, required)
- `usefulLifePeriods` (integer, required)

### `cashflow_statement` (~141 tokens)

Direct-method cash flow statement

Derive an exact direct-method cash flow statement from a serialized ledger: operating / investing / financing flows per currency, with opening and closing cash. Cash accounts are detected by convention (Asset codes starting CASH or names containing "cash") unless cashAccountCodes is supplied. Self-checks that opening + netChange === closing. Kernel verified.

Input parameters:

- `cashAccountCodes` (array): Explicit cash account codes
- `end` (string): Inclusive period end YYYY-MM-DD
- `ledger` (object): Serialized ledger (Ledger.toJSON shape). Strict shape for MCP; kernel fromJSON does final validation.
- `start` (string): Inclusive period start YYYY-MM-DD

### `reconcile_positions` (~111 tokens)

Reconcile positions against an external source

Compare ledger-derived balances against an external snapshot (exchange/custodian/bank), matched by account code AND currency. Returns per-account status (matched / mismatch / missing_in_ledger / missing_in_external) with exact diffs and an overall reconciled flag. Kernel verified.

Input parameters:

- `asOf` (string): Optional as-of date YYYY-MM-DD
- `external` (array, required)
- `ledger` (object): Serialized ledger (Ledger.toJSON shape). Strict shape for MCP; kernel fromJSON does final validation.

### `portfolio_relief` (~120 tokens)

Lot relief with holding-period classification

Reconstruct open lots and realized disposals for an asset from the ledger using FIFO / LIFO / HIFO, with exact cost basis. Each disposal is broken down per consumed lot and classified short vs long term by holding days (default threshold 365). Fails closed on oversell. Kernel verified.

Input parameters:

- `asset` (string, required)
- `ledger` (object): Serialized ledger (Ledger.toJSON shape). Strict shape for MCP; kernel fromJSON does final validation.
- `longTermThresholdDays` (integer)
- `method` (string)

### `settlement_build_entries` (~93 tokens)

Settlement-date (T+N) entries for a fill

Split a fill into trade-date entries (asset moves; cash booked as a settlement receivable on a sell / payable on a buy) and settlement-date entries (the receivable/payable is swapped for cash). All entries are kernel-validated and balanced. Returns both entry sets as JSON. Kernel verified.

Input parameters:

- `fill` (object, required)
- `lotMethod` (string)
- `settlementDate` (string, required)

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/eternal-roman-ledger/eternal-roman-ledger-mcp#diagnostics

## Score history

- 2026-08-18: 69
- 2026-08-17: 69
- 2026-08-16: 69
- 2026-08-15: 69
- 2026-08-14: 69

## Links

- npm package: https://www.npmjs.com/package/@eternal-roman/ledger-mcp
- Socket report: https://socket.dev/npm/package/@eternal-roman/ledger-mcp
- Repository: https://github.com/eternal-roman/ledger
- Changelog RSS feed: https://verifymcp.io/servers/eternal-roman-ledger/eternal-roman-ledger-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/eternal-roman-ledger/eternal-roman-ledger-mcp.json
- HTML version of this page: https://verifymcp.io/servers/eternal-roman-ledger/eternal-roman-ledger-mcp