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

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, 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.