mcp-usc

Локальный и HTTP-first MCP-сервер для виртуального кампуса Moodle Университета Сантьяго-де-Компостела. Позволяет просматривать курсы, календарь, сообщения, форумы, материалы, задания и тесты, а также искать даты экзаменов на официальных страницах и в PDF-документах USC.

Версия 0.3.0 расширяет охват студенческих возможностей до 301 изученной возможности Moodle: 192 разрешённых чтения и 109 выявленных действий. Только двенадцать приватных изменений однозначного охвата можно выполнить через общий интерфейс; публикации, оцениваемые активности, сдачи работ, тесты и удаления используют контекстные инструменты. Любая операция с эффектом требует предварительного просмотра, одноразового токена и одобрения MCP-клиента.

Принципы проектирования

• MCP-сервер использует STDIO; «HTTP-first» описывает соединение между этим процессом и Moodle/USC.

• Обычные запросы и записи не автоматизируют браузер.

• Предпочтение отдаётся официальному REST API Moodle при наличии легитимного токена.

• С cookie MoodleSession чтения используют AJAX same-origin и прямые загрузки /pluginfile.php. HTML-формы reserved только для уже подтверждённых операций с тестами.

• Playwright открывает видимый браузер только для завершения Microsoft Entra/MFA и получения начальной cookie. Он закрывается по завершении входа.

• Весь удалённый текст — имена, сообщения, вопросы, уведомления и документы — помечается как ненадёжное содержимое и никогда не интерпретируется как инструкции.

• Коннектор действует только с правами аутентифицированной учётной записи: не повышает привилегии и не выдаёт себя за преподавателей или администрацию.

• Должен быть настроен с учётной записью студента и токеном минимальных привилегий. Общие API Moodle всегда соблюдают действующие права, и учётная запись с дополнительными ролями может видеть больше данных, чем обычный студент.

Не обращается к почте и 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. Официальный REST, если USC_MOODLE_TOKEN или USC_MOODLE_TOKEN_FILE предоставляет токен.

2. HTTP с cookie MoodleSession, сохранённой через keyring.

REST-токен

Используй только легитимный токен, выданный Moodle для твоей учётной записи и сервиса:

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

Также может быть прочитан из защищённого локального файла:

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

Не используй свой пароль USC с login/token.php и не храни его в .env. Наличие функции в Moodle не означает, что она включена в сервисе, связанном с токеном.

Сессия через cookie

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

Лично заверши Microsoft Entra и MFA в видимом окне. Программа извлекает только MoodleSession, проверяет сессию через HTTP и сохраняет cookie под ключом moodle-session в защищённом хранилище системы — Credential Manager в Windows. Пароль не проходит через MCP.

После входа все операции используют httpx:

• /user/preferences.php предоставляет идентичность и эфемерный sesskey без открытия панели управления;

• /lib/ajax/service.php выполняет функции, помеченные как AJAX;

• чтения закрываются безопасно, если Moodle не публикует их через AJAX;

• аутентифицированные загрузки сохраняют cookie, принимают только прямой /pluginfile.php и применяют локальные ограничения;

• только определённые операции с тестами, после явного подтверждения, могут использовать HTML-формы.

sesskey не сохраняется и не возвращается. По требованию протокола AJAX он может появляться в URL, который видит инфраструктура Moodle. Cookie эквивалентна учётным данным, пока действует: не копируй, не записывай, не публикуй и не синхронизируй её. Когда она истечёт, повтори mcp-usc login.

Матрица совместимости

Менеджер filemanager в Moodle создаёт черновики через JavaScript и не эквивалентен стандартному multipart-полю. Если сдача предлагает только этот менеджер, замена или удаление его файлов требует авторизованного REST-токена; публичные файловые инструменты в режиме сессии останавливаются без изменений. Playwright не используется для эмуляции файлового менеджера.

Разрешённые локальные файлы

Инструменты загрузки отключены до настройки папки allowlist:

$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 МиБ (52428800 байт);

• настраиваемый диапазон: от 1 байта до 100 МиБ;

• онлайн-текст имеет дополнительное ограничение в 1 МиБ.

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, принимает только HTTPS под usc.gal/usc.es, следует максимум пяти перенаправлениям и загружает максимум 15 МБ на документ. Не выполняет массовый краулинг: запрашивает указанные источники и их непосредственные ссылки на экзамены/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 не предоставляет функцию.

Двенадцать общих действий ограничены собственными предпочтениями, личными избранными, отключением звука или пометкой бесед/уведомлений, сохранением неотправленного черновика и пометкой вопроса. Новые контекстные действия разрешаются через проприетарный HTTP, курс, форум, группу, аудиторию, фазу и варианты перед выдачей подтверждения:

• создавать или удалять личные события календаря;

