# Strumenti · Pacchi

> Gli strumenti MCP del modulo Pacchi (coworking): registrare lettere e pacchi con foto, la coda, ritiro, restituzione, scarto, riapertura, eliminazione e il "ho un pacco?" del membro.

Il modulo [Pacchi](/espacos/encomendas) tramite l'assistente: registrare il pacco con foto e avvisare il membro, seguire la coda, gestire le foto, segnare il ritiro, restituire, scartare, riaprire ed eliminare, e il membro che chiede se c'è qualcosa ad aspettarlo. Sono **16 strumenti**.

Ogni strumento ha un'etichetta: <span class="tool-kind tool-kind-read">Solo lettura</span> non cambia nulla, <span class="tool-kind tool-kind-write">Modifica</span> crea o cambia qualcosa subito, e <span class="tool-kind tool-kind-confirm">Chiede conferma</span> agisce solo dopo il tuo sì a un riepilogo. Vedi [Denaro e conferma](/mcp/dinheiro-e-confirmacao).

## In sintesi

| Strumento | Cosa fa | Ruolo minimo | Tipo |
|---|---|---|---|
| [`get_parcels_overview`](#get-parcels-overview) | Lo spazio a colpo d'occhio: la configurazione e quanti sono in attesa | Chiunque veda lo spazio | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`get_parcel`](#get-parcel) | Un pacco, con le foto | Qualsiasi (il tuo); team (qualsiasi) | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`do_i_have_parcels`](#do-i-have-parcels) | I tuoi pacchi, in attesa e storico, con il posto e il codice | Qualsiasi | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`mark_parcel_picked_up`](#mark-parcel-picked-up) | Segna il ritiro | Qualsiasi (il tuo); moderatore o finanza (di altri) | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`search_parcel_recipients`](#search-parcel-recipients) | Trova il destinatario per nome | Moderatore o finanza | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`register_parcel`](#register-parcel) | Registra il pacco e avvisa il destinatario via e-mail | Moderatore o finanza | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`list_pending_parcels`](#list-pending-parcels) | La coda di quelli in attesa di ritiro | Moderatore o finanza | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`list_parcels`](#list-parcels) | Lo storico, con qualsiasi stato | Moderatore o finanza | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`update_parcel`](#update-parcel) | Corregge i dati e il codice dell'armadietto | Moderatore o finanza (in attesa); amministratore (chiuso) | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`add_parcel_photo`](#add-parcel-photo) | Aggiunge una foto | Moderatore o finanza | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`replace_parcel_photo`](#replace-parcel-photo) | Sostituisce una foto | Moderatore o finanza | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`return_parcel`](#return-parcel) | Restituisce al mittente | Moderatore o finanza | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`remove_parcel_photo`](#remove-parcel-photo) | Rimuove una foto definitivamente | Moderatore o finanza | <span class="tool-kind tool-kind-confirm">Chiede conferma</span> |
| [`discard_parcel`](#discard-parcel) | Scarta un pacco non ritirato | Amministratore | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`reopen_parcel`](#reopen-parcel) | Annulla una chiusura | Amministratore | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`delete_parcel`](#delete-parcel) | Elimina un registro fatto per errore | Amministratore | <span class="tool-kind tool-kind-confirm">Chiede conferma</span> |

Lo spazio si crea con [`create_space`](/mcp/ferramentas-comunidade#create-space) e `module: "parcels"`, con l'argomento `parcels` per la configurazione; [`update_space`](/mcp/ferramentas-comunidade#update-space) cambia solo ciò che invii e mantiene il resto.

Il team, qui, è il proprietario, l'amministratore, il moderatore e la finanza. I ruoli sono quelli delle rotte: l'assistente non fa mai più di quanto la persona connessa farebbe nella schermata. Il proprietario e l'amministratore vedono tutti e 16 gli strumenti; il moderatore e la finanza, 13 (senza scartare, riaprire ed eliminare); il membro, 4 (`get_parcels_overview`, `get_parcel`, `do_i_have_parcels` e `mark_parcel_picked_up`, sui propri pacchi).

**Il codice dell'armadietto è un segreto.** Nessuna risposta del team lo riporta, e resta nascosto nel registro di audit dell'MCP; solo `do_i_have_parcels` e `get_parcel` lo mostrano, al destinatario stesso. Chi registra o corregge può **impostare** il codice, mai leggerlo, e l'assistente non lo ripete.

## La configurazione dello spazio

L'argomento `parcels` di `create_space` e `update_space` accetta:

| Campo | Tipo | Descrizione |
|---|---|---|
| `locker_mode` | `none` o `free` | `none`: tutto resta alla reception; `free`: il team scrive dove ha lasciato ogni pacco |
| `locker_pickup_code` | vero o falso | Il team può impostare un codice di ritiro per ogni pacco; lo vede solo il destinatario |
| `email_includes_photo` | vero o falso | L'e-mail di avviso contiene una miniatura della foto (predefinito: sì) |
| `require_staff_confirmation` | vero o falso | Vero: solo il team segna il ritiro. Falso (predefinito): anche il membro |
| `reminder_after_days`, `reminder_max_count` | numeri, o `null` | Termine di fermo e tetto di promemoria. Sono già accettati, ma il promemoria non è ancora attivo |

## `get_parcels_overview`

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

**Lo spazio a colpo d'occhio.** La configurazione (modalità armadietto e se il membro conferma il proprio ritiro), quanti pacchi aspettano **te** (`mine.pendingCount`) e, per il team, quanti sono in attesa e fermi. *Ruolo minimo: chiunque veda lo spazio.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | Lo spazio Pacchi |

**Chiedi così:** *"Quanti pacchi sono fermi nella Sede Centro?"*

## `get_parcel`

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

**Un pacco.** Con le foto, in link firmati che valgono 1 ora. Il team legge qualsiasi pacco della community, senza il codice; il destinatario legge il suo, con il posto e il codice finché è in attesa. Chiunque altro riceve "non trovato". *Ruolo minimo: qualsiasi.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `parcel_id` | id | Sì | Il pacco (da `list_pending_parcels`) |

**Chiedi così:** *"Mostrami il pacco di Maria."*

## `do_i_have_parcels`

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

**"Ho un pacco?"** Solo i **tuoi**: quelli in attesa (tutti) e lo storico (gli ultimi), con dove ritirarli, il codice dell'armadietto finché è in attesa e le foto (link di 1 ora). Mostra il codice solo alla persona stessa. *Ruolo minimo: qualsiasi.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | No | Uno spazio specifico; senza, tutti |
| `history_limit` | numero | No | Quanti dello storico (da 1 a 100) |

**Chiedi così:** *"Ho qualche pacco in attesa?"*

## `mark_parcel_picked_up`

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

**Segnare il ritiro.** Il team segna come `STAFF` (predefinito, con il nome di chi è venuto in `picked_up_by_name`, che per impostazione predefinita è il destinatario) o `THIRD_PARTY` (il nome è obbligatorio). Il destinatario stesso segna come `SELF`, solo se lo spazio non richiede la conferma del team (altrimenti viene rifiutato). Il codice dell'armadietto viene cancellato. È **idempotente**: su un pacco già chiuso, restituisce `already_closed: true`. *Ruolo minimo: qualsiasi (il tuo); moderatore o finanza (di altri).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `parcel_id` | id | Sì | Il pacco (da `list_pending_parcels`) |
| `method` | `STAFF`, `SELF` o `THIRD_PARTY` | No | Come è stato ritirato |
| `picked_up_by_name` | testo | No | Chi è venuto a prenderlo (obbligatorio con `THIRD_PARTY`) |

**Chiedi così:** *"Segna come ritirato il pacco di Maria."* · *"Ho già preso il mio pacco."*

## `search_parcel_recipients`

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

**Chi riceve.** I membri dello spazio il cui nome inizia con `q` (almeno 3 lettere, fino a 8 risultati), solo con id, nome e iniziali. L'`id` è il `recipient_profile_id` di `register_parcel`. *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | Lo spazio Pacchi |
| `q` | testo | Sì | L'inizio del nome |

**Chiedi così:** *"Cerca Maria Rossi per registrare un pacco."*

## `register_parcel`

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

**Registrare il pacco.** Per un membro con accesso allo spazio. **Invia al destinatario l'e-mail di avviso** (con la miniatura, se lo spazio è impostato così), nel fuso della community: l'assistente lo dice. `kind` è `LETTER`, `PACKAGE` o `OTHER` (quest'ultimo richiede `kind_label`). `locker_label` e `locker_pickup_code` (da 4 a 12 caratteri, un segreto) valgono solo se lo spazio lo permette. `client_request_id` fa sì che una chiamata ripetuta restituisca lo stesso pacco, senza una seconda e-mail. Stesso destinatario, tipo e tracking entro 24 ore viene rifiutato (409), a meno che `force` sia vero. *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | Lo spazio Pacchi |
| `recipient_profile_id` | id | Sì | Da `search_parcel_recipients` |
| `kind` | `LETTER`, `PACKAGE` o `OTHER` | Sì | Il tipo |
| `kind_label` | testo | Con `OTHER` | Fino a 60 caratteri |
| `sender_name`, `carrier`, `tracking_code` | testo | No | Mittente, corriere e tracking |
| `notes` | testo | No | Fino a 200 caratteri |
| `locker_label`, `locker_pickup_code` | testo | No | Dove è stato lasciato e il codice |
| `photos` | elenco | No | Fino a 5, ciascuna con `image_url` o `image_base64` |
| `client_request_id`, `force` | testo, vero/falso | No | Idempotenza e registrazione di un duplicato |

**Chiedi così:** *"È arrivato un pacco di Amazon per Maria Rossi, nell'armadietto 12. Foto: [link]."*

## `list_pending_parcels`

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

**La coda.** Quelli in attesa di ritiro, dal più recente al più vecchio, con destinatario, tipo, mittente, posto, da quanto tempo aspettano e `stalled_days` quando hanno superato il termine. Filtri: `kind`, `q` (destinatario, mittente, corriere o tracking), `stalled`, `recipient_profile_id`, `from` e `to` (AAAA-MM-GG, nel fuso della community). Mai il codice (solo `has_locker_code`). *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | Lo spazio Pacchi |
| `kind`, `q`, `stalled`, `recipient_profile_id`, `from`, `to` | vari | No | I filtri |
| `page`, `limit` | numeri | No | Paginazione (fino a 100) |

**Chiedi così:** *"Cosa è fermo alla reception da più di 3 giorni?"*

## `list_parcels`

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

**Lo storico.** Come `list_pending_parcels`, ma con qualsiasi stato (`RECEIVED`, `PICKED_UP`, `RETURNED`, `DISCARDED`), filtrabile per `status`. *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | Lo spazio Pacchi |
| `status` | stato | No | Filtra per stato |
| i filtri di `list_pending_parcels` | vari | No | |

**Chiedi così:** *"Quali pacchi sono stati restituiti questo mese?"*

## `update_parcel`

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

**Correggere.** Tipo, mittente, corriere, tracking, nota, posto e codice dell'armadietto (che si imposta di nuovo, mai si legge) di un pacco in attesa. Un pacco chiuso lo corregge solo il proprietario o l'amministratore, e mai il codice. Ogni correzione entra nel registro. *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `parcel_id` | id | Sì | Il pacco (da `list_pending_parcels`) |
| `kind`, `kind_label`, `sender_name`, `carrier`, `tracking_code`, `notes`, `locker_label`, `locker_pickup_code` | vari | No | Solo ciò che cambia |

**Chiedi così:** *"Correggi il tracking del pacco di Maria in BR123456789."*

## `add_parcel_photo`

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

**Aggiungere una foto.** Fino a 5 per pacco, in un archivio privato. Il team; su un pacco chiuso, solo il proprietario e l'amministratore. *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `parcel_id` | id | Sì | Il pacco (da `list_pending_parcels`) |
| `image_url` o `image_base64` (+ `image_type`) | testo | Sì | La foto: un link pubblico o il file in base64. Resta in un archivio privato |

**Chiedi così:** *"Allega questa foto al pacco di Maria."*

## `replace_parcel_photo`

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

**Sostituire una foto.** Sostituisce una foto con il nuovo file; quello vecchio viene cancellato. *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `parcel_id` | id | Sì | Il pacco (da `list_pending_parcels`) |
| `photo_id` | id | Sì | La foto (da `get_parcel`) |
| `image_url` o `image_base64` (+ `image_type`) | testo | Sì | La foto: un link pubblico o il file in base64. Resta in un archivio privato |

**Chiedi così:** *"Sostituisci la prima foto del pacco con questa."*

## `return_parcel`

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

**Restituire al mittente.** Richiede il motivo. Nulla viene cancellato: il pacco resta nello storico come `RETURNED` e il codice dell'armadietto viene cancellato. Un pacco già chiuso risponde 409. *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `parcel_id` | id | Sì | Il pacco (da `list_pending_parcels`) |
| `reason` | testo | Sì | Il motivo, fino a 200 caratteri; resta nel registro |

**Chiedi così:** *"Restituisci al mittente il pacco di Maria: rifiutato."*

## `remove_parcel_photo`

<span class="tool-kind tool-kind-confirm">Chiede conferma</span>

**Rimuovere una foto.** Il file viene cancellato definitivamente. Alla prima chiamata restituisce il riepilogo e il codice di conferma. *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `parcel_id` | id | Sì | Il pacco (da `list_pending_parcels`) |
| `photo_id` | id | Sì | La foto (da `get_parcel`) |

**Chiedi così:** *"Rimuovi la seconda foto del pacco; mostra l'indirizzo."*

## `discard_parcel`

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

**Scartare.** Per quello che nessuno ha ritirato. Richiede il motivo. Nulla viene cancellato: resta come `DISCARDED` nello storico, e `reopen_parcel` lo annulla. Non chiede conferma, perché è reversibile. *Ruolo minimo: amministratore (proprietario o amministratore).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `parcel_id` | id | Sì | Il pacco (da `list_pending_parcels`) |
| `reason` | testo | Sì | Il motivo, fino a 200 caratteri; resta nel registro |

**Chiedi così:** *"Scarta il pacco di Maria: scaduto senza ritiro."*

## `reopen_parcel`

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

**Riaprire.** Annulla un ritiro, una restituzione o uno scarto fatti per errore: torna a `RECEIVED`, con il motivo. Il codice cancellato non torna; impostane un altro con `update_parcel`. *Ruolo minimo: amministratore (proprietario o amministratore).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `parcel_id` | id | Sì | Il pacco (da `list_pending_parcels`) |
| `reason` | testo | Sì | Il motivo, fino a 200 caratteri; resta nel registro |

**Chiedi così:** *"Riapri il pacco di Maria: il ritiro è stato segnato per errore."*

## `delete_parcel`

<span class="tool-kind tool-kind-confirm">Chiede conferma</span>

**Eliminare un registro fatto per errore.** Esce dagli elenchi e le foto vengono cancellate; il registro conserva chi e perché. Per chiudere davvero un pacco, usa `mark_parcel_picked_up`, `return_parcel` o `discard_parcel`. Alla prima chiamata restituisce il riepilogo e il codice di conferma. *Ruolo minimo: amministratore (proprietario o amministratore).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `parcel_id` | id | Sì | Il pacco (da `list_pending_parcels`) |
| `reason` | testo | Sì | Il motivo, fino a 200 caratteri; resta nel registro |

**Chiedi così:** *"Elimina il registro del pacco di Giovanni: l'ho registrato per la persona sbagliata."*

## Correlati

- [Pacchi](/espacos/encomendas)
- [Strumenti](/mcp/ferramentas)
- [Denaro e conferma](/mcp/dinheiro-e-confirmacao)
- [Ricette](/mcp/receitas)