3v324v23 commited on
Commit
5fc690e
·
1 Parent(s): ccce867

feat(mcp): add scoped monitoring tools

Browse files

Keep activity aggregates within the verified manager scope and expose only whitelisted health statuses without operational secrets.

README.md CHANGED
@@ -577,7 +577,7 @@ Keeping the link from being passed on is done in Vimeo, not here: the page has t
577
 
578
  #### Managing the library and class rosters from Grok
579
 
580
- The app can expose a restricted [Model Context Protocol](https://modelcontextprotocol.io/) connector so a teacher can manage the digital library and basic class rosters from Grok Business without receiving a Supabase secret, Hugging Face token, or general administrator access. It exposes seven tools: the four library tools (list, prepare, publish, rename) plus `list_classes`, `prepare_class_change`, and `publish_class_change`. Class changes are limited to creating or renaming a class and adding or removing one student at a time.
581
 
582
  The connector uses the teacher's existing Supabase account through OAuth 2.1. Grok receives revocable user tokens; it never receives `SUPABASE_SECRET_KEY`. On every MCP request the app asks Supabase who the token belongs to and freshly checks that the account still has `management.access`, so removing the admin/developer role stops the connector even if Grok still has a token.
583
 
@@ -621,7 +621,19 @@ Class mutations use the same two-step rule. Useful prompts include:
621
 
622
  Grok calls `prepare_class_change` with one of `create_class`, `rename_class`, `add_student`, or `remove_student`, then displays the normalized class and email details. After the teacher checks them and explicitly confirms, Grok calls `publish_class_change` with the returned approval id. The approval lasts ten minutes, is single-use, is bound to that signed-in manager, and is refused if the class or the manager's subject scope changed meanwhile.
623
 
624
- Class listing returns only class id, name, subject, student emails, and optional class-local nicknames. The connector cannot delete a class or account, create a login account, change roles or entitlements, assign teachers, edit lessons/homework/daily videos, or read progress, grades, attempts, activity, or recordings. Those operations remain in the browser management screen where applicable. Adding an email to a class does not create a Supabase user; that student still signs in normally.
 
 
 
 
 
 
 
 
 
 
 
 
625
 
626
  The connector does not make calls to the xAI API, so an xAI developer API key and API credits are not required. Grok Business plan or connector charges, if any, are handled by xAI. To revoke one connector, revoke its grant or OAuth application in Supabase. To revoke the teacher immediately, remove their admin/developer role in the management screen; the next MCP request is refused. Existing videos and ordinary management-screen access are otherwise unaffected. Connector mutations appear in the existing management activity log when its optional `system_events` table is installed; application logs are the fallback and never contain OAuth tokens.
627
 
 
577
 
578
  #### Managing the library and class rosters from Grok
579
 
580
+ The app can expose a restricted [Model Context Protocol](https://modelcontextprotocol.io/) connector so a teacher can manage the digital library and basic class rosters, and read privacy-preserving monitoring data, from Grok Business without receiving a Supabase secret, Hugging Face token, or general administrator access. It exposes nine tools: the four library tools (list, prepare, publish, rename), `list_classes`, `prepare_class_change`, `publish_class_change`, `get_activity_timeseries`, and `get_system_health`. Class changes are limited to creating or renaming a class and adding or removing one student at a time.
581
 
582
  The connector uses the teacher's existing Supabase account through OAuth 2.1. Grok receives revocable user tokens; it never receives `SUPABASE_SECRET_KEY`. On every MCP request the app asks Supabase who the token belongs to and freshly checks that the account still has `management.access`, so removing the admin/developer role stops the connector even if Grok still has a token.
583
 
 
621
 
622
  Grok calls `prepare_class_change` with one of `create_class`, `rename_class`, `add_student`, or `remove_student`, then displays the normalized class and email details. After the teacher checks them and explicitly confirms, Grok calls `publish_class_change` with the returned approval id. The approval lasts ten minutes, is single-use, is bound to that signed-in manager, and is refused if the class or the manager's subject scope changed meanwhile.
623
 
624
+ Class listing returns only class id, name, subject, student emails, and optional class-local nicknames. The connector cannot delete a class or account, create a login account, change roles or entitlements, assign teachers, edit lessons/homework/daily videos, or read individual progress, grades, raw attempts, or recordings. Those operations remain in the browser management screen where applicable. Adding an email to a class does not create a Supabase user; that student still signs in normally.
625
+
626
+ The two monitoring tools are read-only and do not use the prepare/publish flow. `get_activity_timeseries` accepts `from_date` and `to_date` as `YYYY-MM-DD`, an `interval` of `day` or `week`, and an optional `class_id`. The inclusive range is limited to 90 non-future days. With a class id it returns only that authorized class; without one it combines only classes currently visible to the signed-in manager. The response contains aggregate attempts, the peak simultaneously active learners reported by the source buckets, and a range summary. It never contains student names, emails, ids, individual scores, answers, recordings, or exact login events.
627
+
628
+ `get_system_health` returns only `healthy`, `degraded`, `unavailable`, or `not_configured` for the application, authentication, database, model, and text-to-speech components. `not_configured` for an optional component such as text-to-speech does not by itself make the service unhealthy. A developer may also see a non-sensitive build version and revision. No caller receives raw logs, stack traces, database queries, internal URLs, paths, environment variables, tokens, credentials, or secret-presence values.
629
+
630
+ Useful read-only prompts include:
631
+
632
+ ```text
633
+ הצג גרף פעילות יומי של כיתה 12 בין 2026-10-01 ל-2026-10-26. אל תציג מידע אישי.
634
+ הצג פעילות שבועית בכל הכיתות שאני מורשה/ית לראות ב-30 הימים האחרונים.
635
+ בדוק את מצב המערכת והסבר בעברית פשוטה אם רכיב כלשהו אינו זמין.
636
+ ```
637
 
638
  The connector does not make calls to the xAI API, so an xAI developer API key and API credits are not required. Grok Business plan or connector charges, if any, are handled by xAI. To revoke one connector, revoke its grant or OAuth application in Supabase. To revoke the teacher immediately, remove their admin/developer role in the management screen; the next MCP request is refused. Existing videos and ordinary management-screen access are otherwise unaffected. Connector mutations appear in the existing management activity log when its optional `system_events` table is installed; application logs are the fallback and never contain OAuth tokens.
639
 
app/auth.py CHANGED
@@ -442,6 +442,17 @@ class SupabaseAuth:
442
  self._classes = (now + CLASSES_TTL, rows)
443
  return rows
444
 
 
 
 
 
 
 
 
 
 
 
 
445
  def save_class(self, id: int | None, name: str, emails: list[str], nicknames: dict[str, str],
446
  lessons: list[str], homeworks: list[dict] = (), dailies: list[dict] | None = None,
447
  subject: str = "", teachers: list[str] | None = None) -> None:
 
442
  self._classes = (now + CLASSES_TTL, rows)
443
  return rows
444
 
445
+ def database_health(self) -> bool:
446
+ """Perform one bounded, read-only PostgREST probe without returning table data."""
447
+ if not self.secret:
448
+ return False
449
+ try:
450
+ self._admin("/rest/v1/classes?select=id&limit=1")
451
+ except AuthUnavailable as exc:
452
+ if "answered 404" not in str(exc):
453
+ raise
454
+ return True
455
+
456
  def save_class(self, id: int | None, name: str, emails: list[str], nicknames: dict[str, str],
457
  lessons: list[str], homeworks: list[dict] = (), dailies: list[dict] | None = None,
458
  subject: str = "", teachers: list[str] | None = None) -> None:
app/grok_mcp.py CHANGED
@@ -18,6 +18,7 @@ from pydantic import AnyHttpUrl
18
 
19
  from . import library
20
  from . import class_management
 
21
  from .access import has_permission, resolve_access
22
  from .auth import AuthUnavailable
23
 
@@ -162,8 +163,9 @@ def build(app, *, approvals: ApprovalStore | None = None, limiter: MutationLimit
162
  resource_url, issuer_url = oauth_urls(app)
163
  server = MCPServer(
164
  "ihki-digital-library",
165
- instructions=("Manage only the ihki digital video library and scoped class rosters. Always prepare a change, "
166
- "show its exact effect to the teacher, and publish only after explicit confirmation."),
 
167
  token_verifier=SupabaseTokenVerifier(app),
168
  auth=AuthSettings(issuer_url=AnyHttpUrl(issuer_url), resource_server_url=AnyHttpUrl(resource_url),
169
  validate_token_resource=False, required_scopes=[]),
@@ -320,6 +322,35 @@ def build(app, *, approvals: ApprovalStore | None = None, limiter: MutationLimit
320
  class_audit("publish_class_change", current, "refused", reason=type(exc).__name__)
321
  return {"ok": False, "error": str(exc)}
322
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
323
  raw = server.streamable_http_app(
324
  streamable_http_path="/",
325
  stateless_http=True,
 
18
 
19
  from . import library
20
  from . import class_management
21
+ from . import monitoring
22
  from .access import has_permission, resolve_access
23
  from .auth import AuthUnavailable
24
 
 
163
  resource_url, issuer_url = oauth_urls(app)
164
  server = MCPServer(
165
  "ihki-digital-library",
166
+ instructions=("Manage only the ihki digital video library and scoped class rosters, and provide read-only "
167
+ "privacy-preserving monitoring. Always prepare a mutation, show its exact effect to the teacher, "
168
+ "and publish only after explicit confirmation."),
169
  token_verifier=SupabaseTokenVerifier(app),
170
  auth=AuthSettings(issuer_url=AnyHttpUrl(issuer_url), resource_server_url=AnyHttpUrl(resource_url),
171
  validate_token_resource=False, required_scopes=[]),
 
322
  class_audit("publish_class_change", current, "refused", reason=type(exc).__name__)
323
  return {"ok": False, "error": str(exc)}
324
 
325
+ @server.tool(description=("Return a read-only daily or weekly aggregate activity series for one authorized class "
326
+ "or all classes in the current manager's scope. Returns no learner identities."),
327
+ structured_output=True)
328
+ async def get_activity_timeseries(
329
+ from_date: str, to_date: str, interval: Literal["day", "week"] = "day",
330
+ class_id: int | None = None,
331
+ ) -> dict[str, Any]:
332
+ current, store = actor(), auth()
333
+ if current is None or store is None:
334
+ return {"ok": False, "error": "נתוני הפעילות אינם זמינים"}
335
+ try:
336
+ return {"ok": True, **monitoring.activity_timeseries(
337
+ store, current, from_date=from_date, to_date=to_date, interval=interval, class_id=class_id)}
338
+ except monitoring.MonitoringError as exc:
339
+ log.info("MCP activity outcome=refused actor_id=%s class_id=%s range=%s..%s reason=%s",
340
+ current.get("id"), class_id, from_date, to_date, type(exc).__name__)
341
+ return {"ok": False, "error": str(exc)}
342
+
343
+ @server.tool(description=("Return a read-only coarse application health summary. Never returns logs, errors, "
344
+ "credentials, internal addresses, or configuration values."), structured_output=True)
345
+ async def get_system_health() -> dict[str, Any]:
346
+ current = actor()
347
+ if current is None:
348
+ return {"ok": False, "error": "אין הרשאת ניהול"}
349
+ try:
350
+ return {"ok": True, **monitoring.system_health(app, current)}
351
+ except monitoring.MonitoringError as exc:
352
+ return {"ok": False, "error": str(exc)}
353
+
354
  raw = server.streamable_http_app(
355
  streamable_http_path="/",
356
  stateless_http=True,
app/main.py CHANGED
@@ -547,6 +547,8 @@ def create_app(scorer: Scorer | None = None, tts: SawtakTTS | None = None,
547
  app.state.video_link = video_link
548
  app.state.initial_class_lessons = {SUBJECT_LABELS["arabic"]: READY_LESSONS[0],
549
  SUBJECT_LABELS["math"]: algebra9()["units"][0]["id"]}
 
 
550
  app.state.mcp_server, mcp_app, app.state.mcp_http = build_grok_mcp(app)
551
  app.mount("/mcp", mcp_app, name="mcp")
552
  app.mount("/static", StaticFiles(directory=STATIC), name="static")
 
547
  app.state.video_link = video_link
548
  app.state.initial_class_lessons = {SUBJECT_LABELS["arabic"]: READY_LESSONS[0],
549
  SUBJECT_LABELS["math"]: algebra9()["units"][0]["id"]}
550
+ metadata = build_metadata()
551
+ app.state.mcp_build_info = {"version": metadata["version"], "revision": metadata["commit"][:40]}
552
  app.state.mcp_server, mcp_app, app.state.mcp_http = build_grok_mcp(app)
553
  app.mount("/mcp", mcp_app, name="mcp")
554
  app.mount("/static", StaticFiles(directory=STATIC), name="static")
app/monitoring.py ADDED
@@ -0,0 +1,157 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Read-only, privacy-preserving monitoring shared by MCP callers."""
2
+ from __future__ import annotations
3
+
4
+ from datetime import date, datetime, time, timedelta, timezone
5
+ from typing import Any, Literal
6
+ from zoneinfo import ZoneInfo
7
+
8
+ from .access import has_permission
9
+ from .auth import AuthUnavailable
10
+ from .class_management import ClassManagementError, visible_classes
11
+
12
+
13
+ LOCAL_TZ = ZoneInfo("Asia/Jerusalem")
14
+ MAX_DAYS = 90
15
+ INTERVALS = frozenset({"day", "week"})
16
+ STATUSES = frozenset({"healthy", "degraded", "unavailable", "not_configured"})
17
+
18
+
19
+ class MonitoringError(ValueError):
20
+ """A safe monitoring error suitable for returning through MCP."""
21
+
22
+
23
+ class MonitoringUnavailable(MonitoringError):
24
+ pass
25
+
26
+
27
+ def _date(value: object, label: str) -> date:
28
+ if not isinstance(value, str):
29
+ raise MonitoringError(f"{label} חייב להיות תאריך בפורמט YYYY-MM-DD")
30
+ try:
31
+ parsed = date.fromisoformat(value)
32
+ except ValueError as exc:
33
+ raise MonitoringError(f"{label} חייב להיות תאריך בפורמט YYYY-MM-DD") from exc
34
+ if parsed.isoformat() != value:
35
+ raise MonitoringError(f"{label} חייב להיות תאריך בפורמט YYYY-MM-DD")
36
+ return parsed
37
+
38
+
39
+ def validate_range(from_date: object, to_date: object, interval: object,
40
+ *, today: date | None = None) -> tuple[date, date, Literal["day", "week"]]:
41
+ start, end = _date(from_date, "from_date"), _date(to_date, "to_date")
42
+ current = today or datetime.now(LOCAL_TZ).date()
43
+ if interval not in INTERVALS:
44
+ raise MonitoringError("interval חייב להיות day או week")
45
+ if start > end:
46
+ raise MonitoringError("from_date חייב להיות לפני או שווה ל-to_date")
47
+ if start > current or end > current:
48
+ raise MonitoringError("אי אפשר לבקש טווח עתידי")
49
+ if (end - start).days + 1 > MAX_DAYS:
50
+ raise MonitoringError("אפשר לבקש עד 90 ימים")
51
+ return start, end, interval # type: ignore[return-value]
52
+
53
+
54
+ def _scope(auth: Any, actor: dict[str, Any], class_id: int | None) -> tuple[list[dict], dict[str, Any]]:
55
+ if not has_permission(actor, "management.access"):
56
+ raise MonitoringError("אין הרשאת ניהול")
57
+ try:
58
+ classes = visible_classes(auth, actor, fresh=True)
59
+ except ClassManagementError as exc:
60
+ raise MonitoringUnavailable("נתוני הפעילות אינם זמינים") from exc
61
+ if class_id is not None:
62
+ if not isinstance(class_id, int) or isinstance(class_id, bool) or class_id <= 0:
63
+ raise MonitoringError("מזהה הכיתה אינו תקין")
64
+ selected = [row for row in classes if row.get("id") == class_id]
65
+ if not selected:
66
+ raise MonitoringError("הכיתה אינה זמינה")
67
+ row = selected[0]
68
+ return selected, {"class_id": row["id"], "class_name": row.get("name", "")}
69
+ return classes, {"class_id": None, "class_name": "כל הכיתות המורשות"}
70
+
71
+
72
+ def _stamp(value: object) -> datetime:
73
+ text = str(value or "").replace("Z", "+00:00")
74
+ parsed = datetime.fromisoformat(text)
75
+ return (parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)).astimezone(LOCAL_TZ)
76
+
77
+
78
+ def _period_key(day: date, interval: str) -> date:
79
+ return day if interval == "day" else day - timedelta(days=day.weekday())
80
+
81
+
82
+ def activity_timeseries(auth: Any, actor: dict[str, Any], *, from_date: object, to_date: object,
83
+ interval: object = "day", class_id: int | None = None,
84
+ today: date | None = None) -> dict[str, Any]:
85
+ start, end, clean_interval = validate_range(from_date, to_date, interval, today=today)
86
+ classes, scope = _scope(auth, actor, class_id)
87
+ emails = {str(email).strip().lower() for row in classes for email in row.get("emails", ()) if email}
88
+ try:
89
+ users = auth.users() if emails else []
90
+ user_ids = {str(user["id"]) for user in users
91
+ if str(user.get("email") or "").strip().lower() in emails and user.get("id")}
92
+ since = datetime.combine(start, time.min, LOCAL_TZ).astimezone(timezone.utc)
93
+ raw = auth.scoped_activity(user_ids, since, 60)
94
+ except (AuthUnavailable, AttributeError, KeyError, TypeError) as exc:
95
+ raise MonitoringUnavailable("נתוני הפעילות אינם זמינים") from exc
96
+
97
+ keys: list[date] = []
98
+ cursor = start
99
+ while cursor <= end:
100
+ key = _period_key(cursor, clean_interval)
101
+ if not keys or keys[-1] != key:
102
+ keys.append(key)
103
+ cursor += timedelta(days=1)
104
+ grouped = {key: {"date": key.isoformat(), "attempts": 0, "peak_active_students": 0} for key in keys}
105
+ for item in raw.get("buckets", ()) if isinstance(raw, dict) else ():
106
+ try:
107
+ local_day = _stamp(item.get("bucket")).date()
108
+ if not start <= local_day <= end:
109
+ continue
110
+ bucket = grouped.get(_period_key(local_day, clean_interval))
111
+ if bucket is None:
112
+ continue
113
+ bucket["attempts"] += max(0, int(item.get("attempts") or 0))
114
+ bucket["peak_active_students"] = max(
115
+ bucket["peak_active_students"], max(0, int(item.get("active_students") or 0)))
116
+ except (TypeError, ValueError, OverflowError):
117
+ continue
118
+
119
+ summary = raw.get("summary") if isinstance(raw, dict) and isinstance(raw.get("summary"), dict) else {}
120
+ safe_summary = {key: max(0, int(summary.get(key) or 0))
121
+ for key in ("attempts", "active_students", "returning_students", "active_days")}
122
+ return {**scope, "from_date": start.isoformat(), "to_date": end.isoformat(),
123
+ "interval": clean_interval, "series": list(grouped.values()), "summary": safe_summary}
124
+
125
+
126
+ def system_health(app: Any, actor: dict[str, Any]) -> dict[str, Any]:
127
+ if not has_permission(actor, "management.access"):
128
+ raise MonitoringError("אין הרשאת ניהול")
129
+ state = app.state
130
+ auth = getattr(state, "auth", None)
131
+ database = "not_configured" if auth is None else "healthy"
132
+ if auth is not None:
133
+ try:
134
+ if hasattr(auth, "database_health"):
135
+ if not auth.database_health():
136
+ database = "unavailable"
137
+ else:
138
+ auth.classes(fresh=True)
139
+ except Exception: # The response deliberately never carries infrastructure exception text.
140
+ database = "unavailable"
141
+ components = {
142
+ "application": "healthy",
143
+ "authentication": "healthy" if auth is not None else "not_configured",
144
+ "database": database,
145
+ "model": "healthy" if getattr(state, "scorer", None) is not None else "unavailable",
146
+ "text_to_speech": "healthy" if getattr(state, "tts", None) is not None else "not_configured",
147
+ }
148
+ required = (components["application"], components["authentication"], components["database"], components["model"])
149
+ overall = "healthy" if all(value == "healthy" for value in required) else "degraded"
150
+ answer: dict[str, Any] = {"status": overall,
151
+ "checked_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
152
+ "components": components}
153
+ if "developer" in actor.get("roles", ()):
154
+ info = getattr(state, "mcp_build_info", {})
155
+ if isinstance(info, dict):
156
+ answer["build"] = {key: str(info[key])[:100] for key in ("version", "revision") if info.get(key)}
157
+ return answer
openspec/changes/add-mcp-monitoring-tools/.openspec.yaml ADDED
@@ -0,0 +1,2 @@
 
 
 
1
+ schema: spec-driven
2
+ created: 2026-10-26
openspec/changes/add-mcp-monitoring-tools/design.md ADDED
@@ -0,0 +1,68 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Design
2
+
3
+ ## Context
4
+
5
+ See `proposal.md` for motivation. The FastAPI management API already calculates privacy-preserving activity through `SupabaseAuth.scoped_activity`, and `class_management.visible_classes` already resolves the verified actor's current class/subject scope. The MCP server receives that actor only from its verified OAuth token. The existing `/api/health` response is broader than the intended MCP contract and contains model-specific diagnostic structures, so it must not be forwarded wholesale.
6
+
7
+ No browser state participates in MCP authorization. Supabase remains optional for ordinary practice, but MCP management and activity monitoring require the configured management store. There is no UI change, so RTL, touch, and keyboard behavior are unaffected.
8
+
9
+ ## Goals / Non-Goals
10
+
11
+ **Goals:**
12
+
13
+ - Share one scoped aggregation path between class-aware monitoring requests and tests.
14
+ - Produce deterministic daily and weekly series in `Asia/Jerusalem`, including zero buckets.
15
+ - Return a deliberately small health schema whose values cannot contain exception text.
16
+ - Keep monitoring calls strictly read-only and independent of mutation approvals.
17
+
18
+ **Non-Goals:**
19
+
20
+ - Diagnosing infrastructure from raw logs, probing third-party paid APIs, or repairing failed components.
21
+ - Returning individual learner activity, rankings, scores, answers, recordings, or login history.
22
+ - Adding a graph-rendering UI, database tables, Supabase RPCs, credentials, or environment settings.
23
+
24
+ ## Decisions
25
+
26
+ ### 1. Add a pure monitoring service between MCP and persistence
27
+
28
+ A small `app/monitoring.py` module will validate ISO dates, resolve the actor's visible classes, map roster emails to Supabase user IDs, call the existing scoped aggregate helper, and normalize its output. MCP tool handlers will remain schema/auth adapters.
29
+
30
+ This avoids calling the internal HTTP API from the same process and prevents authorization logic from diverging between tests and runtime. Directly duplicating `/api/activity` inside `grok_mcp.py` was rejected because that route has legacy parameter shapes and browser-specific compatibility branches.
31
+
32
+ ### 2. Query bounded hourly aggregates and roll them up locally
33
+
34
+ The service will request 60-minute aggregate buckets from the start of the selected local date and combine them into local calendar days or ISO-calendar weeks. It will create missing buckets with zero counts and count `active_students` per source bucket only as an activity indicator; it will not sum that field into a false distinct-person total across a day or week. The series will expose attempts and a bounded active-student indicator supported by the existing aggregate source, with summary values supplied only when their semantics remain valid.
35
+
36
+ The alternative—new daily and weekly database RPCs—would produce more exact distinct counts per output bucket but would require a migration. This change intentionally reuses the existing privacy-preserving RPC/fallback and will name fields according to their actual semantics. If exact daily distinct counts cannot be derived from the current aggregate response, implementation must omit that value rather than fabricate it.
37
+
38
+ ### 3. Resolve class scope before mapping learner identifiers
39
+
40
+ When `class_id` is present, it must match one of `visible_classes`; an unknown and an unauthorized identifier return the same error. When omitted, all visible classes are combined. Roster emails are mapped to IDs using `auth.users()`, and only the ID set is passed to `scoped_activity`. No email or ID is included in the MCP result.
41
+
42
+ Developers retain their existing cross-subject visibility. Subject administrators and class teachers remain constrained by current access data on every invocation. Tool arguments cannot supply roles or subject scope.
43
+
44
+ ### 4. Build health from bounded internal checks, not `/api/health`
45
+
46
+ `get_system_health` will construct a whitelist response: overall status, UTC timestamp, and coarse statuses for application, authentication, database, model, and text-to-speech. Status values are limited to `healthy`, `degraded`, `unavailable`, and `not_configured`. Optional unconfigured components do not fail the overall service.
47
+
48
+ Database reachability will use a minimal bounded read through the existing auth store; exceptions are logged server-side by type only and mapped to `unavailable`. The tool must not call external model or TTS providers, avoiding cost and side effects. Developers may additionally receive existing build/version identifiers, never diagnostic rule maps, paths, URLs, configuration values, or exception strings.
49
+
50
+ ### 5. Do not audit read-only monitoring calls
51
+
52
+ The tools will not write management audit events because the spec requires no application mutation as a consequence of a call. Server logs may record the tool name, outcome category, actor ID, class ID, and requested date range, but not bearer tokens, roster data, returned series, or exception text.
53
+
54
+ ## Risks / Trade-offs
55
+
56
+ - **[Risk] Existing hourly aggregates may not provide exact distinct learners for a larger displayed bucket** → Omit or explicitly label any non-additive metric; never sum hourly distinct counts and present them as daily distinct learners.
57
+ - **[Risk] Mapping all visible roster emails through the user directory may be slower for developers** → Enforce the 90-day limit, reuse one user-directory read per call, and pass only the final bounded ID set to the aggregate helper.
58
+ - **[Risk] A health endpoint can become an infrastructure oracle** → Require OAuth management access and serialize only enum statuses from a fixed whitelist.
59
+ - **[Risk] Database degradation can make both activity and health checks slow** → Use existing bounded request timeouts and map failures to a stable unavailable response.
60
+ - **[Trade-off] No new RPC means local calendar roll-up is less precise for distinct-student counts** → Prefer truthful, limited metrics now; add a dedicated RPC in a future migration if teachers need exact per-day distinct counts.
61
+
62
+ ## Migration Plan
63
+
64
+ 1. Deploy the service and two additional MCP tool schemas without changing the connector URL or OAuth registration.
65
+ 2. Verify local discovery, scoped activity fixtures, privacy assertions, degraded storage, and role-aware health output.
66
+ 3. After deployment, refresh an existing connector session if its client caches tool discovery; no reconnection or Supabase configuration change should normally be required.
67
+ 4. Roll back by reverting the application commit; no stored data or schema requires rollback.
68
+
openspec/changes/add-mcp-monitoring-tools/proposal.md ADDED
@@ -0,0 +1,32 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Proposal
2
+
3
+ ## Why
4
+
5
+ Teachers using the conversational connector can manage content and rosters, but they cannot ask the same assistant for the scoped activity graph already available in the management UI or for a safe operational status summary. Read-only monitoring tools will let a non-technical teacher understand learner activity and whether the service is available without granting access to raw logs or infrastructure secrets.
6
+
7
+ ## What Changes
8
+
9
+ - Add a read-only `get_activity_timeseries` MCP tool that returns aggregate attempt and active-student buckets for one authorized class or the caller's authorized scope.
10
+ - Bound activity requests to supported daily/weekly intervals and at most 90 days, and return no learner identities, scores, answers, recordings, or exact login events.
11
+ - Add a read-only `get_system_health` MCP tool with a small public component-status vocabulary and role-aware detail.
12
+ - Reuse verified OAuth actor permissions and current class/subject scope for every request; reject unavailable persistence safely.
13
+ - Keep both tools outside the mutation approval flow and record only safe operational audit metadata.
14
+ - Explicitly exclude raw logs, stack traces, database queries, environment variables, service endpoints, credentials, per-student timelines, and notification or remediation actions.
15
+
16
+ ## Capabilities
17
+
18
+ ### New Capabilities
19
+
20
+ - `mcp-monitoring`: Privacy-preserving, read-only activity time series and operational health exposed through authenticated MCP clients.
21
+
22
+ ### Modified Capabilities
23
+
24
+ - `teacher-content`: Extend privacy-preserving monitoring to conversational aggregate activity queries within the caller's class and subject scope.
25
+ - `access-and-privacy`: Define the sensitive operational data that MCP health responses must not disclose.
26
+
27
+ ## Impact
28
+
29
+ - Affects `app/grok_mcp.py` and a small shared monitoring service built over the existing class-scope and Supabase activity helpers.
30
+ - Adds focused MCP, authorization, aggregation, privacy, degraded-storage, and health tests; no database migration is expected.
31
+ - Extends README and the Hebrew teacher guide with safe example prompts.
32
+ - Does not add paid API calls, browser UI changes, write operations, new credentials, or deployment configuration.
openspec/changes/add-mcp-monitoring-tools/specs/access-and-privacy/spec.md ADDED
@@ -0,0 +1,21 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Spec Delta
2
+
3
+ ## ADDED Requirements
4
+
5
+ ### Requirement: Operational diagnostic isolation
6
+ Remote monitoring responses SHALL NOT disclose raw logs, stack traces, database queries, internal service addresses, environment variables, credentials, tokens, or secret presence values.
7
+
8
+ #### Scenario: Component check fails
9
+ - **WHEN** a component health check raises an internal error
10
+ - **THEN** the remote response maps the result to a coarse status
11
+ - **AND** the raw error text and internal target are retained only in server-side logging
12
+
13
+ #### Scenario: Developer requests health
14
+ - **WHEN** a caller with the developer role requests system health through MCP
15
+ - **THEN** any additional diagnostic fields remain non-sensitive
16
+ - **AND** developer status does not permit secrets or raw logs to appear in the response
17
+
18
+ #### Scenario: Unauthenticated caller requests monitoring
19
+ - **WHEN** a caller without a valid OAuth access token requests either monitoring tool
20
+ - **THEN** the MCP transport rejects the request before monitoring data is evaluated
21
+
openspec/changes/add-mcp-monitoring-tools/specs/mcp-monitoring/spec.md ADDED
@@ -0,0 +1,77 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Spec Delta
2
+
3
+ ## Purpose
4
+
5
+ Provide authorized MCP clients with bounded, privacy-preserving learning activity trends and a safe operational status summary without exposing learner-level or infrastructure-sensitive data.
6
+
7
+ ## ADDED Requirements
8
+
9
+ ### Requirement: Scoped activity time series
10
+ The MCP service SHALL return aggregate attempt and active-student buckets only for learners in the caller's current authorized class and subject scope.
11
+
12
+ #### Scenario: Teacher requests one authorized class
13
+ - **GIVEN** a teacher is authorized for the requested class
14
+ - **WHEN** the teacher requests its activity time series
15
+ - **THEN** the service returns ordered aggregate buckets for that class
16
+ - **AND** no learner identity, score, answer, recording, or exact login event is returned
17
+
18
+ #### Scenario: Subject administrator requests all visible activity
19
+ - **WHEN** a subject administrator omits the class identifier
20
+ - **THEN** the service aggregates only classes in that administrator's current subject scope
21
+
22
+ #### Scenario: Caller requests an out-of-scope class
23
+ - **WHEN** a caller requests a class outside the caller's current scope
24
+ - **THEN** the service refuses the request without confirming whether the class exists
25
+
26
+ ### Requirement: Bounded activity query
27
+ The activity tool SHALL accept daily or weekly buckets for an inclusive date range of at most 90 days and SHALL reject invalid, future-only, reversed, or oversized ranges.
28
+
29
+ #### Scenario: Valid daily range
30
+ - **WHEN** an authorized caller requests a valid range of 30 days with daily buckets
31
+ - **THEN** the service returns normalized dates and zero-filled buckets for days without activity
32
+
33
+ #### Scenario: Oversized range
34
+ - **WHEN** a caller requests more than 90 days
35
+ - **THEN** the service refuses the request before querying activity storage
36
+
37
+ #### Scenario: Weekly aggregation
38
+ - **WHEN** a caller selects weekly buckets
39
+ - **THEN** the service returns buckets aligned to stable calendar-week boundaries in the application timezone
40
+
41
+ ### Requirement: Safe activity degradation
42
+ The activity tool SHALL return an explicit unavailable response when activity persistence cannot be queried and SHALL not substitute fabricated or stale activity values.
43
+
44
+ #### Scenario: Supabase is not configured
45
+ - **WHEN** an authorized MCP request is handled without configured activity persistence
46
+ - **THEN** the service reports that activity monitoring is unavailable
47
+ - **AND** it returns no time-series values
48
+
49
+ #### Scenario: Aggregate RPC is absent
50
+ - **WHEN** the optimized aggregate query is unavailable but the existing bounded compatibility query succeeds
51
+ - **THEN** the service returns the correctly scoped aggregate result
52
+
53
+ ### Requirement: Safe system health
54
+ The MCP service SHALL return a read-only health summary using a bounded status vocabulary and SHALL expose only details appropriate to the caller's verified management role.
55
+
56
+ #### Scenario: Teacher checks health
57
+ - **WHEN** an authorized teacher requests system health
58
+ - **THEN** the response reports an overall status, check timestamp, and coarse application, authentication, database, model, and text-to-speech component statuses
59
+ - **AND** technical failure details are omitted
60
+
61
+ #### Scenario: Developer checks health
62
+ - **WHEN** a verified developer requests system health
63
+ - **THEN** the response MAY include non-sensitive build identifiers and component availability flags
64
+ - **AND** it still excludes raw errors and secret configuration
65
+
66
+ #### Scenario: Optional component is absent
67
+ - **WHEN** an optional component such as text-to-speech is not configured
68
+ - **THEN** that component is reported as `not_configured`
69
+ - **AND** the whole service is not reported as failed solely for that reason
70
+
71
+ ### Requirement: Monitoring tools are read-only
72
+ Monitoring MCP calls SHALL NOT mutate class, learner, content, audit, configuration, or infrastructure state and SHALL NOT require a prepare/publish approval.
73
+
74
+ #### Scenario: Monitoring call completes
75
+ - **WHEN** either monitoring tool succeeds or fails
76
+ - **THEN** no application record is created, updated, or deleted as a consequence of the call
77
+
openspec/changes/add-mcp-monitoring-tools/specs/teacher-content/spec.md ADDED
@@ -0,0 +1,18 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Spec Delta
2
+
3
+ ## MODIFIED Requirements
4
+
5
+ ### Requirement: Privacy-preserving monitoring
6
+ Teacher activity views and conversational monitoring tools SHALL expose only learners and aggregate data within the caller's scope, and pronunciation-pattern reports SHALL not return learner identities.
7
+
8
+ #### Scenario: Repeated pronunciation issue becomes a candidate
9
+ - **GIVEN** the same judgment occurred in at least five attempts by at least three learners and at least 30 percent of learners who attempted the phrase
10
+ - **WHEN** a teacher opens pronunciation patterns
11
+ - **THEN** the pattern appears as an investigation candidate
12
+ - **AND** it is not automatically applied as a calibration
13
+
14
+ #### Scenario: Teacher asks for an activity graph
15
+ - **WHEN** a teacher requests aggregate activity through an authenticated conversational connector
16
+ - **THEN** the returned series contains only activity belonging to the teacher's current class scope
17
+ - **AND** it contains no learner identities, recordings, answers, or individual scores
18
+
openspec/changes/add-mcp-monitoring-tools/tasks.md ADDED
@@ -0,0 +1,22 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Tasks
2
+
3
+ ## 1. Scoped activity service
4
+
5
+ - [x] 1.1 Add a pure monitoring service that validates inclusive ISO date ranges and `day`/`week` intervals, enforces the 90-day bound, resolves one class or all visible classes from the verified actor, and verify unit tests cover invalid, reversed, future-only, oversized, unknown, and out-of-scope requests.
6
+ - [x] 1.2 Aggregate the existing scoped activity source into ordered Asia/Jerusalem daily or weekly buckets with explicit zero buckets and no fabricated distinct-student counts; verify tests cover timezone boundaries, empty periods, class combination, identity omission, and unavailable persistence.
7
+
8
+ ## 2. Read-only MCP tools
9
+
10
+ - [x] 2.1 Add `get_activity_timeseries` to the MCP server using only OAuth actor context and the shared service; verify MCP schema/discovery and end-to-end calls expose aggregates only and perform no prepare/publish or audit write.
11
+ - [x] 2.2 Add `get_system_health` with whitelisted enum component statuses, a bounded read-only database check, and developer-only build metadata; verify tests cover teacher/developer output, optional components, database failure, and absence of errors, secrets, URLs, paths, tokens, and configuration values.
12
+ - [x] 2.3 Update the exact MCP tool allowlist test to include the two monitoring tools and verify no raw-log, SQL, environment, per-student timeline, remediation, or general infrastructure tool is discoverable.
13
+
14
+ ## 3. Documentation and integration
15
+
16
+ - [x] 3.1 Document Hebrew example prompts, date/interval limits, class scope, health status meanings, privacy exclusions, and read-only behavior in README and the teacher guide; verify HTML parses and the documented tool arguments match runtime schemas.
17
+ - [ ] 3.2 Run focused monitoring, MCP, OAuth, activity, and privacy tests followed by the full suite and strict OpenSpec validation; after deployment, verify the existing connector discovers both tools without OAuth reconfiguration and that a read-only query does not alter management activity.
18
+
19
+ ## Workflow follow-up
20
+
21
+ - Archive the change after production connector verification and review requirements are satisfied.
22
+
static/guide.html CHANGED
@@ -432,6 +432,9 @@ a,button{-webkit-tap-highlight-color:transparent}
432
  <div class="tip"><h3>צפייה</h3><p>כתבו: „הצג את הכיתות והתלמידים שאני רשאי/ת לנהל” או „הצג את הסרטונים בספרייה הדיגיטלית”. ברשימת כיתה מוחזרים רק שם הכיתה, המקצוע, כתובות התלמידים והכינויים המקומיים.</p></div>
433
  <div class="tip"><h3>הכנה לפני שינוי</h3><p>כתבו למשל: „הכן הוספת התלמיד noam@example.com לכיתה 12. אל תבצע עדיין”. בדקו את מספר הכיתה, כתובת המייל והכינוי ש־Grok מציג.</p></div>
434
  <div class="tip"><h3>אישור</h3><p>רק אחרי שהפרטים נכונים כתבו: „אני מאשר/ת לבצע את השינוי שהוכן”. האישור תקף לעשר דקות ולשימוש אחד בלבד.</p></div>
 
 
 
435
  <div class="tip"><h3>מה נשאר במסך הניהול</h3><p>מחיקה, הרשאות ותפקידים, שיוך מורים, שיעורים, שיעורי בית, סרטונים יומיים, ציונים והקלטות אינם זמינים ל־Grok ומנוהלים במסך הניהול בלבד.</p></div>
436
  </div>
437
  </section>
 
432
  <div class="tip"><h3>צפייה</h3><p>כתבו: „הצג את הכיתות והתלמידים שאני רשאי/ת לנהל” או „הצג את הסרטונים בספרייה הדיגיטלית”. ברשימת כיתה מוחזרים רק שם הכיתה, המקצוע, כתובות התלמידים והכינויים המקומיים.</p></div>
433
  <div class="tip"><h3>הכנה לפני שינוי</h3><p>כתבו למשל: „הכן הוספת התלמיד noam@example.com לכיתה 12. אל תבצע עדיין”. בדקו את מספר הכיתה, כתובת המייל והכינוי ש־Grok מציג.</p></div>
434
  <div class="tip"><h3>אישור</h3><p>רק אחרי שהפרטים נכונים כתבו: „אני מאשר/ת לבצע את השינוי שהוכן”. האישור תקף לעשר דקות ולשימוש אחד בלבד.</p></div>
435
+ <div class="tip"><h3>גרף פעילות</h3><p>כתבו: „הצג גרף פעילות יומי של כיתה 12 בין 2026-10-01 ל־2026-10-26”. אפשר לבחור יום או שבוע וטווח של עד 90 יום שאינו בעתיד. בלי מספר כיתה יוצגו יחד רק הכיתות שמותר לכם לראות.</p></div>
436
+ <div class="tip"><h3>מצב המערכת</h3><p>כתבו: „בדוק את מצב המערכת והסבר בעברית פשוטה”. המצבים הם תקין, חלקי, לא זמין או לא מוגדר. רכיב אופציונלי שלא הוגדר, למשל הקראה, אינו הופך לבדו את כל המערכת לתקולה.</p></div>
437
+ <div class="tip"><h3>פרטיות בניטור</h3><p>כלי הניטור הם לקריאה בלבד ואינם דורשים אישור. הם מחזירים ספירות מצטברות בלבד — בלי שמות או כתובות תלמידים, ציונים, תשובות, הקלטות, זמני כניסה מדויקים, לוגים, כתובות פנימיות או סודות.</p></div>
438
  <div class="tip"><h3>מה נשאר במסך הניהול</h3><p>מחיקה, הרשאות ותפקידים, שיוך מורים, שיעורים, שיעורי בית, סרטונים יומיים, ציונים והקלטות אינם זמינים ל־Grok ומנוהלים במסך הניהול בלבד.</p></div>
439
  </div>
440
  </section>
tests/test_activity.py CHANGED
@@ -36,3 +36,11 @@ def test_scoped_activity_fallback_is_not_limited_to_the_newest_day():
36
  data = auth.scoped_activity({"u1", "u2"}, datetime(2026, 10, 15, tzinfo=timezone.utc), 60)
37
  assert data["summary"] == {"attempts": 3, "active_students": 2, "returning_students": 1, "active_days": 2}
38
  assert sum(bucket["attempts"] for bucket in data["buckets"]) == 3
 
 
 
 
 
 
 
 
 
36
  data = auth.scoped_activity({"u1", "u2"}, datetime(2026, 10, 15, tzinfo=timezone.utc), 60)
37
  assert data["summary"] == {"attempts": 3, "active_students": 2, "returning_students": 1, "active_days": 2}
38
  assert sum(bucket["attempts"] for bucket in data["buckets"]) == 3
39
+
40
+
41
+ def test_database_health_uses_one_bounded_read():
42
+ auth = SupabaseAuth("https://example.supabase.co", "public", secret="secret")
43
+ calls = []
44
+ auth._admin = lambda path, *args, **kwargs: calls.append(path) or []
45
+ assert auth.database_health() is True
46
+ assert calls == ["/rest/v1/classes?select=id&limit=1"]
tests/test_grok_mcp.py CHANGED
@@ -53,6 +53,13 @@ class LibraryAuth:
53
  def classes(self, fresh=False):
54
  return [dict(row) for row in self.class_rows]
55
 
 
 
 
 
 
 
 
56
  def save_class(self, class_id, name, emails, nicknames, lessons, homeworks=(), dailies=None,
57
  subject="", teachers=None):
58
  if class_id is None:
@@ -80,7 +87,8 @@ class UnavailableAuth(LibraryAuth):
80
 
81
  def connector(auth=None, clock=None, actor=None):
82
  clock = clock or Clock()
83
- host = SimpleNamespace(state=SimpleNamespace(auth=auth, video_link=video_link,
 
84
  initial_class_lessons={"ערבית": "1", "מתמטיקה": "linear-functions"}))
85
  server, protected, _ = build(host, approvals=ApprovalStore(clock), limiter=MutationLimiter(clock),
86
  class_approvals=ClassApprovalStore(clock), actor_provider=(lambda: actor) if actor else None)
@@ -92,15 +100,17 @@ def call(server, name, arguments=None):
92
  return answer.structured_content
93
 
94
 
95
- def test_exactly_seven_narrow_tools_are_discoverable():
96
  server, _ = connector(LibraryAuth())
97
  tools = asyncio.run(server.list_tools())
98
  assert [tool.name for tool in tools] == [
99
  "list_library_videos", "prepare_library_video", "publish_library_video", "rename_library_video",
100
- "list_classes", "prepare_class_change", "publish_class_change"]
 
101
  assert all(tool.output_schema for tool in tools)
102
  assert not any(word in tool.name for tool in tools
103
- for word in ("delete", "teacher", "user", "role", "lesson", "homework", "grade", "recording", "sql"))
 
104
 
105
 
106
  def test_list_and_rename_return_only_library_metadata():
@@ -253,6 +263,54 @@ def test_failed_class_publish_consumes_approval_and_does_not_claim_success():
253
  assert failed["ok"] is False and replay["ok"] is False and auth.class_rows[0]["name"] == "א"
254
 
255
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
256
  def test_streamable_http_initializes_and_discovers_tools(monkeypatch):
257
  monkeypatch.setenv("MCP_PUBLIC_URL", "http://test/mcp/")
258
  monkeypatch.setenv("SUPABASE_URL", "")
@@ -280,7 +338,8 @@ def test_streamable_http_initializes_and_discovers_tools(monkeypatch):
280
  assert initialized.json()["result"]["serverInfo"]["name"] == "ihki-digital-library"
281
  assert [tool["name"] for tool in discovered.json()["result"]["tools"]] == [
282
  "list_library_videos", "prepare_library_video", "publish_library_video", "rename_library_video",
283
- "list_classes", "prepare_class_change", "publish_class_change"]
 
284
 
285
 
286
  def test_existing_library_api_is_compatible_and_mcp_token_has_no_api_authority(monkeypatch):
 
53
  def classes(self, fresh=False):
54
  return [dict(row) for row in self.class_rows]
55
 
56
+ def users(self):
57
+ return [{"id": "student-1", "email": "student@example.com", "name": "Student"}]
58
+
59
+ def scoped_activity(self, ids, since, bucket_minutes):
60
+ return {"buckets": [], "summary": {"attempts": 0, "active_students": 0,
61
+ "returning_students": 0, "active_days": 0}}
62
+
63
  def save_class(self, class_id, name, emails, nicknames, lessons, homeworks=(), dailies=None,
64
  subject="", teachers=None):
65
  if class_id is None:
 
87
 
88
  def connector(auth=None, clock=None, actor=None):
89
  clock = clock or Clock()
90
+ host = SimpleNamespace(state=SimpleNamespace(auth=auth, video_link=video_link, scorer=object(), tts=None,
91
+ mcp_build_info={"version": "test", "revision": "abc"},
92
  initial_class_lessons={"ערבית": "1", "מתמטיקה": "linear-functions"}))
93
  server, protected, _ = build(host, approvals=ApprovalStore(clock), limiter=MutationLimiter(clock),
94
  class_approvals=ClassApprovalStore(clock), actor_provider=(lambda: actor) if actor else None)
 
100
  return answer.structured_content
101
 
102
 
103
+ def test_exactly_nine_narrow_tools_are_discoverable():
104
  server, _ = connector(LibraryAuth())
105
  tools = asyncio.run(server.list_tools())
106
  assert [tool.name for tool in tools] == [
107
  "list_library_videos", "prepare_library_video", "publish_library_video", "rename_library_video",
108
+ "list_classes", "prepare_class_change", "publish_class_change",
109
+ "get_activity_timeseries", "get_system_health"]
110
  assert all(tool.output_schema for tool in tools)
111
  assert not any(word in tool.name for tool in tools
112
+ for word in ("delete", "teacher", "user", "role", "lesson", "homework", "grade", "recording",
113
+ "sql", "log", "environment", "timeline", "remediate", "restart", "shell"))
114
 
115
 
116
  def test_list_and_rename_return_only_library_metadata():
 
263
  assert failed["ok"] is False and replay["ok"] is False and auth.class_rows[0]["name"] == "א"
264
 
265
 
266
+ def test_monitoring_tools_are_scoped_read_only_and_privacy_preserving():
267
+ actor = {"id": "admin-1", "email": "admin@example.com", "roles": ["admin"],
268
+ "subject": "ערבית", "permissions": ["management.access"]}
269
+
270
+ class MonitoringAuth(LibraryAuth):
271
+ def __init__(self):
272
+ super().__init__()
273
+ self.class_rows = [
274
+ {"id": 1, "name": "ערבית", "subject": "ערבית", "emails": ["student@example.com"]},
275
+ {"id": 2, "name": "מתמטיקה", "subject": "מתמטיקה", "emails": ["math@example.com"]},
276
+ ]
277
+ self.activity_ids = None
278
+
279
+ def users(self):
280
+ return [{"id": "student-1", "email": "student@example.com"},
281
+ {"id": "math-1", "email": "math@example.com"}]
282
+
283
+ def scoped_activity(self, ids, since, bucket_minutes):
284
+ self.activity_ids = ids
285
+ return {"buckets": [{"bucket": "2026-10-25T09:00:00+00:00", "attempts": 4,
286
+ "active_students": 1}],
287
+ "summary": {"attempts": 4, "active_students": 1,
288
+ "returning_students": 0, "active_days": 1}}
289
+
290
+ auth = MonitoringAuth()
291
+ server, _ = connector(auth, actor=actor)
292
+ before = list(auth.events)
293
+ activity = call(server, "get_activity_timeseries", {
294
+ "from_date": "2026-10-25", "to_date": "2026-10-26", "interval": "day", "class_id": 1})
295
+ health = call(server, "get_system_health")
296
+ assert activity["ok"] and auth.activity_ids == {"student-1"}
297
+ assert activity["series"][0]["attempts"] == 4
298
+ assert not any(word in str(activity).lower() for word in ("student@example", "student-1", "score", "recording"))
299
+ assert health["ok"] and health["status"] == "healthy" and "build" not in health
300
+ assert auth.events == before
301
+ assert call(server, "get_activity_timeseries", {
302
+ "from_date": "2026-10-25", "to_date": "2026-10-26", "class_id": 2})["ok"] is False
303
+
304
+
305
+ def test_system_health_developer_metadata_is_whitelisted():
306
+ actor = {"id": "dev-1", "email": "dev@example.com", "roles": ["developer"],
307
+ "subject": "", "permissions": ["management.access"]}
308
+ server, _ = connector(LibraryAuth(), actor=actor)
309
+ health = call(server, "get_system_health")
310
+ assert health["build"] == {"version": "test", "revision": "abc"}
311
+ assert not any(word in str(health).lower() for word in ("token", "secret", "trace", "http", "path"))
312
+
313
+
314
  def test_streamable_http_initializes_and_discovers_tools(monkeypatch):
315
  monkeypatch.setenv("MCP_PUBLIC_URL", "http://test/mcp/")
316
  monkeypatch.setenv("SUPABASE_URL", "")
 
338
  assert initialized.json()["result"]["serverInfo"]["name"] == "ihki-digital-library"
339
  assert [tool["name"] for tool in discovered.json()["result"]["tools"]] == [
340
  "list_library_videos", "prepare_library_video", "publish_library_video", "rename_library_video",
341
+ "list_classes", "prepare_class_change", "publish_class_change",
342
+ "get_activity_timeseries", "get_system_health"]
343
 
344
 
345
  def test_existing_library_api_is_compatible_and_mcp_token_has_no_api_authority(monkeypatch):
tests/test_monitoring.py ADDED
@@ -0,0 +1,115 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from datetime import date
2
+ from types import SimpleNamespace
3
+
4
+ import pytest
5
+
6
+ from app.auth import AuthUnavailable
7
+ from app.monitoring import (MonitoringError, MonitoringUnavailable, activity_timeseries,
8
+ system_health, validate_range)
9
+
10
+
11
+ ACTOR = {"id": "a1", "roles": ["admin"], "subject": "ערבית", "permissions": ["management.access"]}
12
+
13
+
14
+ class ActivityAuth:
15
+ def __init__(self):
16
+ self.class_rows = [
17
+ {"id": 1, "name": "ערבית א", "subject": "ערבית", "emails": ["one@example.com"]},
18
+ {"id": 2, "name": "ערבית ב", "subject": "ערבית", "emails": ["two@example.com"]},
19
+ {"id": 3, "name": "מתמטיקה", "subject": "מתמטיקה", "emails": ["math@example.com"]},
20
+ ]
21
+ self.seen_ids = None
22
+
23
+ def access_for(self, user_id, fresh=False):
24
+ return {}
25
+
26
+ def classes(self, fresh=False):
27
+ return list(self.class_rows)
28
+
29
+ def users(self):
30
+ return [{"id": "u1", "email": "one@example.com"}, {"id": "u2", "email": "two@example.com"},
31
+ {"id": "u3", "email": "math@example.com"}]
32
+
33
+ def scoped_activity(self, ids, since, bucket_minutes):
34
+ self.seen_ids = ids
35
+ assert bucket_minutes == 60
36
+ return {"buckets": [
37
+ {"bucket": "2026-10-24T21:30:00+00:00", "attempts": 2, "active_students": 1},
38
+ {"bucket": "2026-10-25T10:00:00+00:00", "attempts": 3, "active_students": 2},
39
+ ], "summary": {"attempts": 5, "active_students": 2, "returning_students": 1, "active_days": 1}}
40
+
41
+
42
+ @pytest.mark.parametrize("start,end,interval", [
43
+ ("bad", "2026-10-26", "day"), ("2026-10-27", "2026-10-26", "day"),
44
+ ("2026-10-26", "2026-10-27", "day"), ("2026-07-28", "2026-10-26", "day"),
45
+ ("2026-10-01", "2026-10-26", "month"),
46
+ ])
47
+ def test_range_rejects_invalid_reversed_future_oversized_and_unknown_interval(start, end, interval):
48
+ with pytest.raises(MonitoringError):
49
+ validate_range(start, end, interval, today=date(2026, 10, 26))
50
+
51
+
52
+ def test_daily_series_is_scoped_zero_filled_and_privacy_preserving():
53
+ auth = ActivityAuth()
54
+ data = activity_timeseries(auth, ACTOR, from_date="2026-10-24", to_date="2026-10-26",
55
+ interval="day", class_id=1, today=date(2026, 10, 26))
56
+ assert auth.seen_ids == {"u1"}
57
+ assert data["class_name"] == "ערבית א"
58
+ assert data["series"] == [
59
+ {"date": "2026-10-24", "attempts": 0, "peak_active_students": 0},
60
+ {"date": "2026-10-25", "attempts": 5, "peak_active_students": 2},
61
+ {"date": "2026-10-26", "attempts": 0, "peak_active_students": 0},
62
+ ]
63
+ assert data["summary"]["active_students"] == 2
64
+ assert not any(word in str(data).lower() for word in ("example.com", "u1", "score", "recording", "answer"))
65
+
66
+
67
+ def test_all_visible_classes_combine_and_week_starts_on_monday():
68
+ auth = ActivityAuth()
69
+ data = activity_timeseries(auth, ACTOR, from_date="2026-10-20", to_date="2026-10-26",
70
+ interval="week", today=date(2026, 10, 26))
71
+ assert auth.seen_ids == {"u1", "u2"}
72
+ assert [row["date"] for row in data["series"]] == ["2026-10-19", "2026-10-26"]
73
+ assert data["series"][0]["attempts"] == 5 and data["series"][1]["attempts"] == 0
74
+
75
+
76
+ def test_unknown_and_out_of_scope_class_have_the_same_safe_error():
77
+ auth = ActivityAuth()
78
+ for class_id in (3, 999):
79
+ with pytest.raises(MonitoringError, match="הכיתה אינה זמינה"):
80
+ activity_timeseries(auth, ACTOR, from_date="2026-10-25", to_date="2026-10-26",
81
+ class_id=class_id, today=date(2026, 10, 26))
82
+
83
+
84
+ def test_empty_roster_and_unavailable_storage_are_explicit():
85
+ auth = ActivityAuth()
86
+ auth.class_rows[0]["emails"] = []
87
+ data = activity_timeseries(auth, ACTOR, from_date="2026-10-26", to_date="2026-10-26",
88
+ class_id=1, today=date(2026, 10, 26))
89
+ assert data["series"] == [{"date": "2026-10-26", "attempts": 0, "peak_active_students": 0}]
90
+ auth.scoped_activity = lambda *args: (_ for _ in ()).throw(AuthUnavailable("secret database URL"))
91
+ with pytest.raises(MonitoringUnavailable, match="אינם זמינים") as failure:
92
+ activity_timeseries(auth, ACTOR, from_date="2026-10-26", to_date="2026-10-26",
93
+ class_id=1, today=date(2026, 10, 26))
94
+ assert "secret" not in str(failure.value)
95
+
96
+
97
+ def test_health_is_whitelisted_role_aware_and_read_only():
98
+ auth = ActivityAuth()
99
+ state = SimpleNamespace(auth=auth, scorer=object(), tts=None,
100
+ mcp_build_info={"version": "v1", "revision": "abc", "secret": "never"})
101
+ teacher = system_health(SimpleNamespace(state=state), ACTOR)
102
+ assert teacher["status"] == "healthy"
103
+ assert teacher["components"]["text_to_speech"] == "not_configured"
104
+ assert "build" not in teacher
105
+ developer = system_health(SimpleNamespace(state=state), {**ACTOR, "roles": ["developer"]})
106
+ assert developer["build"] == {"version": "v1", "revision": "abc"}
107
+ assert not any(word in str(developer).lower() for word in ("secret", "http", "token", "trace", "path"))
108
+
109
+
110
+ def test_health_maps_database_error_without_leaking_it():
111
+ auth = ActivityAuth()
112
+ auth.classes = lambda fresh=False: (_ for _ in ()).throw(AuthUnavailable("postgres://secret"))
113
+ data = system_health(SimpleNamespace(state=SimpleNamespace(auth=auth, scorer=object(), tts=object())), ACTOR)
114
+ assert data["status"] == "degraded" and data["components"]["database"] == "unavailable"
115
+ assert "postgres" not in str(data).lower() and "secret" not in str(data).lower()