• начинать обсуждение или отвечать публично на форуме, без вложений и без личного ответа;

• отправлять или отзывать собственные ответы в активности Choice.

Эти шесть контекстных действий требуют, чтобы их объявлял легитимный 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 возвращает непрозрачные ссылки на десять минут. Только недавняя ссылка может использоваться с read_course_resource.

• read_course_resource поддерживает PDF, текст/HTML и OOXML (.docx, .pptx, .xlsx). По умолчанию ограничивает загрузку 25 МиБ, текст 100 000 символами и PDF 100 страницами; максимальные значения, принимаемые за вызов: 50 МиБ, 500 000 символов и 300 страниц.

• В режиме сессии содержимое и объявления требуют чистой AJAX-функции, а ресурсы должны указывать напрямую на /pluginfile.php; открытие course/view.php, mod/*/view.php или страниц форума отклоняется, поскольку может регистрировать посещения, помечать прочитанное или изменять завершение.

Задания и сдачи

• С REST-токеном, объявляющим необходимые функции, можно перечислять задания и запрашивать черновик, файлы, онлайн-текст, отзыв и разрешения.

• HTML-страницы заданий регистрируют просмотры и могут изменять завершение; поэтому все чтения, предпросмотры и записи заданий завершаются с ошибкой до их открытия в режиме сессии.

• Сохранение текста, замена/удаление файлов, отправка на оценку или удаление всей сдачи — это разные записи, каждая со своим предпросмотром.

• submit_assignment может закрыть редактирование черновика и должен соблюдать заявление о сдаче, которое показывает Moodle.

• remove_submission использует mod_assign_remove_submission, доступную в Moodle 4.5 или новее. Это деструктивно и не эквивалентно «повторному открытию».

• 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. Инструмент записи использует этот токен только если действие и параметры совпадают точно.

Токены существуют только в памяти, истекают через пять минут и одноразовые. Изменение текста, получателя, файлов, ответов, попытки или любых других входных данных аннулирует подтверждение. Одобрение writes хоста должно оставаться активным, чтобы второй вызов требовал вмешательства человека.

Каждая ссылка на контакт и токен подтверждения также привязаны к user_id Moodle, который их создал. Если учётная запись или сессия меняется между предпросмотром и записью, операция отклоняется. Действительный ответ на HTML-форму подтверждает только то, что запрос был отправлен: возвращается outcome="unknown", когда Moodle не предлагает однозначного постусловия, и повторная попытка через второй транспорт при неоднозначном ответе никогда не выполняется.

Тайм-аут или обрыв соединения во время записи неоднозначен: Moodle мог применить операцию, даже если клиент не получил ответ. Не повторяй автоматически сообщение, сдачу, сохранение или завершение. Перечитай беседу, состояние сдачи или попытку и решай на основе этих данных; в тесте с таймером проверь также часы напрямую в Moodle.

Тестирование

uv run pytest
uv run ruff check .

Набор тестов заменяет HTTP, keyring, формы, загрузки и скачивания тестовыми двойниками. Он не содержит токенов, cookie или реальных данных и не выполняет никаких записей против USC. Реальный доступ проверяется только вручную и локально.

Официальные источники

Контракт был сверен с официальной документацией и кодом:

• External Services от Moodle и его рекомендации по безопасности.

• Определения Moodle 4.5 для обмена сообщениями, форумов, контента, заданий и тестов из официального репозитория GPL-3.0.

• 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 same-origin.

• 1alexandrer/moodle-mcp (MIT): инструменты, ориентированные на студентов, и действенные события.

• mrcinv/moodle_api.py (MIT): универсальный клиент и core_course_get_contents.

• lmscloud-io/moodle-mcp-server (GPL-3.0): MCP-представление функций Moodle с минимальными привилегиями.

loyaniu/moodle-mcp использовался только для сравнения охвата, поскольку репозиторий не объявляет лицензию; код не копировался.

Известные ограничения

• Доступность каждого Web Service зависит от версии, конфигурации и разрешений, которые USC назначает токену или сессии.

• Сессия OIDC и MoodleSession истекают; нужно снова выполнить mcp-usc login.

• AJAX и формы тестов могут меняться между версиями. Коннектор отказывает в закрытом режиме, если не может безопасно распознать операцию.

• Задания требуют REST: их страницы регистрируют просмотры, а JavaScript-filemanager не эквивалентен нативному multipart-полю.

• Удаление полной сдачи требует Moodle 4.5+ и действующих разрешений. Повторное открытие закрытой сдачи — задача преподавательского состава.

• Не весь преподавательский состав использует Campus Virtual; почта или Teams могут содержать информацию, которую этот сервер не запрашивает.

• Дата в Moodle может быть непрерывной оценкой, а публичная дата — официальным экзаменом. Они сохраняются как разные источники.