ufsc-moodle-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PORT | No | Porta do servidor HTTP MCP. | 8088 |
| MOODLE_URL | No | URL base do Moodle da UFSC. | https://presencial.moodle.ufsc.br |
| MCP_AUTH_TOKEN | No | Token Bearer obrigatório para autenticar clientes MCP no modo HTTP. | |
| MOODLE_OCR_DPI | No | Resolução de rasterização Poppler. | 200 |
| MOODLE_PASSWORD | No | Senha CAS UFSC para obtenção dinâmica de token do Moodle. | |
| MOODLE_USERNAME | No | Usuário CAS UFSC para obtenção dinâmica de token do Moodle. | |
| PUBLIC_BASE_URL | No | URL pública externa do proxy (ex.: https://n8n.labsec.ufsc.br/mcp/moodle). | |
| MOODLE_API_TOKEN | No | Token Web Service estático do Moodle (moodle_mobile_app). | |
| MOODLE_OCR_ENABLED | No | Habilita o processamento local de OCR. | true |
| MOODLE_OCR_LANGUAGES | No | Idiomas padrão do Tesseract. | eng,por |
| MOODLE_OCR_MAX_PAGES | No | Limite máximo de páginas por arquivo para OCR. | 30 |
| MOODLE_OCR_TIMEOUT_MS | No | Timeout global base de OCR por documento, ajustado dinamicamente pelo número de páginas. | 120000 |
| MOODLE_GRADING_STATE_DIR | No | Diretório para persistência de operações em lote. | /config/grading-state |
| MOODLE_OCR_MAX_CONCURRENCY | No | Limite de processos de OCR concorrentes. | 2 |
| MOODLE_OCR_PAGE_TIMEOUT_MS | No | Timeout individual de OCR por página renderizada. | 60000 |
| MOODLE_GRADING_AUDIT_LOG_PATH | No | Caminho do log JSONL de auditoria de avaliações. | /config/grading-audit.jsonl |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Use get_moodle_capabilities para inspecionar ferramentas expostas, limites, OCR e capacidades do servidor v1.2.1. Para avaliar uma tarefa de turma inteira com mínima latência: (1) chame get_assignment_grading_overview(assignmentId) para obter resumo da tarefa, grupos efetivos (excluindo grupos gerais de turma), entregas, notas agregadas/individuais, comentários de feedback e cobertura; (2) use get_submission_content(assignmentId, groupId ou studentId, extractFiles=true, ocrMode="auto") ou read_moodle_file(..., ocrMode="auto") para ler tanto PDFs nativos quanto PDFs digitalizados/Canvas com coordenadas visuais sem precisar sair do MCP (ou download_moodle_file para obter o binário original); (3) NUNCA altere notas/feedbacks sem revisão do professor: gere primeiro uma prévia estritamente de leitura com prepare_grading_batch, apresente ao professor, publique somente após confirmação explícita via commit_grading_batch (com planId, approvedPlanHash, confirmedByReviewer=true, operationId, publicationState e notificationPolicy) e valide em seguida com verify_grading_batch.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_site_infoB | Retorna informações do usuário autenticado (userid, nome completo, username) e da instância do Moodle da UFSC. |
| get_coursesA | Lista todas as disciplinas (cursos) em que o usuário está inscrito ou leciona no Moodle da UFSC. Permite filtrar por código/nome/semestre (ex: "20262" ou "INE5429") ou buscar um courseId específico. |
| get_course_contentsA | Retorna todas as seções/tópicos, materiais (arquivos PDF, slides, links) e atividades (tarefas, fóruns, questionários) de uma disciplina. As URLs de arquivos retornadas podem ser baixadas via download_moodle_file ou lidas via read_moodle_file. |
| get_studentsA | Lista os participantes inscritos em uma disciplina (alunos, professores, monitores) com nome, e-mail, papéis (roles) e grupos. |
| get_assignmentsA | Lista todas as tarefas (assignments) de uma disciplina, incluindo enunciado, anexos do enunciado (baixáveis via download_moodle_file), configuração de entrega em grupo (teamsubmission), prazos e nota máxima. |
| get_submissionsB | Lista as entregas individuais e coletivas (userid=0) de uma tarefa ou disciplina, diferenciando grupos gerais de turma de grupos efetivos do projeto (assignmentGroupId / assignmentGroupMembers sem professores), e separando o estado bruto da linha coletiva no Moodle (rawMoodleGradingStatus) do estado real agregado das avaliações dos integrantes (aggregatedGradingStatus: not_graded | partially_graded | fully_graded | inconsistent, commonGroupGrade e memberEvaluations). |
| get_submission_contentA | Obtém os detalhes completos da entrega individual e/ou coletiva em grupo (teamsubmission / userid=0) em uma tarefa, resolvendo deterministicamente o grupo efetivo da tarefa (excluindo grupos gerais de turma como INE5458-08208), deduplicando arquivos por fileKey, suportando OCR automático local (ocrMode="auto"|"force"|"status") com blocos visuais posicionados e separando explicitamente submissionComments (comentários da entrega) de gradingFeedbackComments (comentários da avaliação). |
| download_moodle_fileA | Baixa os bytes originais preservados de um arquivo do Moodle (submissões individuais ou em grupo, anexos de enunciados e materiais da disciplina) reutilizando a autenticação da integração, sem depender de navegador e sem converter/substituir o PDF por texto. Retorna metadados verificados (fileId, tamanho, MIME, SHA-256, validade), downloadUrl temporária autenticada por token de capacidade e resourceUri MCP. |
| read_moodle_fileA | Lê qualquer arquivo autorizado do Moodle (por fileurl ou reutilizando fileId já baixado em TempFileStore sem novo download), preservando o arquivo original via downloadUrl/resourceUri e extraindo texto nativo (PDF, DOCX, ODT, PPTX, ZIP, código) ou executando OCR local automático no servidor (ocrMode="auto"|"force"|"status" via Poppler pdftoppm + Tesseract) com blocos visuais posicionados (coordenadas, região na página, confiança e ordem de leitura). |
| provide_feedbackA | Registra ou atualiza a nota e/ou o comentário da avaliação (assignfeedback_comments) de um aluno em uma tarefa do Moodle, preservando valores existentes quando grade, feedback ou workflowState forem omitidos. Para avaliações em lote ou de grupos com etapa de revisão do professor, prefira prepare_grading_batch -> commit_grading_batch -> verify_grading_batch. |
| get_quizzesB | Lista todos os questionários (quizzes) de uma disciplina, com datas de abertura/fechamento, limite de tempo e nota máxima. |
| get_quiz_gradeA | Retorna a melhor nota e o histórico de tentativas de um aluno em um questionário (quiz) do Moodle. |
| send_messageB | Envia uma mensagem instantânea direta pelo Moodle para um aluno ou usuário (core_message_send_instant_messages). |
| get_messagesB | Lista as mensagens diretas ou notificações recentes da conta do professor no Moodle. |
| get_forumsA | Lista os fóruns de uma disciplina (ex: "Avisos" e "Fórum de Discussão"), retornando seus IDs para leitura ou publicação de avisos. |
| get_forum_discussionsA | Lista os tópicos/discussões de um fórum ou lê todas as postagens/respostas de uma discussão específica. |
| post_forum_discussionB | Publica um novo aviso/tópico em um fórum da disciplina (ex: fórum de Avisos) ou responde a uma postagem existente. |
| get_course_groupsA | Lista todos os grupos de uma disciplina no Moodle (core_group_get_course_groups), seus participantes atuais, agrupamentos (groupings), permissão moodle/course:managegroups, sugestão de próximo nome único e a configuração completa das atividades mod_groupselect (como agrupamento associado, limites mínimo/máximo de participantes, prazos e permissões de criação). |
| get_group_membersA | Retorna a lista atualizada e confirmada de integrantes de um grupo específico no Moodle, juntamente com contagem de membros, limite máximo configurado (maxMembers), vagas restantes e disponibilidade na atividade mod_groupselect. |
| create_course_groupA | Cria um novo grupo em uma disciplina validando moodle/course:managegroups, permitindo escolher um nome explícito (sem nunca sobrescrever nem reutilizar grupos preexistentes) ou gerar automaticamente um nome único a partir dos grupos existentes. Se a atividade mod_groupselect exigir um agrupamento (targetgrouping > 0), associa o grupo automaticamente e confirma o estado final no Moodle antes de retornar. |
| add_group_memberA | Adiciona um ou mais alunos matriculados a um grupo existente, validando moodle/course:managegroups, matrícula na disciplina, limite máximo de participantes (maxMembers do mod_groupselect) e unicidade de grupo. Operação idempotente e auditada que confirma o estado final no Moodle antes de retornar. |
| remove_group_memberA | Remove um ou mais participantes de um grupo da disciplina validando moodle/course:managegroups e matrícula no curso. Operação idempotente e auditada que confirma a remoção no Moodle antes de retornar. |
| create_group_with_membersA | Cria um grupo novo na disciplina (com nome escolhido ou único gerado automaticamente, disponível no mod_groupselect) e adiciona os participantes informados de forma idempotente, validando previamente permissões, matrícula e limite máximo de vagas, relatando qualquer falha parcial e confirmando o estado final no Moodle. |
| get_moodle_capabilitiesA | Retorna metadados de versão e protocolo do servidor UFSC Moodle MCP (v1.2.1), a lista completa de 28 ferramentas registradas e disponíveis, funcionalidades ativas, status detalhado dos motores de OCR local (Poppler pdftoppm + Tesseract e idiomas instalados), limites operacionais, suporte a avaliação em lote controlada (prepare/commit/verify) e guia de atualização de cache de catálogo em clientes MCP externos. |
| get_assignment_grading_overviewA | Recupera em uma única operação consolidada todo o panorama de avaliação de uma tarefa do Moodle: metadados da tarefa, grupos efetivos do projeto (excluindo grupos gerais de turma), integrantes confirmados (sem docentes), entregas coletivas e individuais com arquivos deduplicados, notas individuais e agregadas por grupo (fully_graded, partially_graded, not_graded, inconsistent), comentários de avaliação existentes (gradingFeedbackComments), estados de workflow e visibilidade, cobertura percentual e inconsistências detectadas. |
| prepare_grading_batchA | Prepara, valida e calcula o diff completo de um lote de avaliações (notas e/ou gradingFeedbackComments por groupId ou studentId) SEM realizar nenhuma escrita no Moodle. Distingue alterações solicitadas de alterações efetivas: se notas/feedbacks propostos forem idênticos aos já armazenados, classifica a ação como "preserve", reporta status="prepared_no_changes" e readyToCommit=false. Detecta conflitos (grupos gerais inválidos, ambiguidade, bloqueios, notas fora da faixa ou divergências), gera planId + planHash (SHA-256) e detalha os 4 níveis de garantia exigidos para autorização humana. |
| commit_grading_batchA | Executa exclusivamente um plano preparado por prepare_grading_batch e formalmente autorizado pelo professor. Distingue 4 níveis de controle: (1) validação técnica do plano, (2) integridade criptográfica pelo approvedPlanHash, (3) confirmação declarada via confirmedByReviewer=true e (4) autorização humana efetiva do docente. Se o plano não contiver alterações efetivas (status="prepared_no_changes"), commit_grading_batch retorna "unchanged_no_action_required" com 0 escritas no Moodle de forma totalmente idempotente. Protegido por verificação otimista de concorrência e registro em log de auditoria local redigido. |
| verify_grading_batchA | Reconsulta os dados diretamente no Moodle (fresh=true, nunca confiando apenas na resposta de escrita) e confere, para cada grupo e cada integrante afetado, se nota, comentário da avaliação (gradingFeedbackComments), contagem de membros, estado de workflow e visibilidade correspondem exatamente ao plano aprovado. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 28 tools
Most tools have clearly distinct resource+action targets, and the read/write boundary is well documented (e.g. prepare vs commit vs verify in the grading flow). A few clusters still overlap: get_submissions, get_submission_content and get_assignment_grading_overview all return submission/grade data at different granularities, and get_course_groups vs get_group_members both return member lists. provide_feedback also overlaps in outcome with the batch grading tools, though its description explicitly redirects bulk cases to prepare/commit.
Nearly all names follow a snake_case verb_noun pattern (get_courses, create_course_group, add_group_member, post_forum_discussion, download_moodle_file), which is predictable and readable. Minor deviations exist: «provide_feedback» uses a less standard verb than send_message/post_forum_discussion for what is effectively an update operation, and some get_* names are long compound phrases (get_assignment_grading_overview, get_moodle_capabilities) breaking the simple verb_noun shape.
At 28 tools the surface sits above the comfortable 3-15 band and feels heavy, with six group-management tools and seven grading/submission tools. The breadth is partly justified because the server spans genuinely separate domains (grading workflows, group management, files/OCR, forums, messaging), but a few read variants (get_submissions vs get_assignment_grading_overview vs get_submission_content) inflate the count more than necessary.
The core teaching lifecycle is well covered: discover courses/contents/students, read assignments/quizzes/submissions, grade individually or via a guarded batch flow, manage groups and members, post to forums, send messages, and fetch/read files with OCR. The main gaps are the absence of a delete/update group operation (create/add/remove exist but no remove_course_group) and no edit/delete for forum posts or messages, which could dead-end some management workflows.