# University Content MCP

Servidor MCP local em Node.js + TypeScript para dar ao Codex ou a outro cliente MCP contexto sobre materiais universitários. Lê PDF, PPTX e DOCX, cria um índice JSON e pesquisa texto sem embeddings, base de dados ou serviços pagos.

## Como funciona

```text
Cadeiras/ -> extratores -> .mcp-index/index.json -> pesquisa full-text -> MCP stdio
```

O Google Drive é opcional e read-only. Depois de criar o índice, o servidor MCP funciona totalmente offline.

## Estrutura dos materiais

```text
Cadeiras/
  Estatistica/
    Capitulo 1/
      slides.pdf
      exercicios.docx
    Capitulo 2/
      regressao.pdf
  Algoritmos/
    Grafos/
      bfs.pdf
      dfs.pdf
```

A primeira pasta representa a cadeira. As pastas seguintes formam o capítulo; níveis adicionais aparecem separados por ` / `. Um ficheiro diretamente dentro da cadeira fica no capítulo `Geral`.

Formatos suportados:

- PDF: texto separado por página.
- PPTX: texto separado por slide.
- DOCX: texto contínuo, sem número de página porque esse dado não é estável no formato DOCX.
- Google Docs e Google Slides: quando a sincronização opcional está ativa, são exportados para DOCX e PPTX.

Ficheiros `.ppt` antigos não são suportados; converta-os para `.pptx`.

## Instalação

Requer Node.js 20.16 ou superior.

```bash
npm install
```

Copie `.env.example` para `.env`:

```dotenv
MATERIALS_ROOT=./Cadeiras
GOOGLE_DRIVE_ENABLED=false
GOOGLE_DRIVE_FOLDER_ID=
```

Coloque os documentos dentro de `MATERIALS_ROOT` e construa o índice:

```bash
npm run index
```

O índice é escrito atomicamente em `.mcp-index/index.json`. Execute novamente `npm run index` sempre que adicionar, alterar ou remover materiais. O MCP deteta automaticamente uma nova versão do índice sem precisar de reiniciar.

## Google Drive opcional

Se a pasta local já for sincronizada pelo Google Drive para desktop, deixe `GOOGLE_DRIVE_ENABLED=false`: o indexador lê diretamente essa pasta e não precisa da API Google.

Para usar a sincronização integrada:

1. Ative a Google Drive API no projeto Google Cloud.
2. Autentique Application Default Credentials com uma conta que tenha acesso à pasta:

   ```bash
   gcloud auth application-default login --scopes=https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/cloud-platform
   ```

3. Configure:

   ```dotenv
   MATERIALS_ROOT=./Cadeiras
   GOOGLE_DRIVE_ENABLED=true
   GOOGLE_DRIVE_FOLDER_ID=ID_DA_PASTA
   ```

4. Sincronize e indexe:

   ```bash
   npm run sync-drive
   npm run index
   ```

`sync-drive` cria um espelho local da pasta remota. O Drive é sempre aberto com scope read-only, mas o conteúdo local de `MATERIALS_ROOT` é substituído pelo espelho. Não misture ficheiros exclusivamente locais nessa pasta quando usar este modo.

## Scripts

- `npm run index`: reconstrói `.mcp-index/index.json`.
- `npm run sync-drive`: espelha opcionalmente o Google Drive para `MATERIALS_ROOT`.
- `npm run dev:mcp`: inicia o MCP diretamente a partir do TypeScript.
- `npm run build`: compila TypeScript para `dist/`.
- `npm run start:mcp`: inicia o build compilado.
- `npm run typecheck`: valida os tipos sem gerar ficheiros.

## Tools MCP

### `list_courses()`

Lista cadeiras e totais de capítulos e materiais.

### `list_course_materials(course?: string)`

Lista caminhos, cadeiras, capítulos, tipos e contagens de páginas/slides.

### `search_materials(query: string, course?: string, chapter?: string)`

Faz pesquisa full-text local. O ranking combina cobertura dos termos, frequência e correspondência da frase. Devolve sempre ficheiro, cadeira, capítulo, página/slide, excerto e referência completa.

### `read_material(filePath: string, page?: number, slide?: number)`

Lê os excertos indexados de um caminho devolvido por `list_course_materials`. Aceita uma página ou um slide, nunca ambos.

### `get_relevant_context(query: string, course?: string)`

Devolve até seis excertos relevantes, prontos para serem usados como contexto pelo agente, cada um com referência completa.

## Ligar ao Codex

