# Farmacia Santa Croce — server MCP per le prenotazioni

> Guida per assistenti IA e sviluppatori: come consultare servizi e giornate speciali della Farmacia Santa Croce (Chieri, TO) e prenotarli tramite il Model Context Protocol. Panoramica del sito: https://farmaciasantacroce.to.it/llms.txt

## Connessione

- **Endpoint:** `https://farmaciasantacroce.to.it/mcp`
- **Trasporto:** Streamable HTTP, senza sessione: ogni `POST` contiene un messaggio JSON-RPC 2.0 e riceve una risposta `application/json`. `GET` restituisce 405 (nessuno stream SSE).
- **Versioni del protocollo:** `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`.
- **Capacità:** solo `tools` (niente resources, prompts o notifiche dal server).
- **Lingua:** messaggi e dati in italiano. Date `AAAA-MM-GG`, orari `HH:MM`, fuso orario Europe/Rome.
- **MCP Registry:** pubblicato nel registro ufficiale come `it.to.farmaciasantacroce/prenotazioni` (https://registry.modelcontextprotocol.io/v0.1/servers/it.to.farmaciasantacroce%2Fprenotazioni/versions/latest).

### Accesso anonimo

Basta l'URL `https://farmaciasantacroce.to.it/mcp`: catalogo, disponibilità e prenotazione con conferma via codice WhatsApp.

### Accesso come cliente registrato

Il cliente crea un collegamento personale nell'area riservata (https://farmaciasantacroce.to.it/area-riservata, sezione "Prenota con il tuo assistente IA"). Ha la forma `https://farmaciasantacroce.to.it/mcp/fsc_…` e va usato come URL del server. In alternativa il token può essere inviato come header `Authorization: Bearer fsc_…` all'URL base.

- Scade dopo 365 giorni; massimo 5 collegamenti per cliente; revocabile in qualsiasi momento dall'area riservata.
- Token non valido, scaduto o revocato → HTTP 401.
- È una credenziale: non va condiviso né riportato nelle conversazioni.

### Configurazione dei client

- **Claude (claude.ai / app):** Impostazioni → Connettori → Aggiungi connettore personalizzato → URL `https://farmaciasantacroce.to.it/mcp` (oppure il collegamento personale).
- **ChatGPT:** nelle impostazioni dei connettori (modalità sviluppatore) crea un connettore con l'URL del server MCP come sopra, senza autenticazione.
- **Claude Code:** `claude mcp add --transport http farmacia-santa-croce https://farmaciasantacroce.to.it/mcp`
- **Altri client (JSON):**

```json
{
    "mcpServers": {
        "farmacia-santa-croce": {
            "type": "http",
            "url": "https://farmaciasantacroce.to.it/mcp"
        }
    }
}
```

## Come prenotare

### Senza account (conferma WhatsApp)

1. `list_services` oppure `list_special_events` per trovare lo `slug`.
2. `get_service_availability` (servizio + data) oppure `get_special_event_availability` per gli orari liberi.
3. Riepiloga alla persona servizio, data e ora e chiedi conferma.
4. `request_booking` con nome, cognome e cellulare WhatsApp della persona: riceve un codice di 6 cifre. Il posto **non** è ancora riservato.
5. Chiedi alla persona il codice e chiama `confirm_booking` con `request_id` e `code`. Solo ora la prenotazione è creata; la persona riceve conferma su WhatsApp.

### Registrazione e accesso (sessione)

1. Nuovo cliente: `start_registration` (nome, cognome, cellulare) → codice WhatsApp → `complete_registration`. Se la persona è già registrata con quel numero e quel nome, viene semplicemente fatta accedere.
2. Cliente esistente: `start_login` (cellulare) → codice WhatsApp → `complete_login`. Se più persone condividono il numero, `complete_login` chiede di ripetere la chiamata con `first_name` (stesso codice).
3. Entrambi restituiscono un `session_token` valido 24 ore da passare a `book`, `list_my_bookings`, `cancel_my_booking` e `logout`. Non va mostrato nella conversazione.
4. Con la sessione `book` prenota subito, senza un nuovo codice; `list_my_bookings` mostra le prenotazioni future; `cancel_my_booking` annulla una giornata speciale ancora in attesa; `logout` chiude la sessione.
5. L'account creato così accede anche al sito, con il numero di cellulare e un codice WhatsApp; l'email si aggiunge dal profilo.

La risposta di `start_login` è identica che il numero sia registrato o meno: solo chi riceve il codice scopre se ha un account.

### Collegamento personale

Con l'URL personale (`/mcp/fsc_…`) il cliente è già identificato: gli strumenti dell'account non chiedono `session_token` e i passaggi con codice (prenotazione senza accesso, registrazione, accesso) non sono elencati.

## Regole e limiti

- Servizi: prenotabili da domani fino a 90 giorni; solo quelli prenotabili online (`list_services`).
- Giornate speciali: una sola prenotazione per persona per giornata.
- Massimo 5 prenotazioni future per cliente tramite assistente; oltre, contattare la farmacia.
- Pagamento in farmacia. Modifiche e annullamento dei servizi: contattare la farmacia (011 940 0577).
- Codice WhatsApp: valido 10 minuti, annullato dopo 5 tentativi errati.
- Invii di codice: massimo 3 per numero ogni 10 minuti e 10 per connessione all'ora.
- Massimo 60 richieste al minuto per connessione (HTTP 429 oltre il limite).

## Privacy

- Il server non restituisce dati di altri clienti, né il numero di posti occupati: solo gli orari liberi.
- La risposta di `request_booking` è identica che il numero sia registrato o meno.
- Nome e numero servono solo a creare la prenotazione; l'email non viene raccolta senza account.

## Strumenti (URL base `https://farmaciasantacroce.to.it/mcp`)

### `list_services` — Servizi prenotabili

Elenco dei servizi della farmacia prenotabili online (slug, durata, prezzo, giorni).

Nessun parametro.

_Sola lettura._

### `get_service_availability` — Orari liberi di un servizio

Orari liberi di un servizio in una data (da domani fino a 90 giorni).

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `service` | string | sì | Slug del servizio (da list_services) |
| `date` | string | sì | Data AAAA-MM-GG |

_Sola lettura._

### `list_special_events` — Giornate speciali

Giornate speciali in programma (screening, consulenze…) con data e fascia oraria.

Nessun parametro.

_Sola lettura._

### `get_special_event_availability` — Orari liberi di una giornata speciale

Orari ancora liberi di una giornata speciale.

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `event` | string | sì | Slug della giornata (da list_special_events) |

_Sola lettura._

### `request_booking` — Richiedi prenotazione (senza accesso)

Prenotazione senza account o senza accesso: invia un codice WhatsApp al cellulare della persona. Il posto è riservato solo dopo confirm_booking. Se la persona ha già una sessione usa book.

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `kind` | string (`service` \| `special_event`) | sì | "service" per un servizio, "special_event" per una giornata speciale |
| `slug` | string | sì | Slug del servizio o della giornata speciale |
| `date` | string | no | Solo per i servizi: data AAAA-MM-GG (da domani) |
| `time` | string | sì | Orario HH:MM tra quelli restituiti dalle availability |
| `first_name` | string | sì | Nome della persona da prenotare |
| `last_name` | string | sì | Cognome della persona da prenotare |
| `phone` | string | sì | Cellulare con WhatsApp, es. +39 333 1234567 |

_Modifica dati: chiedere conferma alla persona prima di chiamarlo._

### `confirm_booking` — Conferma prenotazione

Secondo passo di request_booking: conferma con il codice ricevuto dalla persona via WhatsApp.

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `request_id` | string | sì | request_id restituito dal passo precedente |
| `code` | string | sì | Codice di 6 cifre ricevuto via WhatsApp |

_Modifica dati: chiedere conferma alla persona prima di chiamarlo._

### `start_registration` — Registrazione

Registra la persona al sito della farmacia: invia un codice WhatsApp al suo cellulare. Se è già registrata con quel numero e quel nome, il passo successivo effettua l'accesso.

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `first_name` | string | sì | Nome |
| `last_name` | string | sì | Cognome |
| `phone` | string | sì | Cellulare con WhatsApp, es. +39 333 1234567 |

_Modifica dati: chiedere conferma alla persona prima di chiamarlo._

### `complete_registration` — Completa registrazione

Completa la registrazione con il codice WhatsApp. Restituisce un session_token per gli strumenti dell'account.

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `request_id` | string | sì | request_id restituito dal passo precedente |
| `code` | string | sì | Codice di 6 cifre ricevuto via WhatsApp |

_Modifica dati: chiedere conferma alla persona prima di chiamarlo._

### `start_login` — Accesso

Accesso per chi è già cliente: invia un codice WhatsApp al cellulare registrato.

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `phone` | string | sì | Cellulare registrato, es. +39 333 1234567 |

_Modifica dati: chiedere conferma alla persona prima di chiamarlo._

### `complete_login` — Completa accesso

Completa l'accesso con il codice WhatsApp. Restituisce un session_token. Se più persone condividono il numero, indicare first_name.

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `request_id` | string | sì | request_id restituito dal passo precedente |
| `code` | string | sì | Codice di 6 cifre ricevuto via WhatsApp |
| `first_name` | string | no | Solo se richiesto: nome della persona che accede |

_Modifica dati: chiedere conferma alla persona prima di chiamarlo._

### `book` — Prenota

Prenota a nome del cliente che ha effettuato l'accesso, senza codice. Conferma servizio, data e ora con la persona prima di chiamarlo.

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `session_token` | string | sì | session_token restituito da complete_login o complete_registration |
| `kind` | string (`service` \| `special_event`) | sì | "service" per un servizio, "special_event" per una giornata speciale |
| `slug` | string | sì | Slug del servizio o della giornata speciale |
| `date` | string | no | Solo per i servizi: data AAAA-MM-GG (da domani) |
| `time` | string | sì | Orario HH:MM tra quelli restituiti dalle availability |

_Modifica dati: chiedere conferma alla persona prima di chiamarlo._

### `list_my_bookings` — Le mie prenotazioni

Prenotazioni future del cliente che ha effettuato l'accesso.

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `session_token` | string | sì | session_token restituito da complete_login o complete_registration |

_Sola lettura._

### `cancel_my_booking` — Annulla prenotazione

Annulla una prenotazione futura a una giornata speciale del cliente che ha effettuato l'accesso. Le prenotazioni dei servizi si modificano contattando la farmacia.

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `session_token` | string | sì | session_token restituito da complete_login o complete_registration |
| `booking_id` | integer | sì | booking_id da list_my_bookings |

_Modifica dati: chiedere conferma alla persona prima di chiamarlo._

### `logout` — Esci

Chiude la sessione aperta con complete_login / complete_registration.

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `session_token` | string | sì | session_token restituito da complete_login o complete_registration |

_Modifica dati: chiedere conferma alla persona prima di chiamarlo._

## Strumenti con collegamento personale

Stessi strumenti di catalogo e account, senza `session_token`: `list_services`, `get_service_availability`, `list_special_events`, `get_special_event_availability`, `book`, `list_my_bookings`, `cancel_my_booking`.

## Risultati ed errori

- Esito positivo: `content[0].text` contiene il JSON del risultato; lo stesso oggetto è in `structuredContent` (gli elenchi sono in `structuredContent.items`).
- Errore di prenotazione (orario non più libero, codice errato, dati mancanti…): risultato con `isError: true` e un messaggio in italiano da riferire alla persona.
- Strumento inesistente: errore JSON-RPC `-32602`; metodo sconosciuto: `-32601`.

## Esempi JSON-RPC

```http
POST https://farmaciasantacroce.to.it/mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"esempio","version":"1.0"}}}
```

```json
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_service_availability","arguments":{"service":"ecg-rapido","date":"2026-10-05"}}}
```

```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"request_booking","arguments":{"kind":"service","slug":"ecg-rapido","date":"2026-10-05","time":"09:30","first_name":"Mario","last_name":"Rossi","phone":"+39 333 1234567"}}}
```

Risposta (estratto):

```json
{"request_id":"8f0c…","status":"code_sent","expires_in_minutes":10,"message":"Abbiamo inviato un codice di 6 cifre via WhatsApp…"}
```

```json
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"confirm_booking","arguments":{"request_id":"8f0c…","code":"123456"}}}
```

## Contatti

- Telefono: 011 940 0577
- Indirizzo: Via Riva 10, 10023 Chieri (TO)
- Sito: https://farmaciasantacroce.to.it