aspirebooks-demo
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 │
└────────────────────────────────────┘Related MCP server: Antigravity PDF MCP Server
MCP tools
Tool | Arguments | Returns |
|
| Invoices, newest first |
|
| One invoice plus |
|
| Top-k chunks with |
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.
limitis clamped to 50 andkto 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 |
| 5 accounting notes: GST, expense categories, month-end close, invoices & credit notes, FX gains/losses (the RAG corpus) |
| Creates |
| Small dependency-free BM25 scorer |
| Heading-aware chunking (max 180 words, 30-word overlap) + embeddings → |
|
|
| 15 questions, each with its expected source document |
| Reports recall@5 and MRR for a given |
| The MCP server (stdio transport) |
| 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.pyConnect to Claude Desktop
Edit claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%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 # hybridResults with all-MiniLM-L6-v2 (15 questions):
Run | recall@5 | MRR | Misses |
Embeddings only ( | 15/15 | 1.00 | none |
Keywords only ( | 14/15 | 0.90 | "Figma subscription" (word not in the docs) |
Hybrid ( | 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
.npyfiles, 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Query your books, company data, business health, and ship invoices from your AI assistant.
Private, multimodal knowledge store for agents: hybrid search with cited, provenance-backed results.
Search your knowledge bases from any AI assistant using hybrid RAG.
Ingest, manage, and retrieve documents for RAG-powered AI applications
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI-powered querying of PDF documents using hybrid retrieval (BM25 + vector search) and retrieval-augmented generation, returning structured answers with source citations and confidence scores.-
- FlicenseNot gradedqualityDmaintenanceEnables intelligent ingestion and querying of PDF, Markdown, and text files using hybrid search that combines keyword matching and semantic embeddings with citations.2-
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to search, retrieve, and answer grounded questions over procurement documents (invoices, purchase orders, contracts, etc.) using hybrid SQL and vector retrieval.-
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants to inspect and extract invoice metadata from PDFs, Word documents, Excel files, and images, then synchronize and enrich the extracted data into an Excel ledger.-