MCP Accounting Platform

An AI-powered accounting anomaly detection platform built with FastAPI, PostgreSQL, React, and OpenAI, featuring a complete production-ready authentication system.

🚀 Overview

MCP Accounting is a full-stack system designed to:

• Ingest financial transaction data

• Detect anomalies (large transactions, duplicates)

• Generate AI-powered explanations

• Expose functionality as MCP-style callable APIs

Related MCP server: Quack MCP

🧱 Tech Stack

Backend

• FastAPI

• SQLAlchemy

• PostgreSQL

• Passlib (bcrypt)

• JWT (authentication)

• Docker

Frontend

• React (TypeScript)

• Tailwind CSS

AI Layer

• OpenAI API (explanations)

🔐 Authentication System (Production-Ready)

Features Implemented

• ✅ User registration

• ✅ Email verification (token-based)

• ✅ Secure password hashing (bcrypt)

• ✅ Login with JWT (stateless auth)

• ✅ Password reset flow

• ✅ Protected routes (JWT-ready)

Auth Flow

Registration

1. User registers

2. User is created as inactive/unverified

3. Verification token generated (DB)

4. Email sent with verification link

Email Verification

• Token validated

• User marked as:

  • is_active = True

  • is_verified = True

• Token invalidated after use

Login

• Validates:

  • Email exists

  • Password matches (bcrypt)

  • User is verified

• Returns JWT:

{
  "access_token": "jwt-token",
  "token_type": "bearer"
}

Password Reset

1. Request reset

2. Token generated and emailed

3. User submits new password

4. Token invalidated

🏗️ Architecture

Frontend (React)
        ↓
FastAPI (API Layer)
        ↓
Service Layer (Business Logic)
        ↓
SQLAlchemy ORM
        ↓
PostgreSQL
        ↓
AI Layer (OpenAI)

🔄 Data Flow

Register → Verify Email → Login → Upload CSV
        ↓
Store Transactions → Detect Anomalies
        ↓
Generate Report → AI Explanation

🧩 API Endpoints

Auth

• POST /auth/register

• POST /auth/login

• GET /verify-email

• POST /forgot-password

• POST /reset-password

Core Features

• POST /upload-transactions

• POST /tools/get_transactions

• POST /tools/detect_large_expenses

• POST /tools/find_duplicate_payments

• POST /report/anomalies

• POST /report/anomalies/explain

🐳 Running with Docker

docker compose up --build

Access:

• API Docs: http://localhost:8000/docs

• Frontend: http://localhost:3000

⚙️ Environment Variables

DATABASE_URL=postgresql://postgres:postgres@db:5432/mcp_accounting
SECRET_KEY=your-secret-key
FRONTEND_URL=http://localhost:3000

🧠 Key Technical Decisions

1. Separation of Token Types

2. Security Practices

• Password hashing via bcrypt

• No plaintext password storage

• Token invalidation after use

• Generic login errors (no user enumeration)

3. SQLAlchemy Best Practices

• Single Base instance

• Proper model registration

• Dependency-injected DB sessions

4. Dockerized Environment

• Service-based networking (db)

• Environment-driven configuration

• Clean container rebuilds

🧪 Current Status

• ✅ End-to-end functional

• ✅ Authentication fully implemented

• ✅ Stable Docker environment

• ✅ Clean API contracts

• ✅ AI integration working

📌 Next Steps

• Alembic migrations (schema versioning)

• JWT-protected endpoints

• Role-based access control (RBAC)

• Background jobs (email queue)

• Token hashing (security hardening)

• Observability (logs + metrics)

💡 Project Purpose

This project demonstrates:

• Real-world backend architecture

• Secure authentication design

• AI integration into financial workflows

• MCP-style API exposure for automation

👨‍💻 Author

Developed as a production-style backend system to showcase:

• Python / FastAPI expertise

• System design & architecture

• Secure authentication flows

• AI-driven application design

📄 License

MIT License