latest changes incl grocery list

This commit is contained in:
Joren de Graaf
2026-10-22 10:27:11 +02:00
parent aadadff69e
commit 712af2839d
12 changed files with 413 additions and 1 deletions
+25
View File
@@ -0,0 +1,25 @@
# BoomCast read-only MCP
The stateless Streamable HTTP endpoint is `POST /mcp/` on the **existing Django web server**. The normal local development command uses `127.0.0.1:8000`; MCP needs no second port or process. Use the public HTTPS Django origin for a remote client. Do not expose the local HTTP listener directly.
Run migrations, then issue a separate credential for an active user who has both `fireworks_detect.view_event` and `fireworks_detect.view_pendingevent` permissions:
```sh
python manage.py migrate
python manage.py create_mcp_token USERNAME --name "My MCP client"
```
The command prints the token once. Configure the MCP client with a Streamable HTTP URL such as `https://django.jorendegraaf.eu/mcp/` and header `Authorization: Bearer bmcp_...`. Refresh the client's MCP tools after configuring it. A sensor `ss_...` Bearer token, browser login cookie, or anonymous request cannot access the endpoint. To revoke a credential, set its `McpAccessToken.revoked_at` in Django admin/shell (or delete the record). Removing either Django view permission or deactivating the user also denies access. MCP uses the same Django user permission backend as admin; no write permissions are needed.
Available tools: `submissions_list`, `submissions_get`, `submissions_stats`, and `pending_summary`. Date filters use `YYYY-MM-DD` and apply to review date. A query covers at most 366 days; if omitted, the default is the most recent 366 days. List pages are capped at 100 items and offset 10,000. The endpoint is limited to 120 requests per minute per user. It accepts JSON responses for MCP initialize, tool discovery and tool calls. It supports no write methods or server state changes.
Only approved `Event` rows are individually available. The existing review workflow **deletes denied `PendingEvent` rows**, so historical denial statistics and manually confirmed sound classes do not exist in the current data model. MCP reports `review_outcome: approved`, `confirmed_classification: null`, and `confirmed_classification_available: false` rather than treating a YAMNet prediction as a human confirmation. Pending results contain counts only. The only location field is the existing H3 cell or a cell calculated using the configured H3 resolution; exact coordinates, audio, filenames, free-text locations, notes, sensor identity, and raw classifier responses are omitted.
For a quick protocol check after client setup:
```sh
curl -sS https://django.jorendegraaf.eu/mcp/ \
-H "Authorization: Bearer $BOOMCAST_MCP_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
Binary file not shown.
Binary file not shown.
Binary file not shown.
+11 -1
View File
@@ -10,10 +10,20 @@ from django.urls import path, reverse
from django.utils.html import format_html, format_html_join from django.utils.html import format_html, format_html_join
from django.utils.translation import gettext as _, gettext_lazy, ngettext from django.utils.translation import gettext as _, gettext_lazy, ngettext
from .models import BrowserProcessingSettings, BurstCapture, BurstSession, ClassificationRule, Event, ManualReportRevision, PendingEvent, Sensor from .models import BrowserProcessingSettings, BurstCapture, BurstSession, ClassificationRule, Event, ManualReportRevision, McpAccessToken, PendingEvent, Sensor
from . import views as classifier_views from . import views as classifier_views
@admin.register(McpAccessToken)
class McpAccessTokenAdmin(admin.ModelAdmin):
list_display = ("user", "name", "created_at", "revoked_at")
readonly_fields = ("user", "name", "token_hash", "created_at")
fields = ("user", "name", "created_at", "revoked_at")
def has_add_permission(self, request):
return False
@admin.register(ClassificationRule) @admin.register(ClassificationRule)
class ClassificationRuleAdmin(admin.ModelAdmin): class ClassificationRuleAdmin(admin.ModelAdmin):
list_display = ("value", "rule_type", "enabled") list_display = ("value", "rule_type", "enabled")
@@ -0,0 +1,25 @@
"""Issue a separate, revocable read-only MCP credential."""
import hashlib
import secrets
from django.contrib.auth import get_user_model
from django.core.management.base import BaseCommand, CommandError
from fireworks_detect.models import McpAccessToken
class Command(BaseCommand):
help = "Issue a BoomCast MCP token for an existing user with both review view permissions."
def add_arguments(self, parser):
parser.add_argument("username")
parser.add_argument("--name", default="MCP client")
def handle(self, *args, **options):
user = get_user_model().objects.filter(username=options["username"], is_active=True).first()
if user is None or not (user.has_perm("fireworks_detect.view_event") and user.has_perm("fireworks_detect.view_pendingevent")):
raise CommandError("Active user with view_event and view_pendingevent permissions required")
token = "bmcp_" + secrets.token_urlsafe(36)
McpAccessToken.objects.create(user=user, name=options["name"], token_hash=hashlib.sha256(token.encode()).hexdigest())
self.stdout.write("Store this token securely; it is shown only once:")
self.stdout.write(token)
+225
View File
@@ -0,0 +1,225 @@
"""Stateless, read-only MCP endpoint for reviewed BoomCast metadata."""
import hashlib
import json
from datetime import timedelta
from urllib.parse import urlsplit
from django.contrib.auth import get_user_model
from django.core.cache import cache
from django.db.models import Count
from django.db.models.functions import TruncDate
from django.http import JsonResponse
from django.utils import timezone
from django.utils.dateparse import parse_date
from django.views.decorators.csrf import csrf_exempt
from .h3_utils import cell_from_coordinates
from .models import Event, PendingEvent
PROTOCOL_VERSION = "2025-06-18"
TOOLS = [
{"name": "submissions_list", "description": "Page through reviewed submissions only. Review outcome is approved; denied records are deleted by the review workflow.", "inputSchema": {"type": "object", "properties": {"date_from": {"type": "string", "format": "date"}, "date_to": {"type": "string", "format": "date"}, "classification": {"type": "string"}, "review_outcome": {"type": "string", "enum": ["approved"]}, "limit": {"type": "integer", "minimum": 1, "maximum": 100}, "offset": {"type": "integer", "minimum": 0, "maximum": 10000}}, "additionalProperties": False}},
{"name": "submissions_get", "description": "Get one reviewed submission by Event ID; pending IDs are inaccessible.", "inputSchema": {"type": "object", "properties": {"id": {"type": "integer", "minimum": 1}}, "required": ["id"], "additionalProperties": False}},
{"name": "submissions_stats", "description": "Reviewed submission counts by day, predicted class, and confirmed review outcome.", "inputSchema": {"type": "object", "properties": {"date_from": {"type": "string", "format": "date"}, "date_to": {"type": "string", "format": "date"}, "classification": {"type": "string"}, "review_outcome": {"type": "string", "enum": ["approved"]}}, "additionalProperties": False}},
{"name": "pending_summary", "description": "Only aggregate count and counts by predicted class for pending review; no individual records.", "inputSchema": {"type": "object", "properties": {}, "additionalProperties": False}},
]
def _error(code, message, request_id=None):
return {"jsonrpc": "2.0", "id": request_id, "error": {"code": code, "message": message}}
def _reply(request_id, result):
return {"jsonrpc": "2.0", "id": request_id, "result": result}
def _prediction(record):
payload = record.classifier_response if isinstance(record.classifier_response, dict) else {}
predictions = payload.get("predictions", [])
if not isinstance(predictions, list):
return []
clean = []
for item in predictions[:10]:
if not isinstance(item, dict):
continue
label, score = item.get("class"), item.get("score")
if isinstance(label, str) and len(label) <= 255 and isinstance(score, (int, float)) and not isinstance(score, bool) and 0 <= score <= 1:
clean.append({"class": label, "score": score})
return clean
def _label(record):
prediction = _prediction(record)
return prediction[0]["class"] if prediction else "unclassified"
def _summary(event):
return {"id": event.pk, "occurrence_at": event.captured_at.isoformat() if event.captured_at else None,
"submitted_at": event.submitted_at.isoformat() if event.submitted_at else None,
"reviewed_at": event.approved_at.isoformat(), "source_type": event.source_type,
"predicted_classification": _label(event), "review_outcome": "approved",
"confirmed_classification": None}
def _detail(event):
result = _summary(event)
result.update({"predictions": _prediction(event), "occurrences": event.occurrences,
"occurrence_time_approximate": event.occurrence_time_approximate,
"generalized_location_h3": event.h3_cell or cell_from_coordinates(event.latitude, event.longitude) or None})
return result
def _filters(args):
start, end = args.get("date_from"), args.get("date_to")
if start is not None:
if not isinstance(start, str) or not parse_date(start) or parse_date(start).isoformat() != start:
raise ValueError("date_from must be YYYY-MM-DD")
start = parse_date(start)
if end is not None:
if not isinstance(end, str) or not parse_date(end) or parse_date(end).isoformat() != end:
raise ValueError("date_to must be YYYY-MM-DD")
end = parse_date(end)
if start and end and (end < start or end - start > timedelta(days=366)):
raise ValueError("date range must be ordered and at most 366 days")
if not end:
end = min(timezone.localdate(), start + timedelta(days=366)) if start else timezone.localdate()
if not start:
start = end - timedelta(days=366)
outcome = args.get("review_outcome")
if outcome is not None and outcome != "approved":
raise ValueError("review_outcome must be approved")
classification = args.get("classification")
if classification is not None and (not isinstance(classification, str) or not 1 <= len(classification) <= 255):
raise ValueError("classification must be a nonempty label")
queryset = Event.objects.all()
if start:
queryset = queryset.filter(approved_at__date__gte=start)
if end:
queryset = queryset.filter(approved_at__date__lte=end)
if classification:
queryset = queryset.filter(classifier_response__predictions__0__class=classification)
return queryset
def _validate(name, args):
schema = next((item["inputSchema"] for item in TOOLS if item["name"] == name), None)
if schema is None:
raise ValueError("Unknown tool")
if not isinstance(args, dict) or set(args) - set(schema["properties"]) or set(schema.get("required", [])) - set(args):
raise ValueError("Invalid tool arguments")
for key in ("limit", "offset", "id"):
if key in args and (type(args[key]) is not int or args[key] < (1 if key != "offset" else 0) or args[key] > (100 if key == "limit" else 10000 if key == "offset" else 2147483647)):
raise ValueError(f"Invalid {key}")
def _call(name, args):
_validate(name, args)
if name == "pending_summary":
counts = {}
for pending in PendingEvent.objects.only("classifier_response").iterator(chunk_size=500):
label = _label(pending)
counts[label] = counts.get(label, 0) + 1
return {"total": sum(counts.values()), "by_predicted_classification": counts}
if name == "submissions_get":
event = Event.objects.filter(pk=args["id"]).first()
if event is None:
raise LookupError("Reviewed submission not found")
return _detail(event)
queryset = _filters(args)
if name == "submissions_list":
limit, offset = args.get("limit", 25), args.get("offset", 0)
return {"total": queryset.count(), "limit": limit, "offset": offset,
"items": [_summary(item) for item in queryset.order_by("-approved_at", "-pk")[offset:offset + limit]]}
if name == "submissions_stats":
days = list(queryset.annotate(day=TruncDate("approved_at")).values("day").annotate(count=Count("pk")).order_by("day")[:367])
classes = {}
for event in queryset.only("classifier_response").iterator(chunk_size=500):
label = _label(event)
classes[label] = classes.get(label, 0) + 1
return {"total": sum(classes.values()), "by_day": [{"date": row["day"].isoformat(), "count": row["count"]} for row in days],
"by_predicted_classification": classes, "by_review_outcome": {"approved": sum(classes.values())},
"confirmed_classification_available": False}
raise ValueError("Unknown tool")
def _principal(request):
header = request.headers.get("Authorization", "")
if not header.startswith("Bearer "):
return None
token = header[7:].strip()
if not token.startswith("bmcp_") or len(token) > 120:
return None
from .models import McpAccessToken
digest = hashlib.sha256(token.encode()).hexdigest()
credential = McpAccessToken.objects.select_related("user").filter(token_hash=digest, revoked_at__isnull=True).first()
if not credential or not credential.user.is_active:
return None
return credential.user
@csrf_exempt
def mcp_endpoint(request):
if request.method != "POST":
response = JsonResponse({"detail": "POST only"}, status=405)
response["Allow"] = "POST"
return response
origin = request.headers.get("Origin")
if origin:
parsed = urlsplit(origin)
if parsed.scheme not in ("http", "https") or parsed.netloc != request.get_host():
return JsonResponse({"detail": "Origin not allowed"}, status=403)
user = _principal(request)
if user is None:
response = JsonResponse({"detail": "MCP Bearer token required"}, status=401)
response["WWW-Authenticate"] = 'Bearer realm="BoomCast MCP"'
return response
if not user.has_perm("fireworks_detect.view_event") or not user.has_perm("fireworks_detect.view_pendingevent"):
return JsonResponse({"detail": "Review read permissions required"}, status=403)
key = f"boomcast-mcp:{user.pk}"
if not cache.add(key, 1, 60):
try:
count = cache.incr(key)
except ValueError:
cache.set(key, 1, 60)
count = 1
if count > 120:
response = JsonResponse({"detail": "Rate limit exceeded"}, status=429)
response["Retry-After"] = "60"
return response
if (request.META.get("CONTENT_LENGTH") or "").isdigit() and int(request.META["CONTENT_LENGTH"]) > 65536:
return JsonResponse(_error(-32600, "Request too large"), status=413)
if len(request.body) > 65536:
return JsonResponse(_error(-32600, "Request too large"), status=413)
try:
message = json.loads(request.body)
except (ValueError, UnicodeDecodeError):
return JsonResponse(_error(-32700, "Invalid JSON"), status=400)
if not isinstance(message, dict) or message.get("jsonrpc") != "2.0" or not isinstance(message.get("method"), str):
return JsonResponse(_error(-32600, "Invalid request"), status=400)
request_id, method = message.get("id"), message["method"]
if method == "notifications/initialized" and "id" not in message:
from django.http import HttpResponse
return HttpResponse(status=202)
if "id" not in message or not (isinstance(request_id, (str, int)) and not isinstance(request_id, bool)):
return JsonResponse(_error(-32600, "Request ID required"), status=400)
if method == "initialize":
result = {"protocolVersion": PROTOCOL_VERSION, "capabilities": {"tools": {}}, "serverInfo": {"name": "boomcast-readonly", "version": "1.0.0"}}
elif method == "tools/list":
result = {"tools": TOOLS}
elif method == "tools/call":
params = message.get("params")
if not isinstance(params, dict) or not isinstance(params.get("name"), str):
return JsonResponse(_error(-32602, "Invalid tool call", request_id))
try:
output = _call(params["name"], params.get("arguments", {}))
except ValueError as error:
result = {"content": [{"type": "text", "text": str(error)}], "isError": True}
except LookupError:
result = {"content": [{"type": "text", "text": "Reviewed submission not found"}], "isError": True}
else:
result = {"content": [{"type": "text", "text": json.dumps(output, ensure_ascii=False)}], "structuredContent": output}
else:
return JsonResponse(_error(-32601, "Method not found", request_id))
response = JsonResponse(_reply(request_id, result))
response["Cache-Control"] = "no-store"
return response
@@ -0,0 +1,27 @@
# Generated by Django 6.1.1 on 2026-10-16 15:29
import django.db.models.deletion
from django.conf import settings
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [
('fireworks_detect', '0015_burstsession_burstcapture'),
migrations.swappable_dependency(settings.AUTH_USER_MODEL),
]
operations = [
migrations.CreateModel(
name='McpAccessToken',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('name', models.CharField(max_length=100)),
('token_hash', models.CharField(max_length=64, unique=True)),
('created_at', models.DateTimeField(auto_now_add=True)),
('revoked_at', models.DateTimeField(blank=True, null=True)),
('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='boomcast_mcp_tokens', to=settings.AUTH_USER_MODEL)),
],
),
]
+13
View File
@@ -489,3 +489,16 @@ class FieldNoteAssociation(models.Model):
if not self._state.adding: if not self._state.adding:
raise ValidationError("Association history is append-only.") raise ValidationError("Association history is append-only.")
return super().save(*args, **kwargs) return super().save(*args, **kwargs)
class McpAccessToken(models.Model):
"""Revocable credential for read-only MCP access; never stores the raw token."""
user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name="boomcast_mcp_tokens")
name = models.CharField(max_length=100)
token_hash = models.CharField(max_length=64, unique=True)
created_at = models.DateTimeField(auto_now_add=True)
revoked_at = models.DateTimeField(null=True, blank=True)
def __str__(self):
return f"{self.user}: {self.name}"
+85
View File
@@ -0,0 +1,85 @@
import hashlib
import json
from django.contrib.auth.models import Permission, User
from django.test import TestCase, override_settings
from django.urls import reverse
from .models import Event, McpAccessToken, PendingEvent, Sensor
@override_settings(ALLOWED_HOSTS=["testserver"])
class McpTests(TestCase):
def setUp(self):
self.url = reverse("boomcast_mcp")
self.user = User.objects.create_user("review_reader", password="unused")
self.user.user_permissions.add(*Permission.objects.filter(codename__in=["view_event", "view_pendingevent"], content_type__app_label="fireworks_detect"))
self.token = "bmcp_test_read_only"
McpAccessToken.objects.create(user=self.user, name="test", token_hash=hashlib.sha256(self.token.encode()).hexdigest())
self.pending = PendingEvent.objects.create(original_filename="private.wav", classifier_response={"predictions": [{"class": "Fireworks", "score": 0.9}]}, latitude="52.123456", longitude="5.123456")
self.event = Event.objects.create(original_filename="reviewed.wav", classifier_response={"predictions": [{"class": "Fireworks", "score": 0.8}]}, latitude="52.123456", longitude="5.123456")
def call(self, method, params=None, token=None):
return self.client.post(self.url, data=json.dumps({"jsonrpc": "2.0", "id": 1, "method": method, "params": params or {}}), content_type="application/json", HTTP_AUTHORIZATION=f"Bearer {token or self.token}")
def result(self, name, args=None):
return self.call("tools/call", {"name": name, "arguments": args or {}}).json()["result"]
def test_discovery_and_reviewed_only(self):
self.assertEqual(self.call("initialize").json()["result"]["serverInfo"]["name"], "boomcast-readonly")
self.assertEqual(len(self.call("tools/list").json()["result"]["tools"]), 4)
listing = self.result("submissions_list")["structuredContent"]
self.assertEqual(listing["total"], 1)
self.assertEqual(listing["items"][0]["id"], self.event.pk)
self.assertNotIn("private.wav", json.dumps(listing))
other_pending = PendingEvent.objects.create(original_filename="another-private.wav", classifier_response={})
self.assertTrue(self.result("submissions_get", {"id": other_pending.pk})["isError"])
def test_pending_is_aggregate_only(self):
result = self.result("pending_summary")["structuredContent"]
self.assertEqual(result, {"total": 1, "by_predicted_classification": {"Fireworks": 1}})
self.assertNotIn("private.wav", json.dumps(result))
def test_details_are_privacy_limited(self):
result = self.result("submissions_get", {"id": self.event.pk})["structuredContent"]
self.assertEqual(result["predictions"][0]["score"], 0.8)
for key in ("latitude", "longitude", "audio_file", "original_filename", "sensor", "location", "device_metadata"):
self.assertNotIn(key, result)
self.assertIsNotNone(result["generalized_location_h3"])
def test_pagination_filter_and_stats(self):
Event.objects.create(original_filename="other.wav", classifier_response={"predictions": [{"class": "Thunder", "score": 0.7}]})
self.assertEqual(self.result("submissions_list", {"limit": 1, "offset": 1})["structuredContent"]["total"], 2)
filtered = self.result("submissions_list", {"classification": "Thunder"})["structuredContent"]
self.assertEqual(filtered["total"], 1)
stats = self.result("submissions_stats")["structuredContent"]
self.assertEqual(stats["by_predicted_classification"], {"Fireworks": 1, "Thunder": 1})
self.assertEqual(stats["by_review_outcome"], {"approved": 2})
self.assertTrue(self.result("submissions_list", {"limit": 101})["isError"])
self.assertTrue(self.result("submissions_stats", {"date_from": "2020-01-01", "date_to": "2026-01-01"})["isError"])
def test_auth_permissions_and_no_mutations(self):
self.assertEqual(self.client.post(self.url, data="{}", content_type="application/json").status_code, 401)
sensor = Sensor.objects.create(name="test sensor")
self.assertEqual(self.call("tools/list", token=sensor.issue_token()).status_code, 401)
self.user.user_permissions.clear()
self.assertEqual(self.call("tools/list").status_code, 403)
self.user.is_superuser = True
self.user.save(update_fields=["is_superuser"])
self.assertEqual(self.call("tools/call", {"name": "approve", "arguments": {}}).json()["result"]["isError"], True)
self.assertEqual(PendingEvent.objects.count(), 1)
self.assertEqual(self.client.get(self.url, HTTP_AUTHORIZATION=f"Bearer {self.token}").status_code, 405)
def test_revocation_inactive_user_and_origin(self):
self.assertEqual(self.call("tools/list", token="bmcp_wrong").status_code, 401)
self.assertEqual(self.client.post(self.url, data='{"jsonrpc":"2.0","id":1,"method":"tools/list"}', content_type="application/json", HTTP_AUTHORIZATION=f"Bearer {self.token}", HTTP_ORIGIN="https://evil.example").status_code, 403)
self.user.is_active = False
self.user.save(update_fields=["is_active"])
self.assertEqual(self.call("tools/list").status_code, 401)
self.user.is_active = True
self.user.save(update_fields=["is_active"])
credential = McpAccessToken.objects.get(user=self.user)
from django.utils import timezone
credential.revoked_at = timezone.now()
credential.save(update_fields=["revoked_at"])
self.assertEqual(self.call("tools/list").status_code, 401)
Binary file not shown.
+2
View File
@@ -7,11 +7,13 @@ from django.urls import include, path, re_path
from django.views.static import serve from django.views.static import serve
from fireworks_detect.views import dashboard_view, submit_sensor_pending from fireworks_detect.views import dashboard_view, submit_sensor_pending
from fireworks_detect.mcp import mcp_endpoint
from hello.views import hello_view from hello.views import hello_view
from members.language_views import set_anonymous_language from members.language_views import set_anonymous_language
from members.views import register from members.views import register
urlpatterns = [ urlpatterns = [
path("mcp/", mcp_endpoint, name="boomcast_mcp"),
path("language/", set_anonymous_language, name="set_anonymous_language"), path("language/", set_anonymous_language, name="set_anonymous_language"),
path("admin/", admin.site.urls), path("admin/", admin.site.urls),
path("login/", auth_views.LoginView.as_view(template_name="members/login.html"), name="login"), path("login/", auth_views.LoginView.as_view(template_name="members/login.html"), name="login"),