mcp-usc

Santiago de Compostela 대학교(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 쿠키가 있으면 읽기는 동일 출처 AJAX와 직접 다운로드 /pluginfile.php를 사용합니다. HTML 양식은 이미 확인된 퀴즈 작업에만 사용됩니다.

• Playwright는 Microsoft Entra/MFA를 완료하고 초기 쿠키를 얻기 위해서만 보이는 브라우저를 엽니다. 로그인이 끝나면 닫힙니다.

• 모든 원격 텍스트(이름, 메시지, 질문, 공지 및 문서)는 신뢰할 수 없는 콘텐츠로 표시되며 지침으로 해석되지 않습니다.

• 커넥터는 인증된 계정의 권한으로만 작동합니다. 권한을 상승시키거나 교수진 또는 관리자를 사칭하지 않습니다.

• 학생 계정과 최소 권한 토큰으로 구성해야 합니다. 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 쿠키가 있는 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에 기능이 존재한다고 해서 토큰과 연결된 서비스에서 활성화되어 있다는 의미는 아닙니다.

쿠키 세션

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

보이는 창에서 Microsoft Entra 및 MFA를 직접 완료하세요. 프로그램은 MoodleSession만 추출하고, HTTP를 통해 세션을 확인한 후 시스템 보안 저장소(Windows의 Credential Manager)에 moodle-session 키로 쿠키를 저장합니다. 비밀번호는 MCP를 통과하지 않습니다.

로그인 후 모든 작업은 httpx를 사용합니다:

• /user/preferences.php는 대시보드를 열지 않고 신원과 임시 sesskey를 제공합니다;

• /lib/ajax/service.php는 AJAX로 표시된 기능을 실행합니다;

• Moodle이 AJAX로 게시하지 않으면 읽기는 폐쇄적으로 실패합니다;

• 인증된 다운로드는 쿠키를 유지하고, 직접 /pluginfile.php만 허용하며 로컬 제한을 적용합니다;

• 명시적 확인 후 특정 퀴즈 작업만 HTML 양식을 사용할 수 있습니다.

sesskey는 영구 저장되지 않으며 반환되지 않습니다. AJAX 프로토콜 요구 사항에 따라 Moodle 인프라가 보는 URL에 나타날 수 있습니다. 쿠키는 유효 기간 동안 자격 증명과 동일합니다. 복사, 기록, 게시 또는 동기화하지 마세요. 만료되면 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는 제출물의 전체 파일 세트를 교체합니다. 기존 파일에 조용히 하나를 추가하지 않습니다. 확인을 발급하기 전에 서비스가 업로드를 허용하고 제출물에 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개의 리디렉션을 따르며 문서당 최대 15MB를 다운로드합니다. 대규모 크롤링을 하지 않습니다. 지정된 소스와 해당 소스의 즉시 시험/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 활동에 대한 자신의 응답 제출 또는 철회.

이 여섯 가지 상황별 작업은 합법적인 REST 토큰이 이를 공개해야 합니다. Moodle 4.5–5.2는 일반적으로 해당 함수를 AJAX로 표시하지 않습니다. 쿠키 모드는 미리보기 전에 중지되며 브라우저로 이를 에뮬레이션하려고 시도하지 않습니다.

카탈로그는 아직 안전한 실행기가 없는 학생 작업도 식별합니다. 이들은 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)을 지원합니다. 기본적으로 다운로드를 25MiB, 텍스트를 100,000자, PDF를 100페이지로 제한합니다. 호출당 허용되는 최대값은 50MiB, 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가 필요합니다. 양식은 잠재적으로 상태를 가진 시도를 검사하거나, 시작하거나, 저장하거나, 종료하기 위해 두 번째 확인된 호출에서만 열립니다. 미리보기는 mod/quiz/view.php를 열지 않습니다.

• start_quiz는 즉시 타이머를 활성화할 수 있습니다.

• save_quiz_answers는 열린 시도를 수정하지만 종료하지는 않습니다.

• finish_quiz는 일반적으로 되돌릴 수 없습니다.

• 질문과 필드 이름은 Moodle에서 제공되며 신뢰할 수 없는 데이터로 취급되고 커넥터는 답변이 올바른지 절대 추론하지 않습니다.

• 각 쓰기 작업은 독립적인 미리보기를 요구합니다. 이전 승인은 시도의 다음 단계를 허가하지 않습니다.

확인 및 쓰기

모든 쓰기는 두 번의 호출을 따릅니다:

1. preview_*는 상태를 검증하고 표시 가능한 매개변수와 confirmation_token을 반환합니다.

2. 쓰기 도구는 작업과 매개변수가 정확히 일치하는 경우에만 해당 토큰을 사용합니다.

토큰은 메모리에만 존재하며 5분 후에 만료되고 일회용입니다. 텍스트, 수신자, 파일, 응답, 시도 또는 기타 입력을 변경하면 확인이 무효화됩니다. 호스트의 writes 승인은 두 번째 호출이 인간의 개입을 요구하도록 계속 활성 상태여야 합니다.

각 연락처 참조와 확인 토큰은 이를 생성한 Moodle user_id에도 연결됩니다. 미리보기와 쓰기 사이에 계정이나 세션이 변경되면 작업이 거부됩니다. HTML 양식에 대한 유효한 응답은 요청이 전송되었음을 확인할 뿐입니다. Moodle이 명확하지 않은 사후 조건을 제공하지 않으면 outcome="unknown"이 반환되며 모호한 응답에 대해 두 번째 전송 수단으로 재시도하지 않습니다.

쓰기 중 시간 초과 또는 연결 끊김은 모호합니다. 클라이언트가 응답을 받지 못했어도 Moodle이 작업을 적용했을 수 있습니다. 메시지, 제출물, 저장 또는 종료를 자동으로 반복하지 마십시오. 대화, 제출 상태 또는 시도를 다시 읽고 해당 증거로 결정하십시오. 시간 제한이 있는 퀴즈에서는 Moodle에서 직접 시계도 확인하십시오.

테스트

uv run pytest
uv run ruff check .

테스트 스위트는 HTTP, 키링, 양식, 업로드 및 다운로드를 테스트 더블로 대체합니다. 토큰, 쿠키 또는 실제 데이터가 포함되지 않으며 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를 반환하므로 로컬에서 얻은 쿠키를 사용한다.

• 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는 저장소에 라이선스가 명시되어 있지 않아 범위 비교에만 사용했으며 코드는 복사하지 않았다.

알려진 한계

• 각 웹 서비스의 가용성은 USC가 토큰 또는 세션에 부여하는 버전, 구성 및 권한에 따라 달라진다.

• OIDC 세션과 MoodleSession은 만료되므로 mcp-usc login을 다시 실행해야 한다.

• AJAX와 퀴즈 양식은 버전 간에 변경될 수 있다. 커넥터는 작업을 안전하게 인식하지 못하면 폐쇄적으로 실패한다.

• 과제는 REST를 요구한다: 해당 페이지는 조회수를 기록하며 filemanager JavaScript는 기본 multipart 필드와 동일하지 않다.

• 전체 제출물 삭제는 Moodle 4.5+ 및 유효한 권한이 필요하다. 마감된 제출물 재개설은 교수진의 몫이다.

• 모든 교수진이 캠퍼스 가상 환경을 사용하는 것은 아니다. 이메일이나 Teams에는 이 서버가 조회하지 않는 정보가 포함될 수 있다.

• Moodle의 날짜는 지속평가일 수 있고 공개 날짜는 공식 시험일 수 있다. 서로 다른 출처로 유지된다.