Skip to content

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

11.0 KB
Raw Blame
"""Expose the existing categorization-rules API contracts through MCP."""

from __future__ import annotations

import uuid
from typing import Any

from pydantic import BaseModel
from sqlalchemy.ext.asyncio import AsyncSession

from app.api.rules import _rule_match_definition_changed
from app.schemas.rule import RuleCreate, RulePreviewRequest, RuleRead, RuleUpdate
from app.services import rule_service
from mcp_server.auth import CallContext
from mcp_server.registry import tool
from mcp_server.tools._helpers import resolve_workspace_id
from mcp_server.tools.proposals import _APPLY_FIELD, _PROPOSAL_PREFACE, _can_apply


_RULE_CAPABILITIES = (
    " Conditions combine with AND/OR and filter description, payee, notes, "
    "amount, type, account_id, payee_id, date, or status (pending/posted). "
    "Amount is signed in comparisons: credits are positive, debits negative, "
    "so `amount > 0` selects income and `amount < 0` expenses. "
    "Actions can set category, payee, or description, append notes, or ignore "
    "the transaction."
)


def _proposal_schema(
    model: type[BaseModel], *, include_rule_id: bool = False
) -> dict[str, Any]:
    schema = model.model_json_schema()
    if include_rule_id:
        schema["properties"]["rule_id"] = {"type": "string", "format": "uuid"}
        schema.setdefault("required", []).append("rule_id")
    schema["properties"]["apply"] = _APPLY_FIELD
    return schema


@tool(
    name="list_rules",
    description=(
        "List every categorization rule in the current workspace, including "
        "its ordered conditions, actions, priority, and active state. Use this "
        "before proposing an update or deletion so the user can identify the "
        "exact rule."
    ),
    parameters={
        "type": "object",
        "properties": {},
        "additionalProperties": False,
    },
    tags=["read", "rules"],
)
async def list_rules(*, session: AsyncSession, ctx: CallContext) -> dict[str, Any]:
    workspace_id = await resolve_workspace_id(session, ctx)
    rules = await rule_service.get_rules(session, workspace_id)
    items = [
        RuleRead.model_validate(rule).model_dump(mode="json", exclude={"user_id"})
        for rule in rules
    ]
    return {"items": items, "total": len(items)}


@tool(
    name="preview_rule",
    description=(
        "Preview an advanced categorization rule without saving or applying it. "
        "Returns exact match/change counts and a page of matching transactions. "
        "Use category, payee, and account UUIDs obtained from their list tools."
    )
    + _RULE_CAPABILITIES,
    parameters=RulePreviewRequest.model_json_schema(),
    tags=["read", "rules"],
)
async def preview_rule(
    *,
    session: AsyncSession,
    ctx: CallContext,
    conditions: list[dict[str, Any]],
    actions: list[dict[str, Any]] | None = None,
    conditions_op: str = "and",
    is_active: bool = True,
    apply_to_existing: bool = True,
    overwrite_existing_categories: bool = False,
    limit: int = 20,
    offset: int = 0,
) -> dict[str, Any]:
    workspace_id = await resolve_workspace_id(session, ctx)
    draft = RulePreviewRequest.model_validate(
        {
            "conditions_op": conditions_op,
            "conditions": conditions,
            "actions": actions or [],
            "is_active": is_active,
            "apply_to_existing": apply_to_existing,
            "overwrite_existing_categories": overwrite_existing_categories,
            "limit": limit,
            "offset": offset,
        }
    )
    result = await rule_service.preview_rule(
        session,
        workspace_id,
        draft.conditions_op,
        [condition.model_dump() for condition in draft.conditions],
        [action.model_dump() for action in draft.actions],
        is_active=draft.is_active,
        apply_to_existing=draft.apply_to_existing,
        overwrite_existing_categories=draft.overwrite_existing_categories,
        limit=draft.limit,
        offset=draft.offset,
    )
    return result.model_dump(mode="json")


@tool(
    name="propose_create_rule",
    description=_PROPOSAL_PREFACE
    + (
        "Preview creation of an advanced categorization rule with multiple "
        "conditions and actions. The response includes the same transaction "
        "impact preview as preview_rule. Use IDs returned by the corresponding list tools."
    )
    + _RULE_CAPABILITIES,
    parameters=_proposal_schema(RuleCreate),
    is_proposal=True,
    tags=["propose", "rules"],
)
async def propose_create_rule(
    *,
    session: AsyncSession,
    ctx: CallContext,
    name: str,
    conditions: list[dict[str, Any]],
    actions: list[dict[str, Any]],
    conditions_op: str = "and",
    priority: int = 0,
    is_active: bool = True,
    apply_to_existing: bool = True,
    overwrite_existing_categories: bool = False,
    apply: bool = False,
) -> dict[str, Any]:
    workspace_id = await resolve_workspace_id(session, ctx)
    draft = RuleCreate.model_validate(
        {
            "name": name,
            "conditions_op": conditions_op,
            "conditions": conditions,
            "actions": actions,
            "priority": priority,
            "is_active": is_active,
            "apply_to_existing": apply_to_existing,
            "overwrite_existing_categories": overwrite_existing_categories,
        }
    )
    preview = await rule_service.preview_rule(
        session,
        workspace_id,
        draft.conditions_op,
        [condition.model_dump() for condition in draft.conditions],
        [action.model_dump() for action in draft.actions],
        is_active=draft.is_active,
        apply_to_existing=draft.apply_to_existing,
        overwrite_existing_categories=draft.overwrite_existing_categories,
    )
    proposal = {
        "kind": "create_rule",
        "proposed": draft.model_dump(mode="json"),
        "preview": preview.model_dump(mode="json"),
        "apply_endpoint": "POST /api/rules",
    }
    if not _can_apply(ctx, apply):
        return proposal

    created = await rule_service.create_rule(session, workspace_id, ctx.user_id, draft)
    applied_count = (
        await rule_service.apply_single_rule(
            session,
            workspace_id,
            created,
            overwrite_existing_categories=draft.overwrite_existing_categories,
        )
        if draft.apply_to_existing
        else 0
    )
    return {
        **proposal,
        "applied": True,
        "id": str(created.id),
        "applied_count": applied_count,
    }


