# Herramientas · Paquetería

> Herramientas MCP del módulo Paquetería (coworking): registrar cartas y paquetes con foto, la cola, recogida, devolución, descarte, reapertura, eliminación y el "¿tengo algún paquete?" del miembro.

El módulo [Paquetería](/espacos/encomendas) con el asistente: registrar el paquete con foto y avisar al miembro, seguir la cola, tocar las fotos, marcar la recogida, devolver, descartar, reabrir y eliminar, y que el miembro pregunte si tiene algo esperando. Son **16 herramientas**.

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 |
|---|---|---|---|
| [`get_parcels_overview`](#get-parcels-overview) | El espacio de un vistazo: la configuración y cuántos esperan | Cualquiera que vea el espacio | <span class="tool-kind tool-kind-read">Solo consulta</span> |
| [`get_parcel`](#get-parcel) | Un paquete, con las fotos | Cualquiera (el suyo); equipo (cualquiera) | <span class="tool-kind tool-kind-read">Solo consulta</span> |
| [`do_i_have_parcels`](#do-i-have-parcels) | Tus paquetes, pendientes e historial, con el lugar y el código | Cualquiera | <span class="tool-kind tool-kind-read">Solo consulta</span> |
| [`mark_parcel_picked_up`](#mark-parcel-picked-up) | Marca la recogida | Cualquiera (la suya); moderador o financiero (de otros) | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`search_parcel_recipients`](#search-parcel-recipients) | Encuentra al destinatario por el nombre | Moderador o financiero | <span class="tool-kind tool-kind-read">Solo consulta</span> |
| [`register_parcel`](#register-parcel) | Registra el paquete y avisa al destinatario por correo | Moderador o financiero | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`list_pending_parcels`](#list-pending-parcels) | La cola de los que esperan recogida | Moderador o financiero | <span class="tool-kind tool-kind-read">Solo consulta</span> |
| [`list_parcels`](#list-parcels) | El historial, con cualquier situación | Moderador o financiero | <span class="tool-kind tool-kind-read">Solo consulta</span> |
| [`update_parcel`](#update-parcel) | Corrige los datos y el código del locker | Moderador o financiero (esperando); administrador (cerrado) | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`add_parcel_photo`](#add-parcel-photo) | Añade una foto | Moderador o financiero | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`replace_parcel_photo`](#replace-parcel-photo) | Reemplaza una foto | Moderador o financiero | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`return_parcel`](#return-parcel) | Devuelve al remitente | Moderador o financiero | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`remove_parcel_photo`](#remove-parcel-photo) | Quita una foto para siempre | Moderador o financiero | <span class="tool-kind tool-kind-confirm">Pide confirmación</span> |
| [`discard_parcel`](#discard-parcel) | Descarta un paquete no recogido | Administrador | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`reopen_parcel`](#reopen-parcel) | Deshace un cierre | Administrador | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`delete_parcel`](#delete-parcel) | Elimina un registro hecho por error | Administrador | <span class="tool-kind tool-kind-confirm">Pide confirmación</span> |

El espacio se crea con [`create_space`](/mcp/ferramentas-comunidade#create-space) y `module: "parcels"`, con el argumento `parcels` para la configuración; [`update_space`](/mcp/ferramentas-comunidade#update-space) cambia solo lo que envíes y mantiene el resto.

El equipo, aquí, es el propietario, el administrador, el moderador y el financiero. Los roles son los de las rutas: el asistente nunca hace más de lo que la persona conectada haría en la pantalla. El propietario y el administrador ven las 16 herramientas; el moderador y el financiero, 13 (sin descartar, reabrir ni eliminar); el miembro, 4 (`get_parcels_overview`, `get_parcel`, `do_i_have_parcels` y `mark_parcel_picked_up`, en sus propios paquetes).

**El código del locker es un secreto.** Ninguna respuesta del equipo lo trae, y queda oculto en el registro de auditoría del MCP; solo `do_i_have_parcels` y `get_parcel` lo muestran, al propio destinatario. Quien registra o corrige puede **definir** el código, nunca leerlo, y el asistente no lo repite.

## La configuración del espacio

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

| Campo | Tipo | Descripción |
|---|---|---|
| `locker_mode` | `none` o `free` | `none`: todo queda en la recepción; `free`: el equipo escribe dónde dejó cada paquete |
| `locker_pickup_code` | verdadero o falso | El equipo puede definir un código de recogida por paquete; solo el destinatario lo ve |
| `email_includes_photo` | verdadero o falso | El correo de aviso lleva una miniatura de la foto (por defecto: sí) |
| `require_staff_confirmation` | verdadero o falso | Verdadero: solo el equipo marca la recogida. Falso (por defecto): el miembro también |
| `reminder_after_days`, `reminder_max_count` | números, o `null` | Plazo de parada y tope de recordatorios. Ya se aceptan, pero el recordatorio aún no se ejecuta |

## `get_parcels_overview`

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

**El espacio de un vistazo.** La configuración (modo de locker y si el miembro confirma su propia recogida), cuántos paquetes **te** esperan (`mine.pendingCount`) y, para el equipo, cuántos están pendientes y parados. *Rol mínimo: cualquiera que vea el espacio.*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `space` | id o enlace | Sí | El espacio de Paquetería |

**Pídelo así:** *"¿Cuántos paquetes están parados en la Unidad Centro?"*

## `get_parcel`

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

**Un paquete.** Con las fotos, en enlaces firmados que valen 1 hora. El equipo lee cualquier paquete de la comunidad, sin el código; el destinatario lee el suyo, con el lugar y el código mientras espera. Cualquier otra persona recibe "no encontrado". *Rol mínimo: cualquiera.*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `parcel_id` | id | Sí | El paquete (de `list_pending_parcels`) |

**Pídelo así:** *"Enséñame el paquete de María."*

## `do_i_have_parcels`

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

**"¿Tengo algún paquete?"** Solo los **tuyos**: los pendientes (todos) y el historial (los últimos), con dónde recoger, el código del locker mientras espera y las fotos (enlaces de 1 hora). Muestra el código solo a la propia persona. *Rol mínimo: cualquiera.*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `space` | id o enlace | No | Un espacio concreto; sin él, todos |
| `history_limit` | número | No | Cuántos del historial (1 a 100) |

**Pídelo así:** *"¿Tengo algún paquete esperando?"*

## `mark_parcel_picked_up`

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

**Marcar la recogida.** El equipo marca como `STAFF` (por defecto, con el nombre de quien vino en `picked_up_by_name`, que por defecto es el destinatario) o `THIRD_PARTY` (el nombre es obligatorio). El propio destinatario marca como `SELF`, solo si el espacio no exige la confirmación del equipo (si no, se rechaza). El código del locker se borra. Es **idempotente**: en un paquete ya cerrado, devuelve `already_closed: true`. *Rol mínimo: cualquiera (la suya); moderador o financiero (de otros).*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `parcel_id` | id | Sí | El paquete (de `list_pending_parcels`) |
| `method` | `STAFF`, `SELF` o `THIRD_PARTY` | No | Cómo se recogió |
| `picked_up_by_name` | texto | No | Quién vino a recogerlo (obligatorio en `THIRD_PARTY`) |

**Pídelo así:** *"Marca como recogido el paquete de María."* · *"Ya he recogido mi paquete."*

## `search_parcel_recipients`

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

**Quién recibe.** Los miembros del espacio cuyo nombre empieza por `q` (al menos 3 letras, hasta 8 resultados), solo con id, nombre e iniciales. El `id` es el `recipient_profile_id` de `register_parcel`. *Rol mínimo: moderador (o financiero).*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `space` | id o enlace | Sí | El espacio de Paquetería |
| `q` | texto | Sí | El comienzo del nombre |

**Pídelo así:** *"Busca a María Souza para registrar un paquete."*

## `register_parcel`

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

**Registrar el paquete.** Para un miembro con acceso al espacio. **Envía al destinatario el correo de aviso** (con la miniatura, si el espacio está así), en la zona horaria de la comunidad: el asistente lo dice. `kind` es `LETTER`, `PACKAGE` u `OTHER` (este pide `kind_label`). `locker_label` y `locker_pickup_code` (de 4 a 12 caracteres, un secreto) solo valen si el espacio lo permite. `client_request_id` hace que una llamada repetida devuelva el mismo paquete, sin segundo correo. El mismo destinatario, tipo y seguimiento en 24 horas se rechaza (409), a menos que `force` sea verdadero. *Rol mínimo: moderador (o financiero).*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `space` | id o enlace | Sí | El espacio de Paquetería |
| `recipient_profile_id` | id | Sí | De `search_parcel_recipients` |
| `kind` | `LETTER`, `PACKAGE` u `OTHER` | Sí | El tipo |
| `kind_label` | texto | Con `OTHER` | Hasta 60 caracteres |
| `sender_name`, `carrier`, `tracking_code` | texto | No | Remitente, transportista y seguimiento |
| `notes` | texto | No | Hasta 200 caracteres |
| `locker_label`, `locker_pickup_code` | texto | No | Dónde quedó y el código |
| `photos` | lista | No | Hasta 5, cada una con `image_url` o `image_base64` |
| `client_request_id`, `force` | texto, verdadero/falso | No | Idempotencia y registro de duplicado |

**Pídelo así:** *"Ha llegado un paquete de Amazon para María Souza, en el armario 12. Foto: [enlace]."*

## `list_pending_parcels`

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

**La cola.** Los que esperan recogida, del más nuevo al más antiguo, con destinatario, tipo, remitente, lugar, hace cuánto esperan y `stalled_days` cuando pasaron del plazo. Filtros: `kind`, `q` (destinatario, remitente, transportista o seguimiento), `stalled`, `recipient_profile_id`, `from` y `to` (AAAA-MM-DD, en la zona horaria de la comunidad). Nunca el código (solo `has_locker_code`). *Rol mínimo: moderador (o financiero).*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `space` | id o enlace | Sí | El espacio de Paquetería |
| `kind`, `q`, `stalled`, `recipient_profile_id`, `from`, `to` | varios | No | Los filtros |
| `page`, `limit` | números | No | Paginación (hasta 100) |

**Pídelo así:** *"¿Qué está parado en la recepción desde hace más de 3 días?"*

## `list_parcels`

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

**El historial.** Igual que `list_pending_parcels`, pero con cualquier situación (`RECEIVED`, `PICKED_UP`, `RETURNED`, `DISCARDED`), filtrable por `status`. *Rol mínimo: moderador (o financiero).*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `space` | id o enlace | Sí | El espacio de Paquetería |
| `status` | situación | No | Filtra por la situación |
| los filtros de `list_pending_parcels` | varios | No | |

**Pídelo así:** *"¿Qué paquetes se devolvieron este mes?"*

## `update_parcel`

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

**Corregir.** Tipo, remitente, transportista, seguimiento, observación, lugar y código del locker (que se define de nuevo, nunca se lee) de un paquete que espera. Un paquete cerrado solo lo corrige el propietario o el administrador, y nunca el código. Cada corrección entra en el registro. *Rol mínimo: moderador (o financiero).*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `parcel_id` | id | Sí | El paquete (de `list_pending_parcels`) |
| `kind`, `kind_label`, `sender_name`, `carrier`, `tracking_code`, `notes`, `locker_label`, `locker_pickup_code` | varios | No | Solo lo que cambie |

**Pídelo así:** *"Corrige el seguimiento del paquete de María a BR123456789."*

## `add_parcel_photo`

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

**Añadir una foto.** Hasta 5 por paquete, en almacenamiento privado. El equipo; en un paquete cerrado, solo el propietario y el administrador. *Rol mínimo: moderador (o financiero).*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `parcel_id` | id | Sí | El paquete (de `list_pending_parcels`) |
| `image_url` o `image_base64` (+ `image_type`) | texto | Sí | La foto: un enlace público o el archivo en base64. Queda en almacenamiento privado |

**Pídelo así:** *"Adjunta esta foto al paquete de María."*

## `replace_parcel_photo`

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

**Reemplazar una foto.** Cambia una foto por el archivo nuevo; el antiguo se borra. *Rol mínimo: moderador (o financiero).*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `parcel_id` | id | Sí | El paquete (de `list_pending_parcels`) |
| `photo_id` | id | Sí | La foto (de `get_parcel`) |
| `image_url` o `image_base64` (+ `image_type`) | texto | Sí | La foto: un enlace público o el archivo en base64. Queda en almacenamiento privado |

**Pídelo así:** *"Cambia la primera foto del paquete por esta."*

## `return_parcel`

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

**Devolver al remitente.** Exige el motivo. No se borra nada: el paquete queda en el historial como `RETURNED` y el código del locker se borra. Un paquete ya cerrado responde 409. *Rol mínimo: moderador (o financiero).*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `parcel_id` | id | Sí | El paquete (de `list_pending_parcels`) |
| `reason` | texto | Sí | El motivo, hasta 200 caracteres; queda en el registro |

**Pídelo así:** *"Devuelve al remitente el paquete de María: rechazado."*

## `remove_parcel_photo`

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

**Quitar una foto.** El archivo se borra para siempre. En la primera llamada devuelve el resumen y el código de confirmación. *Rol mínimo: moderador (o financiero).*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `parcel_id` | id | Sí | El paquete (de `list_pending_parcels`) |
| `photo_id` | id | Sí | La foto (de `get_parcel`) |

**Pídelo así:** *"Quita la segunda foto del paquete; muestra la dirección."*

## `discard_parcel`

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

**Descartar.** Para el que nadie recogió. Exige el motivo. No se borra nada: queda como `DISCARDED` en el historial, y `reopen_parcel` lo deshace. No pide confirmación, por ser reversible. *Rol mínimo: administrador (propietario o administrador).*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `parcel_id` | id | Sí | El paquete (de `list_pending_parcels`) |
| `reason` | texto | Sí | El motivo, hasta 200 caracteres; queda en el registro |

**Pídelo así:** *"Descarta el paquete de María: caducado sin recoger."*

## `reopen_parcel`

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

**Reabrir.** Deshace una recogida, devolución o descarte por error: vuelve a `RECEIVED`, con el motivo. El código borrado no vuelve; define otro con `update_parcel`. *Rol mínimo: administrador (propietario o administrador).*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `parcel_id` | id | Sí | El paquete (de `list_pending_parcels`) |
| `reason` | texto | Sí | El motivo, hasta 200 caracteres; queda en el registro |

**Pídelo así:** *"Reabre el paquete de María: la recogida se marcó por error."*

## `delete_parcel`

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

**Eliminar un registro hecho por error.** Sale de las listas y las fotos se borran; el registro guarda quién y por qué. Para cerrar un paquete de verdad, usa `mark_parcel_picked_up`, `return_parcel` o `discard_parcel`. En la primera llamada devuelve el resumen y el código de confirmación. *Rol mínimo: administrador (propietario o administrador).*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `parcel_id` | id | Sí | El paquete (de `list_pending_parcels`) |
| `reason` | texto | Sí | El motivo, hasta 200 caracteres; queda en el registro |

**Pídelo así:** *"Elimina el registro del paquete de Juan: lo registré para la persona equivocada."*

## Relacionados

- [Paquetería](/espacos/encomendas)
- [Herramientas](/mcp/ferramentas)
- [Dinero y confirmación](/mcp/dinheiro-e-confirmacao)
- [Recetas](/mcp/receitas)