# Herramientas · Visitantes

> Herramientas MCP del módulo Visitantes (coworking): registrar, listar, leer, editar y cancelar invitados, los esperados de hoy, buscar al anfitrión y marcar o deshacer la llegada en la recepción.

El módulo [Visitantes](/espacos/visitantes) con el asistente: registrar al invitado antes, editar y cancelar, ver a quién se espera hoy en la recepción y marcar la llegada con aviso al anfitrión. El quiosco del visitante es una pantalla del iPad; el asistente **no** lo maneja.

Cada herramienta lleva un sello: <span class="tool-kind tool-kind-read">Solo consulta</span> no cambia nada, <span class="tool-kind tool-kind-write">Modifica</span> crea o cambia algo al momento, y <span class="tool-kind tool-kind-confirm">Pide confirmación</span> solo actúa después de tu sí a un resumen. Consulta [Dinero y confirmación](/mcp/dinheiro-e-confirmacao).

## En resumen

| Herramienta | Qué hace | Rol mínimo | Tipo |
|---|---|---|---|
| [`create_visitor_invitation`](#create-visitor-invitation) | Registra un invitado | Cualquiera con acceso al espacio (la configuración puede restringirlo); el equipo, en nombre de otro anfitrión | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`list_visitor_invitations`](#list-visitor-invitations) | Lista y busca los invitados | Cualquiera (el miembro ve los suyos) | <span class="tool-kind tool-kind-read">Solo consulta</span> |
| [`get_visitor_invitation`](#get-visitor-invitation) | Un registro | Dueño del registro o equipo | <span class="tool-kind tool-kind-read">Solo consulta</span> |
| [`update_visitor_invitation`](#update-visitor-invitation) | Edita antes de la llegada | Dueño del registro o equipo | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`cancel_visitor_invitation`](#cancel-visitor-invitation) | Cancela un registro | Dueño del registro o equipo | <span class="tool-kind tool-kind-confirm">Pide confirmación</span> |
| [`list_visitors_today`](#list-visitors-today) | Los esperados y los llegados de hoy | Moderador o financiero | <span class="tool-kind tool-kind-read">Solo consulta</span> |
| [`search_visitor_hosts`](#search-visitor-hosts) | Encuentra al anfitrión | Moderador o financiero | <span class="tool-kind tool-kind-read">Solo consulta</span> |
| [`mark_visitor_arrived`](#mark-visitor-arrived) | Marca la llegada | Moderador o financiero | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`undo_visitor_arrival`](#undo-visitor-arrival) | Deshace una llegada | Moderador o financiero | <span class="tool-kind tool-kind-write">Modifica</span> |

Los roles son los de las rutas: el asistente nunca hace más de lo que haría en la pantalla la persona conectada. El equipo, aquí, es el propietario, el administrador, el moderador y el financiero; el moderador y el financiero tocan **solo los invitados de hoy**. El espacio se crea con [`create_space`](/mcp/ferramentas-comunidade#create-space) y `module: "visitors"`; [`update_space`](/mcp/ferramentas-comunidade#update-space) cambia solo lo que envíes.

## La configuración del espacio

El argumento `visitors` de `create_space` y `update_space` acepta:

| Campo | Tipo | Descripción |
|---|---|---|
| `attendance_space_id` | id | El espacio [Presencia](/mcp/ferramentas-presenca) donde se registran las llegadas. Obligatorio al crear (`list_spaces`) |
| `who_can_invite` | `members`, `staff` o `group` | Quién registra: cualquier miembro con acceso, solo el equipo, o el grupo de `inviter_group_id` más el equipo |
| `inviter_group_id` | id o `null` | El grupo de quien registra (`list_groups`); obligatorio con `group` |
| `fields` | `{company, email, phone}`, cada uno `off`, `optional` o `required` | Lo que el formulario pide del invitado |
| `notify_host_on_register` | verdadero o falso | Confirma el registro al anfitrión por correo (por defecto: sí) |
| `email_guest` | `off`, `optional` o `always` | El [correo al invitado](/espacos/visitantes#correo-al-invitado) (por defecto: `off`) |
| `arrival_instructions` | texto de hasta 500 caracteres, o `null` | Adónde ir y por quién preguntar |
| `max_expected_per_host_per_day` | 1 a 1000, o `null` | Límite de invitados por anfitrión por día |

## `create_visitor_invitation`

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

**Registrar un invitado.** No crea cuenta para el invitado. Quien la configuración permite registra para sí; el equipo pasa `host_profile_id` para registrar en nombre de otro. Empresa, correo y teléfono siguen la configuración (un campo desactivado se ignora; uno obligatorio que falte se rechaza). El anfitrión puede recibir un correo de confirmación y el invitado otro, según `notify_guest` y la configuración; el asistente avisa a la persona. Son datos personales de un tercero. *Rol: cualquiera con acceso al espacio.*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `space` | id o enlace | Sí | El espacio Visitantes |
| `guest_name` | texto | Sí | Hasta 100 caracteres |
| `expected_date` | `AAAA-MM-DD` | Sí | En la zona horaria de la comunidad; no puede ser pasado |
| `start_time` | `HH:mm` | Sí | Hora inicial, en la zona horaria de la comunidad |
| `end_time` | `HH:mm` | No | Posterior al inicio |
| `guest_company`, `guest_email`, `guest_phone` | texto | Según la configuración | |
| `notify_guest` | verdadero o falso | No | Avisa al invitado por correo; vale solo con correo y según `email_guest` |
| `host_profile_id` | id | No | Solo el equipo: el anfitrión (`search_visitor_hosts`). Sin él, eres tú |

**Pídelo así:** *"Registra a María Souza (maria@memberfy.net) como mi invitada mañana, de 14 a 15 h."*

## `list_visitor_invitations`

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

**Listar los invitados.** Por hora esperada. El miembro ve solo los suyos (como anfitrión o como quien registró), de cualquier fecha; moderador y financiero ven además todos los de hoy; administrador y propietario ven cualquier fecha. Cada elemento dice qué puedes hacer (`canEdit`, `canCancel`, `canArrive`, `canUndoArrival`). *Rol: cualquiera con acceso al espacio.*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `space` | id o enlace | Sí | |
| `status` | `EXPECTED`, `ARRIVED`, `CANCELED` o `NO_SHOW` | No | `EXPECTED` vale de hoy en adelante; `NO_SHOW` es el esperado de un día que pasó |
| `from`, `to` | `AAAA-MM-DD` | No | Período, inclusive, en la zona horaria de la comunidad |
| `q` | texto | No | Parte del nombre o de la empresa |
| `page`, `limit` | números | No | Paginación (hasta 100) |

**Pídelo así:** *"¿Qué invitados tengo registrados para esta semana?"*

## `get_visitor_invitation`

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

**Un registro.** El anfitrión y quien registró leen el suyo; el equipo lee el de hoy; propietario y administrador, cualquiera. Otro registro, otra comunidad o id desconocido: `404`. *Rol: cualquiera.*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `invitation_id` | id | Sí | De `list_visitor_invitations` o `list_visitors_today` |

## `update_visitor_invitation`

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

**Editar antes de la llegada.** Tras la llegada, o si está cancelado, la respuesta es `409`. Envía solo lo que cambia; `host_profile_id` es del equipo. Cambiar el día, la hora o el anfitrión envía una nueva confirmación al anfitrión, una vez por cambio. El dueño del registro y el equipo editan (moderador y financiero, solo los de hoy). *Rol: cualquiera, según quién pueda editar.*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `invitation_id` | id | Sí | |
| `guest_name`, `guest_company`, `guest_email`, `guest_phone` | texto | No | |
| `expected_date`, `start_time`, `end_time` | fecha y horas | No | Mismos formatos de `create_visitor_invitation` |
| `notify_guest` | verdadero o falso | No | |
| `host_profile_id` | id | No | Solo el equipo |

**Pídelo así:** *"Cambia la visita de María a las 15 h."*

## `cancel_visitor_invitation`

<span class="tool-kind tool-kind-confirm">Pide confirmación</span>

**Cancelar un registro.** Pasa a **Cancelado**; no se borra nada. Quien registró, el anfitrión o el equipo (moderador y financiero, solo los de hoy). Ya cancelado: no cambia nada. Ya llegó: `409`, deshaz antes la llegada. *Rol: cualquiera, según quién pueda cancelar.*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `invitation_id` | id | Sí | |

**Devuelve:** en la primera llamada, el resumen (invitado, anfitrión, día y hora) y el código de confirmación.

## `list_visitors_today`

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

**La vista de la recepción.** Los esperados y los que ya llegaron hoy (zona horaria de la comunidad), de todos los anfitriones, con los totales. Los cancelados y "no vino" no entran. `alreadyMember` indica que el correo del invitado es el de un miembro. *Rol mínimo: moderador (o financiero).*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `space` | id o enlace | Sí | |
| `q` | texto | No | Nombre o empresa, sin tildes ni mayúsculas |

**Pídelo así:** *"¿A quién espero hoy en la recepción?"*

## `search_visitor_hosts`

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

**Encontrar al anfitrión.** Miembros del espacio cuyo nombre (o una palabra de él) empieza por `q`, con 3 letras o más. Devuelve solo id, nombre, foto e iniciales; el id es el `host_profile_id` de `create_visitor_invitation`. *Rol mínimo: moderador (o financiero).*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `space` | id o enlace | Sí | |
| `q` | texto | Sí | De 3 a 100 caracteres |

## `mark_visitor_arrived`

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

**Marcar la llegada.** Crea la visita en la Presencia vinculada (método recepción, con el nombre del registro) o vincula la que el equipo ya había registrado. Se avisa al anfitrión por correo cuando la Presencia está ajustada para ello; `hostNotified` dice si el aviso fue a la cola, y el asistente se lo cuenta a la persona. Es idempotente: la segunda llamada devuelve `alreadyArrived: true`. Solo en el día del registro (otro día: `409`); fuera de la ventana de horario vale; cancelado: `409`. *Rol mínimo: moderador (o financiero).*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `invitation_id` | id | Sí | De `list_visitors_today` |

**Devuelve:** `invitation`, `visit`, `hostNotified` y `alreadyArrived`.

**Pídelo así:** *"María Souza ha llegado."*

## `undo_visitor_arrival`

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

**Deshacer una llegada marcada por error.** El mismo día y antes de la salida del invitado. La visita sale de las listas y del aforo (queda en el registro de la Presencia) y el registro vuelve a **Esperado**. Sin llegada, otro día o ya salió: `409`. *Rol mínimo: moderador (o financiero).*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `invitation_id` | id | Sí | |

## Relacionados

- [Visitantes](/espacos/visitantes)
- [Herramientas: Presencia](/mcp/ferramentas-presenca)
- [Herramientas](/mcp/ferramentas)
- [Dinero y confirmación](/mcp/dinheiro-e-confirmacao)
- [Recetas](/mcp/receitas)