E-Disciplinas MCP

Servidor MCP para ler conteúdo de disciplinas do E-Disciplinas (Moodle da USP) via API de Web Services.

O que é?

Este é um servidor Model Context Protocol (MCP) que permite a agentes de IA (como Pi, Claude, Codex e outros) acessar o conteúdo das suas disciplinas no E-Disciplinas de forma segura e estruturada.

Qual problema resolve?

O E-Disciplinas é o ambiente virtual de aprendizagem da USP (baseado no Moodle). Este servidor conecta agentes de IA à sua conta, permitindo que eles consultem suas disciplinas, leiam materiais, baixem arquivos e pesquisem cursos — tudo isso de forma segura, sem expor suas credenciais.

Instalação

Via npm (recomendado)

npx edisciplinas-mcp setup

O npx baixa e executa o pacote automaticamente. Na primeira vez pode demorar alguns segundos para fazer o download; nas próximas execuções usa o cache.

Para instalar globalmente (opcional):

npm install -g edisciplinas-mcp
edisciplinas-mcp setup

A partir do repositório (desenvolvimento)

git clone https://github.com/Miguel-Calhabeu/edisciplinas-mcp.git
cd edisciplinas-mcp
npm install
npm run build
node dist/cli.js setup

Configuração

1. Obter o token do Moodle

1. Acesse edisciplinas.usp.br e faça login
2. Vá em: Menu do Usuário → Preferências → Conta do Usuário → Chaves de segurança
   • Ou acesse diretamente: edisciplinas.usp.br/user/managetoken.php
3. Crie um token para "Moodle mobile web service"
4. Copie o token (32 caracteres alfanuméricos)

Importante: o servidor aceita apenas autenticação por token. Senhas nunca são aceitas.

2. Executar o setup

npx edisciplinas-mcp setup

O setup vai:

• Pedir a URL base (padrão: https://edisciplinas.usp.br)
• Pedir o token do Moodle WS
• Testar a conexão
• Salvar a configuração com permissões restritivas (600 no Unix)

3. Verificar a conexão

npx edisciplinas-mcp status

4. Validar capacidades

npx edisciplinas-mcp validate

Imprime apenas booleanos de capacidade, contagens e códigos de erro — nunca identidade, nomes de disciplinas, conteúdo ou tokens.

Comandos da CLI

O comando sem argumentos inicia o servidor MCP por stdio. serve é o nome explícito para o mesmo modo:

edisciplinas-mcp serve    # inicia o servidor MCP
edisciplinas-mcp           # equivalente a serve

Os comandos de configuração e diagnóstico são setup, status e validate.

Como funciona

┌─────────────────┐     stdio      ┌──────────────────┐     HTTPS + wstoken     ┌─────────────────────┐
│  Cliente MCP    │ ◄────────────► │  Servidor MCP    │ ◄─────────────────────► │  edisciplinas.usp.br│
│  (Pi, Claude,   │                │  (Node.js)       │                         │  Moodle 4.2+ WS API│
│   Codex, etc.)  │                │                  │                         │                     │
└─────────────────┘                └──────────────────┘                         └─────────────────────┘
                                        │
                                        ▼
                               ~/.config/edisciplinas/          (Linux)
                               ~/Library/Application Support/   (macOS)
                               %APPDATA%\edisciplinas\          (Windows)
                                 └── config.json (token, permissões 600)

stdout: apenas protocolo MCP
stderr: diagnósticos, avisos, status de conexão

As seis ferramentas

edisciplinas_diagnose

Verifica status da conexão e capacidades disponíveis. Seguro para executar a qualquer momento. Retorna booleanos de capacidade — nunca expõe tokens.

edisciplinas_list_courses

Lista disciplinas em que você está matriculado, com filtro por período (em andamento, passadas, futuras, favoritas).

edisciplinas_get_course_content

Retorna a estrutura completa de uma disciplina: seções, módulos, atividades, arquivos e textos de disponibilidade. Inclui fallback genérico para tipos de módulo sem função WS dedicada (fórum, tarefa, questionário, etc.).

edisciplinas_get_activity_content

Retorna conteúdo detalhado de uma atividade específica:

• Página: conteúdo HTML completo via mod_page_get_pages_by_courses
• Recurso: metadados de arquivo via mod_resource_get_resources_by_courses
• Etiqueta: intro HTML via mod_label_get_labels_by_courses
• Outros tipos: fallback genérico via core_course_get_contents

edisciplinas_download_file

Baixa um arquivo de um recurso. Validação de URL, limite de tamanho (padrão: 50MB), prevenção de path traversal, nome seguro derivado automaticamente.

edisciplinas_search_courses

Pesquisa disciplinas por nome ou código. Tenta busca server-side primeiro; fallback para filtro de disciplinas matriculadas se a função não estiver disponível.

Configuração para clientes MCP

Pi

Adicione à configuração MCP do Pi (projeto ou global):

{
  "mcpServers": {
    "edisciplinas": {
      "command": "npx",
      "args": ["edisciplinas-mcp"]
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "edisciplinas": {
      "command": "npx",
      "args": ["edisciplinas-mcp"],
      "env": {}
    }
  }
}

O campo env do Claude Desktop permite passar variáveis de ambiente se necessário. Objeto vazio = não herdar nada (mais seguro).

Codex / ChatGPT Desktop (STDIO)

{
  "mcpServers": {
    "edisciplinas": {
      "command": "npx",
      "args": ["edisciplinas-mcp"]
    }
  }
}

Nota sobre ambientes corporativos com inspeção TLS: se sua rede usa proxy com inspeção de certificados (ex: Netskope), configure a variável de ambiente NODE_EXTRA_CA_CERTS apontando para o bundle de certificados CA:

{
  "mcpServers": {
    "edisciplinas": {
      "command": "npx",
      "args": ["edisciplinas-mcp"],
      "env": {
        "NODE_EXTRA_CA_CERTS": "/caminho/para/ca-bundle.pem"
      }
    }
  }
}

Cliente genérico (qualquer host STDIO)

{
  "command": "npx",
  "args": ["edisciplinas-mcp"]
}

Windows: comando alternativo

Se npx não estiver disponível no PATH do Windows, use:

{
  "command": "cmd",
  "args": ["/c", "npx", "edisciplinas-mcp"]
}

Ou com instalação global:

{
  "command": "edisciplinas-mcp",
  "args": []
}

Variáveis de ambiente

Variável	Descrição	Padrão
EDISCIPLINAS_CONFIG	Caminho explícito para um arquivo de configuração regular e não simbólico (substitui o padrão da plataforma)	Auto-detectado
EDISCIPLINAS_TOKEN	Token do Moodle WS (alternativa ao arquivo de config; visível em ps e inspetores de processo — use apenas em CI/headless)	—
EDISCIPLINAS_BASE_URL	URL base do Moodle (usado com EDISCIPLINAS_TOKEN)	https://edisciplinas.usp.br
NODE_EXTRA_CA_CERTS	Caminho para bundle de certificados CA (necessário em redes com inspeção TLS)	—

Precedência: EDISCIPLINAS_CONFIG, quando definido, substitui o caminho padrão; caso contrário, usa o caminho da plataforma. Se nenhum arquivo existir, usa EDISCIPLINAS_TOKEN/EDISCIPLINAS_BASE_URL ou retorna erro.

Caminhos de configuração por plataforma

Plataforma	Configuração	Cache/Downloads
macOS	~/Library/Application Support/edisciplinas/config.json	~/Library/Caches/edisciplinas-mcp/downloads/
Linux	~/.config/edisciplinas/config.json (respeita XDG_CONFIG_HOME)	~/.cache/edisciplinas-mcp/downloads/ (respeita XDG_CACHE_HOME)
Windows	%APPDATA%\edisciplinas\config.json (fallback: %USERPROFILE%\AppData\Roaming\edisciplinas\config.json)	%LOCALAPPDATA%\edisciplinas-mcp\downloads\ (fallback: %USERPROFILE%\AppData\Local\edisciplinas-mcp\downloads\)
WSL	Como Linux	Como Linux

Detalhes de permissões, nomes de arquivo e solução de problemas estão no guia multiplataforma.

TLS e redes corporativas

Se você estiver em uma rede corporativa que usa inspeção TLS (proxy que intercepta certificados SSL), as requisições do servidor podem falhar com erro de certificado autoassinado.

Solução: configure NODE_EXTRA_CA_CERTS apontando para o arquivo de certificados CA da sua organização:

export NODE_EXTRA_CA_CERTS=/caminho/para/ca-bundle.pem
npx edisciplinas-mcp setup

Importante: este caminho contém o certificado CA, nunca o token do Moodle. O caminho do certificado não é um segredo.

Nunca desabilite a verificação TLS (NODE_TLS_REJECT_UNAUTHORIZED=0) — isso expõe sua conexão a ataques man-in-the-middle.

Perguntas frequentes

Como obtenho o token?

1. Acesse edisciplinas.usp.br
2. Menu do Usuário → Preferências → Conta do Usuário → Chaves de segurança
3. Crie um token para "Moodle mobile web service"

Erro 500 ou "falha ao autenticar"

Geralmente indica um de:

• Token inválido ou expirado — gere um novo
• Serviço web mobile não habilitado para alunos — contate o STI (sti@usp.br)
• Problema de conectividade — verifique se edisciplinas.usp.br está acessível

Erro de certificado TLS

Seu ambiente pode ter inspeção TLS. Veja a seção TLS e redes corporativas.

O token ou meus dados pessoais ficam expostos?

Não. Quando você usa o arquivo local, o token fica nele e não é impresso pelo CLI; em ambientes headless, EDISCIPLINAS_TOKEN é uma alternativa mais exposta. Os comandos também não exibem identidade, nomes de disciplinas ou conteúdo. As requisições autenticadas são enviadas ao Moodle configurado, e downloads são gravados apenas no diretório escolhido.

Quais moodle/plataformas são suportados?

Testado com Moodle 4.2+ (E-Disciplinas / edisciplinas.usp.br). Usa a API padrão de Web Services do Moodle. Outros servidores Moodle com a mesma API devem funcionar, mas não são testados.

O servidor modifica algo no Moodle?

Não. O servidor é somente leitura. Não realiza inscrições, envios de tarefas, alterações de notas ou qualquer operação de escrita.

Como atualizo?

npx edisciplinas-mcp@latest setup

Ou com instalação global:

npm update -g edisciplinas-mcp

Como desinstalo?

Remova o arquivo de configuração:

# Linux
rm -rf ~/.config/edisciplinas

# macOS
rm -rf ~/Library/Application\ Support/edisciplinas

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:APPDATA\edisciplinas"

Limpe o cache do npx:

npm cache clean --force

Se instalou globalmente:

npm uninstall -g edisciplinas-mcp

Permissões do arquivo de configuração

No macOS e Linux, o arquivo de configuração é criado com permissões 600 (apenas o proprietário pode ler/escrever). No Windows, o fs.chmod é uma operação sem efeito; recomenda-se restringir o acesso manualmente ao seu usuário.

Modelo de segurança

O servidor é somente leitura e o token nunca é exposto ao modelo. As regras detalhadas de armazenamento, transmissão, sanitização, TLS e reporte de vulnerabilidades estão em SECURITY.md.

Contribuição

Veja CONTRIBUTING.md para instruções de desenvolvimento.

Autor

Miguel Filippo Rocha Calhabeu Estudante de Bacharelado em Sistemas de Informação no ICMC-USP, São Carlos.

Transparência sobre IA

Este projeto foi desenvolvido com apoio de modelos de linguagem (LLMs) em sua geração e iteração. Todo código foi revisado e validado por um ser humano. Contribuições humanas responsáveis são bem-vindas e incentivadas.

Licença

MIT