<p align="center"><img src="documents/assets/cover.svg" alt="Focus Faculdade — sua faculdade, organizada com IA" width="100%"></p>

<p align="center">
  <a href="https://github.com/MaxsuelOliveira/focus-faculdade/actions"><img alt="CI" src="https://github.com/MaxsuelOliveira/focus-faculdade/actions/workflows/ci.yml/badge.svg"></a>
  <img alt="Node 24+" src="https://img.shields.io/badge/Node-24%2B-43853d">
  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-typed-3178c6">
  <img alt="MCP stdio" src="https://img.shields.io/badge/MCP-stdio-6554c0">
  <a href="LICENSE"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
</p>

<p align="center"><strong>Disciplinas, prazos, materiais e simulados em um só lugar.<br>Conecte seu assistente de IA pelo MCP e mantenha seus dados no seu computador.</strong></p>

---

O **Focus Faculdade** é um aplicativo pessoal para alunos da Faculdade Focus. Reúne informações do AVA, organiza o estudo e oferece um servidor MCP para assistentes compatíveis consultarem avaliações e materiais, explicarem questões e salvarem simulados locais.

Projeto independente, sem vínculo oficial com a instituição. Cada aluno usa sua própria conta. O repositório contém código e exemplos; credenciais, sessões e dados acadêmicos ficam fora do Git.

## O que você pode fazer

| Recurso                  | Como ajuda                                                        |
| ------------------------ | ----------------------------------------------------------------- |
| Disciplinas e avaliações | Consulte cursos descobertos, regras e estado das tentativas.      |
| Calendário               | Veja os prazos conhecidos e identifique avaliações sem data.      |
| Simulados com IA         | Cole perguntas, receba explicações e salve seu gabarito.          |
| Materiais                | Use textos do AVA e conteúdos adicionados por você como contexto. |
| Checklists               | Acompanhe tarefas e notas com persistência local.                 |
| MCP                      | Use 19 ferramentas, um recurso e um prompt no seu cliente de IA.  |
| Backup e exportação      | Faça cópias do SQLite e exporte seus dados e respostas.           |

## Comece em poucos passos

Você precisa de **Node.js 24+**, npm, Git e uma conta própria no portal.

```sh
git clone https://github.com/MaxsuelOliveira/focus-faculdade.git
cd focus-faculdade
npm ci
npm run browser:install
```

Copie `.env.example` para `.env`. No PowerShell:

```powershell
Copy-Item .env.example .env
```

Edite o arquivo localmente e preencha `USERNAME` e `PASSWORD`. Configure `AVA_COURSE_URL` com o link de uma disciplina sua. **Não envie o `.env` para chats, issues ou GitHub.** No Windows, o aplicativo lê o login acadêmico do arquivo, sem confundir com o `USERNAME` do sistema.

```sh
npm run build
npm start
```

Abra **[http://127.0.0.1:4317](http://127.0.0.1:4317)** e mantenha o aplicativo aberto. Use o IP literal; `localhost` não está entre as origens permitidas. A sincronização acessa sua conta e pode abrir um navegador. CAPTCHA/MFA exigem intervenção do aluno.

> Usa Codex com política RTK? Prefixe os comandos com `rtk proxy`, como em `rtk proxy npm.cmd run build`.

## Conecte sua IA com MCP

O MCP não exige chave de API: o modelo do seu cliente pode consultar o conteúdo e preparar respostas. Ollama e OpenAI são alternativas opcionais dentro do aplicativo.

**Codex:** substitua `/CAMINHO/` pelo caminho absoluto do projeto:

```sh
codex mcp add focus-faculdade --env FOCUS_MCP_PORT=4317 -- node /CAMINHO/focus-faculdade/dist/server/mcp-stdio.js
```

Para clientes com configuração JSON:

```json
{
  "mcpServers": {
    "focus-faculdade": {
      "command": "node",
      "args": ["/CAMINHO/focus-faculdade/dist/server/mcp-stdio.js"],
      "env": { "FOCUS_MCP_PORT": "4317" }
    }
  }
}
```

No Windows, um caminho como `C:/projetos/focus-faculdade/dist/server/mcp-stdio.js` funciona. Se necessário, informe o caminho absoluto de `node.exe`. O aplicativo precisa continuar aberto. A conexão é **local por stdio**; chats sem suporte a MCP local não se conectam diretamente.

Experimente pedir:

- “Mostre minhas disciplinas e a última sincronização.”
- “Quais avaliações têm prazo nesta semana? Quais estão sem data?”
- “Consulte os materiais da avaliação e prepare um simulado com explicações.”
- “Salve minhas respostas como rascunho, sem aprovar nem enviar.”

Se uma disciplina não aparecer, use `portal_job` com `kind: "sync"` e `course_external_id` igual ao ID do link `course/view.php?id=...`. Essa opção consulta uma disciplina específica sem depender da navegação da disciplina inicial.

## Instale a skill pelo GitHub

A skill está em [`skills/focus-faculdade`](skills/focus-faculdade/SKILL.md). No Codex com Skill Installer, peça:

> Instale a skill do repositório https://github.com/MaxsuelOliveira/focus-faculdade, no caminho skills/focus-faculdade.

Alternativamente, copie a pasta `skills/focus-faculdade` para `~/.codex/skills/focus-faculdade`. Reinicie o cliente para carregar a skill e use `$focus-faculdade`.

**Skill e MCP se complementam:** a skill orienta o assistente; o MCP executa consultas. Instalar a skill não instala dependências, não configura credenciais e não inicia o aplicativo.

## Dados privados por padrão

- `.env`, SQLite, backups, cookies e perfil do navegador ficam no computador do aluno.
- `data/`, `academic/`, `private/` e capturas geradas são ignorados pelo Git.
- Sugestões, respostas, aprovação e entrega são etapas distintas.
- Iniciar prova pode consumir tentativa e iniciar cronômetro; exige confirmação específica.
- Entrega exige respostas revisadas e token de uso único. Uma entrega incerta não é repetida automaticamente.
- Uma IA externa recebe os dados que você autorizar consultar; Ollama permite processamento local.

Veja [SECURITY.md](SECURITY.md) e rode `npm run privacy:check` antes de publicar contribuições.

## Arquitetura

```mermaid
flowchart LR
  A[Seu cliente de IA] -->|MCP stdio| B[Servidor MCP]
  B -->|API local| C[Fastify]
  D[Interface React] --> C
  C --> E[(SQLite local)]
  C --> F[Fila serial + Playwright]
  F --> G[JACAD / AVA]
  C --> H[Ollama ou OpenAI opcional]
```

O MCP reutiliza a API e não abre outro banco ou worker. O backend roda em loopback; não é um serviço multiusuário e não deve ser exposto na internet sem autenticação própria.

## Desenvolvimento e contribuição

```sh
npm run dev
npm run typecheck
npm run lint
npm test
npm run build
npm run privacy:check
```

Testes usam dados fictícios e bancos temporários, sem iniciar avaliações reais. E2E exigem a porta 4317 livre: feche o aplicativo pessoal antes de executá-los. Consulte [CONTRIBUTING.md](CONTRIBUTING.md).

## Documentação e limites

- [Ferramentas e configuração MCP](documents/MCP.md)
- [Operação local, IA, backups e recuperação](documents/OPERATIONS.md)
- [Segurança e privacidade](SECURITY.md)
- [Como contribuir](CONTRIBUTING.md)
- [Licença MIT](LICENSE)

A descoberta de cursos depende do acesso da conta e das páginas conhecidas. O calendário contém prazos conhecidos das avaliações, não todo o calendário institucional. A extração textual não interpreta automaticamente imagens, PDFs, vídeos ou SCORM. Questões com editor rico, anexos e tipos especiais podem exigir intervenção manual. Mudanças no portal podem exigir atualização dos adaptadores. Respostas de IA precisam de revisão.

Encontrou um problema? Abra uma issue com um exemplo fictício. Quer ajudar outros alunos? Contribua com acessibilidade, documentação, testes e compatibilidade — sem dados pessoais.