Jaipuria Moodle Reports MCP

교수진용, 읽기 전용 Model Context Protocol (MCP) 서버로, Jaipuria의 student-report-system 데이터를 자연어로 조회할 수 있게 합니다. 어떤 MCP 호스트(대시보드, Claude.ai, ChatGPT, Claude CLI)에 연결하여 학생 성적, 출석, 과목, 코호트 분석, 종단 추세, 위험 학생, 보고서 정확도에 대해 질문할 수 있습니다 — 모든 수집된 학생이 호출자의 캠퍼스 범위로 제한됩니다.

라이브: https://moodle-mcp-f6do.onrender.com/mcp · 헬스: /health · 도구: 27개 저장소: github.com/mansigambhir-1313/Moodle-MCP · 소유자: Jaipuria AI Labs

개요

moodle-agent의 파이프라인은 Moodle 데이터를 수집하고, 분석을 계산하며, 검증된 학생 보고서를 Supabase 프로젝트에 생성합니다. 이 MCP는 교수진과 프로그램 사무국을 위한 그 프로젝트의 읽기 측면입니다. 원시 데이터와 파이프라인의 출력을 호스트 LLM이 라우팅하는 ~27개의 구조화된 자동 승인 가능 도구로 노출합니다.

데이터 우선입니다 — 기본 표면은 원시 성적부와 출석(보고서 유무와 관계없이 모든 학생에 대해 조회 가능)이며, 생성된 보고서와 두 체계 정확도 점수는 보조 계층입니다. 영원히 읽기 전용입니다: 어떤 도구도 쓰기, 수집, 이메일 전송을 하지 않습니다.

설계 계보: Rehearsal MCP 패턴(제한된 캐시, 라우팅 계약 docstring, 응답 예산, 비밀 제거, 우아한 성능 저하)을 해당 서버의 학생별 RLS 모델에서 역할 기반, 캠퍼스 범위 교수진 모델로 적용했습니다.

위치

• 업스트림: 공유 student-report-system Supabase 프로젝트(테이블 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는 한 번의 호출로 전체 학생/전체 코호트를 반환하여 대시보드 서랍이나 랜딩 화면에 바로 사용할 수 있습니다.

• 정확도를 일급 데이터로 — 모든 생성된 보고서는 두 체계 검증 점수(충실도 패널 + 2턴 LLM 판정)를 포함합니다. *"어떤 보고서가 플래그되었고 왜?"*라고 물어보세요.

• 교육 및 커리큘럼 신호 — section_compare(A-vs-B 공정성), assessment_breakdown (퀴즈 vs 과제 vs 프로젝트), subject_difficulty(커리큘럼 압박 지점).

도구 (27개)

모든 도구는 SELECT 전용이며, 호출자의 토큰에 따라 캠퍼스 범위가 제한되고, 제한되며, WHAT / USE WHEN / DO NOT USE / RETURNS 라우팅 docstring을 포함합니다.

학생 — 원시 데이터 (기본)

과목 — 원시 데이터 (기본)

인사이트 — 종단 및 단일 창 (히어로)

분석 및 위험 (기본)

보고서 및 정확도 (보조)

Phase-3 아이디어는 docs/INNOVATION_ROADMAP.md 참조 (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>"

그런 다음 자연어로 질문하세요:

"자이푸르 2024-26 코호트 펄스" · "누가 하락 중인가" · "내 워치리스트 만들기" · "JJ24PG001의 전체 기록 보기" · "가장 어려운 과목" · "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)와 달리, 이 서버는 캠퍼스의 기관 데이터를 보는 교수진을 대상으로 합니다. 베어러 토큰은 허용된 캠퍼스 집합을 가진 주체에 매핑됩니다. 모든 도구는 요청된 캠퍼스를 해당 집합과 교차합니다. 허용 범위 밖의 캠퍼스는 {"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
}

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 (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.

런북

액세스 토큰 교체 — MCP_TOKENS 재생성(동일 생성기), Render 환경 변수 업데이트; 서비스가 재시작되고 이전 토큰은 작동을 멈춥니다. 새 토큰을 교수진에게 재발급하세요.

캠퍼스별 교수진 추가 — MCP_TOKENS에 "mcp_...": {"name": "...", "campuses": ["<campus>"]} 항목을 하나 추가하고, 재배포한 뒤 해당 토큰을 전달하세요.

새 도구 추가 — 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}로 통일된 미스 응답(존재 여부 오라클 없음) · 비밀 정보 제거(실행 ID / 스토리지 키 / 해시 / 이메일이 서버 밖으로 나가지 않음) · 서비스 역할 키는 서버 측에서만 사용 · 응답 예산 + 페이지네이션 · 우아한 성능 저하(턴을 500으로 만들지 않음) · 제한된 캐시만 사용(OOM 안전). 자세한 내용은 docs/ARCHITECTURE.md §3, §11 참조.