mcp-usc

サンティアゴ・デ・コンポステーラ大学（Universidade de Santiago de Compostela）のMoodleバーチャルキャンパス向けの、ローカルかつHTTPファーストなMCPサーバーです。コース、カレンダー、メッセージ、フォーラム、教材、課題、小テストの参照に加え、USC公式のページやPDFから試験日を検索することもできます。

バージョン0.3.0では、学生のカバレッジを調査済みのMoodle機能301件（許可された読み取り192件、特定された操作109件）に拡大しています。曖昧さのない範囲のプライベートな変更のうち、汎用インターフェースで実行できるのはわずか12件のみです。投稿、評価対象アクティビティ、提出物、小テスト、削除にはコンテキストツールを使用します。効果を伴うすべての操作には、プレビュー、ワンタイムトークン、MCPクライアントの承認が必要です。

設計原則

• MCPサーバーはSTDIOを使用します。「HTTPファースト」とは、このプロセスとMoodle/USC間の接続を指します。

• 通常のクエリおよび書き込み操作はブラウザを自動化しません。

• 正当なトークンがある場合は、Moodleの公式REST APIを優先します。

• MoodleSession Cookieがある場合、読み取りは同一オリジンのAJAXと直接ダウンロード/pluginfile.phpを使用します。HTMLフォームは、確認済みの小テスト操作にのみ予約されています。

• Playwrightは、Microsoft Entra/MFAを完了して初期Cookieを取得するためだけに、可視ブラウザを開きます。ログイン完了時に閉じられます。

• すべてのリモートテキスト（名前、メッセージ、質問、通知、ドキュメント）は信頼できないコンテンツとしてマークされ、指示として解釈されることは決してありません。

• コネクタは、認証されたアカウントの権限でのみ動作します。特権を昇格させたり、教員や管理者になりすましたりすることはありません。

• 学生アカウントと最小権限のトークンで設定する必要があります。Moodleの共有APIは常に実効権限を尊重し、追加のロールを持つアカウントは通常の学生よりも多くのデータを表示できる可能性があります。

メールやTeamsにはアクセスしません。Moodleの内部メッセージは、受信者の設定に応じて外部通知を生成する可能性があります。プレビューでは送信前にその旨が警告されます。

Related MCP server: MCP UJI Academic Server

要件

• Windows、Linux、またはmacOS

• Python 3.11以降

• uv推奨

• プライベートデータ用の有効なUSCアカウント

• オプションで、必要な機能を公開するMoodle Web Servicesトークン

インストール

git clone https://github.com/PabloPC05/mcp-usc.git
cd mcp-usc
uv sync --extra dev

これで、RESTトークンまたは保存済みセッションを使用してサーバーを実行するのに十分です。ログインアシスタントでセッションを作成または更新する必要がある場合にのみ、Playwrightをインストールします。

uv sync --extra dev --extra browser-auth
uv run playwright install chromium

アシスタントはChromiumまたはインストール済みのChrome/Edgeを使用できます。

$env:USC_BROWSER_CHANNEL = "chrome" # también "msedge" o "chromium"

認証とHTTPトランスポート

コネクタは、プライベートトランスポートを次の順序で自動的に選択します。

1. USC_MOODLE_TOKENまたはUSC_MOODLE_TOKEN_FILEがトークンを提供する場合の公式REST。

2. keyringに保存されたMoodleSession Cookieを使用したHTTP。

RESTトークン

アカウントとサービスに対してMoodleが発行した正当なトークンのみを使用します。

$env:USC_MOODLE_TOKEN = "..."
uv run mcp-usc status

保護されたローカルファイルから読み取ることもできます。

$env:USC_MOODLE_TOKEN_FILE = "C:\ruta\privada\moodle-token.txt"

login/token.phpでUSCパスワードを使用したり、.envに保存したりしないでください。Moodleに関数が存在しても、トークンに関連付けられたサービスで有効になっているとは限りません。

Cookieによるセッション

uv run mcp-usc login
uv run mcp-usc status

可視ウィンドウでMicrosoft EntraとMFAを自分で完了します。プログラムはMoodleSessionのみを抽出し、HTTPでセッションを検証し、Cookieをmoodle-sessionキーでシステムのセキュアストア（WindowsではCredential Manager）に保存します。パスワードはMCPを経由しません。

ログイン後、すべての操作はhttpxを使用します。

• /user/preferences.phpは、ダッシュボードを開かずにIDと一時的なsesskeyを提供します。

• /lib/ajax/service.phpはAJAXとしてマークされた関数を実行します。

• MoodleがAJAXで公開しない読み取りは、クローズドに失敗します。

