claude-plugins/wordpress/skills/mcp-bit-integrations/SKILL.md

name, description, layer

name	description	layer
mcp-bit-integrations	MCP dedicado multi-site (node stdio, ligação `bit-integrations` em ~/.omp/agent/mcp.json) para o Bit Integrations / Bit Integrations Pro (BitApps) no bundle Descomplicar® — o plugin de automação/workflow que liga formulários (WPForms, FluentBooking, ...) a apps de terceiros (Perfex CRM/Desk, Google Contacts, etc.), distinto do BitSocial (mcp-bit-social, sharing social). Flows (integrações), logs de execução, ligações a apps, estatísticas agregadas, activar/desactivar flow. Único documento de referência para o schema `btcbi_*` — não existe skill de conhecimento separada. Usar quando "bit integrations", "btcbi", "flow bitapps", "porque falhou a integração com o Perfex/Desk", "logs bit integrations", "desactivar flow", "ligações apps terceiras bitapps".	wiki

/mcp-bit-integrations — MCP dedicado multi-site ao Bit Integrations

Projecto em /media/ealmeida/Dados/Dev/mcp-bit-integrations/ (TypeScript, SDK MCP oficial, stdio). Sem código PHP novo no WordPress: cada tool corre wp db query/wp option get/wp plugin list via ssh server sobre o WP-CLI já instalado, contra o schema <wp_prefix>btcbi_* e as wp_options btcbi_*/bit_integrations_* do plugin. Distinto do BitSocial (mesmo fabricante BitApps, coberto por mcp-bit-social): o BitSocial publica posts do blog em redes sociais; o Bit Integrations é um motor de automação genérico (tipo Zapier interno) que liga eventos WordPress (submissão de formulário, marcação de reunião) a acções em CRMs/apps externas.

Sites conhecidos

Chamar bi_list_sites para a lista actual com path e nota de estado. Verificado ao vivo 19-08-2026 (wp plugin list), Bit Integrations 2.10.2 está activo em todo o bundle — descomplicar (produção), starter (staging), care, ecommerce-demo, e-commerce, ecommerce. Só descomplicar e starter estão no âmbito verificado ponta-a-ponta deste MCP (pedido original); os restantes 4 estão listados como bónus (mesma arquitectura, tabelas confirmadas por wp plugin list, dados não auditados). Também aceita um path absoluto directamente para sites fora desta lista.

Estado real dos dois sites principais (19-08-2026):

• descomplicar (produção, /home/ealmeida/public_html, prefixo BD wpah_): 10 flows, 75 logs. Bit Integrations Pro 2.4.7 instalado mas inactivo.
• starter (staging, /home/ealmeida/starter.descomplicar.pt, prefixo BD wpbk_): plugin activo, 0 flows/logs configurados (tabelas vazias).

Tools (9)

Tool	Read-only	Uso
bi_list_sites	sim	Aliases conhecidos, path WP, nota de estado
bi_get_plugin_status	sim	Versões free/Pro, activo real (wp plugin list), db version, licença Pro (chave mascarada)
bi_list_flows	sim	Lista btcbi_flow — filtra por status/triggered_entity/search (nome), paginado. Resumo sem flow_details
bi_get_flow	sim	Detalhe completo de um flow, flow_details parseado e mascarado (apps ligados, trigger, mapeamento de campos)
bi_set_flow_status	não	Única write tool — activa/desactiva um flow (status 0/1 apenas, nunca trash=2). Mirror de FlowController::updateStatus
bi_list_logs	sim	Lista btcbi_log — filtra por flow_id/response_type (success|error)/since, paginado, com nome do flow via JOIN
bi_get_log	sim	Detalhe completo de um log, response_obj/field_data parseados e mascarados
bi_get_execution_stats	sim	Contagens sucesso/falha agregadas por flow (GROUP BY flow_id), ordenado por volume
bi_list_connections	sim	Lista btcbi_connections (ligações OAuth/API reutilizáveis) — nunca encrypt_keys/auth_details

Todas exigem site como primeiro parâmetro.

Modelo de dados — resumo

Ver references/data-model.md para o schema completo das 4 tabelas e a forma observada de flow_details por app (PerfexCRM, Google Contacts). Resumo:

