Skip to main content
Glama

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개의 읽기 전용 외부 함수, 실제 권한(capability) 적용 및 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로 유출되지 않습니다.

도구 표면이 수백 개가 아닌 7개인 이유를 포함한 세부 사항은 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

도구

도구

답변 내용

moodle_site_inspect

이 Moodle은 무엇인가, 어떤 사용자로 연결되었는가, 해당 사용자가 무엇을 할 수 있는가, 어떤 플러그인과 H5P를 사용할 수 있는가.

moodle_course_list

이 사용자에게 존재하고 표시되는 강좌는 무엇인가, 선택적으로 검색 가능.

moodle_course_inspect

하나의 강좌 구조: 순서대로 된 섹션, 강좌 페이지 순서의 활동, 완료 구성 및 성적 항목 구성. 호출자가 볼 수 없는 것은 생략하고, 강좌 관리 필드(원시 가용성 규칙, 모듈 ID 번호)는 Moodle 자체 편집자 권한 뒤에 게이트하며, 얼마나 숨겼는지 명시.

moodle_functions_search

이 연결이 도달할 수 있는 Moodle 외부 함수는 무엇인가, 관련성 순으로 정렬. 내장 목록이 아닌 실시간 검색.

moodle_functions_describe

하나의 함수 전체 시그니처: Moodle 자체 매개변수 및 반환 트리, 생성된 JSON Schema 및 변환 메모.

moodle_h5p_types

어떤 H5P 라이브러리가 설치되어 있는가, 정확한 버전, 실행 가능한 콘텐츠 유형은 무엇인가, 종속성 전용은 무엇인가, Moodle이 현재 저작에 제공하는 것은 무엇인가.

moodle_h5p_schema

하나의 H5P 라이브러리 버전에 대한 설치된 의미론, 생성된 JSON Schema 및 H5P가 표현하지만 JSON Schema로는 표현할 수 없는 모든 것에 대한 메모.

모든 도구는 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

통합 테스트 스위트는 목(mock)이 아닙니다: 빌드된 서버를 자식 프로세스로 실행하고, 공식 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 스키마 생성은 한 단계 깊이입니다: 중첩된 library 필드는 래퍼 형태와 허용된 라이브러리 버전을 고정하지만, 해당 params는 그 라이브러리 자체의 의미론을 따릅니다 — 두 번째 moodle_h5p_schema 호출로 가져오세요.

  • 일부 H5P 및 Moodle 구조는 JSON Schema로 표현할 수 없습니다(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에 있습니다.

문서

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers