# sigaa-ifsc-mcp

Servidor [MCP](https://modelcontextprotocol.io) para consultar o portal do
discente do [SIGAA do IFSC](https://sig.ifsc.edu.br/sigaa): perfil, turmas,
notas, frequência, tarefas, notícias e avaliações.

A navegação e a extração de dados foram portadas da biblioteca
[sigaa-api](https://github.com/GeovaneSchmitz/sigaa-api), de Geovane Schmitz.

> Projeto não oficial, sem vínculo com o IFSC.

## Autenticação

O login do SIGAA tem um CAPTCHA (Cloudflare Turnstile), então este servidor
**não digita a sua senha nem resolve o CAPTCHA**. Quem loga é você, numa janela
do navegador que o próprio servidor abre:

1. Você pede algo ao Claude (por exemplo, "quais são minhas notas?").
2. Se não houver sessão válida, o servidor abre uma janela do Edge (no Windows)
   ou do Chromium na tela de login do SIGAA.
3. Você entra normalmente. Quando o portal do discente abre, o servidor captura
   o cookie `JSESSIONID`, fecha a janela e responde ao que você pediu.

O perfil desse navegador fica salvo em `~/.sigaa-mcp/browser-profile`. Se você
deixar o navegador lembrar a senha, os próximos logins são só clicar em "Entrar".

Para logar sem esperar uma consulta, use a ferramenta `login_navegador` ou o
comando `sigaa-mcp login`. Para desligar a janela automática, use
`SIGAA_AUTO_LOGIN=0`.

**Alternativa: colar o cookie.** Entre em <https://sig.ifsc.edu.br/sigaa> no seu
navegador, abra as ferramentas de desenvolvedor (F12) > **Application** >
**Cookies** > `https://sig.ifsc.edu.br`, copie o valor de `JSESSIONID` e chame
`definir_cookie`, ou rode:

```bash
sigaa-mcp cookie SEU_JSESSIONID
```

> O cliente MCP precisa esperar enquanto você loga. No Claude Code, se a
> ferramenta der timeout antes de você terminar, aumente `MCP_TOOL_TIMEOUT`
> (em milissegundos).

### Manter a sessão viva

A sessão do SIGAA expira por inatividade. Enquanto o servidor estiver rodando,
ele acessa o portal a cada 10 minutos (`SIGAA_KEEPALIVE_MIN`) para a sessão não
cair. Para manter a sessão ativa também com o cliente MCP fechado, deixe isto
rodando num terminal:

```bash
sigaa-mcp keepalive
```

O keepalive não evita que a sessão termine se o SIGAA reiniciar ou impuser um
tempo máximo de sessão. Quando ela cair, as ferramentas avisam e explicam como
reconectar.

O cookie fica salvo em `~/.sigaa-mcp/session.json`. **Ele dá acesso à sua conta
enquanto a sessão estiver ativa: não compartilhe esse arquivo.**

## Instalação

Cole no terminal o comando do seu sistema. O instalador coloca o `uv` (se
faltar), instala o servidor, prepara o navegador do login por janela e registra
o servidor no Claude Code e no Claude Desktop, se estiverem instalados.

**Linux (inclusive Arch) e macOS**

```bash
curl -fsSL https://raw.githubusercontent.com/heitorsDev/sigaa-ifsc-mcp/main/install.sh | bash
```

**Windows (PowerShell)**

```powershell
irm https://raw.githubusercontent.com/heitorsDev/sigaa-ifsc-mcp/main/install.ps1 | iex
```

Rodar o mesmo comando de novo atualiza para a versão mais recente.

No Arch, o instalador usa o `pacman` (pede `sudo`) para instalar o `uv` e, se não
houver Chromium/Chrome, o `chromium`. No Windows, o login usa o Edge. Nos outros
casos, ele usa o Chrome/Chromium do sistema ou baixa o do Playwright.

Variáveis opcionais do instalador: `SIGAA_MCP_REF` (branch ou tag),
`SIGAA_MCP_NAME` (nome do servidor, padrão `sigaa`) e `SIGAA_BROWSER_PATH`.

### Instalação manual

```bash
uv tool install "sigaa-ifsc-mcp @ https://github.com/heitorsDev/sigaa-ifsc-mcp/archive/main.zip"
claude mcp add --scope user sigaa -- sigaa-mcp
```

Para o Claude Desktop (`claude_desktop_config.json`), use o caminho completo
mostrado por `uv tool dir --bin`:

```json
{
  "mcpServers": {
    "sigaa": { "command": "/caminho/para/sigaa-mcp", "args": [] }
  }
}
```

Fora do Windows, sem Chrome/Chromium no sistema, rode `sigaa-mcp install-browser`.

## Ferramentas

| Ferramenta | O que faz |
|---|---|
| `definir_cookie(cookie)` | Valida e salva o `JSESSIONID` |
| `login_navegador()` | Abre o navegador para logar e captura o cookie (acontece sozinho quando a sessão expira) |
| `status()` | Diz se a sessão é válida |
| `esquecer_sessao()` | Apaga o cookie salvo |
| `perfil()` | Nome, matrícula, curso, status, período atual |
| `atividades()` | Tarefas, questionários e avaliações próximas do portal |
| `turmas(todos_periodos)` | Turmas do semestre (ou de todos os períodos) |
| `grade_horarios(data)` | Grade da semana (aulas por dia, horário, sala), montada a partir do comprovante de matrícula |
| `historico(com_aee)` | Histórico escolar: salva o PDF e devolve o texto |
| `boletim()` | Boletim do semestre |
| `atestado_matricula()` / `declaracao_vinculo()` | Documentos: salva e devolve o texto |
| `menu_portal(item, filtro)` | Lista ou abre qualquer item do menu do portal (Ensino, Pesquisa, Extensão...) |
| `buscar_turmas(disciplina, codigo, docente, horario, local, ano_periodo)` | Consulta turmas de todo o IFSC |
| `detalhes_turma(id)` | Capacidade, matriculados, professores e vagas de uma turma |
| `buscar_componentes(nome, codigo)` | Consulta disciplinas (componentes curriculares) |
| `calendario_academico()` | Prazos do calendário acadêmico mais recente |
| `notas(turma)` | Notas por unidade e avaliação |
| `frequencia(turma)` | Faltas por aula, total e máximo permitido |
| `tarefas(turma)` | Tarefas, prazos e se já foram enviadas |
| `avaliacoes(turma)` | Calendário de provas da turma |
| `noticias(turma, com_conteudo, limite)` | Notícias da turma, com o texto |
| `topicos(turma)` | Tópicos de aula com conteúdo e materiais (arquivos, tarefas, links) |
| `arquivos(turma)` | Arquivos da seção Arquivos da turma |
| `baixar_arquivo(turma, arquivo, pasta)` | Baixa um arquivo da turma ou de um tópico para `~/Downloads/SIGAA` |
| `enviar_tarefa(turma, tarefa, arquivo, comentario, confirmar)` | Entrega uma tarefa com arquivo e/ou comentário |
| `secao_turma(turma, secao)` | Texto de qualquer seção da turma (Plano de Ensino, Participantes, Referências...) |
| `abrir_pagina(caminho)` | Texto de uma página do SIGAA com URL fixa |
| `pagina_atual()` | Texto da última página aberta |
| `links_pagina(filtro)` | Links da página atual, com índice |
| `clicar(texto \| indice)` | Segue um link; se for arquivo, salva em `~/Downloads/SIGAA` |
| `formularios_pagina()` | Formulários da página atual: campos, arquivos e botões |
| `enviar_formulario(formulario, campos, arquivos, botao, confirmar)` | Preenche e envia um formulário, inclusive com arquivos |

`turma` aceita o código ou um trecho do nome da disciplina, sem acentos.

### Moodle

O servidor também acessa o [Moodle do IFSC](https://moodle.ifsc.edu.br) pela
API oficial do app Moodle Mobile. O instalador pergunta usuário e senha do
Moodle no terminal e troca por um token de API; **a senha não é salva**, só o
token (em `~/.sigaa-mcp/moodle.json`). Para refazer o login:

```bash
sigaa-mcp moodle-login
```

Os cursos de antes de 2026 ficam em outro site (`moodle4.ifsc.edu.br`). Para
acessá-los, rode `sigaa-mcp moodle-login --antigo` e use `site="antigo"` nas
ferramentas.

Os cursos do Moodle são criados a partir das turmas do SIGAA: o `idnumber` é
`COMPONENTE<id da turma>` e o nome curto começa com o código do componente.
`moodle_cursos` devolve esses dois campos, e `curso` aceita o código do
componente (ex.: `CAB22402`).

| Ferramenta | O que faz |
|---|---|
| `moodle_status()` | Verifica o token |
| `moodle_cursos(classificacao)` | Cursos (todos, em andamento, passados, futuros) com progresso e ligação ao SIGAA |
| `moodle_buscar_cursos(texto)` | Busca cursos de todo o IFSC pelo nome |
| `moodle_conteudo(curso)` | Seções e itens do curso, com arquivos e links embutidos |
| `moodle_materiais(curso, tipo)` | Todos os materiais numa lista: arquivos e links (YouTube, Drive, PDFs) de páginas, pastas e rótulos |
| `moodle_buscar_material(texto, curso)` | Busca nos nomes, textos e links dos materiais |
| `moodle_ler_item(curso, item)` | Texto de página, rótulo ou pasta (com TeX); PDF baixado e lido |
| `moodle_baixar_arquivo(curso, arquivo, pasta)` | Baixa um arquivo (PDFs voltam com o texto) |
| `moodle_baixar_curso(curso, pasta, limite_mb)` | Baixa todos os arquivos do curso, por seção |
| `moodle_prazos(dias, incluir_atrasados)` | Prazos atrasados e próximos de todos os cursos |
| `moodle_calendario(mes, ano)` | Eventos do calendário no mês |
| `moodle_notas(curso)` | Sem curso: nota de cada curso. Com curso: itens com peso, nota, %, média e feedback |
| `moodle_tarefas(curso)` / `moodle_tarefa(curso, tarefa)` | Tarefas, regras de envio, status, nota e comentários |
| `moodle_enviar_tarefa(curso, tarefa, arquivos, texto, finalizar, confirmar)` | Entrega com arquivos e/ou texto; `finalizar` envia para avaliação |
| `moodle_questionarios(curso)` | Questionários, tentativas e melhor nota (não inicia tentativas) |
| `moodle_foruns(curso)` / `moodle_topicos(curso, forum)` / `moodle_posts(topico_id)` | Fóruns, tópicos e mensagens |
| `moodle_avisos()` | Avisos de todos os cursos em andamento |
| `moodle_postar_forum(...)` / `moodle_responder_forum(...)` | Cria tópico ou responde, com `confirmar` |
| `moodle_mensagens()` / `moodle_conversa(id)` | Conversas e mensagens (não marca como lidas) |
| `moodle_enviar_mensagem(conversa_id, texto, confirmar)` | Envia mensagem numa conversa |
| `moodle_notificacoes()` | Notificações recentes |
| `moodle_progresso(curso)` / `moodle_emblemas()` | Conclusão de atividades e emblemas |
| `moodle_api(funcao, parametros)` | Chama uma função de leitura da API do Moodle |

Todas aceitam `site` (`"atual"` ou `"antigo"`). Entregar tarefa, postar em
fórum e mandar mensagem só acontecem com `confirmar=true`; antes disso a
ferramenta devolve uma prévia para você aprovar.

### Envios

`enviar_tarefa` e `enviar_formulario` mudam dados no SIGAA em seu nome. Por
isso, sem `confirmar=true` elas **só mostram uma prévia** do que seria enviado.
O Claude deve mostrar essa prévia e pedir a sua aprovação antes de confirmar.

O formulário de entrega de tarefa ainda não foi visto aberto: quando o
explorei, nenhuma tarefa estava no prazo. `enviar_tarefa` procura o campo de
arquivo, o de comentário e o botão "Enviar" por heurística. Se falhar, a
navegação genérica (`formularios_pagina` + `enviar_formulario`) cobre o caso.

## Variáveis de ambiente

| Variável | Padrão | |
|---|---|---|
| `MOODLE_URL` | `https://moodle.ifsc.edu.br` | Endereço do Moodle |
| `MOODLE_TOKEN` | | Token da API do Moodle (tem prioridade sobre o arquivo salvo) |
| `MOODLE_LEGACY_URL` | `https://moodle4.ifsc.edu.br` | Moodle com os cursos anteriores a 2026 |
| `SIGAA_SKIP_MOODLE` | | No instalador, não pergunta o login do Moodle |
| `SIGAA_AUTO_LOGIN` | `1` | Abre a janela de login quando a sessão expira; `0` desativa |
| `SIGAA_JSESSIONID` | | Cookie de sessão (tem prioridade sobre o arquivo salvo) |
| `SIGAA_KEEPALIVE_MIN` | `10` | Intervalo do keepalive; `0` desativa |
| `SIGAA_STATE_DIR` | `~/.sigaa-mcp` | Onde ficam o cookie e o perfil do navegador |
| `SIGAA_MAX_CHARS` | `20000` | Limite de texto por página devolvida |
| `SIGAA_DOWNLOAD_DIR` | `~/Downloads/SIGAA` | Onde os arquivos baixados são salvos |
| `SIGAA_MAX_UPLOAD_MB` | `50` | Tamanho máximo de arquivo enviado |
| `SIGAA_LOGIN_TIMEOUT` | `300` | Segundos esperando o login por janela |
| `SIGAA_BROWSER_CHANNEL` | `msedge` no Windows | Navegador do login por janela; vazio usa o Chromium do Playwright |
| `SIGAA_BROWSER_PATH` | | Executável de um Chrome/Chromium do sistema para o login por janela |

## Limitações

- A grade de horários do SIGAA do IFSC só existe no comprovante de matrícula,
  e turmas de horário flexível não aparecem desenhadas nela. `grade_horarios`
  monta a grade decodificando os códigos de horário (`24M34` = seg e qua, manhã,
  3ª e 4ª aulas), respeitando o período de validade de cada padrão.
- A área pública do SIGAA (`/sigaa/public`) exige CAPTCHA mesmo para quem está
  logado, então o servidor não a usa. As buscas partem do portal do discente.
- A biblioteca (SophiA) é um sistema separado, fora do SIGAA, e não está coberta.

- Se você tiver mais de um vínculo (por exemplo, dois cursos), o servidor usa o
  vínculo escolhido na sessão do navegador.
- O HTML do SIGAA muda com o tempo; se uma ferramenta parar de funcionar,
  `secao_turma` e `abrir_pagina` ainda devolvem o texto cru da página.