Content
# 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.
