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

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

Uso

stdio (Claude Desktop / Claude Code)

usp-mcp

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

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

HTTP (FastAPI + Streamable HTTP)

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

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.