feat(wordpress): nova skill mcp-fluent-crm - MCP dedicado FluentCRM/FluentCRM Pro
20 tools (10 leitura + 10 escrita) para descomplicar.pt (produção, 291k contactos). Escritas via FluentCrmApi()/modelos do próprio plugin por SSH+wp eval, sem escrever ficheiros no servidor. Guardas de status explícitas (force_update/confirm) para nunca rebaixar/ressuscitar contactos sem intenção clara.
This commit is contained in:
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"name": "wordpress",
|
||||
"description": "WordPress development, maintenance and optimization - plugins, themes, WooCommerce, Elementor, Crocoblock, EMCP Tools MCP (page building, content ops, security/performance audit), Elementor Pro/ElementsKit/PowerPack widget catalogs. Backed by NotebookLM notebooks.",
|
||||
"version": "1.5.0",
|
||||
"version": "1.6.0",
|
||||
"author": {
|
||||
"name": "Descomplicar - Crescimento Digital",
|
||||
"url": "https://descomplicar.pt"
|
||||
},
|
||||
"homepage": "https://git.descomplicar.pt/ealmeida/descomplicar-plugins",
|
||||
"license": "MIT",
|
||||
"keywords": ["wordpress", "woocommerce", "elementor", "crocoblock", "development", "performance", "licensing", "emcp-tools", "elementskit", "powerpack", "cloudflare", "social-media", "booking"]
|
||||
"keywords": ["wordpress", "woocommerce", "elementor", "crocoblock", "development", "performance", "licensing", "emcp-tools", "elementskit", "powerpack", "cloudflare", "social-media", "booking", "fluentcrm"]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,77 @@
|
||||
---
|
||||
name: mcp-fluent-crm
|
||||
description: MCP dedicado (HTTP StreamableHTTP local, ligação `fluent-crm` em ~/.claude.json, porta 3202) para FluentCRM 3.1.10 + FluentCRM Pro 2.9.86 em descomplicar.pt (produção, 291k+ contactos reais) — contactos, tags, listas, empresas, notas, campanhas e estatísticas. Escritas sempre via FluentCrmApi()/modelos do próprio plugin (nunca SQL directo), por SSH sem escrever ficheiros no servidor. Usar quando "fluentcrm", "contactos crm", "tags fluentcrm", "listas fluentcrm", "estatísticas subscritores", "campanha email estatísticas", "empresas fluentcrm", "subscriber status", "unsubscribe contacto", ou qualquer gestão de contactos/marketing automation em descomplicar.pt.
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# /mcp-fluent-crm — MCP dedicado FluentCRM (descomplicar.pt)
|
||||
|
||||
Projecto em `/media/ealmeida/Dados/Dev/mcp-fluent-crm/` (TypeScript, SDK MCP oficial,
|
||||
StreamableHTTP). FluentCRM não tem WP-CLI para CRUD (só `license_status`/`stats`/`sync_*`) nem
|
||||
API REST configurada (sem chave gerada) — as escritas seguras vivem na camada de serviço oficial
|
||||
do plugin (`FluentCrmApi('contacts')->createOrUpdate()`, `Subscriber::attachTags()`, etc.), lida
|
||||
por completo do código-fonte antes de desenhar as tools.
|
||||
|
||||
**Zona-alvo: descomplicar.pt (produção), 291 441 contactos reais** (81 881 subscribed, 209 559
|
||||
unsubscribed, 1 transactional, 13 customer/291 428 lead). Não confundir com
|
||||
`starter.descomplicar.pt` (staging, FluentCRM Free sem Pro, dataset de teste) onde o mapeamento
|
||||
inicial do código foi feito.
|
||||
|
||||
## Arquitectura — sem tocar no filesystem do servidor
|
||||
|
||||
Leituras: SQL directo via `$wpdb` (rápido, tipado). Escritas: SEMPRE via `FluentCrmApi()`/modelos
|
||||
— nunca INSERT/UPDATE directo, para preservar guardas de estado, hooks e invalidação de cache.
|
||||
Ambas correm por SSH via `wp eval`, com o corpo PHP + dados de entrada codificados em base64
|
||||
dentro de uma variável de ambiente remota — **nunca ficheiros escritos/apagados no servidor**
|
||||
(`cat >`/`rm`/redirecção), o que evitaria deliberadamente o GATE 5.1 de mutação de infra-estrutura
|
||||
(bloqueia mutações de ficheiro em `server` sem `~/.claude/hooks/infra-auth.sh server`; escritas de
|
||||
base de dados via `wp eval` não são bloqueadas por este gate). Ver `src/wp-bridge.ts` (`runPhp()`).
|
||||
|
||||
## Tools (20)
|
||||
|
||||
**Leitura (10):** `fcrm_list_contacts` (filtros status/pesquisa/tag_id/list_id/company_id — usar
|
||||
sempre, nunca listar sem filtro/limit com 291k linhas), `fcrm_get_contact`,
|
||||
`fcrm_list_contact_notes`, `fcrm_list_tags`, `fcrm_list_lists`, `fcrm_list_companies`,
|
||||
`fcrm_get_company`, `fcrm_list_campaigns`, `fcrm_get_campaign_stats`, `fcrm_get_subscriber_stats`.
|
||||
|
||||
**Escrita (10):** `fcrm_create_or_update_contact`, `fcrm_update_contact_status`,
|
||||
`fcrm_attach_tags`, `fcrm_detach_tags`, `fcrm_attach_lists`, `fcrm_detach_lists`,
|
||||
`fcrm_add_contact_note`, `fcrm_create_tag`, `fcrm_create_list`, `fcrm_create_or_update_company`.
|
||||
|
||||
## Guardas de segurança em status (contactos reais, cuidado)
|
||||
|
||||
- `fcrm_create_or_update_contact` nunca rebaixa um contacto `subscribed` nem ressuscita um
|
||||
suprimido (`unsubscribed`/`bounced`/`complained`/`spammed`) sem `force_update=true` — mesma
|
||||
guarda que o `Contacts::createOrUpdate()` do próprio plugin implementa (o código documenta isto
|
||||
como correcção de uma escalada de estado indevida que existia antes).
|
||||
- `fcrm_update_contact_status` (mudança directa, sem as guardas do createOrUpdate) exige
|
||||
`confirm=true` explícito nas duas direcções de risco: `subscribed`→suprimido, ou
|
||||
suprimido→qualquer outro estado. Sem `confirm`, a tool recusa com erro accionável.
|
||||
- Estados válidos: `subscribed`, `pending`, `unsubscribed`, `transactional`, `bounced`,
|
||||
`complained`, `spammed`. Suprimidos: `unsubscribed`/`bounced`/`complained`/`spammed`.
|
||||
|
||||
## Fora do v1 (decisão deliberada)
|
||||
|
||||
Criação/envio de campanhas (dispara emails reais, sem dry-run, blast-radius incompatível com um
|
||||
v1), CRUD de funnels/automações (sequências JSON complexas), event tracking de escrita, segmentos
|
||||
dinâmicos (Pro), gestão de licença. Ler/gerir manualmente no wp-admin.
|
||||
|
||||
## Credenciais
|
||||
|
||||
`.env` local (`WP_SSH_HOST=server`, `WP_PATH=/home/ealmeida/public_html`), não versionado. Sem
|
||||
tokens/API keys — a autenticação é a própria sessão SSH root já configurada em `~/.ssh/config`.
|
||||
|
||||
## Verificação
|
||||
|
||||
Construído e testado ponta-a-ponta contra a zona real 19-08-2026: todas as 20 tools exercitadas
|
||||
manualmente (incl. guarda de status bloqueada e depois confirmada) + 14/14 evaluations
|
||||
automatizadas (`npm run eval:ci`), que criam e limpam os seus próprios artefactos
|
||||
(`__mcp_eval__`) sem tocar em dados reais. Deploy como processo `hub` persistente
|
||||
(`mcp-fluent-crm`, porta 3202, `http://127.0.0.1:3202/mcp`), registado em `~/.claude.json` como
|
||||
`fluent-crm`.
|
||||
|
||||
## Skills relacionadas
|
||||
|
||||
Nenhuma skill de gestão de zona equivalente ao `app-for-cloudflare` existe para FluentCRM — este
|
||||
MCP é a única via programática. Para gestão manual, usar o wp-admin de descomplicar.pt
|
||||
(**FluentCRM → Subscribers/Automations/Email Campaigns**).
|
||||
Reference in New Issue
Block a user