aspirebooks-demo
README.md
# aspire-mcp-demo
An MCP (Model Context Protocol) server that lets an AI assistant such as Claude Desktop
**query invoices** and **answer accounting questions from a document corpus** using
hybrid RAG (embeddings + BM25), with a small retrieval evaluation harness.
> Personal learning prototype built around an accounting-product use case
> (Singapore SME bookkeeping). All data is fake. Not affiliated with or endorsed by any company.
  
---
## What it does
Ask Claude things like:
- *"Which invoices are overdue, and how much is still open on each?"* → `list_invoices` + `get_invoice`
- *"Can I claim GST on club subscription fees?"* → `search_accounting_notes`, answer grounded in the notes with citations like `[gst-basics#2]`
```
┌──────────────────┐ JSON-RPC over stdio ┌──────────────────────────────┐
│ Claude Desktop │ ────────────────────▶ │ server.py (MCPServer) │
│ (MCP host) │ ◀──────────────────── │ │
└──────────────────┘ │ list_invoices ─┐ │
│ get_invoice ──┼─▶ SQLite │ invoices.db (read-only)
│ │ │
│ search_accounting_notes ─▶ Retriever
└──────────────────────────────┘ │
┌────────────────────────┴──────────┐
│ embeddings (all-MiniLM-L6-v2) │
│ + BM25 keywords, min-max blend │
│ index/ ← ingest.py ← docs/*.md │
└────────────────────────────────────┘
```
## MCP tools
| Tool | Arguments | Returns |
|---|---|---|
| `list_invoices` | `status?` (DRAFT, ISSUED, PARTIALLY_PAID, PAID, VOID), `overdue_only?`, `limit` (1–50) | Invoices, newest first |
| `get_invoice` | `invoice_id` | One invoice plus `open_minor` (unpaid amount) |
| `search_accounting_notes` | `question`, `k` (1–8) | Top-k chunks with `id`, `heading`, `text`, `score` |
## Design decisions
- **Narrow, task-shaped tools, not `run_sql`.** The model can only do what the tools allow, and the descriptions double as API docs for the model.
- **Read-only by construction.** SQLite is opened with `mode=ro`; there are no write tools.
- **Bounded output.** `limit` is clamped to 50 and `k` to 8, so a single call can't flood the context window.
- **Money in integer minor units** (cents; JPY has 0 decimals), so there are no floating-point rounding errors.
- **Errors the model can act on.** Bad input raises `ToolError`, whose message goes back to the model (for example, the list of valid statuses).
- **stdout is the protocol.** All logging goes to stderr.
- **Hybrid retrieval.** Embeddings catch paraphrases ("Figma subscription" → software expenses); BM25 catches exact terms ("GST F5"). Scores are min-max normalized and blended with `alpha`.
- **Grounded answers.** The search tool's description tells the model to answer only from the returned chunks, cite chunk ids, and say "I don't know" when nothing relevant comes back.
## Project layout
| File | Purpose |
|---|---|
| `docs/*.md` | 5 accounting notes: GST, expense categories, month-end close, invoices & credit notes, FX gains/losses (the RAG corpus) |
| `seed.py` | Creates `invoices.db` with 40 deterministic fake invoices (SGD/USD/JPY) |
| `bm25.py` | Small dependency-free BM25 scorer |
| `ingest.py` | Heading-aware chunking (max 180 words, 30-word overlap) + embeddings → `index/` |
| `retrieval.py` | `Retriever`: hybrid dense + sparse search |
| `eval_questions.json` | 15 questions, each with its expected source document |
| `eval_retrieval.py` | Reports recall@5 and MRR for a given `alpha` |
| `server.py` | The MCP server (stdio transport) |
| `ask.py` | Optional: end-to-end RAG answer with the Claude API |
## Quick start
Requires [uv](https://docs.astral.sh/uv/) (it installs Python 3.12 for you).
```bash
git clone https://github.com/<your-username>/aspire-mcp-demo.git
cd aspire-mcp-demo
uv sync # install dependencies
uv run seed.py # -> invoices.db (40 fake invoices)
uv run ingest.py # -> index/ (18 chunks; downloads the embedding model once)
```
Test the tools in the browser with the MCP Inspector (needs Node.js 18+):
```bash
uv run mcp dev server.py
```
### Connect to Claude Desktop
Edit `claude_desktop_config.json`:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"aspirebooks-demo": {
"command": "/absolute/path/to/uv",
"args": ["--directory", "/absolute/path/to/aspire-mcp-demo", "run", "server.py"],
"env": { "HF_HUB_OFFLINE": "1" }
}
}
}
```
Use `which uv` to find the uv path. `HF_HUB_OFFLINE=1` stops the server from calling Hugging Face at startup once the model is cached by `ingest.py`. Fully quit and reopen Claude Desktop, and the three tools appear under the tools menu.
### Optional: end-to-end RAG with the Claude API
```bash
ANTHROPIC_API_KEY=... uv run ask.py "Is a laptop an expense or a fixed asset?"
```
## Retrieval evaluation
```bash
uv run eval_retrieval.py 1.0 # embeddings only
uv run eval_retrieval.py 0.0 # BM25 keywords only
uv run eval_retrieval.py 0.5 # hybrid
```
Results with `all-MiniLM-L6-v2` (15 questions):
| Run | recall@5 | MRR | Misses |
|---|---|---|---|
| Embeddings only (`alpha=1.0`) | 15/15 | 1.00 | none |
| Keywords only (`alpha=0.0`) | 14/15 | 0.90 | "Figma subscription" (word not in the docs) |
| Hybrid (`alpha=0.5`) | 15/15 | 0.96 | none |
With `MAX_WORDS=40` (21 chunks) the results were the same apart from hybrid MRR at 0.95. The sections are already short, so this corpus is too small to show a chunking effect.
## Production path
What would change for a real multi-tenant accounting product:
- **Remote transport** (Streamable HTTP) with **OAuth**: each call runs as the signed-in user, so existing role permissions apply.
- **Call existing service APIs**, not the database: the MCP server stays a thin adapter.
- **Write tools create drafts only** (for example `create_invoice_draft`); issuing or paying stays a human action in the app.
- **Per-tool admin toggles and an audit log** of every tool call.
- **Vector store** (for example pgvector) instead of `.npy` files, a reranker, and a larger eval set run in CI.
## License
MIT
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues