Finance App

Double-entry accounting service for personal finance with MCP (Model Context Protocol) tools. Provides a ledger, budgets, and analytics over PostgreSQL, exposed as an MCP server for use by AI agents and the central chat agent.

Features

• Double-entry ledger: Accounts (ASSET, LIABILITY, EQUITY, EXPENSE, REVENUE) with enforced balance invariants
• MCP tools (exposed via SSE for agent use):
  • Accounts: create account, list accounts, get account balance
  • Transactions: transfer between accounts, record expense, record income
  • Budgets: create budget for an expense account over a date range, get available-to-spend
  • Analytics: net worth, expense breakdown, cashflow
• Health endpoint for load balancers and orchestration
• Docker Compose with PostgreSQL; runs on a shared web network for Caddy and chat-agent integration

Prerequisites

• Docker and Docker Compose
• An existing Docker network named web (e.g. docker network create web)

Quick Start

1. Clone and enter the repo

   git clone https://github.com/youssefaltai/finance-app.git
   cd finance-app
   

2. Configure environment

   cp .env.example .env
   

   Edit .env and set at least:

   • SERVICE_NAME=finance
   • SERVICE_PORT=3000
   • DATABASE_URL — PostgreSQL connection URL (default in code: postgresql+psycopg2://finance:finance@postgres:5432/finance)

3. Run with Docker

   docker compose up -d --build
   

4. Verify

   • GET http://localhost:3000/health → {"status": "ok", "service": "finance"}
   • MCP SSE endpoint: GET http://localhost:3000/mcp/sse (for agent connections)

Configuration

Variable	Description	Default
SERVICE_NAME	Service name in health response	finance
SERVICE_PORT	Port the app listens on	3000
DATABASE_URL	PostgreSQL URL (SQLAlchemy style)	postgresql+psycopg2://finance:finance@postgres:5432/finance
MCP_ENABLED	Mount MCP at /mcp	true
OPENAI_API_KEY	Not used by this service; optional	—
REDIS_URL	Not used by this service; optional	—

Integration (Caddy + Chat Agent)

• Caddy: Add a route so the service is reachable, e.g.
  handle_path /finance/* { reverse_proxy finance_app:3000 }
• Chat agent: Add this service’s MCP SSE URL to MCP_SERVER_URLS, e.g.
  MCP_SERVER_URLS=http://finance_app:3000/mcp/sse

Then the chat agent can use the finance tools (accounts, transactions, budgets, analytics) in conversation.

Project Structure

app/
  main.py       # FastAPI app: /health, MCP mounted at /mcp
  config.py     # Pydantic settings from .env
  mcp.py        # FastMCP instance, tool discovery, SSE sub-app
  db/           # SQLAlchemy models and session
  services/     # Ledger, finance, analytics business logic
  tools/        # MCP tool wrappers (account_tools, transaction_tools, budget_tools, analytics_tools)

MCP Endpoints

• SSE (agent connects here): GET /mcp/sse
• Messages (used by MCP client): /mcp/messages/

Validation Checklist

• GET /health returns {"status": "ok", "service": "finance"}
• MCP tools are available at GET /mcp/sse
• Double-entry invariant is enforced; balances and analytics are computed from journal entries

License

MIT