claude-plugins/wordpress/skills/mcp-fluent-crm/SKILL.md

name, description, layer

name	description	layer
mcp-fluent-crm	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.	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).