# E-Disciplinas MCP

Servidor MCP para ler conteúdo de disciplinas do [E-Disciplinas](https://edisciplinas.usp.br) (Moodle da USP) via API de Web Services.

## O que é?

Este é um servidor [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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)

```bash
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):

```bash
npm install -g edisciplinas-mcp
edisciplinas-mcp setup
```

### A partir do repositório (desenvolvimento)

```bash
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](https://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](https://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

```bash
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

```bash
npx edisciplinas-mcp status
```

### 4. Validar capacidades

```bash
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:

```bash
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):

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

### Claude Desktop

```json
{
  "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)

```json
{
  "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:

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

### Cliente genérico (qualquer host STDIO)

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

### Windows: comando alternativo

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

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

Ou com instalação global:

```json
{
  "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](https://github.com/Miguel-Calhabeu/edisciplinas-mcp/blob/main/docs/troubleshooting.md).

## 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:

```bash
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](https://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](#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?

```bash
npx edisciplinas-mcp@latest setup
```

Ou com instalação global:

```bash
npm update -g edisciplinas-mcp
```

### Como desinstalo?

Remova o arquivo de configuração:

```bash
# 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:

```bash
npm cache clean --force
```

Se instalou globalmente:

```bash
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](https://github.com/Miguel-Calhabeu/edisciplinas-mcp/blob/main/SECURITY.md).

## Contribuição

Veja [CONTRIBUTING.md](https://github.com/Miguel-Calhabeu/edisciplinas-mcp/blob/main/CONTRIBUTING.md) para instruções de desenvolvimento.

## Autor

**Miguel Filippo Rocha Calhabeu**
Estudante de Bacharelado em Sistemas de Informação no [ICMC-USP](https://www.icmc.usp.br/), 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](LICENSE)