• 認証付きダウンロードはCookieを保持し、直接の/pluginfile.phpのみを受け入れ、ローカル制限を適用します。

• 明示的な確認後、特定の小テスト操作のみがHTMLフォームを使用できます。

sesskeyは永続化も返却もされません。AJAXプロトコルの要件により、Moodleインフラストラクチャから見えるURLに表示される可能性があります。Cookieは有効な間は資格情報と同等です。コピー、記録、公開、同期はしないでください。期限切れになったら、mcp-usc loginを繰り返します。

互換性マトリックス

MoodleのfilemanagerマネージャーはJavaScriptでドラフトを作成するため、標準のmultipartフィールドとは異なります。提出物がそのマネージャーのみを提供する場合、ファイルの置換または削除には認可されたRESTトークンが必要です。セッションモードの公開ファイルツールは、何も変更せずに停止します。ファイルマネージャーのエミュレーションにPlaywrightは使用されません。

許可されたローカルファイル

アップロードツールは、許可リストフォルダーを設定するまで無効です。

$env:USC_UPLOAD_ROOT = "C:\Users\TU_USUARIO\Documents\mcp-usc-uploads"
$env:USC_MAX_UPLOAD_BYTES = "52428800"

USC_UPLOAD_ROOTが存在している必要があります。そのフォルダー内に解決される通常のファイルのみが受け入れられます。フォルダーから逃れるパスは追跡されず、同じファイルの二重受け入れはありません。プレビューでは、トークンを発行する前に、相対パス、名前、サイズ、SHA-256が表示されます。

アップロードのローカル制限：

• 操作ごとの最大ファイル数は20

• USC_MAX_UPLOAD_BYTESは各ファイルと合計の両方に適用されます

• デフォルト値：50 MiB（52428800バイト）

• 設定可能な範囲：1バイトから100 MiB

• オンラインテキストには追加で1 MiBの制限があります

replace_submission_filesは提出物のファイルセット全体を置き換えます。既存のファイルに静かに1つ追加することはありません。確認を発行する前に、サービスがアップロードを許可し、提出物にfileプラグインのみがアクティブであることを確認します。同様に、RESTテキスト保存は、onlinetextが唯一のアクティブなプラグインである場合にのみ有効になります。Moodleはmod_assign_save_submissionで全プラグインを処理するため、未知の組み合わせはドラフト作成や提出物の変更前に拒否されます。

試験の公開ソース

各USCセンターは独自のカレンダーを公開しています。正規のページまたはPDFをセミコロン区切りで設定します。

$env:USC_EXAM_SOURCES = "https://www.usc.gal/gl/centro/MI_CENTRO/horarios/cursos;https://assets.usc.gal/ruta/calendario.pdf"

検索は直接HTTPを使用し、usc.gal/usc.es配下のHTTPSのみを受け入れ、最大5回のリダイレクトを追跡し、ドキュメントあたり最大15 MBをダウンロードします。大規模なクローリングは行いません。指定されたソースとその直接の試験/PDFリンクを照会します。各証拠はURL、該当する場合はPDFページ、照会時刻を保持します。矛盾するソースは競合として表示されます。

Codexへの接続

このマシンのPowerShellから：

codex mcp add usc-campus -- uv --directory C:\Users\pablo\mcp-usc run mcp-usc serve
codex mcp list

MCP設定から公開ソースを含めるには：

codex mcp remove usc-campus
codex mcp add usc-campus --env USC_EXAM_SOURCES="https://www.usc.gal/gl/centro/MI_CENTRO/horarios/cursos" -- uv --directory C:\Users\pablo\mcp-usc run mcp-usc serve

クライアントを再起動するか、新しいセッションを開いてサーバーを読み込みます。OpenAI公式ドキュメントによると、MCP設定はChatGPTアプリ、Codex CLI、同じホストのIDE拡張機能の間で共有されます。

さらに、%USERPROFILE%\.codex\config.tomlでホストの承認を有効にして、すべての書き込みを許可します。

[mcp_servers.usc-campus]
command = "uv"
args = ["--directory", 'C:\Users\pablo\mcp-usc', "run", "mcp-usc", "serve"]
default_tools_approval_mode = "writes"

MCPアノテーション、プレビュー、トークン、ホストの承認は補完的なレイヤーであり、いずれも正確なパラメータに関する人間の判断に取って代わるものではありません。

MCPツール

バージョン0.3.0は75のツールを公開します：39の読み取り、18のプレビュー、18の効果を伴う操作。完全な機能調査では、インベントリ、セキュリティ境界、Moodle 4.5と5.2の違いについて説明しています。

