framework360-mcp-server

Server MCP e CLI per l'API REST di Framework360 (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 — una skill per Claude Code che documenta come usare la CLI di questo repo direttamente in una sessione di Claude Code.

Indice

• Cos'è
• Requisiti
• Installazione
• Configurazione
• Uso come server MCP
• Uso come CLI
  • Comandi principali
  • Opzioni per passare i parametri
  • Esempi
  • Codici di uscita
• Riferimento completo degli endpoint
• Struttura del progetto
• Test
• Troubleshooting
• Sicurezza
• Contribuire
• 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 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

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:

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), 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:

{
  "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

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

# 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 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

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.