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

도구

모든 도구는 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에 있습니다.

문서

• docs/ARCHITECTURE.md — 설계 및 경계

• docs/REFERENCE-ARCHITECTURE.md — 재사용 매트릭스 및 라이선스

• docs/LOCAL-DEV.md — 재현 가능한 로컬 설정

• docs/SECURITY.md — 비밀 처리, 인증, 표면 제약