---
name: mcp-fluent-booking
description: MCP dedicado (node stdio, ligação `fluent-booking` em ~/.omp/agent/mcp.json) para o FluentBooking/FluentBooking Pro (WPManageNinja) em descomplicar.pt — a agenda de marcação de reuniões (`/marcar-reuniao/`). Calendários, reservas/marcações, disponibilidade, reports, cancelar/reagendar. Usar quando "fluent booking", "marcações", "reuniões agendadas", "quem marcou reunião", "cancelar reserva", "reagendar reunião", "disponibilidade calendário", "reservas fluentbooking", "reenviar confirmação de reunião", "licença fluent booking pro".
layer: wiki
---

# /mcp-fluent-booking — MCP dedicado FluentBooking / FluentBooking Pro

Projecto em `/media/ealmeida/Dados/Dev/mcp-fluent-booking/` (TypeScript, SDK MCP oficial, stdio).
Ao contrário de `mcp-bit-social`/`mcp-element-pack`, **não usa SSH/WP-CLI para os dados de
negócio** — o FluentBooking regista uma REST API real (`register_rest_route` sob
`fluent-booking/v2`, confirmado em `vendor/wpfluent/framework/.../Route.php`) com
`permission_callback` baseado em capabilities (`current_user_can`), não em nonce de sessão
wp-admin. Autentica com uma **Application Password** WordPress (Basic Auth), e cada escrita passa
pela lógica de negócio real do plugin (emails, activity log, side-effects de pagamento) em vez de
um `UPDATE` SQL directo.

## Auth

Application Password dedicada (utilizador `ealmeida`, nome `mcp-fluent-booking`), guardada só no
`env:` da ligação MCP (`~/.omp/agent/mcp.json`) — nunca em ficheiro commitado. Revogar em
WordPress → Utilizadores → perfil → Application Passwords se deixar de ser necessária. Recriar com
`wp user application-password create ealmeida mcp-fluent-booking --porcelain`.

## Tools (15)

**Estado (read-only):**
- `fb_get_plugin_status` — versões free/pro (via WP-CLI, único tool que ainda usa SSH — a API não
  expõe versão) + estado da licença Pro (via API).

**Calendários e event types (read-only):**
- `fb_list_calendars` / `fb_get_calendar` — páginas de agendamento por anfitrião.
- `fb_get_event` — um tipo de evento (ex.: "Diagnóstico Digital Gratuito, 30min").

**Reservas — o domínio principal:**
- `fb_list_bookings` (read-only) — filtros `period` (upcoming/completed/cancelled/pending/
  no_show/latest_bookings/**all**), `calendar_id`, `event_id`, `event_type`, `email`, `search`,
  intervalo de datas, paginação. **`period` por omissão é `upcoming`** — usar `all` para histórico.
- `fb_get_booking` (read-only) — reserva completa: convidado, campos de formulário custom, local,
  pagamento.
- `fb_list_activities` (read-only) — timeline de uma reserva (`booking_id`) ou log do site inteiro
  (sem argumento).
- `fb_update_booking_status` (**write**) — muda `status` para
  `scheduled|completed|cancelled|rejected|no_show` pela API real (`PUT /schedules/{id}`,
  `column=status`). Único caminho de escrita de estado; dispara os efeitos correctos do plugin
  (email de cancelamento com `cancel_reason`, log de actividade, marcação de pagamento).
- `fb_send_confirmation_email` (**write**) — reenvia o email de confirmação a um convidado real.
  Envia um email de verdade — usar com intenção, nunca para "testar".

**Disponibilidade e reports (read-only):**
- `fb_list_availability_schedules` / `fb_get_availability_schedule` — templates de horário
  semanal reutilizáveis entre event types.
- `fb_get_reports` — overview (totais, últimas reservas).
- `fb_get_graph_reports` — série temporal (reservas/concluídas/canceladas por dia), intervalo
  `date_from`/`date_to` opcional.
- `fb_get_general_settings` — moeda, remetente de email, cancelamento automático.
- `fb_list_hosts` — utilizadores WordPress com calendário próprio.

## Fora do âmbito

Equipa/permissões, métodos de pagamento, integrações Zoom/Google/CalDAV, Twilio SMS, webhooks,
cupões, activação/desactivação de licença — gestão de credenciais/integrações externas fica no
wp-admin. Criar reservas em nome de alguém (`POST /bookings/create/{event_id}`) também fica fora:
o payload depende de slots computados dinamicamente e uma reserva mal formada dispara emails reais
a um convidado.

## Segurança

`fb_send_confirmation_email` e o ramo `cancelled`/`rejected` de `fb_update_booking_status`
disparam emails reais a convidados verdadeiros — nunca invocar como "teste". Verificação sem
mutação real: mudar um booking para o estado que **já tem** devolve 422 "No changes found" do
próprio plugin (confirma o caminho de escrita sem alterar nada).

## Verificação

Construído e testado ponta-a-ponta contra produção 19-08-2026: as 15 tools exercitadas com dados
reais (1 calendário, 39 reservas no histórico, licença Pro "Agency License" válida), incluindo o
caso 422 "No changes found" acima (escrita testada sem mutar dados reais) e 404 correcto em id
inexistente (`fb_get_booking`, `fb_send_confirmation_email`).

## Recursos adicionais

- **`references/api-reference.md`** — endpoints REST completos, filtros (`period`, `author`,
  `range`), enums, forma real das respostas (`booking`, `calendar`, `event`, `availability`).
- **`references/diagnostics.md`** — playbook: quem marcou uma reunião, cancelar/reagendar
  correctamente, health check rápido, o que fazer quando `fb_list_bookings` devolve vazio.