# usp-mcp

MCP (Model Context Protocol) server para os sistemas estudantis da
Universidade de São Paulo — Moodle (e-Disciplinas), JupiterWeb, notas,
faltas, grade horária e tarefas — usando o
[Heidy backend](https://github.com/iDavi/heidy_backend) como camada de
acesso segura.

Com ele, um assistente (Claude Desktop, Claude Code, ou qualquer cliente
MCP) consegue responder coisas como *"quais atividades tenho no Moodle
essa semana?"*, *"como está minha média em ACH2034?"* ou *"monta minha
grade de horários"*.

## Como funciona

```
cliente MCP  ──stdio/HTTP──▶  usp-mcp (Python/FastAPI)  ──HTTPS──▶  Heidy backend  ──▶  Moodle / JupiterWeb
```

- **A senha nunca viaja em texto claro.** No login, o servidor busca a
  chave pública atual do backend (`GET /auth/login-key`) e sela a Senha
  Única num envelope HPKE-Base(X25519, HKDF-SHA256, AES-256-GCM). Só o
  backend consegue abri-lo, e a senha não é retida em lugar nenhum deste
  processo depois do login.
- **A sessão vive só em memória.** O login devolve um bearer token e um
  *credential blob* (ciphertext opaco que só o backend abre); ambos ficam
  apenas na memória do processo e são descartados no logout.

## Instalação

```bash
pip install .          # ou: pip install -e .[dev] para desenvolver
```

## Uso

### stdio (Claude Desktop / Claude Code)

```bash
usp-mcp
```

Configuração para Claude Desktop/Code (`mcpServers`):

```json
{
  "mcpServers": {
    "usp": {
      "command": "usp-mcp"
    }
  }
}
```

### HTTP (FastAPI + Streamable HTTP)

```bash
usp-mcp --http --port 8000
# ou diretamente:
uvicorn usp_mcp.app:app --host 0.0.0.0 --port 8000
```

- Endpoint MCP: `http://localhost:8000/mcp`
- Health check (deste serviço e do backend): `http://localhost:8000/health`

### Variáveis de ambiente

| Variável         | Efeito                                                        |
| ---------------- | ------------------------------------------------------------- |
| `HEIDY_BASE_URL` | Backend alternativo (padrão: `https://heidy-backend.fly.dev`) |
| `HEIDY_USERNAME` | Número USP para login automático na primeira ferramenta       |
| `HEIDY_PASSWORD` | Senha Única para login automático                             |
| `HEIDY_DOWNLOAD_DIR` | Pasta padrão para `moodle_download_file` (padrão: `./downloads`) |

Sem `HEIDY_USERNAME`/`HEIDY_PASSWORD`, chame a ferramenta `usp_login`
primeiro.

## Ferramentas

| Ferramenta                                       | O que faz                                                    |
| ------------------------------------------------ | ------------------------------------------------------------ |
| `usp_login` / `usp_logout`                       | Abre/encerra a sessão com número USP + Senha Única           |
| `get_profile`                                    | Perfil do estudante                                          |
| `moodle_courses`                                 | Disciplinas no e-Disciplinas                                 |
| `moodle_course`                                  | Conteúdo de uma disciplina (atividades, materiais)           |
| `moodle_activity`                                | Abre uma atividade pelo URL (conteúdo, links, metadados de arquivo) |
| `moodle_download_file`                           | Baixa um arquivo do Moodle (PDF, slides, ...) para o disco (até 10 MB) |
| `usp_sync` / `usp_sync_status` / `usp_sync_history` | Sincroniza grade, notas, faltas e Moodle do JupiterWeb   |
| `list_semesters`                                 | Semestres do estudante                                       |
| `get_schedule`                                   | Grade horária semanal de um semestre                         |
| `list_enrollments`                               | Matrículas (turmas), com horários e professor                |
| `list_grades` / `grade_summary`                  | Notas e média ponderada/status de aprovação por turma        |
| `list_absences` / `absence_summary`              | Faltas e situação frente ao limite                           |
| `list_tasks` / `create_task` / `update_task_status` | Tarefas do planner (provas, entregas, leituras)          |

## Desenvolvimento

```bash
pip install -e .[dev]
pytest
```

Os testes cobrem o esquema de criptografia do envelope (compatível com o
vault do backend), o cliente HTTP (com backend simulado) e a superfície de
ferramentas MCP.