Skip to main content
Glama
aspirebooks-demo

aspirebooks-demo

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.

Python MCP License


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     │
                                                         └────────────────────────────────────┘

Related MCP server: Antigravity PDF MCP Server

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 (it installs Python 3.12 for you).

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+):

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

{
  "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

ANTHROPIC_API_KEY=... uv run ask.py "Is a laptop an expense or a fixed asset?"

Retrieval evaluation

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers