ealmeida
eae213c7f0
Cobre: calendarios, event types, reservas (listar/detalhe/mudar estado/reenviar confirmacao), actividade, disponibilidade, reports, definicoes gerais, anfitrioes, estado do plugin/licenca Pro. 15 tools via REST API real com Application Password (nao SSH/SQL como mcp-bit-social - o FluentBooking regista register_rest_route com permission_callback por capability). Testado ponta-a-ponta em producao 19-08-2026, incluindo escrita sem mutar dados reais (422 'No changes found' do proprio plugin). references/api-reference.md com os endpoints/filtros/enums confirmados e references/diagnostics.md com o playbook de uso (agenda, cancelamento, health check).
87 lines
5.2 KiB
Markdown
87 lines
5.2 KiB
Markdown
---
|
|
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.
|