feat(mcp): add scoped monitoring tools
Browse filesKeep activity aggregates within the verified manager scope and expose only whitelisted health statuses without operational secrets.
- README.md +14 -2
- app/auth.py +11 -0
- app/grok_mcp.py +33 -2
- app/main.py +2 -0
- app/monitoring.py +157 -0
- openspec/changes/add-mcp-monitoring-tools/.openspec.yaml +2 -0
- openspec/changes/add-mcp-monitoring-tools/design.md +68 -0
- openspec/changes/add-mcp-monitoring-tools/proposal.md +32 -0
- openspec/changes/add-mcp-monitoring-tools/specs/access-and-privacy/spec.md +21 -0
- openspec/changes/add-mcp-monitoring-tools/specs/mcp-monitoring/spec.md +77 -0
- openspec/changes/add-mcp-monitoring-tools/specs/teacher-content/spec.md +18 -0
- openspec/changes/add-mcp-monitoring-tools/tasks.md +22 -0
- static/guide.html +3 -0
- tests/test_activity.py +8 -0
- tests/test_grok_mcp.py +64 -5
- tests/test_monitoring.py +115 -0
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
|
| 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,
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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
|
| 166 |
-
"show its exact effect to the teacher,
|
|
|
|
| 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
|
| 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",
|
|
|
|
| 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()
|