Jaipuria Moodle Reports MCP

Ориентированный на преподавателей, доступный только для чтения сервер Model Context Protocol (MCP), который делает данные student-report-system Jaipuria доступными для запросов на естественном языке. Подключите его к любому MCP-хосту (дашборду, Claude.ai, ChatGPT, Claude CLI) и спрашивайте об оценках студентов, посещаемости, предметах, аналитике когорт, долгосрочных трендах, студентах группы риска и точности отчетов — по каждому загруженному студенту, с учетом кампусов вызывающего.

Live: https://moodle-mcp-f6do.onrender.com/mcp · Health: /health · Инструменты: 27 Репозиторий: github.com/mansigambhir-1313/Moodle-MCP · Владелец: Jaipuria AI Labs

Обзор

Конвейер в moodle-agent загружает данные Moodle, вычисляет аналитику и генерирует проверенные отчеты о студентах в проект Supabase. Этот MCP — сторона чтения этого проекта для преподавателей и программного офиса: он предоставляет необработанные данные и результаты конвейера в виде ~27 структурированных, автоматически одобряемых инструментов, которые LLM хоста маршрутизирует.

Он ориентирован на данные — основная поверхность — это необработанная журнал оценок и посещаемость (доступны для запросов по каждому студенту, независимо от отчета); сгенерированные отчеты и их оценки точности по двум схемам — вторичный слой. Он только для чтения навсегда: ни один инструмент не пишет, не загружает и не отправляет электронные письма.

Происхождение дизайна: паттерны Rehearsal MCP (ограниченные кэши, docstrings контракта маршрутизации, бюджеты ответов, удаление секретов, корректная деградация), адаптированные от модели RLS для отдельных студентов этого сервера к ролевой модели преподавателя с ограничением по кампусу.

Где это вписывается

• Выше по потоку: общий проект Supabase student-report-system (таблицы students, courses, enrolments, marks, attendance_sessions, student_reports, report_accuracy), записываемый moodle-agent.

• Ниже по потоку: любой MCP-хост — дашборд преподавателя, коннекторы Claude.ai / ChatGPT, Claude CLI.

Related MCP server: VortexIQ MCP Connector

Что делает его эксклюзивным

• Лонгитюдный, а не только снимок — один запуск содержит каждый триместр (T1–T6). Такие инструменты, как student_trajectory и declining_students, выявляют студента, скатывающегося от семестра к семестру, чего точечный запрос никогда не покажет.

• Единые панели — student_360 и cohort_pulse возвращают целого студента / всю когорту за один вызов, готовые для выдвижного ящика дашборда или стартового экрана.

• Точность как данные первого класса — каждый сгенерированный отчет несет оценку валидации по двум схемам (панель достоверности + двухходовой LLM-судья). Спрашивайте "какие отчеты помечены и почему?"

• Сигналы преподавания и учебной программы — section_compare (справедливость A-против-B), assessment_breakdown (тест против задания против проекта), subject_difficulty (точки напряжения учебной программы).

Инструменты (27)

Каждый инструмент — только SELECT, ограничен кампусом вызывающего токена, ограничен по объему и несет docstring маршрутизации ЧТО / КОГДА ИСПОЛЬЗОВАТЬ / НЕ ИСПОЛЬЗОВАТЬ / ВОЗВРАЩАЕТ.

Студенты — необработанные данные (основные)

Предметы — необработанные данные (основные)

Инсайты — лонгитюдные и единые панели (герои)

Аналитика и группа риска (основные)

Отчеты и точность (вторичные)

См. docs/INNOVATION_ROADMAP.md для идей Фазы 3 (attendance_eligibility, attendance_marks_link, anomalies, roster_health).

Быстрый старт

Подключение хоста (развернутый сервер)

claude mcp add moodle --transport http https://moodle-mcp-f6do.onrender.com/mcp \
  --header "Authorization: Bearer <your MCP_TOKENS value>"

Затем спрашивайте на естественном языке:

"cohort pulse for jaipur 2024-26" · "who's declining" · "build my watchlist" · "show JJ24PG001's full record" · "hardest subjects" · "compare sections of Wealth Management"

Запуск локально

cd moodle-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env            # fill in the vars below
uvicorn server:app --port 8899
curl localhost:8899/health      # {"status":"ok",...}

Дымовой тест (реальное рукопожатие MCP + живые запросы)

