cloudbroker-mcp

Servidor MCP para consultar dados de FinOps do CloudBroker (custo por app/grupo, forecast, uso de IA, recomendações, anomalias) direto de um assistente de IA — sem entrar na console.

Leitura + escrita completas: budget, criação/edição de App e Grupo, e descoberta automática de apps a partir de recursos não tagueados (ACDE Lite). connect_aws ainda não tem prioridade definida — ver docs/mvp-mcp-server.md.

Configuração (Claude Desktop, Cursor, etc.)

Pegue sua CloudBroker API key (cb_live_…) em Configurações → API key e adicione:

{
  "mcpServers": {
    "cloudbroker": {
      "command": "npx",
      "args": ["-y", "cloudbroker-mcp"],
      "env": { "CLOUDBROKER_API_KEY": "cb_live_xxx" }
    }
  }
}

Variável opcional CLOUDBROKER_ENDPOINT (default https://api.cloudbroker.app.br).

Tools disponíveis

Leitura

| Tool | Descrição | |---|---| | get_cost_overview | Custo por app/grupo (month YYYY-MM ou months) | | list_apps | Apps/serviços cadastrados | | list_groups | Grupos/produtos de negócio | | get_forecast | Projeção de custo de fim de mês | | get_ai_usage | Custo de IA por produto/modelo (month ou days) | | get_recommendations | Plano de otimização | | get_anomalies | Anomalias de custo | | discovery_scan | Descobre apps a partir de recursos sem tag, agrupados por similaridade (threshold opcional) |

Escrita ✏️

| Tool | Descrição | |---|---| | set_budget | Define budget mensal (USD) + alerta (%) de um app/grupo | | create_app | Cria um novo app (name obrigatório; description, color, tags opcionais) | | update_app | Edita um app existente (nome, cor, tags, budget) | | create_group | Cria um novo grupo/produto (name obrigatório) | | update_group | Edita um grupo existente (nome, budget) |

✏️ Tools de escrita alteram dados. O cliente MCP (Claude Desktop, etc.) pede sua aprovação a cada chamada. A API key precisa de permissão de escrita (os endpoints REST correspondentes aceitam a cb-key via requireAuthOrApiKey).

Exemplos de perguntas

• "Qual meu custo de nuvem em maio por produto?"
• "Qual a projeção de gasto desse mês?"
• "Tem alguma anomalia de custo recente?"
• "Quanto gastei de IA nos últimos 30 dias por modelo?"
• "Define o budget do app backend em $45 e alerta em 90%"
• "Cria um app chamado checkout com a tag app=checkout"
• "Roda a descoberta de apps e me diga quais recursos não estão atribuídos a nenhum app"

Autenticação

A API key autentica via header x-api-key nos endpoints REST do CloudBroker (middleware requireAuthOrApiKey). A key dá acesso de leitura à sua conta — trate como segredo e rotacione em Configurações → API key se necessário.

Desenvolvimento

npm install
npm test     # testa os handlers com API mockada
npm start    # inicia o servidor (precisa de CLOUDBROKER_API_KEY)