Ferramentas · VisitantesEm breve
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 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.
Em breve Chegando às comunidades: estas 9 ferramentas passam a existir no servidor quando a atualização for ao ar. Até lá, o assistente não as oferece.
Cada ferramenta traz um selo: Só consulta não muda nada, Altera cria ou muda algo na hora, e Pede confirmação só age depois do seu sim a um resumo. Ver Dinheiro e confirmação.
Em resumo
| Ferramenta | O que faz | Papel mínimo | Tipo |
|---|---|---|---|
create_visitor_invitation | Cadastra um convidado | Qualquer com acesso ao espaço (a configuração pode restringir); equipe, em nome de outro anfitrião | Altera |
list_visitor_invitations | Lista e busca os convidados | Qualquer (o membro vê os seus) | Só consulta |
get_visitor_invitation | Um cadastro | Dono do cadastro ou equipe | Só consulta |
update_visitor_invitation | Edita antes da chegada | Dono do cadastro ou equipe | Altera |
cancel_visitor_invitation | Cancela um cadastro | Dono do cadastro ou equipe | Pede confirmação |
list_visitors_today | Os esperados e os chegados de hoje | Moderador ou financeiro | Só consulta |
search_visitor_hosts | Acha o anfitrião | Moderador ou financeiro | Só consulta |
mark_visitor_arrived | Marca a chegada | Moderador ou financeiro | Altera |
undo_visitor_arrival | Desfaz uma chegada | Moderador ou financeiro | Altera |
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 e module: "visitors"; 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 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 (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
Altera
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 ([email protected]) como minha convidada amanhã, das 14h às 15h."
list_visitor_invitations
Só consulta
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
Só consulta
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
Altera
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
Pede confirmação
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
Só consulta
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
Só consulta
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
Altera
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
Altera
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 |