convez.ai
MCP ServerDados & AnalyticsIntermediário
chf3198

Receipts API MCP

chf3198/receipts-api-mcp

API de recibos com MCP nativo e dashboard web zero-setup

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor FastAPI com camada MCP integrada para análise de recibos mensais em CSV com estatísticas SQL-style agrupadas. Inclui dashboard interativo em GitHub Pages (sem setup) e suporte a filtros avançados por empresa, categoria e período.

Instalação

$npx convez-ai chf3198/receipts-api-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 2 meses
Versão
—
Issues abertas
6
Contribuidores
2

Casos de uso

  • Análise de despesas e gastos pessoais/empresariais
  • Prototipagem rápida de ferramentas MCP com dados reais
  • Dashboard de relatórios financeiros sem infra backend

Veredito

Projeto bem-executado que demonstra padrão MCP moderno com FastAPI, traz valor imediato via dashboard em GitHub Pages e oferece API limpa para integração. Código de qualidade e documentação clara tornam relevante tanto para aprendizado quanto uso prático.

README

A tradução para o português deste README ainda está na fila.

receipts-api-mcp

banner

FastAPI receipts statistics server with a built-in MCP layer and a self-contained GitHub Pages testing dashboard.

CI

Live dashboard (no setup required): https://chf3198.github.io/receipts-api-mcp/

The dashboard loads CSV data directly from this repository and processes everything in the browser. No server, no account, no cold start — open the link and it works.


Overview

LayerTechnologyNotes
Demo dashboardVanilla JS + Chart.js + Papa Parse (GitHub Pages)Always-on, zero setup — visit the link above
REST APIFastAPIRun locally: uv run receipts-api → http://localhost:8000
MCP serverfastapi-mcp (Streamable HTTP)Available at http://localhost:8000/mcp when running locally

Data source: data/receipts_2025_01.csv + data/receipts_2025_02.csv (also served from docs/data/ for the dashboard).


Quick Start

Prerequisites

Install uv (replaces pip + venv):

curl -LsSf https://astral.sh/uv/install.sh | sh

Run locally

git clone https://github.com/chf3198/receipts-api-mcp.git
cd receipts-api-mcp
uv sync
uv run uvicorn receipts_api.main:app --reload

Or via the project script:

uv run receipts-api

API is live at http://localhost:8000
Interactive docs: http://localhost:8000/docs


API Endpoints

MethodPathDescription
GET/receiptsList receipts with optional filters
GET/receipts/statsSQL-style grouped statistics
GET/receipts/companiesDistinct company names
GET/receipts/categoriesDistinct product categories
GET/receipts/{receipt_id}Single receipt by ID

Filters (all endpoints)

ParamTypeDescription
companystringExact match, case-insensitive
product_categorystringExact match, case-insensitive
date_fromISO dateEarliest receipt date (inclusive)
date_toISO dateLatest receipt date (inclusive)
statusstringe.g. Paid

/receipts/stats — grouping

?group_by=company · ?group_by=product_category · ?group_by=company,product_category

Returns receipt_count, sum/avg/min/max_total_usd, sum_discount_usd, sum_tax_usd per group.


MCP Connection

Connect any MCP-compatible client (Cursor, Claude Desktop, etc.) to the running server:

{
  "mcpServers": {
    "receipts-api": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

All five receipt endpoints are auto-exposed as MCP tools with full parameter schemas.


Development

uv sync --extra dev   # installs pytest + httpx
uv run pytest -v      # run test suite (16 smoke tests)
uv run ruff check .   # lint
uv run ruff format .  # format

Security

This is a public, read-only demo API — authentication is intentionally absent by design.

AspectPosture
CORSallow_origins=["*"], allow_methods=["GET"] — required for GitHub Pages dashboard access
AuthNone — all endpoints are public read-only; no PII or sensitive data
DataSynthetic sample CSV — no real financial records or personal information
DependenciesAudited via pip-audit + Dependabot — no known CVEs
CDN integritySRI hashes on Chart.js and PapaParse script tags
Branch protectionmaster requires PR + CI green before merge

A full Phase-0 security audit (threat model, automated scans, cross-family fleet red-team) completed 2026-06-08. See SECURITY.md for the full posture report.

Project Structure

receipts-api-mcp/
├── src/
│   └── receipts_api/
│       ├── main.py            # FastAPI app, CORS, MCP mount, entrypoint
│       ├── data_loader.py     # CSV → shared in-memory list
│       ├── utils.py           # shared filter + serialise helpers
│       └── routers/
│           ├── receipts.py    # /receipts endpoints
│           └── stats.py       # /receipts/stats grouped aggregates
├── data/                      # CSV source files (API runtime reads here)
├── docs/                      # GitHub Pages dashboard (zero-build HTML/JS)
│   ├── assets/                # dashboard images
│   ├── data/                  # CSV copy for browser fetch (Pages same-origin)
│   └── index.html             # self-contained dashboard
├── assets/
│   └── interview/             # original interview brief + setup instructions
├── tests/
│   └── test_api.py            # 16 pytest smoke tests (TestClient)
├── pyproject.toml             # uv + ruff + pytest config
├── uv.lock                    # deterministic lockfile
└── .python-version            # pins Python 3.11 for uv

Data Layout

The CSV data exists in two locations intentionally — each serves a different consumer:

PathConsumerNotes
data/API runtimedata_loader.py reads data/*.csv at startup; this is the source of truth for all API responses
docs/data/GitHub Pages dashboardThe dashboard (docs/index.html) fetches CSV files via relative path in the browser; GitHub Pages same-origin policy requires a local copy under docs/

These two copies must remain in sync. The assets/interview/ folder contains the original interview brief and setup instructions (not consumed by any runtime).

Ver o original no GitHub

Bom para

Relacionados