O Codex suporta servidores MCP locais por stdio no CLI e na extensão IDE. A configuração pode ficar em `~/.codex/config.toml` ou em `.codex/config.toml` dentro de um projeto confiável.

Primeiro compile o servidor:

```bash
npm run build
```

Adicione ao `config.toml`, usando caminhos absolutos:

```toml
[mcp_servers.university_content]
command = "node"
args = ["C:/caminho/school-mcp/dist/mcp/server.js"]
cwd = "C:/caminho/school-mcp"
startup_timeout_sec = 10
tool_timeout_sec = 60

[mcp_servers.university_content.env]
MATERIALS_ROOT = "C:/caminho/school-mcp/Cadeiras"
GOOGLE_DRIVE_ENABLED = "false"
GOOGLE_DRIVE_FOLDER_ID = ""
```

Reinicie o Codex depois de alterar a configuração. No Codex CLI, use `/mcp` para confirmar que `university_content` está ativo. Esta configuração segue a documentação oficial de [MCP no Codex](https://developers.openai.com/codex/mcp).

## Testar

1. Confirme que existem documentos em `Cadeiras/Estatistica/...`.
2. Execute `npm run index`.
3. Confirme o servidor em `/mcp` no Codex.
4. Pergunte:

   > Resolve este exercício de Estatística usando os conteúdos da cadeira.

Para um exercício concreto, inclua o enunciado na mesma mensagem. O agente deverá chamar `get_relevant_context` ou `search_materials`, usar os excertos encontrados e citar referências como:

```text
Estatistica > Capitulo 1 > slides.pdf > página 12
```

Se a pesquisa não encontrar termos do enunciado, peça ao agente para chamar `list_course_materials` e depois `read_material` no ficheiro ou página relevante.

## Publicar lectureHub na Vercel

O projeto também expõe uma landing page da marca `lectureHub` e um endpoint MCP HTTP:

- Landing: `/`
- Health check: `/health`
- MCP Streamable HTTP: `/mcp`

Antes de publicar, reconstrua o índice:

```bash
npm run index
```

O deploy inclui `.mcp-index/index.json`, mas não inclui a pasta `Cadeiras/`. Isto reduz tamanho e evita subir os ficheiros originais; o índice contém o texto extraído, por isso continua a ser conteúdo privado.

### Segurança do endpoint `/mcp`

Por defeito, `/mcp` fica bloqueado em produção se não configurar uma destas opções:

```bash
MCP_ACCESS_TOKEN=<token-longo-aleatorio>
```

ou, apenas se aceitar expor o conteúdo a quem conhecer o URL:

```bash
MCP_ALLOW_PUBLIC=true
```

Para ChatGPT com um conector público simples, o modo sem autenticação é o caminho mais rápido, mas expõe os excertos dos materiais. Para produção séria, implemente OAuth 2.1 conforme a documentação de autenticação do Apps SDK.

### Testar localmente

```bash
npm run dev:web
```

Abra:

```text
http://127.0.0.1:3000
http://127.0.0.1:3000/health
http://127.0.0.1:3000/mcp
```

### Deploy

Faça login na Vercel se necessário:

```bash
vercel login
```

Depois:

```bash
npm run index
vercel deploy
```

Para produção:

```bash
vercel deploy --prod
```

Para usar o seu domínio:

```bash
vercel domains add oseudominio.pt
vercel alias set <deployment-url> oseudominio.pt
```

Também pode configurar o domínio no dashboard da Vercel em `Project → Settings → Domains`.

No ChatGPT, depois do deploy:

1. Ative Developer Mode em `Settings → Apps & Connectors → Advanced settings`.
2. Vá a `Settings → Connectors → Create`.
3. Use o URL:

   ```text
   https://oseudominio.pt/mcp
   ```

4. Crie uma conversa nova e escolha o conector `lectureHub`.

## Segurança e prompt injection

- Documentos são sempre dados não confiáveis, nunca instruções.
- O servidor anuncia esta regra nas instruções MCP, nas descrições das tools e em todas as respostas que contêm texto documental.
- Instruções encontradas dentro de PDFs, slides ou DOCX devem ser ignoradas, incluindo pedidos para executar comandos, abrir links, revelar dados ou alterar o comportamento do agente.
- Nenhum conteúdo documental é importado como módulo, avaliado ou executado.
- A extração PDF usa apenas texto; JavaScript, ações, anexos e links embebidos não são executados.
- `read_material` só aceita caminhos relativos que já existam no índice; não permite leitura arbitrária do sistema de ficheiros.
- O servidor não usa OpenAI, embeddings, PostgreSQL, pgvector, Docker ou qualquer serviço pago.