Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

4.3 KB
Raw Blame
from __future__ import annotations

from typing import Any

from sqlalchemy.ext.asyncio import AsyncSession

from app.core.app_clock import app_today
from app.services import dashboard_service, report_service
from mcp_server.auth import CallContext
from mcp_server.registry import tool
from mcp_server.tools._helpers import parse_date, resolve_workspace_id


def _pri_currency(ctx: CallContext) -> str:
    # The user model defaults to USD; reports reach into the DB for the
    # actual primary currency, so the value passed here is just the fallback.
    return "USD"


def _serialize_report(r: Any) -> dict[str, Any]:
    if hasattr(r, "model_dump"):
        return r.model_dump(mode="json")
    return r if isinstance(r, dict) else {"value": str(r)}


@tool(
    name="get_net_worth",
    description="Net worth time series over the last N months. Use to answer 'how is my net worth trending?'",
    parameters={
        "type": "object",
        "properties": {
            "months": {"type": "integer", "minimum": 1, "maximum": 60, "default": 12},
            "interval": {"type": "string", "enum": ["daily", "weekly", "monthly", "yearly"], "default": "monthly"},
        },
        "additionalProperties": False,
    },
    tags=["read", "reports"],
)
async def get_net_worth(
    *,
    session: AsyncSession,
    ctx: CallContext,
    months: int = 12,
    interval: str = "monthly",
) -> dict[str, Any]:
    ws_id = await resolve_workspace_id(session, ctx)
    rep = await report_service.get_net_worth_report(
        session, ws_id, ctx.user_id, months=int(months), interval=interval, currency=_pri_currency(ctx)
    )
    return _serialize_report(rep)


@tool(
    name="get_income_expenses",
    description="Income vs expenses over the last N months. Use for budgeting questions.",
    parameters={
        "type": "object",
        "properties": {
            "months": {"type": "integer", "minimum": 1, "maximum": 60, "default": 12},
            "interval": {"type": "string", "enum": ["daily", "weekly", "monthly", "yearly"], "default": "monthly"},
        },
        "additionalProperties": False,
    },
    tags=["read", "reports"],
)
async def get_income_expenses(
    *,
    session: AsyncSession,
    ctx: CallContext,
    months: int = 12,
    interval: str = "monthly",
) -> dict[str, Any]:
    ws_id = await resolve_workspace_id(session, ctx)
    rep = await report_service.get_income_expenses_report(
        session, ws_id, ctx.user_id, months=int(months), interval=interval, currency=_pri_currency(ctx)
    )
    return _serialize_report(rep)


@tool(
    name="get_cash_flow",
    description="Forward-looking cash flow projection — current balance plus future bookings and recurring transactions.",
    parameters={
        "type": "object",
        "properties": {
            "months": {"type": "integer", "minimum": 1, "maximum": 24, "default": 6},
            "interval": {"type": "string", "enum": ["daily", "weekly", "monthly"], "default": "daily"},
        },
        "additionalProperties": False,
    },
    tags=["read", "reports"],
)
async def get_cash_flow(
    *,
    session: AsyncSession,
    ctx: CallContext,
    months: int = 6,
    interval: str = "daily",
) -> dict[str, Any]:
    ws_id = await resolve_workspace_id(session, ctx)
    rep = await report_service.get_cash_flow_report(
        session, ws_id, ctx.user_id, months=int(months), interval=interval, currency=_pri_currency(ctx)
    )
    return _serialize_report(rep)


@tool(
    name="get_dashboard_snapshot",
    description=(
        "One-call month snapshot: total income/expenses/savings, balances by "
        "currency, top categories. Defaults to the current month."
    ),
    parameters={
        "type": "object",
        "properties": {
            "month": {"type": "string", "format": "date", "description": "Any date inside the target month"},
        },
        "additionalProperties": False,
    },
    tags=["read", "dashboard"],
)
async def get_dashboard_snapshot(
    *,
    session: AsyncSession,
    ctx: CallContext,
    month: str | None = None,
) -> dict[str, Any]:
    target = parse_date(month) or app_today().replace(day=1)
    ws_id = await resolve_workspace_id(session, ctx)
    summary = await dashboard_service.get_summary(session, ws_id, ctx.user_id, month=target)
    if hasattr(summary, "model_dump"):
        return summary.model_dump(mode="json")
    return {"value": str(summary)}