• btcbi_flow — um flow por automação configurada. triggered_entity identifica a origem (WPF = WPForms, FluentBooking); flow_details (longtext JSON) mistura configuração (mapeamento de campos, condições, listas seleccionadas) e credenciais em claro da app terceira (nomes de chave variam por app: api_token+domain para PerfexCRM, clientId+ clientSecret+tokenDetails para Google Contacts). status: 0 disabled, 1 enabled, 2 trashed.
• btcbi_log — um log por execução. api_type é um JSON pequeno ({"type":"Lead", "type_name":"Lead creating"}); response_obj é a resposta da app terceira (por vezes HTML de erro PHP, não JSON — fica como string); field_data são os valores do trigger nessa execução. response_type é a string "success" ou "error" directamente na coluna (sem enum numérico).
• btcbi_connections — ligações OAuth/API reutilizáveis, independentes de um flow. Vazia nos dois sites principais: os 10 flows de produção guardam a credencial embutida no próprio flow_details em vez de usar uma connection partilhada (feature mais recente do plugin).
• btcbi_auth — armazém interno de tokens OAuth (tokenDetails, userInfo). Sem tool dedicada — vazio nos sites verificados, e o conteúdo é puro segredo sem informação não-sensível a expor.

Segurança — mascaramento recursivo, não exclusão de coluna

Ao contrário do BitSocial (onde o token OAuth vive isolado numa coluna própria, nunca seleccionada), o Bit Integrations mistura config e credenciais no mesmo blob JSON. A exclusão a nível de SQL não chega — src/mask.ts percorre recursivamente o objecto já parseado e substitui por ***MASCARADO*** qualquer valor cuja chave (normalizada, sem separadores) contenha uma palavra da lista: token, secret, password, credential, apikey, privatekey, accesskey, encryptkeys, authdetails, userinfo, clientsecret, clientid. domain (URL da instância CRM) e isAuthorized (flag booleana) ficam de propósito fora da lista — não são segredos e o segundo teria um falso positivo por conter "auth" como substring solta se a lista fosse menos específica. bi_get_plugin_status mascara a chave de licença Pro à parte (só os últimos 4 caracteres, license_key_masked). bi_list_connections nunca selecciona encrypt_keys/auth_details a nível de SQL (mesma convenção do BitSocial para custom_apps).

Texto livre (pesquisa por nome, filtros de app) viaja como SQL escapado (sqlString), nunca interpolado na linha de comando SSH. O prefixo de tabela WordPress (wpah_, wpbk_, wpv4_, ...) nunca é assumido por site — é sempre resolvido ao vivo via wp db prefix (getWpPrefix em src/db.ts, cache em memória por processo), porque o plugin usa o prefixo curto btcbi_ (não o Config::VAR_PREFIX = 'bit_integrations_' usado só para hooks/options) e esse prefixo varia por site.

Verificação

Construído e testado ponta-a-ponta contra produção e staging 19-08-2026:

• bi_get_plugin_status em descomplicar: free 2.10.2 activo, Pro 2.4.7 inactivo, licença mascarada (********************a2be, confere com os últimos 4 caracteres da chave real lida por SQL directo). Em starter: free activo, Pro ausente.
• bi_list_flows em descomplicar: 10/10 flows — confere com SELECT COUNT(*) FROM wpah_btcbi_flow directo. Em starter: 0/0 — confere com tabela vazia.
• bi_get_flow (id=4 "PerfexCRM", id=7 "Google Contacts"): flow_details devolvido com api_token/clientId/clientSecret/tokenDetails mascarados e todo o resto (mapeamento de campos, listas de clientes/staff, domain, isAuthorized) legível — confirmado visualmente linha a linha.
• bi_list_logs/bi_get_log: filtro flow_id=4, response_type=error devolveu 11 logs — confere com bi_get_execution_stats (flow 4: total 20, success 9, error 11) e com a soma success=52+error=23=75 do total de logs em produção. bi_get_log num log de erro real mostrou o stack trace PHP genuíno (Unknown column 'rate_limit_checked' no Desk CRM), sem nenhum segredo.
• bi_list_connections: [] em ambos os sites, confere com SELECT COUNT(*) directo.
• Write: bi_set_flow_status no flow 13 (descomplicar) — round-trip active → inactive → active, cada transição confirmada por SQL directo fora do MCP (status 1→0→1, updated_at avançou como esperado). Produção devolvida ao estado original (status=1).

Skills relacionadas

• mcp-bit-social — mesmo fabricante (BitApps), mesma convenção SSH+WP-CLI+JSON_OBJECT, mas single-site e domínio de sharing social em vez de automação.
• mcp-wpmeteor / mcp-wpfc — mesma convenção multi-site (site como parâmetro em cada tool, sites.ts com aliases + path absoluto), mas sobre wp_options, não tabelas custom.