moodle-ai-mcp

Moodle向けAIネイティブMCPコントロールプレーン。

MCPクライアント（Claude Code、ChatGPT、Cursor、その他Model Context Protocolを話す任意のクライアント）がこのサーバーに接続し、実際のMoodleサイトに関する構造化された正確な回答を得ます。すなわち、サイトが何であるか、接続が誰として認証されているか、その接続に何が許可されているか、Moodleの外部関数のうちどれに到達できるか、そして——RESTラッパー以上の価値を生む部分——サイトにインストールされているH5Pライブラリが正確にどれで、そのコンテンツスキーマが何であるか、です。

これはMoodle RESTの薄いラッパーではありません。長期的な目標は、AIクライアントがコース全体を安全に設計・構築するために使用できるコントロールプレーンです。このリポジトリには現在、その最初の基盤が含まれています。

現在の成熟度: 基盤マイルストーン、読み取り専用

現在動作しているもの:

• 公式MCP TypeScript SDK上に構築された、7つの厳選ツールを備えたstdio上のMCPサーバー

• 7つの読み取り専用外部関数、実際のケイパビリティ強制、PHPUnitカバレッジを備えたMoodle 5.2ローカルプラグイン（local_aimcp）

• ケイパビリティを認識するコース読み取りモデル: セクション、アクティビティ、完了設定、成績設定。hiddenフラグが付いたすべてではなく、認証されたアイデンティティが実際に閲覧できるものを反映

• 認証されたサービスが到達できる外部関数の動的発見と、ロスレスのシグネチャイントロスペクション

• インストール済みH5Pライブラリとその実際のインストール済みセマンティクスの動的発見。JSON Schemaが表現できないすべてのものに明示的な注記を付けてJSON Schemaに変換

意図的に構築していないもの: 書き込み操作、コース/アクティビティ/H5P作成、Course Blueprintエンジン、ブラウザ自動化、ファイル転送、ホスティングインフラストラクチャ。下記の「制限事項」を参照してください。

Related MCP server: Drupal Bridge MCP

アーキテクチャ

AI client  --MCP/stdio-->  apps/mcp-server (TypeScript, MIT)
                                 |
                                 |  authenticated Moodle web service call
                                 v
                           moodle/local/aimcp (Moodle plugin, GPL-3.0-or-later)
                                 |
                                 v
                           Moodle 5.2 core + H5P core

サーバーはプロトコル、ツールサーフェス、オーケストレーション、スキーマ変換を所有します。プラグインはMoodleだけが答えられるすべてを所有します: アイデンティティ、コンテキスト、ケイパビリティ、外部関数レジストリ、H5Pエンジン。MoodleのロジックがTypeScriptで再実装されることは決してなく、オーケストレーションがPHPに漏れることもありません。

ツールサーフェスが数百ではなく6つのツールである理由を含む詳細は、docs/ARCHITECTURE.mdにあります。

前提条件

• Node.js 24

• moodle-dockerのMoodle 5.2スタックを備えたDocker

• 有効な外部サービスで認可されたユーザーのMoodleウェブサービストークン

ローカル開発

完全な手順: docs/LOCAL-DEV.md。短いバージョン:

cd ~/DEV/moodle-ai/moodle-ai-mcp

# 1. Start the Moodle stack (installs the persistence override, mounts the plugin)
./scripts/stack.sh start

# 2. Register the plugin with Moodle
docker exec -u www-data -w /var/www/html moodle-ai-webserver-1 \
  php admin/cli/upgrade.php --non-interactive

# 3. Attach the plugin's functions to your external service (idempotent)
docker exec -u www-data -w /var/www/html moodle-ai-webserver-1 \
  php public/local/aimcp/cli/provision_service.php --service=moodle_ai_mcp_dev

# 4. Build and run the server
npm install
npm run build
./scripts/run-server.sh

データベース、moodledata、インストール済みH5Pライブラリは名前付きDockerボリュームに格納されるため、./scripts/stack.sh recreateは安全です。データを破壊するのは./scripts/stack.sh resetだけで、しかも確認を求めます。いつでも./scripts/backup.shでバックアップできます。

