---
name: mcp-bit-integrations
description: 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".
layer: 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.