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

Related MCP server: Agent Ledger

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

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