# Assistente de Vendas Cognitivo — MCP Lab2Dev

Localizador cognitivo de cases comerciais baseado no Model Context Protocol.
O sistema mantém os textos factuais dos cases em arquivos versionáveis,
indexa-os em PostgreSQL/pgvector e oferece busca híbrida para clientes de IA.
Cada resultado é devolvido como um case completo e inclui a apresentação pronta.

## Requisitos

- Docker Desktop 29+ com Compose 2.40+
- Node.js 22+ para desenvolvimento local
- Aproximadamente 4 GB livres para imagens e o modelo `bge-m3`

## Primeiro startup

```powershell
Copy-Item .env.example .env
docker compose up --build
```

Na primeira execução, o container `bootstrap` baixa o modelo de embeddings, aplica as migrations e ingere `content/`. Esse processo pode levar alguns minutos.

Verificações:

```text
http://localhost:3001/health/live
http://localhost:3001/health/ready
http://localhost:9001
```

Credenciais locais do MinIO: `lab2dev` / `lab2dev-secret`.

Com o `.env.example`, o MCP local fica em `http://localhost:3001/mcp` e
inicia sem autenticação para facilitar a demonstração. Não mantenha esse modo
exposto permanentemente em um ambiente público.

## Teste temporário no Claude

O Claude precisa alcançar um MCP remoto por HTTPS. Para um teste descartável,
é possível iniciar um Cloudflare Quick Tunnel em outro container:

```powershell
docker run -d --name lab2dev-cloudflared --restart unless-stopped `
  cloudflare/cloudflared:latest tunnel --no-autoupdate `
  --url http://host.docker.internal:3001
docker logs lab2dev-cloudflared
```

Copie a URL `https://...trycloudflare.com` mostrada no log e configure `.env`:

```dotenv
PUBLIC_BASE_URL=https://...trycloudflare.com
AUTH_MODE=none
ALLOW_INSECURE_PUBLIC_TEST=true
ALLOWED_ORIGINS=https://claude.ai,https://claude.com,http://localhost:6274,http://localhost:3001
```

Depois recrie apenas a API:

```powershell
docker compose up -d --force-recreate mcp-api
```

No Claude, adicione `https://...trycloudflare.com/mcp` como conector
personalizado. O túnel rápido é temporário, não tem garantia de disponibilidade
e fica sem autenticação. Para encerrá-lo:

```powershell
docker stop lab2dev-cloudflared
```

Ao recriar o container do túnel, a URL muda; atualize `PUBLIC_BASE_URL` e o
conector do Claude. Para produção, use domínio estável e autenticação.

## Conteúdo

Edite somente `content/lab2dev.yaml`, os arquivos em `content/projetos/` e
as imagens em `content/imagens/`. Consulte
[docs/content-guide.md](docs/content-guide.md).

```powershell
npm run content:validate
docker compose run --rm bootstrap
```

O segundo comando reaplica migrations idempotentes e atualiza somente itens alterados. Para regenerar todos os embeddings:

```powershell
docker compose run --rm mcp-api node dist/apps/mcp-api/src/cli.js reindex
```

Para avaliar se os dez casos de consulta objetiva encontram um projeto correto no top 3:

```powershell
docker compose exec -T mcp-api node dist/apps/mcp-api/src/cli.js evaluate
```

`content/` é montado como somente leitura nos containers. Alterações nos YAMLs
não exigem reconstruir as imagens.

## Desenvolvimento

```powershell
npm install
npm run content:validate
npm run build
npm test
npm run dev
```

Para executar fora do Docker, ajuste `DATABASE_URL`, `OLLAMA_URL` e `MINIO_ENDPOINT` no ambiente.

## Operação

```powershell
npm run db:backup
npm run db:restore -- backups/lab2dev-data.sql
docker compose --profile tools up -d adminer
docker compose ps
docker compose logs -f mcp-api
```

O restore foi projetado para banco vazio ou para substituir objetos incluídos no dump. Faça um backup antes de restaurar.
Para validar em outro banco, defina `DB_NAME` antes do comando.

## Ferramentas MCP

- `find_relevant_cases`: localiza até cinco cases completos por contexto e filtros opcionais.
- `list_sales_cases`: consulta o catálogo por segmento, tecnologia, tipo de projeto ou tema.
- `get_sales_case`: recupera um case completo pelo ID.

As ferramentas são somente leitura. Elas retornam os textos cadastrados sem
gerar ou alterar afirmações, métricas, tecnologias ou resultados.

Arquitetura e decisões estão em [docs/architecture.md](docs/architecture.md).
O procedimento futuro para substituir o Quick Tunnel por uma URL fixa está em
[docs/url-fixa.md](docs/url-fixa.md).