ealmeida
46175594c1
fluent-crm documenta arquitectura Free/Pro, schema fc_*, FluentCrmApi(), guarda anti-escalada de status, wp-admin, Funnels/Dynamic Segments — companheira de conhecimento da mcp-fluent-crm (execução), mesmo padrão app-for-cloudflare/mcp-cloudflare-app.
80 lines
5.2 KiB
Markdown
80 lines
5.2 KiB
Markdown
---
|
|
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
|
|
|
|
- `fluent-crm` — conhecimento profundo do plugin: arquitectura Free/Pro, schema completo `fc_*`,
|
|
API de desenvolvimento (`FluentCrmApi()`), modelo de estados e a guarda anti-escalada (§3),
|
|
wp-admin, arquitectura de Automations/Funnels e Dynamic Segments (Pro) — consultar antes de
|
|
desenhar uma automação ou entender uma decisão de status que este MCP não cobre (Funnels,
|
|
Dynamic Segments, campanhas de envio ficam fora do v1 desta ferramenta — gerir via wp-admin).
|