# framework360-mcp-server

[![License: ISC](https://img.shields.io/github/license/VadaLinux/framework360-mcp-server)](LICENSE)
[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)
[![MCP server](https://img.shields.io/badge/MCP-server-blueviolet)](https://modelcontextprotocol.io)
[![Endpoints](https://img.shields.io/badge/endpoints-141-informational)](endpoints.json)

Server **MCP** e **CLI** per l'API REST di [Framework360](https://www.framework360.it) (CRM/CMS). Espone i 141 endpoint dell'API come tool/comandi pronti all'uso, sia dentro un client MCP (es. Claude Code) sia da riga di comando/script.

> Progetto correlato: [framework360-skill](https://github.com/VadaLinux/framework360-skill) — una skill per Claude Code che documenta come usare la CLI di questo repo direttamente in una sessione di Claude Code.

## Indice

- [Cos'è](#cosè)
- [Requisiti](#requisiti)
- [Installazione](#installazione)
- [Configurazione](#configurazione)
- [Uso come server MCP](#uso-come-server-mcp)
- [Uso come CLI](#uso-come-cli)
  - [Comandi principali](#comandi-principali)
  - [Opzioni per passare i parametri](#opzioni-per-passare-i-parametri)
  - [Esempi](#esempi)
  - [Codici di uscita](#codici-di-uscita)
- [Riferimento completo degli endpoint](#riferimento-completo-degli-endpoint)
- [Struttura del progetto](#struttura-del-progetto)
- [Test](#test)
- [Troubleshooting](#troubleshooting)
- [Sicurezza](#sicurezza)
- [Contribuire](#contribuire)
- [Licenza](#licenza)

## Cos'è

Framework360 espone un'API REST autenticata via header (`X-Fw360-Key`) per gestire clienti, utenti, ordini, chat, marketing, contenuti, report e i plugin del CMS (calendario, pipeline, ticket, membership, blog). Questo repo fornisce due modi equivalenti per usarla senza scrivere codice HTTP a mano:

- **Server MCP** (`src/index.mjs`) — implementa il [Model Context Protocol](https://modelcontextprotocol.io) su stdio. Ogni endpoint dell'API diventa un tool MCP, richiamabile da un client compatibile (es. Claude Code, Claude Desktop, o qualunque host MCP).
- **CLI** (`bin/cli.mjs`) — stesso set di endpoint, richiamabili da terminale o da script di automazione, senza bisogno di un client MCP.

Entrambi condividono:
- la stessa configurazione (`.env`) — un'unica fonte di verità per API key e URL base;
- la stessa definizione degli endpoint (`endpoints.json`) — 141 endpoint con metodo HTTP, path, titolo, descrizione e parametri attesi, ricavati dalla documentazione ufficiale dell'API.

## Requisiti

- Node.js 18 o superiore (usa il `fetch` globale, nessuna dipendenza HTTP esterna richiesta a runtime)
- Una API key Framework360 (header `X-Fw360-Key`) e l'URL base del sito su cui è attivo il modulo API

## Installazione

```bash
git clone https://github.com/VadaLinux/framework360-mcp-server.git
cd framework360-mcp-server
npm install
cp .env.example .env
```

## Configurazione

Tutta la configurazione vive in un unico file `.env` nella root del progetto:

```env
FRAMEWORK360_API_KEY=la-tua-api-key
FRAMEWORK360_BASE_URL=https://tuosito.example.com
```

| Variabile | Obbligatoria | Descrizione |
|---|---|---|
| `FRAMEWORK360_API_KEY` | sì | API key del sito, inviata nell'header `X-Fw360-Key` su ogni richiesta |
| `FRAMEWORK360_BASE_URL` | no (default `https://crigamo3.com`) | URL base del sito Framework360, senza slash finale |

`.env` è l'**unica fonte di verità**: sia il server MCP sia la CLI lo caricano da soli all'avvio (tramite [`dotenv`](https://www.npmjs.com/package/dotenv)), quindi non serve impostare le variabili altrove (né duplicarle nella config del client MCP). Per cambiare API key o dominio in futuro basta modificare questo file.

## Uso come server MCP

Aggiungi il server alla configurazione MCP del tuo client (es. Claude Code), puntando a `src/index.mjs` con un percorso assoluto:

```json
{
  "mcpServers": {
    "framework360": {
      "type": "stdio",
      "command": "node",
      "args": ["/percorso/assoluto/framework360-mcp-server/src/index.mjs"]
    }
  }
}
```

Non serve passare `env` nella configurazione: il server carica da solo `.env` dalla root del progetto al momento dell'avvio del processo.

Ogni endpoint dell'API viene esposto come tool MCP: il nome del tool corrisponde al path (es. `/m/api/customers/get`), e accetta un parametro `args`, una stringa JSON con i parametri della chiamata (es. `{"id": 101}`). Le richieste GET/DELETE passano i parametri come query string, le altre come body JSON.

> Nota: se modifichi `.env` mentre il server MCP è già connesso in una sessione, serve riavviare la connessione (o la sessione del client) perché il processo rilegga l'ambiente — viene letto una sola volta all'avvio.

## Uso come CLI

```bash
node bin/cli.mjs <comando> [opzioni]
```

In alternativa, dopo `npm link`, il comando è disponibile globalmente come `framework360` (vedi il campo `bin` in `package.json`).

### Comandi principali

| Comando | Descrizione |
|---|---|
| `list [testo]` | Elenca gli endpoint disponibili, filtrabili per parola chiave su path, titolo o descrizione |
| `describe <risorsa azione...>` | Mostra metodo HTTP, path completo, descrizione e parametri attesi di un comando |
| `<risorsa> <azione...> [opzioni]` | Scorciatoia che invoca `/m/api/<risorsa>/<azione...>` (es. `customers get` → `/m/api/customers/get`) |
| `call <path> [opzioni]` | Invoca un endpoint per path esatto, utile se non segue lo schema a due parole |
| `check` | Scorciatoia per `/m/api/check` — verifica la connessione, nessun parametro, nessun effetto collaterale |
| `help`, `-h`, `--help` | Mostra l'aiuto |

### Opzioni per passare i parametri

| Opzione | Descrizione |
|---|---|
| `-p, --param key=value` | Un parametro (ripetibile). Il valore è interpretato come JSON se possibile (`id=101` → numero, `active=true` → booleano). Ripetere la stessa chiave produce un array (utile per `customer_ids`, `label_ids`, ecc.) |
| `-d, --data '<json>'` | Payload JSON completo, ha priorità sui `-p` (si sovrappone) — utile per payload nidificati |
| `-f, --file <path>` | Legge il payload da un file JSON, unito sotto `--data` |
| `--dry-run` | Mostra URL, metodo e body che verrebbero inviati **senza eseguire** la richiesta |
| `--raw` | Stampa il body della risposta così com'è, senza provare a formattarlo come JSON |
| `-o, --output <path>` | Salva il body della risposta in un file invece di stamparlo |
| `--env <path>` | Usa un file `.env` alternativo invece di quello del progetto |

### Esempi

```bash
# verifica connessione
node bin/cli.mjs check

# scoprire i comandi disponibili
node bin/cli.mjs list customers
node bin/cli.mjs describe customers get

# lettura dati
node bin/cli.mjs customers get -p id=101
node bin/cli.mjs customers list -p query=Mario -p limit=15

# parametri array (stessa chiave ripetuta)
node bin/cli.mjs customers labels assign -p customer_ids=1 -p customer_ids=2 -p label_ids=5

# payload JSON complesso
node bin/cli.mjs report export -d '{"reportName":"sales_summary","format":"csv","dateFrom":"2023-01-01","dateTo":"2023-01-31"}'

# testare una chiamata prima di eseguirla davvero (consigliato per create/update/delete)
node bin/cli.mjs customers delete -p id=42 --dry-run

# salvare la risposta su file
node bin/cli.mjs report data -p start_date=2024-01-01 -p end_date=2024-03-31 -o report.json
```

### Codici di uscita

La CLI esce con codice `0` in caso di successo (anche se l'API restituisce un errore applicativo nel body, es. `{"status":0,"error":"..."}` — quella è comunque una risposta HTTP valida) e con codice `1` per errori della CLI stessa: parametri mal formati, comando/path sconosciuto, `.env` mancante o senza API key, file non leggibile, ecc.

## Riferimento completo degli endpoint

I 141 endpoint sono definiti in [`endpoints.json`](./endpoints.json) e raggruppati per risorsa. Per ognuno è indicato il metodo HTTP, il path REST e il comando CLI equivalente.

<details>
<summary><strong>chat</strong> (11 endpoint)</summary>

- `GET` `/m/api/chat/list` — Lista chat (`chat list`)
- `GET` `/m/api/chat/messages` — Messaggi chat (`chat messages`)
- `GET` `/m/api/chat/get` — Recupera chat (`chat get`)
- `POST` `/m/api/chat/reply` — Rispondi chat (`chat reply`)
- `POST` `/m/api/chat/deleteMessage` — Elimina messaggio chat (`chat deleteMessage`)
- `GET` `/m/api/chat/types` — Tipi messaggi chat (`chat types`)
- `GET` `/m/api/chat/templates` — Lista template chat (`chat templates`)
- `POST` `/m/api/chat/create` — Crea conversazione (`chat create`)
- `POST` `/m/api/chat/updateStatus` — Aggiorna stato chat (`chat updateStatus`)
- `POST` `/m/api/chat/markAs` — Segna chat (`chat markAs`)
- `POST` `/m/api/chat/assign` — Assegna chat (`chat assign`)
</details>

<details>
<summary><strong>check</strong> (1 endpoint)</summary>

- `GET` `/m/api/check` — Controllo connessione (`check`)
</details>

<details>
<summary><strong>checkouts</strong> (1 endpoint)</summary>

- `GET` `/m/api/checkouts/get` — Dettaglio checkout (`checkouts get`)
</details>

<details>
<summary><strong>content</strong> (1 endpoint)</summary>

- `GET` `/m/api/content/sliders/get` — Dettagli slider (`content sliders get`)
</details>

<details>
<summary><strong>customers</strong> (20 endpoint)</summary>

- `GET` `/m/api/customers/profile` — Profilo cliente (`customers profile`)
- `GET` `/m/api/customers/get` — Recupera cliente (`customers get`)
- `GET` `/m/api/customers/list` — Lista clienti (`customers list`)
- `GET` `/m/api/customers/search` — Ricerca cliente (`customers search`)
- `POST` `/m/api/customers/delete` — Elimina cliente (`customers delete`)
- `POST` `/m/api/customers/login` — Accesso cliente (`customers login`)
- `POST` `/m/api/customers/registration` — Registrazione cliente (`customers registration`)
- `POST` `/m/api/customers/update` — Aggiorna cliente (`customers update`)
- `GET` `/m/api/customers/sources` — Fonti clienti (`customers sources`)
- `GET` `/m/api/customers/labels/list` — Lista etichette clienti (`customers labels list`)
- `POST` `/m/api/customers/labels/assign` — Assegna etichette cliente (`customers labels assign`)
- `POST` `/m/api/customers/labels/remove` — Rimuovi etichette cliente (`customers labels remove`)
- `GET` `/m/api/customers/history/list` — Lista storici cliente (`customers history list`)
- `POST` `/m/api/customers/history/create` — Crea storico cliente (`customers history create`)
- `POST` `/m/api/customers/history/update` — Aggiorna storico cliente (`customers history update`)
- `GET` `/m/api/customers/notifications/status` — Stato notifiche cliente (`customers notifications status`)
- `GET` `/m/api/customers/notifications/list` — Lista notifiche cliente (`customers notifications list`)
- `POST` `/m/api/customers/notifications/mark` — Segna notifica come letta (`customers notifications mark`)
- `POST` `/m/api/customers/notifications/register` — Registra dispositivo notifiche cliente (`customers notifications register`)
- `POST` `/m/api/customers/notifications/unregister` — Rimuovi dispositivo notifiche cliente (`customers notifications unregister`)
</details>

<details>
<summary><strong>dashboard</strong> (1 endpoint)</summary>

- `GET` `/m/api/dashboard/get` — Dati cruscotto (`dashboard get`)
</details>

<details>
<summary><strong>datatables</strong> (1 endpoint)</summary>

- `GET` `/m/api/datatables/get` — Dati datatables (`datatables get`)
</details>

<details>
<summary><strong>forms</strong> (1 endpoint)</summary>

- `POST` `/m/api/forms/submit` — Invia modulo (`forms submit`)
</details>

<details>
<summary><strong>leadflow</strong> (7 endpoint)</summary>

- `GET` `/m/api/leadflow/settings` — Configura Leadflow (`leadflow settings`)
- `GET` `/m/api/leadflow/history` — Storico Leadflow (`leadflow history`)
- `GET` `/m/api/leadflow/schedule/list` — Lista schedulazioni leadflow (`leadflow schedule list`)
- `POST` `/m/api/leadflow/schedule/save` — Salva schedulazione leadflow (`leadflow schedule save`)
- `GET` `/m/api/leadflow/flow/get_contact` — Recupera contatto leadflow (`leadflow flow get_contact`)
- `POST` `/m/api/leadflow/flow/save` — Salva contatto leadflow (`leadflow flow save`)
- `POST` `/m/api/leadflow/flow/owner` — Assegna proprietario lead (`leadflow flow owner`)
</details>

<details>
<summary><strong>marketing</strong> (8 endpoint)</summary>

- `GET` `/m/api/marketing/tags` — Lista tag marketing (`marketing tags`)
- `GET` `/m/api/marketing/campaigns/flow` — Flusso campagna (`marketing campaigns flow`)
- `GET` `/m/api/marketing/campaigns/contacts` — Contatti campagna (`marketing campaigns contacts`)
- `POST` `/m/api/marketing/campaigns/updateStatus` — Aggiorna stato campagna (`marketing campaigns updateStatus`)
- `GET` `/m/api/marketing/campaigns/action/summary` — Riepilogo azione campagna (`marketing campaigns action summary`)
- `GET` `/m/api/marketing/campaigns/action/stats` — Statistiche azione campagna (`marketing campaigns action stats`)
- `GET` `/m/api/marketing/campaigns/statuses` — Stati campagne (`marketing campaigns statuses`)
- `GET` `/m/api/marketing/campaigns/types` — Tipi campagne (`marketing campaigns types`)
</details>

<details>
<summary><strong>media</strong> (6 endpoint)</summary>

- `GET` `/m/api/media/list` — Lista media (`media list`)
- `GET` `/m/api/media/directories` — Elenco directory media (`media directories`)
- `POST` `/m/api/media/delete` — Elimina media (`media delete`)
- `POST` `/m/api/media/add` — Aggiungi media (`media add`)
- `POST` `/m/api/media/update` — Aggiorna media (`media update`)
- `POST` `/m/api/media/format` — Formatta media (`media format`)
</details>

<details>
<summary><strong>orders</strong> (15 endpoint)</summary>

- `POST` `/m/api/orders/create` — Crea ordine (`orders create`)
- `POST` `/m/api/orders/import` — Importa ordini (`orders import`)
- `GET` `/m/api/orders/list` — Lista ordini (`orders list`)
- `GET` `/m/api/orders/get` — Dettagli ordine (`orders get`)
- `POST` `/m/api/orders/updateStatus` — Aggiorna stato ordine (`orders updateStatus`)
- `POST` `/m/api/orders/resendNotifications` — Reinvia notifiche ordine (`orders resendNotifications`)
- `POST` `/m/api/orders/cancel` — Annulla ordine (`orders cancel`)
- `POST` `/m/api/orders/delete` — Elimina ordine (`orders delete`)
- `POST` `/m/api/orders/repeat` — Ripeti ordine (`orders repeat`)
- `POST` `/m/api/orders/prepareCart` — Prepara carrello (`orders prepareCart`)
- `POST` `/m/api/orders/shippings` — Metodi di spedizione disponibili (`orders shippings`)
- `POST` `/m/api/orders/applyCoupon` — Applica coupon (`orders applyCoupon`)
- `GET` `/m/api/orders/statuses` — Lista stati ordine (`orders statuses`)
- `GET` `/m/api/orders/coupons` — Lista coupon (`orders coupons`)
- `GET` `/m/api/orders/labels` — Dettagli etichette ordini (`orders labels`)
</details>

<details>
<summary><strong>payments</strong> (2 endpoint)</summary>

- `GET` `/m/api/payments/list` — Lista metodi di pagamento (`payments list`)
- `GET` `/m/api/payments/taxes` — Elenco imposte (`payments taxes`)
</details>

<details>
<summary><strong>plugins</strong> (38 endpoint)</summary>

- `POST` `/m/api/plugins/install` — Installa plugin (`plugins install`)
- `GET` `/m/api/plugins/settings` — Impostazioni plugin (`plugins settings`)
- `GET` `/m/api/plugins/calendar/forms/list` — Lista moduli calendario (`plugins calendar forms list`)
- `GET` `/m/api/plugins/calendar/forms/select` — Dettagli modulo calendario (`plugins calendar forms select`)
- `GET` `/m/api/plugins/calendar/forms/getAvailability` — Disponibilità orari (`plugins calendar forms getAvailability`)
- `GET` `/m/api/plugins/calendar/forms/getLockedDays` — Giorni bloccati (`plugins calendar forms getLockedDays`)
- `POST` `/m/api/plugins/calendar/create` — Crea appuntamento (`plugins calendar create`)
- `POST` `/m/api/plugins/calendar/cancel` — Annulla appuntamento (`plugins calendar cancel`)
- `POST` `/m/api/plugins/calendar/update` — Aggiorna appuntamento (`plugins calendar update`)
- `GET` `/m/api/plugins/pipeline/pipelines/list` — Lista pipeline (`plugins pipeline pipelines list`)
- `GET` `/m/api/plugins/pipeline/pipelines/get` — Dettaglio pipeline (`plugins pipeline pipelines get`)
- `GET` `/m/api/plugins/pipeline/items/list` — Lista elementi pipeline (`plugins pipeline items list`)
- `POST` `/m/api/plugins/pipeline/items/add` — Aggiungi elemento pipeline (`plugins pipeline items add`)
- `POST` `/m/api/plugins/pipeline/items/move` — Sposta elemento pipeline (`plugins pipeline items move`)
- `POST` `/m/api/plugins/pipeline/items/delete` — Elimina elemento pipeline (`plugins pipeline items delete`)
- `GET` `/m/api/plugins/pipeline/groups/list` — Lista gruppi pipeline (`plugins pipeline groups list`)
- `GET` `/m/api/plugins/pipeline/groups/get` — Dettaglio gruppo pipeline (`plugins pipeline groups get`)
- `POST` `/m/api/plugins/pipeline/groups/create` — Crea gruppo pipeline (`plugins pipeline groups create`)
- `POST` `/m/api/plugins/pipeline/groups/update` — Aggiorna gruppo pipeline (`plugins pipeline groups update`)
- `POST` `/m/api/plugins/pipeline/groups/delete` — Elimina gruppo pipeline (`plugins pipeline groups delete`)
- `POST` `/m/api/plugins/pipeline/groups/sort` — Ordina gruppi pipeline (`plugins pipeline groups sort`)
- `POST` `/m/api/plugins/pipeline/groups/truncate` — Svuota gruppo pipeline (`plugins pipeline groups truncate`)
- `GET` `/m/api/plugins/tickets/list` — Lista ticket (`plugins tickets list`)
- `GET` `/m/api/plugins/tickets/departments` — Reparti ticket (`plugins tickets departments`)
- `POST` `/m/api/plugins/tickets/create` — Crea ticket (`plugins tickets create`)
- `GET` `/m/api/plugins/tickets/detail` — Dettaglio ticket (`plugins tickets detail`)
- `POST` `/m/api/plugins/tickets/reply` — Rispondi ticket (`plugins tickets reply`)
- `POST` `/m/api/plugins/tickets/close` — Chiudi ticket (`plugins tickets close`)
- `GET` `/m/api/plugins/membership/getPlans` — Lista piani membership (`plugins membership getPlans`)
- `GET` `/m/api/plugins/membership/getSubscriptionStatus` — Stato sottoscrizione membership (`plugins membership getSubscriptionStatus`)
- `GET` `/m/api/plugins/protectedContent/list` — Lista contenuti protetti (`plugins protectedContent list`)
- `GET` `/m/api/plugins/blog/posts/list` — Lista post blog (`plugins blog posts list`)
- `GET` `/m/api/plugins/blog/posts/get` — Dettagli post blog (`plugins blog posts get`)
- `POST` `/m/api/plugins/blog/posts/trackView` — Traccia visualizzazione post (`plugins blog posts trackView`)
- `POST` `/m/api/plugins/blog/posts/add` — Aggiungi post blog (`plugins blog posts add`)
- `POST` `/m/api/plugins/blog/posts/delete` — Elimina post blog (`plugins blog posts delete`)
- `GET` `/m/api/plugins/blog/categories/list` — Lista categorie blog (`plugins blog categories list`)
- `GET` `/m/api/plugins/blog/categories/get` — Dettagli categoria blog (`plugins blog categories get`)
</details>

<details>
<summary><strong>report</strong> (4 endpoint)</summary>

- `GET` `/m/api/report/lists` — Liste report (`report lists`)
- `GET` `/m/api/report/data` — Dati report (`report data`)
- `GET` `/m/api/report/dashboard` — Dashboard report (`report dashboard`)
- `POST` `/m/api/report/export` — Esporta report (`report export`)
</details>

<details>
<summary><strong>reports</strong> (2 endpoint)</summary>

- `POST` `/m/api/reports/get` — Recupera report (`reports get`)
- `GET` `/m/api/reports/categories` — Categorie report (`reports categories`)
</details>

<details>
<summary><strong>search</strong> (1 endpoint)</summary>

- `GET` `/m/api/search/list` — Ricerca dati (`search list`)
</details>

<details>
<summary><strong>site</strong> (5 endpoint)</summary>

- `GET` `/m/api/site/data` — Dati sito (`site data`)
- `GET` `/m/api/site/assets` — Risorse sito (`site assets`)
- `GET` `/m/api/site/settings` — Impostazioni sito (`site settings`)
- `GET` `/m/api/site/plugins` — Plugin sito (`site plugins`)
- `GET` `/m/api/site/theme` — Tema sito (`site theme`)
</details>

<details>
<summary><strong>slug</strong> (1 endpoint)</summary>

- `GET` `/m/api/slug/check` — Controlla slug (`slug check`)
</details>

<details>
<summary><strong>subscriptions</strong> (2 endpoint)</summary>

- `GET` `/m/api/subscriptions/getSubscriptionStatus` — Stato abbonamento (`subscriptions getSubscriptionStatus`)
- `POST` `/m/api/subscriptions/addSubscription` — Aggiungi abbonamento (`subscriptions addSubscription`)
</details>

<details>
<summary><strong>users</strong> (10 endpoint)</summary>

- `GET` `/m/api/users/get` — Recupera utente (`users get`)
- `POST` `/m/api/users/update` — Aggiorna utente (`users update`)
- `GET` `/m/api/users/profile` — Profilo utente (`users profile`)
- `GET` `/m/api/users/list` — Lista utenti (`users list`)
- `POST` `/m/api/users/delete` — Elimina utente (`users delete`)
- `POST` `/m/api/users/login` — Login utente (`users login`)
- `POST` `/m/api/users/reset` — Reset password (`users reset`)
- `POST` `/m/api/users/registration` — Registrazione utente (`users registration`)
- `POST` `/m/api/users/notifications/register` — Registra notifica utente (`users notifications register`)
- `POST` `/m/api/users/notifications/unregister` — Annulla registrazione notifica utente (`users notifications unregister`)
</details>

<details>
<summary><strong>webhooks</strong> (3 endpoint)</summary>

- `POST` `/m/api/webhooks/create` — Crea webhook (`webhooks create`)
- `POST` `/m/api/webhooks/delete` — Elimina webhook (`webhooks delete`)
- `GET` `/m/api/webhooks/test` — Test webhook (`webhooks test`)
</details>

Per il dettaglio completo di titolo, descrizione e parametri di ciascun endpoint usa `node bin/cli.mjs describe <risorsa azione...>`, oppure consulta direttamente `endpoints.json`.

## Struttura del progetto

```
bin/cli.mjs          entry point della CLI (shebang eseguibile)
src/index.mjs         server MCP (stdio)
src/cli.mjs           logica dei comandi CLI (parsing argomenti, list/describe/call)
src/lib.mjs           logica condivisa: caricamento .env, header di autenticazione,
                      normalizzazione payload, esecuzione chiamate HTTP
endpoints.json        definizione dei 141 endpoint (metodo, path, titolo, descrizione, parametri)
tests/verify.mjs      smoke test di struttura del progetto
verify.py             script di verifica addizionale (struttura endpoints.json + src/index.mjs)
.env.example          template di configurazione
```

## Test

```bash
npm test
```

Esegue `tests/verify.mjs`, che verifica la struttura di `endpoints.json`, la presenza dei componenti richiesti dal server MCP (`Server`, `CallToolRequestSchema`, `ListToolsRequestSchema`, `StdioServerTransport`) e la presenza di `.env.example` con la chiave attesa.

## Troubleshooting

**`Missing FRAMEWORK360_API_KEY (impostala nel file .env del progetto)`**
Il file `.env` non esiste o non contiene `FRAMEWORK360_API_KEY`. Copia `.env.example` in `.env` e compilalo.

**La CLI risponde `HTTP 200` ma con una pagina HTML "Sito non trovato"**
Il dominio in `FRAMEWORK360_BASE_URL` non corrisponde a un sito Framework360 attivo. Verifica l'URL base con il gestionale/pannello del sito.

**Un comando restituisce `{"status":0,"error":"..."}` con HTTP 200**
È una risposta valida dell'API che segnala un errore applicativo (es. risorsa non trovata, parametri mancanti), non un errore della CLI/MCP. Usa `describe <comando>` per controllare i parametri attesi.

**Comando/path non riconosciuto**
Usa `node bin/cli.mjs list <parola chiave>` per cercare il comando corretto: la CLI suggerisce anche le corrispondenze più vicine quando un comando non esiste.

**Ho cambiato `.env` ma il server MCP usa ancora i valori vecchi**
Il processo MCP legge l'ambiente una sola volta all'avvio: riavvia la connessione/sessione del client MCP dopo aver modificato `.env`.

## Sicurezza

- `.env` contiene credenziali reali e **non va mai committato**: è già escluso da `.gitignore`. Usa `.env.example` come riferimento per chi clona il repo.
- Prima di eseguire comandi che modificano dati (`create`, `update`, `delete`, `registration`, `assign`/`remove` di etichette, ecc.) è consigliato usare `--dry-run` per controllare la richiesta che verrà inviata.
- L'API key viene inviata solo nell'header `X-Fw360-Key` verso `FRAMEWORK360_BASE_URL`; nessun dato viene inviato altrove.

## Contribuire

Pull request e segnalazioni di bug sono benvenute. Per aggiungere un nuovo endpoint: aggiungilo a `endpoints.json` (metodo, path, titolo, descrizione, parametri) — sia il server MCP sia la CLI lo esporranno automaticamente, senza altre modifiche al codice.

## Licenza

ISC — vedi il campo `license` in [`package.json`](./package.json).