# Ferramentas · Visitantes

> Ferramentas MCP do módulo Visitantes (coworking): cadastrar, listar, ler, editar e cancelar convidados, os esperados de hoje, buscar o anfitrião e marcar ou desfazer a chegada na recepção.

O módulo [Visitantes](/espacos/visitantes) pelo assistente: cadastrar o convidado antes, editar e cancelar, ver quem é esperado hoje na recepção e marcar a chegada com aviso ao anfitrião. O quiosque do visitante é uma tela do iPad; o assistente **não** o opera.

Cada ferramenta traz um selo: <span class="tool-kind tool-kind-read">Só consulta</span> não muda nada, <span class="tool-kind tool-kind-write">Altera</span> cria ou muda algo na hora, e <span class="tool-kind tool-kind-confirm">Pede confirmação</span> só age depois do seu sim a um resumo. Ver [Dinheiro e confirmação](/mcp/dinheiro-e-confirmacao).

## Em resumo

| Ferramenta | O que faz | Papel mínimo | Tipo |
|---|---|---|---|
| [`create_visitor_invitation`](#create-visitor-invitation) | Cadastra um convidado | Qualquer com acesso ao espaço (a configuração pode restringir); equipe, em nome de outro anfitrião | <span class="tool-kind tool-kind-write">Altera</span> |
| [`list_visitor_invitations`](#list-visitor-invitations) | Lista e busca os convidados | Qualquer (o membro vê os seus) | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`get_visitor_invitation`](#get-visitor-invitation) | Um cadastro | Dono do cadastro ou equipe | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`update_visitor_invitation`](#update-visitor-invitation) | Edita antes da chegada | Dono do cadastro ou equipe | <span class="tool-kind tool-kind-write">Altera</span> |
| [`cancel_visitor_invitation`](#cancel-visitor-invitation) | Cancela um cadastro | Dono do cadastro ou equipe | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`list_visitors_today`](#list-visitors-today) | Os esperados e os chegados de hoje | Moderador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`search_visitor_hosts`](#search-visitor-hosts) | Acha o anfitrião | Moderador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`mark_visitor_arrived`](#mark-visitor-arrived) | Marca a chegada | Moderador ou financeiro | <span class="tool-kind tool-kind-write">Altera</span> |
| [`undo_visitor_arrival`](#undo-visitor-arrival) | Desfaz uma chegada | Moderador ou financeiro | <span class="tool-kind tool-kind-write">Altera</span> |

Os papéis são os das rotas: o assistente nunca faz mais do que a pessoa conectada faria na tela. A equipe, aqui, é o proprietário, o administrador, o moderador e o financeiro; o moderador e o financeiro mexem **só nos convidados de hoje**. O espaço se cria com [`create_space`](/mcp/ferramentas-comunidade#create-space) e `module: "visitors"`; [`update_space`](/mcp/ferramentas-comunidade#update-space) muda só o que você mandar.

## A configuração do espaço

O argumento `visitors` de `create_space` e `update_space` aceita:

| Campo | Tipo | Descrição |
|---|---|---|
| `attendance_space_id` | id | O espaço [Presença](/mcp/ferramentas-presenca) onde as chegadas são registradas. Obrigatório ao criar (`list_spaces`) |
| `who_can_invite` | `members`, `staff` ou `group` | Quem cadastra: qualquer membro com acesso, só a equipe, ou o grupo de `inviter_group_id` mais a equipe |
| `inviter_group_id` | id ou `null` | O grupo de quem cadastra (`list_groups`); obrigatório com `group` |
| `fields` | `{company, email, phone}`, cada um `off`, `optional` ou `required` | O que o formulário pede do convidado |
| `notify_host_on_register` | verdadeiro ou falso | Confirma o cadastro ao anfitrião por e-mail (padrão: sim) |
| `email_guest` | `off`, `optional` ou `always` | O [e-mail ao convidado](/espacos/visitantes#e-mail-ao-convidado) (padrão: `off`) |
| `arrival_instructions` | texto até 500 caracteres, ou `null` | Onde ir e por quem perguntar |
| `max_expected_per_host_per_day` | 1 a 1000, ou `null` | Limite de convidados por anfitrião por dia |

## `create_visitor_invitation`

<span class="tool-kind tool-kind-write">Altera</span>

**Cadastrar um convidado.** Não cria conta para o convidado. Quem a configuração permite cadastra para si; a equipe passa `host_profile_id` para cadastrar em nome de outro. Empresa, e-mail e telefone seguem a configuração (um campo desligado é ignorado; um obrigatório faltando é recusado). O anfitrião pode receber um e-mail de confirmação e o convidado outro, conforme `notify_guest` e a configuração; o assistente avisa a pessoa. São dados pessoais de um terceiro. *Papel: qualquer com acesso ao espaço.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `space` | id ou link | Sim | O espaço Visitantes |
| `guest_name` | texto | Sim | Até 100 caracteres |
| `expected_date` | `AAAA-MM-DD` | Sim | No fuso da comunidade; não pode ser passado |
| `start_time` | `HH:mm` | Sim | Horário inicial, no fuso da comunidade |
| `end_time` | `HH:mm` | Não | Depois do início |
| `guest_company`, `guest_email`, `guest_phone` | texto | Conforme a configuração | |
| `notify_guest` | verdadeiro ou falso | Não | Avisa o convidado por e-mail; vale só com e-mail e conforme `email_guest` |
| `host_profile_id` | id | Não | Só a equipe: o anfitrião (`search_visitor_hosts`). Sem ele, é você |

**Peça assim:** *"Cadastre a Maria Souza (maria@memberfy.net) como minha convidada amanhã, das 14h às 15h."*

## `list_visitor_invitations`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Listar os convidados.** Por horário esperado. O membro vê só os seus (como anfitrião ou quem cadastrou), de qualquer data; moderador e financeiro veem também todos os de hoje; administrador e proprietário veem qualquer data. Cada item diz o que você pode fazer (`canEdit`, `canCancel`, `canArrive`, `canUndoArrival`). *Papel: qualquer com acesso ao espaço.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `space` | id ou link | Sim | |
| `status` | `EXPECTED`, `ARRIVED`, `CANCELED` ou `NO_SHOW` | Não | `EXPECTED` vale de hoje em diante; `NO_SHOW` é o esperado de um dia que passou |
| `from`, `to` | `AAAA-MM-DD` | Não | Período, inclusive, no fuso da comunidade |
| `q` | texto | Não | Parte do nome ou da empresa |
| `page`, `limit` | números | Não | Paginação (até 100) |

**Peça assim:** *"Quais convidados eu tenho cadastrados para esta semana?"*

## `get_visitor_invitation`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Um cadastro.** O anfitrião e quem cadastrou leem o seu; a equipe lê o de hoje; proprietário e administrador, qualquer um. Outro cadastro, outra comunidade ou id desconhecido: `404`. *Papel: qualquer.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `invitation_id` | id | Sim | De `list_visitor_invitations` ou `list_visitors_today` |

## `update_visitor_invitation`

<span class="tool-kind tool-kind-write">Altera</span>

**Editar antes da chegada.** Depois da chegada, ou de cancelado, a resposta é `409`. Mande só o que muda; `host_profile_id` é da equipe. Mudar o dia, o horário ou o anfitrião manda uma nova confirmação ao anfitrião, uma vez por mudança. O dono do cadastro e a equipe editam (moderador e financeiro, só os de hoje). *Papel: qualquer, conforme quem pode editar.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `invitation_id` | id | Sim | |
| `guest_name`, `guest_company`, `guest_email`, `guest_phone` | texto | Não | |
| `expected_date`, `start_time`, `end_time` | data e horários | Não | Mesmos formatos de `create_visitor_invitation` |
| `notify_guest` | verdadeiro ou falso | Não | |
| `host_profile_id` | id | Não | Só a equipe |

**Peça assim:** *"Mude a visita da Maria para as 15h."*

## `cancel_visitor_invitation`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Cancelar um cadastro.** Vira **Cancelado**; nada é apagado. Quem cadastrou, o anfitrião ou a equipe (moderador e financeiro, só os de hoje). Já cancelado: nada muda. Já chegou: `409`, desfaça a chegada antes. *Papel: qualquer, conforme quem pode cancelar.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `invitation_id` | id | Sim | |

**Devolve:** na primeira chamada, o resumo (convidado, anfitrião, dia e horário) e o código de confirmação.

## `list_visitors_today`

<span class="tool-kind tool-kind-read">Só consulta</span>

**A visão da recepção.** Os esperados e os que já chegaram hoje (fuso da comunidade), de todos os anfitriões, com as contagens. Cancelados e "não veio" não entram. `alreadyMember` indica que o e-mail do convidado é de um membro. *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `space` | id ou link | Sim | |
| `q` | texto | Não | Nome ou empresa, sem acento nem caixa |

**Peça assim:** *"Quem eu espero hoje na recepção?"*

## `search_visitor_hosts`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Achar o anfitrião.** Membros do espaço cujo nome (ou uma palavra dele) começa com `q`, com 3 letras ou mais. Devolve só id, nome, foto e iniciais; o id é o `host_profile_id` de `create_visitor_invitation`. *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `space` | id ou link | Sim | |
| `q` | texto | Sim | De 3 a 100 caracteres |

## `mark_visitor_arrived`

<span class="tool-kind tool-kind-write">Altera</span>

**Marcar a chegada.** Cria a visita na Presença ligada (método recepção, com o nome do cadastro) ou liga a que a equipe já tinha registrado. O anfitrião é avisado por e-mail quando a Presença está ajustada para isso; `hostNotified` diz se o aviso foi para a fila, e o assistente conta à pessoa. É idempotente: a segunda chamada devolve `alreadyArrived: true`. Só no dia do cadastro (outro dia: `409`); fora da janela de horário vale; cancelado: `409`. *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `invitation_id` | id | Sim | De `list_visitors_today` |

**Devolve:** `invitation`, `visit`, `hostNotified` e `alreadyArrived`.

**Peça assim:** *"A Maria Souza chegou."*

## `undo_visitor_arrival`

<span class="tool-kind tool-kind-write">Altera</span>

**Desfazer uma chegada marcada por engano.** No mesmo dia e antes da saída do convidado. A visita sai das listas e da lotação (fica no registro da Presença) e o cadastro volta a **Esperado**. Sem chegada, outro dia ou já saiu: `409`. *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `invitation_id` | id | Sim | |

## Relacionados

- [Visitantes](/espacos/visitantes)
- [Ferramentas: Presença](/mcp/ferramentas-presenca)
- [Ferramentas](/mcp/ferramentas)
- [Dinheiro e confirmação](/mcp/dinheiro-e-confirmacao)
- [Receitas](/mcp/receitas)