# voiceledger-mcp

A self-hosted MCP server that gives an assistant a cash trader's books.

Ask it what you sold today, what is running out, and who still owes you, and it answers from the same
append-only ledger the trader actually writes into. Built for the Alexa+ track of Build, Ship, Shape:
Amazon Developer Hackathon.

## Why this exists

Most of the shops in a Nigerian market run on memory and a paper book. The book is honest and the
memory is not, and neither of them can answer a question while the owner's hands are full of rice.
The gap is not a dashboard. It is being able to ask out loud and get a number you can stand behind.

## What it does

Five tools and one resource, over MCP:

- `record_entry` writes a sale, expense, restock, credit or repayment.
- `day_summary` gives the day's totals and the cash that should be in the box.
- `summarise_day_for_speech` gives the same figures, phrased to be read aloud.
- `low_stock` lists what is running out, counted from restocks minus everything that left.
- `outstanding_debts` lists who still owes, largest first.
- `ledger://entries` exposes the raw book as JSON.

## The rules it will not bend

- Money is integer kobo. No float ever touches a naira figure, so a hundred small entries do not drift.
- The ledger is append-only. A mistake is corrected by writing another entry, the way a paper book works.
- Goods on credit are not sales. They leave stock, they raise a debt, and they stay out of the day's takings.
- A credit entry with no customer name is refused, because an unnamed debt is an unrecoverable one.
- A model never phrases a number. Figures are computed here and passed through verbatim; Bedrock only
  warms up the sentence around them, and if it is down the deterministic line goes out unchanged.

## Running it

```
cp .env.example .env
npm install
npm test
npm run dev
```

The Streamable HTTP endpoint is then at `http://localhost:8787/mcp`, with `/healthz` alongside it.
Set `MCP_AUTH_TOKEN` to require `Authorization: Bearer <token>`; leave it unset to run open locally.

## Stack

TypeScript and Node 20+, the Model Context Protocol SDK over Streamable HTTP (spec 2025-11-25),
Express for the endpoint, Zod for tool schemas, Vitest for the tests. Amazon Bedrock is optional and
used only for speech phrasing.

## Status

Built for the Alexa+ track of Build, Ship, Shape: Amazon Developer Hackathon (deadline 23 October 2026),
and entered in the AWS Builder and Open Source mini challenges. MIT licensed.