call_student_read はホワイトリストに明示的に含まれる192の関数のみを受け付ける。任意のMoodleプロキシではない。RESTトークンを使用する場合、list_student_capabilities(available_only=true) で設定されたサービスが公開する関数を確認できる。AJAXセッションでは完全な利用可能性が常に検出できるとは限らず、Moodleが関数を公開していない場合、各呼び出しはクローズドで失敗する。

12の汎用アクションは、自分の設定、プライベートお気に入り、会話・通知のミュートまたはマーク、未送信下書きの保持、質問のマークに限定される。新しいコンテキストアクションは、確認を発行する前に、独自HTTP、コース、フォーラム、グループ、対象、フェーズ、オプションを解決する：

• カレンダーの個人イベントを作成または削除する；

• 添付ファイルなし・プライベート返信なしで、フォーラムでディスカッションを開始するか公開返信する；

• Choiceアクティビティの自分の回答を送信または撤回する。

これらの6つのコンテキストアクションは、正当なRESTトークンがそれらを公開している必要がある。Moodle 4.5–5.2 は通常、その関数をAJAXとしてマークしない。Cookieモードはプレビュー前に停止し、ブラウザでエミュレートしようとしない。

カタログはまた、まだ安全な実行基盤がない学生アクションも識別する。これらは generic_execution_supported=false として公開される：インベントリに表示されても実行できるわけではなく、USCが対応するモジュールやプラグインを有効にしていることを意味するわけでもない。

メッセージ、フォーラム、教材

• list_messages は受信または送信メッセージを既読にせずに読み取る。list_conversations は互換性のためだけに保持され、クローズドで失敗する：一部のMoodleバージョンでは、その想定された読み取りを実行すると、自分自身との会話が作成されお気に入りにマークされる可能性がある。

• フォーラムには、お知らせだけでなく、表示可能なすべてのフォーラムが含まれる。Moodleは mod_forum_get_discussion_posts の実行時に投稿を既読としてマークする可能性がある。そのため list_discussion_posts はクローズドで失敗し、preview_inspect_discussion_posts / inspect_discussion_posts のペアは、投稿と添付ファイルのメタデータを走査する前に確認を要求する。

• search_message_contacts は受信者への一時参照を作成する。preview_message は最近の検索を要求し、名前、ID、テキストを表示し、決して送信しない。

• list_course_contents はセクション、アクティビティ、ページ、リンク、ファイルを一覧表示する。

• list_course_resources は10分間有効な不透明な参照を返す。最近の参照のみが read_course_resource で使用できる。

• read_course_resource はPDF、テキスト/HTML、OOXML（.docx、.pptx、.xlsx）をサポートする。デフォルトではダウンロードを25 MiB、テキストを100,000文字、PDFを100ページに制限する。呼び出しごとに受け入れられる最大値は50 MiB、500,000文字、300ページ。

