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の構造化された自動承認可能なツールとして公開します。

これはデータファーストです。主要な表面は生の成績表と出席（レポートの有無にかかわらずすべての学生に対して 照会可能）であり、生成されたレポートとその2スキームの正確性スコアは二次レイヤーです。永久に読み取り専用です。 書き込み、取り込み、メール送信を行うツールはありません。

設計の系譜: 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

独自性

• スナップショットだけでなく長期的 — 1回の実行で全学期（T1–T6）を保持します。student_trajectory や declining_students のようなツールは、学期ごとに低下する学生を捉えます。これは一時点のクエリでは決して表示されません。

• シングルペインビュー — student_360 と cohort_pulse は、1回の呼び出しで学生全体/コホート全体を返し、 ダッシュボードのドロワーやランディング画面にそのまま使えます。

• 正確性を第一級のデータとして — 生成されたすべてのレポートには、2スキームの検証スコア （忠実性パネル + 2ターンLLMジャッジ）が付いています。「どのレポートがフラグされ、なぜか」 と尋ねられます。

• 教育とカリキュラムのシグナル — section_compare（A対Bの公平性）、assessment_breakdown （小テスト vs 課題 vs プロジェクト）、subject_difficulty（カリキュラムの圧力ポイント）。

ツール（27）

すべてのツールは SELECT のみで、呼び出し元のトークンにキャンパススコープされ、境界があり、 WHAT / USE WHEN / DO NOT USE / RETURNS のルーティングdocstringを備えています。

学生 — 生データ（主要）

科目 — 生データ（主要）

インサイト — 長期的 & シングルペイン（ヒーロー）

分析 & リスク（主要）

レポート & 正確性（二次）

フェーズ3のアイデア（attendance_eligibility、attendance_marks_link、anomalies、roster_health）については、 docs/INNOVATION_ROADMAP.md を参照してください。

クイックスタート

ホストを接続（デプロイ済みサーバー）

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

次に、平易な言葉で尋ねます:

「ジャイプール 2024-26 のコホートパルス」 · 「誰が低下しているか」 · 「ウォッチリストを作成」 · 「JJ24PG001 の完全な記録を表示」 · 「最も難しい科目」 · 「ウェルスマネジメントのセクションを比較」

ローカルで実行

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>"]} エントリを1件追加し、再デプロイして、そのトークンを本人に渡します。

新しいツールを追加する — docs/ARCHITECTURE.md §11 に従います。Params モデル + _impl(svc,…) + register() を追加し、すべてのクエリをキャンパススコープにし、strip_secrets を適用し、ルーティングの docstring を書き、server.py に登録します。tools/common.py の生データヘルパーを再利用します。

コールドスタート / 最初のリクエストが遅い — Free インスタンスがアイドル状態から起動したためです（約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 を参照。