docs: skill mcp-bit-integrations — MCP dedicado Bit Integrations/Bit Integrations Pro (BitApps)
Único documento de referência para o schema btcbi_* (sem skill de conhecimento separada): flows, logs de execução, connections, mapeamento completo de flow_details por app (PerfexCRM/Desk, Google Contacts), mascaramento recursivo de credenciais, verificação ponta-a-ponta contra produção (10 flows/75 logs) e staging.
This commit is contained in:
Emanuel Almeida
@@ -0,0 +1,117 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user