認証情報は.env.localから取得されます。これはこのリポジトリの外部にあるファイルへのシンボリックリンクです。.env*はgitignoreされています。docs/SECURITY.mdを参照してください。

MCPクライアントの接続

claude mcp add moodle-ai --scope local -- \
  /absolute/path/to/moodle-ai-mcp/scripts/run-server.sh

またはInspectorを使用:

npx @modelcontextprotocol/inspector ./scripts/run-server.sh

ツール

すべてのツールはreadOnlyHint: true、destructiveHint: falseで注釈され、structuredContentとJSONテキストのフォールバックの両方を返します。

「任意のMoodle関数を呼び出す」汎用ツールは意図的にありません。検索と説明によってロングテールを発見可能にします。任意の関数の実行には、まだ存在しない安全性の分類が必要です。

テスト

npm --prefix apps/mcp-server run typecheck      # TypeScript, strict
npm --prefix apps/mcp-server run test:unit      # pure logic, no Moodle needed
npm --prefix apps/mcp-server run build
npm --prefix apps/mcp-server run test:integration  # real Moodle + real MCP session

./scripts/lint-plugin.sh    # php -l over the plugin
./scripts/check-plugin.sh   # Moodle coding standard (moodle-cs)
./scripts/test-plugin.sh    # PHPUnit inside the Moodle container

統合スイートはモックではありません。ビルド済みサーバーを子プロセスとして起動し、公式SDKクライアントでMCPを話し、ライブサイトに対してアサートします——アイデンティティが期待どおりのMoodleユーザーであること、トークンがどの出力にも現れないことを含みます。

制限事項

• MCP上では読み取り専用。 作成、更新、削除、登録、採点、アップロード、ダウンロードはありません。リポジトリ内でMoodleに書き込む唯一のものは開発フィクスチャCLIであり、これはMCPクライアントやウェブサービスからは到達できません（docs/SECURITY.mdを参照）。

• 任意の関数実行は不可。 検索と説明のみ。

• stdioのみ。 HTTPトランスポートは将来の追加予定。ドメイン層はすでにトランスポート非依存。

• Course Blueprintなし、diff/applyエンジンなし、コンテンツ生成なし。

• ブラウザ自動化なし、スクリーンショットなし、アクセシビリティ監査なし。

• moodle_course_inspectはコースの構造を返します。学習者のパフォーマンスではありません。成績もユーザーごとの完了状態もありません。

• Moodleのフロントページはコース行ですが教育用コースではないため、moodle_course_inspectはそれを拒否します。moodle_course_listは依然としてそれを報告し、isSiteCourseフラグを付けます。

• H5Pスキーマ生成は1レベル深さまで: ネストされたlibraryフィールドはラッパーの形状と許可されたライブラリバージョンを固定しますが、そのparamsはそのライブラリ自身のセマンティクスに従います——2回目のmoodle_h5p_schema呼び出しで取得してください。

• JSON Schemaで表現できないH5PおよびMoodleの構造がいくつかあります（showWhen条件、HTMLタグホワイトリスト、PCREパターン、PARAMクリーニングルール）。これらはx-h5p-* / x-moodle-*注釈として保持され、破棄されるのではなく変換ノートとして報告されます。

• Moodle RESTは空の配列や真のnullを表現できません。クライアントは両方を明示的な警告として報告します。

• プラグインはこのリポジトリからコンテナにバインドマウントされます。rsyncコピーはフォールバックとしてのみ保持されます。ホストのシンボリックリンクは機能しません。理由はdocs/LOCAL-DEV.mdで説明されています。

ライセンス

• apps/mcp-server/ — MIT

• moodle/local/aimcp/ — GPL-3.0-or-later（必須: Moodleプラグインのため）

GPL実装コードはMITサーバーにコピーされていません。参照プロジェクトはアーキテクチャ参照として研究され、クリーンルームで再実装されました。プロジェクトごとの論拠はdocs/REFERENCE-ARCHITECTURE.mdにあります。

ドキュメント

• docs/ARCHITECTURE.md — 設計と境界

• docs/REFERENCE-ARCHITECTURE.md — 再利用マトリックスとライセンス

• docs/LOCAL-DEV.md — 再現可能なローカルセットアップ

• docs/SECURITY.md — シークレット処理、認可、サーフェス制約