MCP_URL="http://localhost:8899/mcp" MCP_TOKEN="<a token>" python test_client.py

Конфигурация

config.py (pydantic-settings, читает .env + переменные окружения). validate_config() — это проверка при загрузке с отказом по умолчанию для переменных Supabase.

Все логирование идет в stderr; строки логов никогда не содержат содержимого токенов или PII.

Модель доступа (ролевая, с ограничением по кампусу)

В отличие от студенческого MCP (RLS для каждого пользователя), этот обслуживает преподавателей, которые видят институциональные данные для своих кампусов. Bearer-токен сопоставляется с принципалом с набором разрешенных кампусов; каждый инструмент пересекает запрошенный кампус с этим набором. Кампус вне разрешения возвращает {"found": false} — утечки данных нет.

Сгенерируйте блок токена для каждого кампуса:

python3 -c "import secrets; print('mcp_'+secrets.token_urlsafe(24))"   # one per faculty

// MCP_TOKENS (single-line JSON in the env var)
{
  "mcp_...indore": {"name": "Indore TNP",       "campuses": ["indore"]},
  "mcp_...office": {"name": "Programme Office",  "campuses": null}      // null = all campuses
}

Ключ service-role Supabase остается на стороне сервера и никогда не передается хосту. В кодовой базе нет пути записи.

Архитектура

MCP host (dashboard / Claude / ChatGPT)
        │  MCP over HTTP + Bearer <faculty token>
        ▼
server.py (FastMCP /mcp, /health)
  get_authenticated_service()  → verify token → MoodleService(allowed_campuses)
        │
  tools/* (6 modules, 27 tools) — each: Params model + _impl(svc,…) + register()
        │  every query .in_("campus", allowed) ; strip_secrets ; response budgets
        ▼
Supabase (read service role) — students · courses · enrolments · marks ·
                               attendance_sessions · student_reports · report_accuracy

Полный дизайн: docs/ARCHITECTURE.md.

Ключевые файлы

Кэши (безопасно для OOM — только ограниченный TTLCache)

_run_cache (последний финальный запуск для области), _rollup_cache / _marks_cache (сводки необработанных данных когорты). Инструменты когорт обходят ограничение PostgREST в 1000 строк и кэшируют результат на 5 минут.

Развертывание

• Render (blueprint render.yaml или Docker): Python 3.12 / Docker, uvicorn server:app, проверка здоровья /health. Установите SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, MCP_TOKENS в дашборде.

• Docker: docker build -t moodle-mcp . && docker run -p 8000:8000 --env-file .env moodle-mcp

• Текущий прод находится на Free-инстансе (выключается после ~15 минут простоя → ~50 секунд холодный старт). Обновитесь до Starter для постоянной работы.

Полные шаги тестирования/развертывания: DEPLOY.md.

Runbooks

Ротация токенов доступа — перегенерируйте MCP_TOKENS (тем же генератором), обновите переменную окружения Render; сервис перезапустится, и старые токены перестанут работать. Выдайте новые токены преподавателям.

Добавить факультет для кампуса — добавьте одну запись "mcp_...": {"name": "...", "campuses": ["<campus>"]} в MCP_TOKENS, переразверните, передайте им их токен.

Добавить новый инструмент — следуйте docs/ARCHITECTURE.md §11: добавьте модель Params + _impl(svc,…) + register(), ограничьте каждый запрос рамками кампуса, strip_secrets, напишите docstring маршрутизации, зарегистрируйте в server.py. Используйте повторно помощники для сырых данных из tools/common.py.

Холодный старт / первый запрос медленный — бесплатный инстанс проснулся из простоя (~50 с). Прогрейте его с помощью curl <url>/health или обновите инстанс.

Проверить развёртывание — curl <url>/health, затем MCP_URL="<url>/mcp" MCP_TOKEN="<token>" python test_client.py.

Инварианты безопасности

Только чтение навсегда · ограничение каждого запроса рамками кампуса · единообразные промахи {"found": false} (без оракула существования) · удаление секретов (идентификаторы запусков / ключи хранилища / хэши / электронные письма никогда не покидают сервер) · ключ сервисной роли только на стороне сервера · бюджеты ответов + разбиение на страницы · корректная деградация (никогда не 500 на ход) · только ограниченные кэши (безопасно от OOM). Подробности в docs/ARCHITECTURE.md §3, §11.