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

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:

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:

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:

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:

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:

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.

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:

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:

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

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

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. O procedimento futuro para substituir o Quick Tunnel por uma URL fixa está em docs/url-fixa.md.