@tool(
    name="propose_update_rule",
    description=_PROPOSAL_PREFACE
    + (
        "Preview changes to an existing categorization rule and their impact. "
        "Call list_rules first and pass only the fields the user wants changed."
    )
    + _RULE_CAPABILITIES,
    parameters=_proposal_schema(RuleUpdate, include_rule_id=True),
    is_proposal=True,
    tags=["propose", "rules"],
)
async def propose_update_rule(
    *,
    session: AsyncSession,
    ctx: CallContext,
    rule_id: str,
    name: str | None = None,
    conditions_op: str | None = None,
    conditions: list[dict[str, Any]] | None = None,
    actions: list[dict[str, Any]] | None = None,
    priority: int | None = None,
    is_active: bool | None = None,
    apply_to_existing: bool | None = None,
    overwrite_existing_categories: bool = False,
    apply: bool = False,
) -> dict[str, Any]:
    workspace_id = await resolve_workspace_id(session, ctx)
    rule = await rule_service.get_rule(session, uuid.UUID(rule_id), workspace_id)
    if rule is None:
        return {"error": "rule not found"}

    changes: dict[str, Any] = {}
    for key, value in (
        ("name", name),
        ("conditions_op", conditions_op),
        ("conditions", conditions),
        ("actions", actions),
        ("priority", priority),
        ("is_active", is_active),
        ("apply_to_existing", apply_to_existing),
    ):
        if value is not None:
            changes[key] = value
    if overwrite_existing_categories:
        changes["overwrite_existing_categories"] = True
    if not changes:
        return {"error": "no changes provided"}

    update = RuleUpdate(**changes)
    current = RuleRead.model_validate(rule)
    should_apply = (
        update.apply_to_existing
        if update.apply_to_existing is not None
        else _rule_match_definition_changed(current, update)
    )
    preview = await rule_service.preview_rule(
        session,
        workspace_id,
        update.conditions_op or current.conditions_op,
        [condition.model_dump() for condition in update.conditions]
        if update.conditions is not None
        else current.conditions,
        [action.model_dump() for action in update.actions]
        if update.actions is not None
        else current.actions,
        is_active=update.is_active if update.is_active is not None else current.is_active,
        apply_to_existing=should_apply,
        overwrite_existing_categories=update.overwrite_existing_categories,
    )
    proposal = {
        "kind": "update_rule",
        "target": current.model_dump(mode="json", exclude={"user_id"}),
        "changes": update.model_dump(mode="json", exclude_unset=True),
        "preview": preview.model_dump(mode="json"),
        "apply_endpoint": f"PATCH /api/rules/{rule_id}",
    }
    if not _can_apply(ctx, apply):
        return proposal

    updated = await rule_service.update_rule(
        session, uuid.UUID(rule_id), workspace_id, update
    )
    if updated is None:
        return {"error": "rule not found"}
    applied_count = (
        await rule_service.apply_single_rule(
            session,
            workspace_id,
            updated,
            overwrite_existing_categories=update.overwrite_existing_categories,
        )
        if should_apply
        else 0
    )
    return {
        **proposal,
        "applied": True,
        "id": str(updated.id),
        "applied_count": applied_count,
    }


@tool(
    name="propose_delete_rule",
    description=_PROPOSAL_PREFACE
    + "Preview deletion of one existing categorization rule. Call list_rules first.",
    parameters={
        "type": "object",
        "properties": {
            "rule_id": {"type": "string", "format": "uuid"},
            "apply": _APPLY_FIELD,
        },
        "required": ["rule_id"],
        "additionalProperties": False,
    },
    is_proposal=True,
    tags=["propose", "rules"],
)
async def propose_delete_rule(
    *,
    session: AsyncSession,
    ctx: CallContext,
    rule_id: str,
    apply: bool = False,
) -> dict[str, Any]:
    workspace_id = await resolve_workspace_id(session, ctx)
    rule = await rule_service.get_rule(session, uuid.UUID(rule_id), workspace_id)
    if rule is None:
        return {"error": "rule not found"}
    proposal = {
        "kind": "delete_rule",
        "target": RuleRead.model_validate(rule).model_dump(
            mode="json", exclude={"user_id"}
        ),
        "apply_endpoint": f"DELETE /api/rules/{rule_id}",
    }
    if not _can_apply(ctx, apply):
        return proposal

    await rule_service.delete_rule(session, uuid.UUID(rule_id), workspace_id)
    return {**proposal, "applied": True, "id": rule_id}