@nectarcrm/devcenter-mcp

Servidor MCP para gerenciar seu app no Nectar Dev Center de dentro de uma sessão Claude Code (ou qualquer cliente MCP): sincronizar functions, settings, custom fields, inbound/outbound e env vars — com descoberta tipada, diff e guardrails que o curl não tem.

Instalação

Adicione ao .mcp.json do seu projeto (ou à config do cliente MCP):

{
  "mcpServers": {
    "devcenter": {
      "command": "npx",
      "args": ["-y", "@nectarcrm/devcenter-mcp"],
      "env": {
        "NECTAR_DEVCENTER_API_KEY": "nct_ak_…",
        "NECTAR_DEVCENTER_APP_ID": "<uuid do seu app>",
        "NECTAR_DEVCENTER_BASE_URL": "https://developer.nectarcrm.com.br"
      }
    }
  }
}

• API key: gere em Configuration → API Keys do seu app. A chave é escopada ao app (só alcança /api/v1/apps/{seu-appId}/**) — o blast radius é 1 app.
• App ID: copie o UUID do app. É obrigatório porque a chave não o expõe por si só.

Para múltiplos ambientes, crie uma entrada por ambiente (devcenter-qa2, devcenter-prod), cada uma com sua tríade key/appId/baseUrl.

Variáveis de ambiente

| Var | Obrigatória | Descrição | |---|---|---| | NECTAR_DEVCENTER_API_KEY | sim | nct_ak_… | | NECTAR_DEVCENTER_APP_ID | sim | UUID do app | | NECTAR_DEVCENTER_BASE_URL | sim | ex.: https://developer.nectarcrm.com.br | | DEVCENTER_MCP_READONLY | não | 1 desliga todas as escritas | | DEVCENTER_MCP_PROTECTED | não | CSV de hosts protegidos; "" desliga (dev local) |

Skills

O pacote traz as skills do Dev Center — documentação estruturada (contrato de functions, client bundle, settings/custom fields, integrações e workflow) que ensina uma sessão Claude Code a criar e editar apps corretamente. Instale-as no seu projeto:

npx -y @nectarcrm/devcenter-mcp install-skills          # popula ./.claude/skills/
npx -y @nectarcrm/devcenter-mcp install-skills --force  # sobrescreve as existentes

As mesmas skills estão publicadas em /docs/skills (com download .zip). Com o MCP + skills instalados, o Claude Code entende toda a superfície do Dev Center.

Tools

Leitura (sempre disponíveis)

| Tool | O que faz | |---|---| | dc_whoami | valida a key e mostra app + flags do MCP | | dc_pull | baixa o app e materializa o layout git-friendly em <dir>/ | | dc_functions_list / dc_function_get | lista functions / retorna uma com código | | dc_function_logs | logs de execução (filtro por function/status; detalhe por logId) | | dc_settings_list / dc_settings_diff | setting templates / diff local × remoto | | dc_custom_fields_list · dc_connectors_list · dc_inbound_list · dc_outbound_list · dc_environments_list · dc_test_cases_list · dc_bundle_versions | listagens | | dc_envvars_list | env vars (key/tipo) — nunca revela secrets |

Escrita (guarded — exigem confirm:true)

| Tool | O que faz | |---|---| | dc_push | sincroniza o app a partir do layout local (dry-run por padrão) | | dc_function_put | cria/atualiza uma function (upsert por nome) | | dc_function_activate / dc_function_deactivate | liga/desliga uma function | | dc_function_run_cron | dispara agora o fan-out de uma function agendada | | dc_run_test_cases | roda os casos de teste do app | | dc_bundle_push | sobe o bundle frontend para o draft (não publica) | | dc_bundle_publish | publica o draft — rollout global no ambiente | | dc_setting_put | upsert de setting template ou valor de instalação | | dc_cf_template_put | upsert de custom field template | | dc_connector_set | cria/anexa um connector (ou renomeia) |

Fluxo típico

dc_pull { dir: "apps/meu-app" }         # baixa o estado atual
# … edite functions/*.js, settings.json etc …
dc_push { dir: "apps/meu-app" }         # DRY-RUN: mostra o diff, não aplica
dc_push { dir: "apps/meu-app", apply: true, confirm: true }   # aplica

Modelo de segurança

O dc_push usa o sync-import, cuja semântica varia por recurso (verificado no backend + QA2):

• functions, settings, custom fields → UPSERT (cria/atualiza; não remove). Deletar localmente e dar push não remove do app — o dc_push só avisa (ignoredLocalDeletions).
• inbound, outbound, env vars → cria/atualiza e REMOVE órfãos.

Os guardrails:

• Dry-run por padrão — dc_push sem apply:true só mostra o diff + o resumo do dry-run do servidor (a verdade de fundo). Nada é aplicado.
• Aplicar exige apply:true + confirm:true.
• Gate de remoção — se o dry-run do servidor indicar remoção real (inbound/outbound/env vars), é preciso force:true. A tool lista o que será removido (realRemovals).
• Escopo only:[...] — limita quais seções são aplicadas (functions, settings, customFields, inbound, outbound, envVars); as demais viram no-op, mesmo que estejam divergentes localmente. Resolve o all-or-nothing.
• dc_function_put monta o AppFunctionRequest correto (só os campos que você passa) — evita o erro de enviar o objeto errado num PUT.
• DEVCENTER_MCP_READONLY=1 bloqueia toda escrita.
• A API key nunca aparece em retorno, log ou mensagem de erro.

Desenvolvimento

npm install
npm run build      # tsc → dist/
npm run dev        # roda do fonte com tsx

Node ≥ 18 (usa fetch/FormData/Blob nativos).