Open-source personal finance manager. Self-hosted, privacy-first.
feat: expose advanced rules through MCP (#910)
Daniel Suhettb4772d7845df
diff --git a/backend/mcp_server/tools/__init__.py b/backend/mcp_server/tools/__init__.pyindex c7309a66..2a7aebf3 100644--- a/backend/mcp_server/tools/__init__.py+++ b/backend/mcp_server/tools/__init__.py@@ -14,4 +14,5 @@ from mcp_server.tools import ( # noqa: F401knowledge,lifecycle,groups,+ rules,)diff --git a/backend/mcp_server/tools/rules.py b/backend/mcp_server/tools/rules.pynew file mode 100644index 00000000..261cde66--- /dev/null+++ b/backend/mcp_server/tools/rules.py@@ -0,0 +1,334 @@+"""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, or date. 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}diff --git a/backend/tests/test_mcp_server_main.py b/backend/tests/test_mcp_server_main.pyindex 40ccf87b..122f3dfd 100644--- a/backend/tests/test_mcp_server_main.py+++ b/backend/tests/test_mcp_server_main.py@@ -8,6 +8,7 @@ read-only paths (avoid pgvector-dependent tools).from __future__ import annotationsimport json+import uuidimport httpximport pytest@@ -28,6 +29,32 @@ def _auth_headers(user_id) -> dict[str, str]:return {"Authorization": f"Bearer {mint_token(user_id=user_id)}"}+def _external_auth_headers(user_id) -> dict[str, str]:+ return {"Authorization": f"Bearer {mint_token(user_id=user_id, external=True)}"}+++async def _call_tool(user_id, monkeypatch, name, arguments=None, *, external=False):+ from tests.conftest import TestSessionLocal+ import mcp_server.main as mcp_main++ monkeypatch.setattr(mcp_main, "async_session_maker", TestSessionLocal)+ headers = _external_auth_headers(user_id) if external else _auth_headers(user_id)+ async with _client() as cli:+ response = await cli.post(+ "/mcp",+ json={+ "jsonrpc": "2.0",+ "id": 9,+ "method": "tools/call",+ "params": {"name": name, "arguments": arguments or {}},+ },+ headers=headers,+ )+ result = response.json()["result"]+ assert result["isError"] is False+ return result["structuredContent"]++@pytest.mark.asyncioasync def test_health_endpoint_lists_registered_tool_count(test_user):async with _client() as cli:@@ -126,6 +153,26 @@ async def test_mcp_tools_list(test_user):assert {"list_accounts", "list_categories", "list_payees", "aggregate", "list_groups"} <= names+async def test_mcp_tools_list_advertises_advanced_rule_management(test_user):+ async with _client() as cli:+ response = await cli.post(+ "/mcp",+ json={"jsonrpc": "2.0", "id": 1, "method": "tools/list"},+ headers=_auth_headers(test_user.id),+ )++ assert response.status_code == 200+ tools = response.json()["result"]["tools"]+ assert {+ "list_rules",+ "preview_rule",+ "propose_create_rule",+ "propose_update_rule",+ "propose_delete_rule",+ } <= {tool["name"] for tool in tools}++@pytest.mark.asyncioasync def test_mcp_tools_call_missing_name(test_user):async with _client() as cli:@@ -201,3 +248,232 @@ async def test_mcp_tools_call_runs_real_tool(test_user, monkeypatch):# `content[0].text` is JSON-encoded for clients that prefer text.parsed = json.loads(result["content"][0]["text"])assert "items" in parsed+++async def test_mcp_list_rules_returns_advanced_rule_definition(+ session, test_user, test_workspace, test_categories, monkeypatch+):+ from app.models.rule import Rule++ rule = Rule(+ user_id=test_user.id,+ workspace_id=test_workspace.id,+ name="Rent",+ conditions_op="and",+ conditions=[+ {"field": "payee_id", "op": "equals", "value": str(test_user.id)},+ {"field": "type", "op": "equals", "value": "debit"},+ ],+ actions=[+ {"op": "set_description", "value": "Rent"},+ {"op": "set_category", "value": str(test_categories[0].id)},+ ],+ priority=7,+ is_active=True,+ )+ session.add(rule)+ await session.commit()+ listed = await _call_tool(test_user.id, monkeypatch, "list_rules")+ assert listed == {+ "items": [+ {+ "id": str(rule.id),+ "name": "Rent",+ "conditions_op": "and",+ "conditions": rule.conditions,+ "actions": rule.actions,+ "priority": 7,+ "is_active": True,+ }+ ],+ "total": 1,+ }+++async def test_mcp_preview_rule_reports_effect_without_writing(+ session, test_user, test_transactions, monkeypatch+):+ from sqlalchemy import func, select+ from app.models.rule import Rule++ before = (await session.execute(select(func.count()).select_from(Rule))).scalar_one()+ preview = await _call_tool(+ test_user.id,+ monkeypatch,+ "preview_rule",+ {+ "conditions_op": "and",+ "conditions": [+ {"field": "description", "op": "contains", "value": "UBER"},+ {"field": "type", "op": "equals", "value": "debit"},+ ],+ "actions": [{"op": "set_description", "value": "Ride"}],+ "apply_to_existing": True,+ },+ )+ assert preview["matched"] == 1+ assert preview["will_change"] == 1+ assert preview["will_apply"] is True+ assert preview["sample"][0]["description"] == "UBER TRIP"+ after = (await session.execute(select(func.count()).select_from(Rule))).scalar_one()+ assert after == before+++async def test_mcp_propose_create_rule_preserves_advanced_draft_without_writing(+ session, test_user, test_categories, monkeypatch+):+ from sqlalchemy import func, select+ from app.models.rule import Rule++ arguments = {+ "name": "Rent",+ "conditions_op": "or",+ "conditions": [+ {"field": "description", "op": "equals", "value": "Bankslip"},+ {"field": "type", "op": "equals", "value": "debit"},+ ],+ "actions": [+ {"op": "set_description", "value": "Rent"},+ {"op": "set_category", "value": str(test_categories[0].id)},+ ],+ "priority": 5,+ "apply_to_existing": False,+ }+ before = (await session.execute(select(func.count()).select_from(Rule))).scalar_one()+ proposal = await _call_tool(+ test_user.id, monkeypatch, "propose_create_rule", arguments+ )+ assert proposal["kind"] == "create_rule"+ assert proposal["proposed"] == {+ **arguments,+ "is_active": True,+ "overwrite_existing_categories": False,+ }+ assert proposal["preview"]["will_apply"] is False+ after = (await session.execute(select(func.count()).select_from(Rule))).scalar_one()+ assert after == before+++async def test_mcp_external_apply_creates_rule_and_applies_it_to_history(+ session, test_user, test_transactions, monkeypatch+):+ from sqlalchemy import select+ from app.models.rule import Rule++ netflix = next(tx for tx in test_transactions if tx.description == "NETFLIX")+ applied = await _call_tool(+ test_user.id,+ monkeypatch,+ "propose_create_rule",+ {+ "name": "Normalize Netflix",+ "conditions": [+ {"field": "description", "op": "equals", "value": "NETFLIX"}+ ],+ "actions": [{"op": "set_description", "value": "Netflix subscription"}],+ "apply_to_existing": True,+ "apply": True,+ },+ external=True,+ )+ assert applied["applied"] is True+ assert applied["applied_count"] == 1+ rule = (+ await session.execute(select(Rule).where(Rule.id == uuid.UUID(applied["id"])))+ ).scalar_one()+ assert rule.actions == [{"op": "set_description", "value": "Netflix subscription"}]+ await session.refresh(netflix)+ assert netflix.description == "Netflix subscription"+++async def test_mcp_propose_update_rule_previews_changes_without_writing(+ session, test_user, test_rules, monkeypatch+):+ rule = test_rules[0]+ original_actions = list(rule.actions)+ proposal = await _call_tool(+ test_user.id,+ monkeypatch,+ "propose_update_rule",+ {+ "rule_id": str(rule.id),+ "actions": [{"op": "set_description", "value": "Ride"}],+ "apply_to_existing": False,+ },+ )+ assert proposal["kind"] == "update_rule"+ assert proposal["target"]["id"] == str(rule.id)+ assert proposal["changes"] == {+ "actions": [{"op": "set_description", "value": "Ride"}],+ "apply_to_existing": False,+ }+ await session.refresh(rule)+ assert rule.actions == original_actions+++async def test_mcp_external_apply_updates_rule_and_matching_history(+ session, test_user, test_rules, test_transactions, monkeypatch+):+ rule = test_rules[0]+ uber = next(tx for tx in test_transactions if tx.description == "UBER TRIP")+ applied = await _call_tool(+ test_user.id,+ monkeypatch,+ "propose_update_rule",+ {+ "rule_id": str(rule.id),+ "actions": [{"op": "set_description", "value": "Ride"}],+ "apply_to_existing": True,+ "apply": True,+ },+ external=True,+ )+ assert applied["applied"] is True+ assert applied["applied_count"] == 1+ await session.refresh(rule)+ await session.refresh(uber)+ assert rule.actions == [{"op": "set_description", "value": "Ride"}]+ assert uber.description == "Ride"+++async def test_mcp_propose_delete_rule_identifies_target_without_deleting(+ session, test_user, test_rules, monkeypatch+):+ from app.models.rule import Rule++ rule = test_rules[0]+ proposal = await _call_tool(+ test_user.id,+ monkeypatch,+ "propose_delete_rule",+ {"rule_id": str(rule.id)},+ )+ assert proposal["kind"] == "delete_rule"+ assert proposal["target"]["id"] == str(rule.id)+ assert await session.get(Rule, rule.id) is not None+++async def test_mcp_external_apply_deletes_rule(+ session, test_user, test_rules, monkeypatch+):+ from app.models.rule import Rule++ rule_id = test_rules[0].id+ applied = await _call_tool(+ test_user.id,+ monkeypatch,+ "propose_delete_rule",+ {"rule_id": str(rule_id), "apply": True},+ external=True,+ )+ assert applied["applied"] is True+ session.expire_all()+ assert await session.get(Rule, rule_id) is Nonediff --git a/frontend/src/components/agents/proposal-card.tsx b/frontend/src/components/agents/proposal-card.tsxindex 1c8ca432..9b2de4ea 100644--- a/frontend/src/components/agents/proposal-card.tsx+++ b/frontend/src/components/agents/proposal-card.tsx@@ -155,6 +155,9 @@ export function ProposalCard({ toolCallId, data }: Props) {}function kindTitle(kind: ProposalKind, t: ReturnType<typeof useTranslation>['t']): string {+ if (kind === 'create_rule') return t('rules.newRule')+ if (kind === 'update_rule') return t('rules.editRule')+ if (kind === 'delete_rule') return t('rules.confirmDeleteTitle')return t(`agents.proposal.kind.${kind}`)}@@ -182,6 +185,14 @@ function renderSummary(kind: ProposalKind, d: ProposalData, t: ReturnType<typeofpattern: String(p.match_pattern ?? '?'),category: String((p.category_name as string) ?? p.category_id ?? '?'),})+ case 'create_rule':+ return `“${String(p.name ?? '?')}”`+ case 'update_rule': {+ const changes = (d.changes || {}) as Record<string, unknown>+ return `${String(tgt.name ?? '?')} → ${Object.keys(changes).join(', ')}`+ }+ case 'delete_rule':+ return `“${String(tgt.name ?? '?')}”`case 'create_transaction':return t('agents.proposal.summary.createTransaction', {description: String(p.description ?? '?'),@@ -312,6 +323,20 @@ async function applyProposal(data: ProposalData): Promise<string | void> {})return r.id}+ case 'create_rule': {+ const r = await rules.create(p as unknown as Parameters<typeof rules.create>[0])+ return r.id+ }+ case 'update_rule': {+ const id = String((data.target as Record<string, unknown>).id)+ await rules.update(id, (data.changes || {}) as Parameters<typeof rules.update>[1])+ return id+ }+ case 'delete_rule': {+ const id = String((data.target as Record<string, unknown>).id)+ await rules.delete(id)+ return id+ }case 'create_transaction': {// If the proposal includes group splits, translate the agent's// {member_id, share_amount, share_pct} preview into the API'sdiff --git a/frontend/src/lib/agent-proposals.ts b/frontend/src/lib/agent-proposals.tsindex bb72aff2..70d85ab9 100644--- a/frontend/src/lib/agent-proposals.ts+++ b/frontend/src/lib/agent-proposals.ts@@ -3,6 +3,9 @@ export type ProposalKind =| 'create_category'| 'create_budget'| 'create_payee_rule'+ | 'create_rule'+ | 'update_rule'+ | 'delete_rule'| 'create_transaction'| 'create_recurring_transaction'| 'update_recurring_transaction'@@ -29,6 +32,7 @@ export function isProposalData(data: unknown): data is ProposalData {const k = (data as { kind?: unknown }).kindreturn typeof k === 'string' && ['categorize', 'create_category', 'create_budget', 'create_payee_rule',+ 'create_rule', 'update_rule', 'delete_rule','create_transaction', 'create_recurring_transaction','update_recurring_transaction', 'cancel_recurring_transaction','create_goal',