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.

Related MCP server: mcpUPB

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

Sem HEIDY_USERNAME/HEIDY_PASSWORD, chame a ferramenta usp_login primeiro.

Ferramentas

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.