FinSight

Ask financial questions. Get answers grounded in real transaction data.

Quick start · Try it · MCP tools · Roadmap

FinSight is an MCP-powered payments analytics service. Financial data stays behind bounded, auditable tools, allowing an AI host to retrieve facts without generating or executing raw SQL.

Demo question: “Which merchants had unusual chargeback spikes?” Grounded answer: “Detected 1 merchant chargeback anomaly: Ember Games.”

✨ What works today

• Generate deterministic synthetic payment data for eight merchants.

• Query transactions through safe filters instead of raw SQL.

• Compare merchant volume and chargeback performance.

• Detect chargeback-rate anomalies against a rolling baseline.

• Use every operation through REST or Model Context Protocol.

• Return the supporting rows with each chat answer.

🧭 Architecture

flowchart LR
    A[Analyst or AI host] -->|Natural language| B[FastAPI gateway]
    A -->|MCP call| C[MCP server]
    B --> D[Grounded assistant]
    D --> E[Bounded analytics tools]
    C --> E
    E -->|Parameterized queries| F[(SQLite payments DB)]
    F -->|Facts and evidence| E
    E --> B
    E --> C

The assistant never receives database credentials or a raw-SQL tool. Both interfaces reuse the same analytics boundary.

🚀 Quick start

Requires Python 3.10+.

py -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt
.venv\Scripts\python -m app.seed --rows 25000
.venv\Scripts\python -m uvicorn app.api:app --reload

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m app.seed --rows 25000
.venv/bin/python -m uvicorn app.api:app --reload

Once running, choose an entry point:

💬 Try it

Ask the grounded chat baseline about chargebacks:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8000/api/chat `
  -ContentType application/json `
  -Body '{"question":"Which merchants had unusual chargeback spikes?"}'

{
  "answer": "Detected 1 merchant chargeback anomaly(s): Ember Games.",
  "tools_used": ["detect_anomalies"],
  "data": [
    {
      "merchant_id": "m_006",
      "merchant_name": "Ember Games",
      "baseline_chargeback_rate_pct": 2.12,
      "recent_chargeback_rate_pct": 14.55,
      "z_score": 10.16
    }
  ]
}

Exact rates vary with the day the deterministic dataset is generated.

Other useful prompts:

• Which merchant had the highest transaction volume?

• Show me a merchant summary.

• Return the most recent transactions.

🧰 MCP tools

Returns recent payments filtered by merchant, date range, or chargeback status. Results are capped at 500 rows.

Aggregates transaction count, payment volume, chargeback count, and chargeback rate by merchant.

Compares each merchant’s recent chargeback rate with its historical baseline and returns merchants above a configurable z-score threshold.

REST equivalents

🗂️ Project map

app/
├── api.py          # FastAPI routes and MCP mount
├── assistant.py    # Deterministic question router
├── analytics.py    # Auditable financial queries
├── database.py     # SQLite schema and connection lifecycle
├── mcp_server.py   # MCP tool definitions
└── seed.py         # Synthetic payment generator
tests/
├── test_analytics.py
└── test_mcp.py

✅ Verify it

.venv\Scripts\python -m unittest -v

The tests verify all three analytics paths, the intentional Ember Games anomaly, input bounds, and MCP tool discovery.

🛣️ Roadmap

• Synthetic transaction dataset

• Auditable analytics boundary

• REST and MCP interfaces

• Grounded chat baseline

• PostgreSQL data layer

• LLM tool-calling orchestrator

• React chat and chart dashboard

• Authentication, RBAC, and audit log

• Live Kafka transaction feed

Current boundary

SQLite keeps the first demo zero-setup. The chat route is deliberately deterministic and supports a focused set of analyst intents; it does not pretend to understand arbitrary questions. PostgreSQL and an actual tool-calling LLM are the next useful slice.