Files
WYGIWYH/app/apps/api/mcp.py
T
Herculino Trotta 4754f7e022 feat(api): serve a native MCP server at /mcp
Off unless MCP_ENABLED=true. Runs inside the web app (stateless Streamable
HTTP, JSON responses), so no extra container or supervisord program.

- Tools run the REST views in-process as the caller, so permissions,
  sharing, validation and transaction rules stay the API's.
- 11 curated tools with compact output, plus search_api/call_api to reach
  every other API endpoint from the OpenAPI schema.
- OAuth protected-resource metadata (RFC 9728) and a WWW-Authenticate hint
  on 401s, so MCP clients find the existing OAuth server and DCR.
- GET /api/transactions/summary/: totals per currency and type, optionally
  grouped by category, tag, entity, account or month.

API changes found while testing it:

- Writes no longer need Django model permissions, which nothing granted;
  access now matches the web UI (signed-in user, scoped querysets, owner-only
  edits of shared objects). API tokens and OAuth apps can now write for
  regular users.
- Account group owner is read-only; it could be set to another user.
- Reject negative installment, recurring, DCA and exchange-rate amounts, a
  zero recurrence interval, and performance on non-investment accounts.
- Accounts can be archived; group_id/exchange_currency_id are optional;
  category accepts null; currency prefix/suffix keep their spaces.
- Transactions filter by tags and entities.
- OpenAPI: separate request schemas (COMPONENT_SPLIT_REQUEST) and real
  descriptions for the viewsets and DCA chart actions.
2026-11-15 16:29:06 -03:00

682 lines
25 KiB
Python

