cds-tools

CLI e servidor MCP para o Blackboard Ultra da Cruzeiro do Sul / Unipê (bb.cruzeirodosulvirtual.com.br). Seu agente de IA (Claude Code, Claude Desktop, Cursor, Codex...) passa a consultar avisos, prazos, notas e material das suas disciplinas, baixar o material para uma pasta de estudos e escrever resumos.

Nenhuma senha é armazenada: o login é feito no navegador, pela conta Microsoft da instituição.

Instalação

1. Instale o uv (uma vez só):

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Instale o cds-tools:

uv tool install git+https://github.com/Eduardozsw/cds-tools

3. Rode o assistente:

cds-tools init

Ele abre o navegador para o login, sincroniza suas disciplinas, baixa o material para ~/faculdade e registra o MCP no Claude Code (se ele estiver instalado). Também mostra o bloco de configuração para outros agentes.

Para atualizar: uv tool upgrade cds-tools.

O login usa o Edge instalado. Sem Edge (comum no Linux), rode cds-tools install-browser e defina BB_BROWSER_CHANNEL="".

Related MCP server: blackboard-mcp

Outros agentes

Qualquer cliente MCP com servidores locais (stdio) funciona. A configuração não depende de pasta nenhuma:

{
  "mcpServers": {
    "cds": { "command": "cds-tools" }
  }
}

Claude Code: claude mcp add --scope user cds -- cds-tools.

Agentes só na web (ChatGPT, claude.ai) não conseguem rodar servidores locais.

Tools

Pasta de estudos: ~/faculdade/<período>/<matéria>/{materiais,resumos}.

CLI

cds-tools init                       # login + sync + estado inicial + material + MCP
cds-tools login                      # refazer o login
cds-tools sync [--materials]         # atualiza o banco local
cds-tools deadlines [--course ED]    # prazos futuros (offline)
cds-tools grades [--course ED]       # notas (offline)
cds-tools news --unread --mark-seen
cds-tools ics --out prazos.ics       # prazos para Google Agenda / Outlook / celular
cds-tools watch --once --notify      # o que mudou desde a última vez
cds-tools watch --once --jsonl --fail-on-error   # para scripts

Sem comando (ou com serve), sobe o servidor MCP.

watch emite eventos news, deadline, grade, material (status new/changed) e error. Cada item é lembrado por id + impressão digital dos campos relevantes, então nada se repete. Disciplinas que respondem 403 para alunos aparecem em restricted e não contam como falha. No modo contínuo, o intervalo padrão é 2 h e o mínimo é 30 min.

Agendar no Windows (a cada 2 h, com notificação):

schtasks /Create /SC HOURLY /MO 2 /TN "CDS Tools watch" /TR "cds-tools watch --once --notify"

macOS/Linux (cron): 0 */2 * * * $HOME/.local/bin/cds-tools watch --once --jsonl --fail-on-error

Como funciona

1. login abre o navegador com um perfil dedicado (~/.cds-tools/profile) direto na entrada SAML do Blackboard (/auth-saml/saml/login), que autentica pela conta Microsoft institucional.

2. Quando /learn/api/public/v1/users/me responde 200 (consultado de dentro da aba, com URL absoluta, porque o Ultra usa <base> apontando pro CDN), os cookies são exportados para ~/.cds-tools/state.json. A navegação do login fica em ~/.cds-tools/login-trace.log (sem valores de cookie nem query strings).

3. As tools usam esses cookies via httpx nas APIs REST que o próprio Ultra consome, e só nos caminhos de ALLOWED_PATHS (src/cds_tools/client.py).

4. Se a sessão expirar, o cliente tenta renová-la em modo headless (o SSO costuma lembrar do login). Se não conseguir, pede um novo login.

Variáveis de ambiente

BB_BASE_URL, BB_DATA_DIR, BB_DB, BB_DOWNLOAD_DIR, BB_STUDY_DIR, BB_BROWSER_CHANNEL, BB_LOGIN_TIMEOUT.

Desenvolvimento

git clone https://github.com/Eduardozsw/cds-tools
cd cds-tools
uv sync
uv run pytest           # offline, com respostas da API em tests/fixtures
uv run ruff check .

Fixtures novas devem ser respostas reais anonimizadas: sem nomes, e-mails, matrículas ou IDs de usuário. Se a API mudar de formato, o cliente deve dar erro, nunca devolver lista vazia.

Inspirado no sigaa-tools.

Licença

MIT. Veja LICENSE.