FastAPI · MCP · GitHub Pages · Python 3.11
Receipts
—
Total Revenue
—
Avg Order
—
Total Discounts
—
Connect to a running Receipts API instance. Run locally with
uv run receipts-api then enter
http://localhost:8000 below.
5
REST Endpoints
GET · read-only · CORS open
5
MCP Tools
Streamable HTTP · spec 2025-03-26
16
Tests Passing
pytest · httpx · TestClient
40
Sample Records
2 CSV files · Jan–Feb 2025
All filtering, grouping, and charting runs client-side — zero server cost.
uv run receipts-api
MCP and REST share the same FastAPI app instance — zero duplication.
fastapi-mcp: zero-config MCP server
FastApiMCP(app).mount_http()
— that single line introspects the FastAPI OpenAPI schema and exposes every route as a
typed MCP tool at /mcp.
No schema files to write. No separate server process. Authentication reuses FastAPI's
Depends() system.
Core server runtime
Auto-generates OpenAPI 3.1 docs at /docs.
CORS open on all GET routes.
Model Context Protocol
Compatible: Claude Desktop, Cursor, VS Code Copilot, ChatGPT (MCP plug-in).
GitHub Pages · no build step
All CSV parsing, filtering, grouping, and charting runs in-browser. Zero backend dependency.
Dev & CI pipeline
uv sync → ruff check → pytest -v
on every PR. Pages deploy on every push to master.
| Method | Endpoint | Description | Key Parameters |
|---|---|---|---|
| GET | /receipts | List all receipts with optional filtering | company, product_category, purchase_date_from, purchase_date_to, status |
| GET | /receipts/stats | Grouped aggregates — revenue, count, avg, min, max | group_by (company | product_category | company,product_category) |
| GET | /receipts/companies | Distinct company names | — |
| GET | /receipts/categories | Distinct product category names | — |
| GET | /receipts/{receipt_id} | Single receipt by ID · 404 if not found | receipt_id (path param) |
All endpoints: read-only · CORS allow_origins=["*"] · allow_methods=["GET"] ·
Interactive docs at /docs (Swagger UI) and /redoc.
What is MCP?
The Model Context Protocol is an open standard (Anthropic / Linux Foundation) that lets
LLM clients connect to external tools and data sources through a uniform interface —
often called the "USB-C port for AI". Once connected, Claude or Cursor can call
list_receipts,
get_receipt_stats, and the other
tools directly using natural language.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json
(macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"receipts": {
"type": "streamableHttp",
"url": "http://localhost:8000/mcp"
}
}
}
Restart Claude Desktop · look for the 🔌 tools indicator.
Add to .cursor/mcp.json (Cursor) or VS Code
settings.json under mcp.servers:
{
"receipts": {
"type": "streamableHttp",
"url": "http://localhost:8000/mcp"
}
}
// Start server first:
// uv run receipts-api
// → listening on http://localhost:8000
Tools appear automatically in agent mode.
| Column | Type | Description | Sample |
|---|---|---|---|
| receipt_id | string | Unique identifier | REC-2025-0001 |
| receipt_date | ISO 8601 | Transaction date | 2025-01-03 |
| company | string | Vendor / supplier name | Northstar Software Co. |
| product_category | string | Category of goods/services | Software Licenses |
| quantity | int | Units purchased | 3 |
| unit_price_usd | float | Price per unit | 149.99 |
| discount_usd | float | Discount applied | 22.50 |
| tax_usd | float | Tax charged | 35.87 |
| total_usd | float | Final amount charged | 463.34 |
| status | enum | Payment status | paid | pending | refunded |
Built using the Megingjord Harness — an AI-agent governance framework that enforces a four-phase baton: Manager → Collaborator → Admin → Consultant on every change. Each phase emits a signed artifact before the next role activates, creating an auditable chain of custody.
View issue tracker (27 tickets) ↗Every PR triggers GitHub Actions:
uv sync --extra devruff check . (E, F, I, UP)pytest -v (16 tests)Dashboard deploys to GitHub Pages on every push to master.