# iClips MCP Bridge

Servidor MCP que conecta o iClips (dados de projetos/jobs da agência) ao Claude,
pra alimentar o "Farol" de capacidade da Vanguarda.

## O que ele expõe

4 tools:

- **`capacidade_do_dia`** — demanda x capacidade de entrega num dia, com déficit e jobs em risco.
- **`aging_por_etapa`** — jobs travados numa etapa (ex: "aprovação interna") há mais tempo que um threshold.
- **`custo_do_off`** — efeito cascata: horas de OFF vs jobs de escopo atrasados no mesmo período.
- **`auditoria_classificacao`** — % de títulos de job que classificam automaticamente como ON/OFF/Mídia Paga.

## ⚠️ Antes de rodar em produção

O endpoint principal usado aqui (`GET /api/v1/projetos`) é citado na Central de
Ajuda do iClips como o recurso de extração de BI, mas **não está detalhado**
na documentação técnica de referência (iclips.readme.io) — que só documenta
18 endpoints, todos de Financeiro/Jobs/Peças/Templates, sem exemplo de
request/response para esse.

Isso significa que os nomes de campos usados em `src/tools/*.js` (ex:
`pecas`, `atividades`, `horasEstimadas`, `historicoStatus`) são **estimativas
baseadas na hierarquia descrita** (Jobs → Peças → Workflows → Atividades e
Tarefas → Apontamentos de horas), não confirmadas contra uma resposta real.

**Antes de usar de verdade:**
1. Faça uma chamada de teste em `/api/v1/projetos` com seu token e confira a
   forma exata do JSON retornado.
2. Ajuste os mapeamentos em `src/tools/capacidadeDoDia.js`,
   `agingPorEtapa.js` e `custoDoOff.js` pra bater com os nomes reais dos campos.
3. Se o suporte do iClips não conseguir esclarecer a estrutura, considere usar
   `GET /api/v1/pieces/{id}` (documentado oficialmente) como fonte alternativa
   do histórico de etapas via `workflowJson`/`checklistJson`.

## Setup local

```bash
cp .env.example .env
# edite o .env e cole seu ICLIPS_API_KEY
npm install
npm run dev
```

O servidor sobe em `http://localhost:3000`, com o endpoint MCP em `/sse`.

## Deploy no Render (gratuito)

1. Suba este projeto pra um repositório no GitHub.
2. Em [render.com](https://render.com), crie um **New Web Service** apontando pro repo.
3. Configurações:
   - **Build Command:** `npm install`
   - **Start Command:** `npm start`
   - **Plano:** Free
4. Em **Environment**, adicione as variáveis do `.env.example`:
   - `ICLIPS_API_KEY` (seu token)
   - `CAPACIDADE_HORAS_POR_COLABORADOR` (opcional, default 6)
   - `AGING_THRESHOLD_HORAS` (opcional, default 2)
5. Deploy. A URL final será algo como `https://iclips-mcp-bridge.onrender.com`,
   com o endpoint MCP em `https://iclips-mcp-bridge.onrender.com/sse`.

**Nota sobre o plano free:** o serviço "dorme" após ~15 min sem uso e demora
cerca de 30s pra acordar na primeira chamada seguinte. Para uso interno da
agência isso não costuma ser um problema.

## Conectando no Claude

Depois de hospedado, use a URL `/sse` como MCP server customizado nas
configurações de conectores do Claude (ou no cliente MCP que vocês usarem).

## Rate limit

A API do iClips permite **10 requisições/minuto** no módulo de Extração de
Dados. O `iclipsClient.js` já implementa uma fila com espaçamento mínimo de
~6.1s entre chamadas pra nunca estourar esse limite — não é necessário (nem
recomendado) reduzir esse intervalo.