---
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**).