"""Native MCP server (Streamable HTTP, stateless, JSON responses only).
Each tool runs the matching REST API view in-process, as the caller, so
permissions, sharing, filters, validation and signals stay the API's.
"""
import json
import logging
import re
from decimal import Decimal
from functools import cache
from threading import Lock
from urllib.parse import urlsplit
from django.conf import settings
from django.http import Http404
from django.test import RequestFactory
from django.urls import Resolver404, resolve
from drf_spectacular.generators import SchemaGenerator
from oauth2_provider.contrib.rest_framework import OAuth2Authentication
from rest_framework.exceptions import ParseError
from rest_framework.parsers import JSONParser
from rest_framework.permissions import IsAuthenticated
from rest_framework.renderers import JSONRenderer
from rest_framework.response import Response
from rest_framework.views import APIView
from apps.api import views
from apps.api.authentication import APITokenAuthentication
from apps.api.permissions import NotInDemoMode
from apps.common.oauth_views import _base_url
PROTOCOL_VERSIONS = ("2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05")
INSTRUCTIONS = (
"WYGIWYH is a personal finance tracker. Amounts are never negative: `type` "
"IN is income and EX is expense. `reference_date` is the month a "
"transaction counts toward: YYYY-MM in these tools, YYYY-MM-DD for recurring "
"transactions and installment plans in call_api. Use summarize_transactions for totals instead "
"of adding up search results. Look up ids with list_accounts and "
"list_categories/list_tags/list_entities. For anything else, find the "
"endpoint with search_api and run it with call_api."
)
_factory = RequestFactory()
logger = logging.getLogger(__name__)
class ToolError(Exception):
pass
def _dispatch(request, view, method, *, path="/", kwargs=None, query=None, data=None):
"""Run an API view as the MCP caller and return its response data."""
host = {"HTTP_HOST": request._request.get_host(), "secure": request.is_secure()}
if method == "get":
inner = _factory.get(path, query or {}, **host)
else:
inner = getattr(_factory, method)(
path, json.dumps(data or {}), content_type="application/json", **host
)
inner._force_auth_user = request.user
inner._force_auth_token = request.auth
response = view(inner, **(kwargs or {}))
if response.status_code >= 400:
raise ToolError(response.data)
return response.data
def _call_api(request, viewset, action, *, method="get", pk=None, query=None, data=None):
return _dispatch(
request,
viewset.as_view({method: action}),
method,
kwargs={"pk": pk} if pk is not None else None,
query=query,
data=data,
)
def _num(value):
"""'50.000000000000000000000000000000' -> '50'."""
if value is None:
return None
return format(Decimal(str(value)).normalize(), "f")
def _clean(item):
return {k: v for k, v in item.items() if v not in (None, "", [])}
def _names(items):
return [i["name"] for i in items or []]
def _transaction(t):
account = t["account"]
exchanged = t["exchanged_amount"] # {amount, prefix, suffix, ...} or None
return _clean(
{
"id": t["id"],
"date": t["date"],
"reference_date": t["reference_date"],
"type": t["type"],
"is_paid": t["is_paid"],
"amount": _num(t["amount"]),
"currency": account["currency"]["code"],
"exchanged": (
f"{exchanged['prefix']}{_num(exchanged['amount'])}{exchanged['suffix']}"
if exchanged
else None
),
"description": t["description"],
"account": {"id": account["id"], "name": account["name"]},
"category": t["category"]["name"] if t["category"] else None,
"tags": _names(t["tags"]),
"entities": _names(t["entities"]),
"notes": t["notes"],
"sub_transactions": [
{"name": s["name"], "amount": _num(s["amount"])}
for s in t["sub_transactions"]
],
"mute": t["mute"] or None,
"transfer_with": t["linked_transaction"],
"installment_plan": t["installment_plan"],
"recurring_transaction": t["recurring_transaction"],
}
)
def _page(data, compact):
return {
"count": data["count"],
"has_more": data["next"] is not None,
"results": [compact(item) for item in data["results"]],
}
# --- tools -------------------------------------------------------------------
DATE = {"type": "string", "format": "date", "description": "YYYY-MM-DD"}
MONTH = {"type": "string", "description": "YYYY-MM"}
TYPE = {"type": "string", "enum": ["IN", "EX"], "description": "IN = income, EX = expense"}
ID = {"type": "integer"}
FILTERS = {
"date_from": DATE,
"date_to": DATE,
"month_from": MONTH,
"month_to": MONTH,
"account_id": ID,
"category_id": ID,
"tag_id": ID,
"entity_id": ID,
"type": TYPE,
"is_paid": {"type": "boolean"},
"description": {"type": "string", "description": "Part of the description, case-insensitive"},
}
FILTER_PARAMS = {
"date_from": "date__gte",
"date_to": "date__lte",
"month_from": "reference_date__gte",
"month_to": "reference_date__lte",
"account_id": "account",
"category_id": "category",
"tag_id": "tags",
"entity_id": "entities",
"type": "type",
"is_paid": "is_paid",
"description": "description__icontains",
}
TRANSACTION_FIELDS = {
"account_id": ID,
"type": TYPE,
"amount": {"type": "string", "description": "Decimal, never negative"},
"date": DATE,
"reference_date": {**MONTH, "description": "YYYY-MM; when creating, defaults to the month of date"},
"description": {"type": "string"},
"is_paid": {"type": "boolean", "description": "false for a planned transaction; when creating, defaults to true"},
"category": {
"type": ["integer", "string", "null"],
"description": "Category id or name; an unknown name creates the category; null clears it",
},
"tags": {
"type": "array",
"items": {"type": ["integer", "string"]},
"description": "Tag ids or names; unknown names are created. Replaces the current tags.",
},
"entities": {
"type": "array",
"items": {"type": ["integer", "string"]},
"description": "Entity ids or names; unknown names are created. Replaces the current entities.",
},
"notes": {"type": "string"},
"mute": {"type": "boolean", "description": "Muted transactions are left out of totals"},
}
def _filters(args):
query = {}
for key, param in FILTER_PARAMS.items():
if key in args:
value = args[key]
if isinstance(value, bool):
value = str(value).lower()
elif key.startswith("month_"): # the filter takes full dates
if not re.fullmatch(r"\d{4}-\d{2}", str(value)):
raise ToolError({key: "Use YYYY-MM."})
value = f"{value}-01"
query[param] = value
return query
def _transaction_body(args):
body = {k: v for k, v in args.items() if k in TRANSACTION_FIELDS}
if "amount" in body:
body["amount"] = str(body["amount"])
return body
def list_accounts(request, args):
query = {} if args.get("include_archived") else {"is_archived": "false"}
data = _call_api(request, views.AccountViewSet, "list", query={**query, "page_size": 1000})
return [
_clean(
{
"id": a["id"],
"name": a["name"],
"group": a["group"]["name"] if a["group"] else None,
"currency": a["currency"]["code"],
"exchange_currency": (a["exchange_currency"] or {}).get("code"),
"is_asset": a["is_asset"] or None,
"is_investment": a["is_investment"] or None,
}
)
for a in data["results"]
]
def get_account_balance(request, args):
data = _call_api(request, views.AccountViewSet, "balance", pk=args["account_id"])
return {
"current_balance": _num(data["current_balance"]),
"projected_balance": _num(data["projected_balance"]),
"currency": data["currency"]["code"],
}
def _filtered_transactions(request, action, query):
"""Like _call_api, but errors name the tool's filters, not the API's."""
try:
return _call_api(request, views.TransactionViewSet, action, query=query)
except ToolError as e:
detail = e.args[0]
if isinstance(detail, dict):
names = {param: arg for arg, param in FILTER_PARAMS.items()}
detail = {names.get(k, k): v for k, v in detail.items()}
raise ToolError(detail) from e
def search_transactions(request, args):
query = _filters(args)
query["page"] = args.get("page", 1)
query["page_size"] = min(int(args.get("page_size", 50)), 100)
query["ordering"] = "-date"
return _page(_filtered_transactions(request, "list", query), _transaction)
def summarize_transactions(request, args):
query = _filters(args)
for key in ("group_by", "include_muted"):
if key in args:
query[key] = str(args[key]).lower()
rows = _filtered_transactions(request, "summary", query)
return [{**row, "total": _num(row["total"])} for row in rows]
def get_transaction(request, args):
return _transaction(
_call_api(request, views.TransactionViewSet, "retrieve", pk=args["id"])
)
def create_transaction(request, args):
return _transaction(
_call_api(
request,
views.TransactionViewSet,
"create",
method="post",
data=_transaction_body(args),
)
)
def update_transaction(request, args):
return _transaction(
_call_api(
request,
views.TransactionViewSet,
"partial_update",
method="patch",
pk=args["id"],
data=_transaction_body(args),
)
)
def delete_transaction(request, args):
_call_api(request, views.TransactionViewSet, "destroy", method="delete", pk=args["id"])
return {"deleted": args["id"]}
def _lister(viewset):
def handler(request, args):
query = {"page_size": 1000}
if not args.get("include_inactive"):
query["active"] = "true"
if args.get("name"):
query["name__icontains"] = args["name"]
data = _call_api(request, viewset, "list", query=query)
return [
_clean(
{
"id": i["id"],
"name": i["name"],
"inactive": not i["active"] or None,
"mute": i.get("mute") or None, # categories only
}
)
for i in data["results"]
]
return handler
_operations_lock = Lock()
def _operations():
# Schema generation isn't thread-safe; concurrent first calls broke it
with _operations_lock:
return _build_operations()
@cache
def _build_operations():
"""The REST API's operations from its OpenAPI schema, with $refs inlined."""
schema = SchemaGenerator().get_schema(request=None, public=True)
components = schema["components"]["schemas"]
def inline(node, depth=0):
if isinstance(node, list):
return [inline(i, depth) for i in node]
if not isinstance(node, dict):
return node
if "$ref" in node:
if depth > 4: # recursive schemas
return {"type": "object"}
return inline(components[node["$ref"].rsplit("/", 1)[-1]], depth + 1)
return {k: inline(v, depth) for k, v in node.items()}
operations = []
for path, item in schema["paths"].items():
if not path.startswith("/api/"):
continue
for method, op in item.items():
content = op.get("requestBody", {}).get("content", {})
body = content.get("application/json") or next(iter(content.values()), None)
operations.append(
_clean(
{
"method": method.upper(),
"path": path,
"summary": op.get("summary"),
"description": op.get("description"),
# name -> enum, format or type; path params are in the path
"query": {
p["name"]: (lambda s: s.get("enum") or s.get("format") or s.get("type"))(
inline(p.get("schema") or {})
)
for p in op.get("parameters", [])
if p["in"] == "query"
},
"body": inline(body["schema"]) if body else None,
}
)
)
return operations
def search_api(request, args):
words = str(args.get("query", "")).lower().split()
if not words:
return [f"{op['method']} {op['path']}" + (f" — {op['summary']}" if "summary" in op else "") for op in _operations()]
scored = []
for op in _operations():
exact = {op["method"].lower(), *op["path"].strip("/").split("/")}
head = f"{op['method']} {op['path']} {op.get('summary', '')}".lower()
text = f"{head} {op.get('description', '')}".lower()
if all(w in text for w in words):
score = sum(2 * (w in exact) + (w in head) for w in words)
scored.append((-score, len(op["path"]), op))
scored.sort(key=lambda s: s[:2])
return [op for _, _, op in scored[: min(int(args.get("limit", 5)), 20)]]
def call_api(request, args):
method = str(args["method"]).lower()
if method not in ("get", "post", "put", "patch", "delete"):
raise ToolError({"method": "Must be GET, POST, PUT, PATCH or DELETE."})
url = urlsplit(str(args["path"]))
if url.scheme or url.netloc:
raise ToolError({"path": "Pass only the path, e.g. /api/accounts/."})
path = url.path
path = path if path.endswith("/") else f"{path}/"
try:
match = resolve(path)
except Resolver404:
match = None
view_class = getattr(match.func, "cls", None) if match else None
if not (view_class and view_class.__module__.startswith("apps.api.views")):
raise ToolError({"path": "Not a WYGIWYH API endpoint; find one with search_api."})
query = {
k: str(v).lower() if isinstance(v, bool) else v
for k, v in (args.get("query") or {}).items()
}
data = _dispatch(
request, match.func, method, path=path, kwargs=match.kwargs, query=query, data=args.get("body")
)
return {"ok": True} if data is None else data
LISTER_INPUT = {
"type": "object",
"properties": {
"name": {"type": "string", "description": "Part of the name, case-insensitive"},
"include_inactive": {"type": "boolean"},
},
}
READ = {"readOnlyHint": True, "openWorldHint": False}
WRITE = {"readOnlyHint": False, "destructiveHint": False, "openWorldHint": False}
TOOLS = [
{
"name": "list_accounts",
"description": "Accounts with their group and currency. Archived accounts are left out unless include_archived is true.",
"inputSchema": {"type": "object", "properties": {"include_archived": {"type": "boolean"}}},
"annotations": READ,
"handler": list_accounts,
},
{
"name": "get_account_balance",
"description": "Current balance (paid transactions only) and projected balance (paid and unpaid) of an account.",
"inputSchema": {"type": "object", "properties": {"account_id": ID}, "required": ["account_id"]},
"annotations": READ,
"handler": get_account_balance,
},
{
"name": "search_transactions",
"description": "Transactions matching the filters, newest date first. Paginated; page_size is at most 100.",
"inputSchema": {
"type": "object",
"properties": {
**FILTERS,
"page": {"type": "integer", "minimum": 1},
"page_size": {"type": "integer", "minimum": 1, "maximum": 100},
},
},
"annotations": READ,
"handler": search_transactions,
},
{
"name": "summarize_transactions",
"description": (
"Totals and counts of the transactions matching the filters, per currency and type, "
"optionally grouped by category, tag, entity, account or month. Muted transactions and "
"those in muted categories (see list_categories) are left out unless include_muted is true. With tag or entity grouping, a transaction counts "
"once per tag/entity. Transfers between accounts count as an expense and an income."
),
"inputSchema": {
"type": "object",
"properties": {
**FILTERS,
"group_by": {"type": "string", "enum": ["category", "tag", "entity", "account", "month"]},
"include_muted": {"type": "boolean"},
},
},
"annotations": READ,
"handler": summarize_transactions,
},
{
"name": "get_transaction",
"description": "One transaction by id.",
"inputSchema": {"type": "object", "properties": {"id": ID}, "required": ["id"]},
"annotations": READ,
"handler": get_transaction,
},
{
"name": "create_transaction",
"description": "Records an income or expense. Your transaction rules run on it, as when created in the app.",
"inputSchema": {
"type": "object",
"properties": TRANSACTION_FIELDS,
"required": ["account_id", "type", "amount", "date"],
},
"annotations": WRITE,
"handler": create_transaction,
},
{
"name": "update_transaction",
"description": "Changes only the fields sent. Your transaction rules run on it, as when edited in the app.",
"inputSchema": {
"type": "object",
"properties": {"id": ID, **TRANSACTION_FIELDS},
"required": ["id"],
},
"annotations": {**WRITE, "idempotentHint": True},
"handler": update_transaction,
},
{
"name": "delete_transaction",
"description": "Deletes a transaction. Deleting either side of a transfer deletes both.",
"inputSchema": {"type": "object", "properties": {"id": ID}, "required": ["id"]},
"annotations": {**WRITE, "destructiveHint": True, "idempotentHint": True},
"handler": delete_transaction,
},
{
"name": "list_categories",
"description": "Transaction categories. Inactive ones are left out unless include_inactive is true.",
"inputSchema": LISTER_INPUT,
"annotations": READ,
"handler": _lister(views.TransactionCategoryViewSet),
},
{
"name": "list_tags",
"description": "Transaction tags. Inactive ones are left out unless include_inactive is true.",
"inputSchema": LISTER_INPUT,
"annotations": READ,
"handler": _lister(views.TransactionTagViewSet),
},
{
"name": "list_entities",
"description": "People and businesses on the other side of transactions. Inactive ones are left out unless include_inactive is true.",
"inputSchema": LISTER_INPUT,
"annotations": READ,
"handler": _lister(views.TransactionEntityViewSet),
},
{
"name": "search_api",
"description": (
"Finds REST API endpoints for anything the other tools don't cover: recurring "
"transactions, installment plans, currencies, exchange rates, account groups, "
"investment classes, DCA strategies, import runs. Returns each match's method, path, "
"parameters and JSON body schema, to use with call_api. Without a query, lists every endpoint."
),
"inputSchema": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "Words that must all appear, e.g. 'recurring list'"},
"limit": {"type": "integer", "minimum": 1, "maximum": 20, "description": "Defaults to 5"},
},
},
"annotations": READ,
"handler": search_api,
},
{
"name": "call_api",
"description": (
"Calls a REST API endpoint found with search_api, as you. Replace path parameters "
"such as {id} with values. Responses are the API's full JSON; list endpoints are "
"paginated (page, page_size). File uploads aren't supported."
),
"inputSchema": {
"type": "object",
"properties": {
"method": {"type": "string", "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"]},
"path": {"type": "string", "description": "e.g. /api/recurring-transactions/12/"},
"query": {"type": "object", "description": "Query string parameters"},
"body": {"type": "object", "description": "JSON body for POST, PUT and PATCH"},
},
"required": ["method", "path"],
},
"annotations": {**WRITE, "destructiveHint": True},
"handler": call_api,
},
]
TOOLS_BY_NAME = {tool["name"]: tool for tool in TOOLS}
# --- protocol ----------------------------------------------------------------
def _tool_result(data, is_error=False):
return {
"content": [{"type": "text", "text": json.dumps(data, ensure_ascii=False, default=str)}],
"isError": is_error,
}
class RpcError(Exception):
def __init__(self, code, message):
self.code, self.message = code, message
class MCPView(APIView):
authentication_classes = [OAuth2Authentication, APITokenAuthentication]
permission_classes = [IsAuthenticated, NotInDemoMode]
parser_classes = [JSONParser]
renderer_classes = [JSONRenderer]
schema = None # not part of the REST API docs
def initial(self, request, *args, **kwargs):
if not settings.MCP_ENABLED:
raise Http404
super().initial(request, *args, **kwargs)
def get_authenticate_header(self, request):
# Points MCP clients at the OAuth metadata (RFC 9728).
url = f"{_base_url(request)}/.well-known/oauth-protected-resource/mcp"
return f'Bearer resource_metadata="{url}"'
def handle_exception(self, exc):
# The body may be parsed during authentication, before post() runs
if isinstance(exc, ParseError):
return self._error(None, -32700, "Parse error")
return super().handle_exception(exc)
def post(self, request):
message = request.data
if (
not isinstance(message, dict)
or message.get("jsonrpc") != "2.0"
or not isinstance(message.get("method"), str)
):
return self._error(message.get("id") if isinstance(message, dict) else None, -32600, "Invalid Request")
if "id" not in message: # notification or response
return Response(status=202)
params = message.get("params") or {}
try:
result = self.handle(request, message["method"], params)
except RpcError as e:
return self._error(message["id"], e.code, e.message)
return Response({"jsonrpc": "2.0", "id": message["id"], "result": result})
def handle(self, request, method, params):
if method == "initialize":
requested = params.get("protocolVersion")
return {
"protocolVersion": requested if requested in PROTOCOL_VERSIONS else PROTOCOL_VERSIONS[0],
"capabilities": {"tools": {}},
"serverInfo": {"name": "WYGIWYH", "version": settings.APP_VERSION},
"instructions": INSTRUCTIONS,
}
if method == "ping":
return {}
if method == "tools/list":
return {"tools": [{k: v for k, v in t.items() if k != "handler"} for t in TOOLS]}
if method == "tools/call":
tool = TOOLS_BY_NAME.get(params.get("name"))
if tool is None:
raise RpcError(-32602, f"Unknown tool: {params.get('name')}")
args = params.get("arguments") or {}
if not isinstance(args, dict):
raise RpcError(-32602, "arguments must be an object")
missing = [k for k in tool["inputSchema"].get("required", []) if k not in args]
if missing:
return _tool_result({"missing": missing}, is_error=True)
try:
return _tool_result(tool["handler"](request, args))
except ToolError as e:
return _tool_result(e.args[0], is_error=True)
except Exception:
logger.exception("MCP tool %s failed", tool["name"])
return _tool_result({"detail": "Internal server error."}, is_error=True)
raise RpcError(-32601, f"Method not found: {method}")
@staticmethod
def _error(id_, code, message):
return Response({"jsonrpc": "2.0", "id": id_, "error": {"code": code, "message": message}})