---
name: mcp-kivicare
description: MCP dedicado (node stdio, ligação `kivicare` em ~/.omp/agent/mcp.json) para o KiviCare Clinic Management System (Free e Pro) em WordPress via WP-CLI/SSH. 24 tools tipadas — clínicas, médicos/profissionais, horários semanais, pacientes (perfil 360º e histórico médico), consultas (listar/detalhe/agendar/mudar estado com disparo de hooks nativos/reagendar), encontros clínicos, prescrições e facturação. Usar quando "kivicare", "consulta médica", "agendar consulta", "médicos clínica", "paciente kivicare", "encontro clínico", "familyclinic.pt" ou qualquer operação clínica no KiviCare.
---

# /mcp-kivicare — MCP KiviCare Clinic Management System

MCP dedicado ao **KiviCare Clinic Management System** (Free e Pro) em WordPress via WP-CLI/SSH (ambiente padrão `familyclinic.pt` em `/home/familycl/public_html`, com suporte a `care.descomplicar.pt`).

- **Código-fonte:** `/media/ealmeida/Dados/Dev/mcp-kivicare/` (TypeScript)
- **Ligação:** `kivicare` em `~/.omp/agent/mcp.json` (transporte `stdio` via Node)
- **Target:** `familyclinic.pt` (servidor Hetzner CWP, prefixo `wpej_`, DB `familycl_wp417`)

---

## 1. Arquitectura & Dupla Ponte

O `mcp-kivicare` resolve todas as operações através de uma arquitectura de dupla ponte:

1. **Bridge SQL Directo** (`wp db query --raw` sobre SSH):
   - Executa consultas estruturadas com MariaDB `JSON_OBJECT()` e `JSON_ARRAYAGG()`.
   - Paginação optimizada por subquery (`LIMIT` / `OFFSET` na query interna).
   - Respostas instantâneas em milissegundos sem arranque/bootstrap do WordPress.
2. **Bridge PHP Seguro** (`wp eval-file -` com JSON via STDIN):
   - Para mutações (criação de pacientes, agendamento de consultas, mudança de estado, reagendamento, novos encontros clínicos).
   - Garante transacções atómicas na base de dados e dispara as acções e filtros nativos do WordPress/KiviCare (ex: `do_action('kc_appointment_status_update', ...)`), permitindo que plugins integradores (WhatsSMS, SincCare, email) enviem as notificações automáticas.
   - No check-in de consulta (estado `4`), cria automaticamente o encontro clínico (`kc_patient_encounters`) caso ainda não exista.

---

## 2. Catálogo Completo de Tools (24)

### 2.1 Clínicas & Dashboard
| Tool | O que faz |
|---|---|
| `kc_get_clinic_summary` | Resumo estatístico geral: consultas por estado, pacientes, médicos, encontros, receita paga vs pendente e consultas de hoje. |
| `kc_list_clinics` | Lista todas as clínicas registadas com contactos, moradas e especialidades. |
| `kc_get_clinic` | Detalhes completos de uma clínica pelo seu ID. |

### 2.2 Médicos & Profissionais
| Tool | O que faz |
|---|---|
| `kc_list_doctors` | Lista médicos com especialidades, contactos e clínicas atribuídas. |
| `kc_get_doctor` | Perfil detalhado de um médico pelo ID. |
| `kc_get_doctor_sessions` | Horários e sessões semanais de atendimento (dias da semana, início/fim, slot em minutos). |
| `kc_list_receptionists` | Lista de funcionários da recepção por clínica. |

### 2.3 Serviços & Preçário
| Tool | O que faz |
|---|---|
| `kc_list_services` | Catálogo de serviços clínicos e psicológicos com preços base e categorias. |
| `kc_get_service_doctor_mappings` | Atribuição de serviços a médicos específicos com preços customizados e durações. |

### 2.4 Pacientes
| Tool | O que faz |
|---|---|
| `kc_list_patients` | Pesquisa e lista pacientes com paginação e filtros (nome, email, telefone, clínica). |
| `kc_get_patient` | Perfil 360º: dados pessoais, grupo sanguíneo, contagens e últimas consultas/encontros. |
| `kc_get_patient_medical_history` | Histórico clínico, alergias e patologias registadas do paciente. |
| `kc_create_patient` | Regista novo paciente no KiviCare (utilizador WP `kivicare_patient` + `basic_data` + clínica). |
| `kc_update_patient` | Actualiza contactos e dados pessoais de um paciente existente. |

### 2.5 Consultas & Marcações
| Tool | O que faz |
|---|---|
| `kc_list_appointments` | Lista e filtra consultas por médico, paciente, clínica, estado (0-4) ou datas. |
| `kc_get_today_appointments` | Agenda de consultas do dia actual. |
| `kc_get_appointment` | Detalhe completo de uma consulta com serviços associados, notas e estado. |
| `kc_create_appointment` | Agenda nova consulta com médico, paciente, clínica e serviços. |
| `kc_update_appointment_status` | Altera estado de consulta (0=Cancelled, 1=Booked, 2=Pending, 3=Check-Out, 4=Check-In) com hooks. |
| `kc_reschedule_appointment` | Reagenda uma consulta para nova data e hora. |

### 2.6 Encontros Clínicos & Prescrições
| Tool | O que faz |
|---|---|
| `kc_list_encounters` | Lista encontros clínicos abertos (1) ou fechados (0). |
| `kc_get_encounter` | Detalhes do encontro com sintomas, prescrições e factura associada. |
| `kc_create_encounter` | Abre um novo encontro clínico. |

### 2.7 Facturação
| Tool | O que faz |
|---|---|
| `kc_list_bills` | Lista facturas com filtro por estado (`paid`/`unpaid`), clínica e datas. |
| `kc_get_bill` | Detalhes da factura com itens, quantidades, preços e descontos. |

---

## 3. Códigos de Estado das Consultas

No KiviCare, o campo `status` das consultas (`kc_appointments`) segue a seguinte convenção canónica:

- `0` — **Cancelled** (Consulta cancelada)
- `1` — **Booked** (Consulta agendada / confirmada)
- `2` — **Pending** (Consulta pendente de confirmação)
- `3` — **Check-Out** (Consulta concluída / finalizada)
- `4` — **Check-In** (Paciente presente / em atendimento — cria encontro clínico automaticamente)

---

## 4. Variáveis de Ambiente

| Variável | Padrão | Descrição |
|---|---|---|
| `KC_SSH_HOST` | `server` | Host SSH no `~/.ssh/config` |
| `KC_WP_PATH` | `/home/familycl/public_html` | Directório raiz da instalação WordPress |
| `KC_PHP_BIN` | `/opt/alt/php-fpm82/usr/bin/php` | Caminho do executável PHP no servidor |
| `KC_WP_CLI` | `/usr/local/bin/wp` | Caminho do WP-CLI no servidor |
| `KC_DB_PREFIX` | `wpej_` | Prefixo das tabelas da base de dados |

---

*mcp-kivicare | Descomplicar® | v1.0.0 | 2026-08-19*