• セッションモードでは、コンテンツとお知らせは純粋なAJAX関数を要求し、リソースは /pluginfile.php を直接指す必要がある。course/view.php、mod/*/view.php、フォーラムページを開くことは、閲覧の記録、既読のマーク、完了状態の変更につながる可能性があるため拒否される。

課題と提出

• 必要な関数を公開するRESTトークンを使用すると、課題の一覧表示、下書き、ファイル、オンラインテキスト、フィードバック、権限の照会ができる。

• 課題のHTMLページは閲覧を記録し、完了状態を変更する可能性がある。そのため、セッションモードでは、すべての課題の読み取り、プレビュー、書き込みは、ページを開く前に失敗する。

• テキストの保存、ファイルの置換/削除、採点のための提出、提出全体の削除は、それぞれ独自のプレビューを持つ別々の書き込みである。

• submit_assignment は下書きの編集を閉じる可能性があり、Moodleが表示する提出宣言を尊重しなければならない。

• remove_submission は Moodle 4.5 以降で利用可能な mod_assign_remove_submission を使用する。破壊的であり、「再開」と同等ではない。

• check_submission_reopen は状態を決して変更しない。提出がすでに編集可能であればそれを通知し、閉じられている場合、標準APIは再開を教員に留保する。コネクタはその制限を回避しようとしない：通常のチャネルで教員に再開を依頼する必要がある。

小テスト

• 小テストと自分の受験を一覧表示し、すでに終了した受験の許可されたレビューを読み取ることができる。

• アクティブな受験のデータまたはサマリーを開くと、Moodleが期限切れを処理してその状態を変更する可能性がある。そのため get_quiz_attempt_page と get_quiz_attempt_summary はクローズドで失敗する。preview_inspect_quiz_attempt はリスクを表示し、inspect_quiz_attempt は確認を要求する。

• セッションモードでは、純粋な一覧はAJAXを要求する。フォームは、潜在的にステートフルな受験の検査、開始、保存、終了のために、2回目の確認済み呼び出しでのみ開かれる。プレビューは mod/quiz/view.php を開かない。

• start_quiz は即座にタイマーを起動する可能性がある。

• save_quiz_answers は開いている受験を変更するが、終了はしない。

• finish_quiz は通常、不可逆的である。

• 質問とフィールド名はMoodleから取得され、信頼できないデータとして扱われ、コネクタは回答が正しいかどうかを決して推測しない。

• 各書き込み操作は独立したプレビューを要求する。以前の承認は受験の次のステップを許可しない。

確認と書き込み

すべての書き込みは2回の呼び出しに従う：

1. preview_* は状態を検証し、表示可能なパラメータと confirmation_token を返す。

2. 書き込みツールは、アクションとパラメータが完全に一致する場合にのみそのトークンを消費する。

トークンはメモリ内にのみ存在し、5分で期限切れになり、一度きりの使用である。テキスト、受信者、ファイル、回答、受験、その他の入力を変更すると、確認は無効になる。ホストの writes 承認が引き続き有効でなければ、2回目の呼び出しで人間の介入が必要になる。

各連絡先参照と確認トークンは、それを作成したMoodleの user_id にも結び付けられる。プレビューと書き込みの間でアカウントまたはセッションが変更された場合、操作は拒否される。HTMLフォームへの有効な応答は、リクエストが送信されたことのみを確認する：Moodleが明確な事後条件を提供しない場合、outcome="unknown" が返され、曖昧な応答に対して2番目のトランスポートで再試行されることは決してない。

書き込み中のタイムアウトまたは接続切断は曖昧である：クライアントが応答を受信しなくても、Moodleが操作を適用した可能性がある。メッセージ、提出、保存、終了を自動的に繰り返さない。会話、提出状態、受験を再読み込みし、その証拠に基づいて判断する。時間制限付き小テストでは、Moodleで直接時計も確認する。

テスト

uv run pytest
uv run ruff check .

スイートはHTTP、キーリング、フォーム、アップロード、ダウンロードをテストダブルに置き換える。トークン、Cookie、実データは含まれず、USCに対して書き込みを実行しない。実際のアクセスは手動かつローカルのみで検証される。

公式ソース

この契約は公式のドキュメントとコードと照合された：

• Moodleの外部サービスとその セキュリティ推奨事項。

• 公式GPL-3.0リポジトリからのMoodle 4.5の メッセージング、 フォーラム、 コンテンツ、 課題、 小テスト の定義。

• moodlehq/moodleapp（Apache-2.0）、クライアントから サービス、コンテンツ、リソースを利用する際の公式リファレンス。

レビュー済みの先行研究

すでに解決済みのパターンを繰り返さないよう、ライセンスのあるプロジェクトを調査した。 アーキテクチャのアイデアと公開契約は再利用したが、認証情報や互換性のないコードは再利用していない。

• haolamnm/moodle-mcp-srv（Apache-2.0）：アーキテクチャ、 診断、RESTクライアント。

• Snaw80/moodle-mcp（MIT）：SSOログインとモバイルフロー。USCの 公開モバイルエンドポイントは404を返すため、ローカルで取得したCookieを使用する。

• GhaithAlHallak8/moodler-mcp（MIT）：Moodleセッション と同一オリジンのAJAX。

• 1alexandrer/moodle-mcp（MIT）：学生向けツールと アクション可能なイベント。

• mrcinv/moodle_api.py（MIT）：汎用クライアントと core_course_get_contents。

• lmscloud-io/moodle-mcp-server（GPL-3.0）： 最小権限でMoodle関数をMCP公開。

loyaniu/moodle-mcpは、リポジトリがライセンスを宣言していないため、スコープ比較のみに使用した。 コードはコピーしていない。

既知の制限事項

• 各Webサービスの利用可否は、USCがトークンまたはセッションに割り当てるバージョン、設定、権限に依存する。

• OIDCセッションとMoodleSessionは失効するため、mcp-usc loginを再実行する必要がある。

• AJAXと小テストのフォームはバージョン間で変更される可能性がある。コネクタは、操作を安全に認識できない場合、 フェイルクローズド方式で失敗する。

• 課題にはRESTが必要である。そのページはビューを記録し、filemanager JavaScriptはネイティブの multipartフィールドに相当しない。

• 提出物全体の削除にはMoodle 4.5以上と有効な権限が必要である。クローズ済みの提出物の再オープンは 教員の権限である。

• すべての教員がCampus Virtualを使用しているわけではない。メールやTeamsには、このサーバーが 参照しない情報が含まれる可能性がある。

• Moodleの日付は継続的評価であり、公開日付は公式試験である場合がある。これらは別々の情報源として 保持される。