Skip to content

SKILL.md

Latest commit

 

History

History
97 lines (82 loc) · 4.74 KB

SKILL.md

File metadata and controls

97 lines (82 loc) · 4.74 KB
Raw
name framework360
description Interagisce con l'API Framework360 tramite la CLI del progetto framework360-mcp-server (bin/cli.mjs). Usa questa skill quando l'utente chiede di leggere/gestire clienti, utenti, ordini, chat, marketing, report, contenuti o altre risorse Framework360 da riga di comando, o quando chiede di eseguire/testare un endpoint dell'API Framework360.

Framework360 CLI

CLI per l'API Framework360, fornita dal progetto framework360-mcp-server. Legge API key e base URL dal file .env di quel progetto (FRAMEWORK360_API_KEY, FRAMEWORK360_BASE_URL) e mappa tutti i 141 endpoint descritti in endpoints.json su comandi CLI.

Questa skill richiede che framework360-mcp-server sia già clonato e configurato (vedi il suo README). Nelle istruzioni sotto, <progetto> indica la directory in cui è stato clonato — sostituiscila con il percorso reale (es. /home/utente/framework360-mcp-server).

Come invocarla

Esegui sempre da dentro la directory del progetto, oppure con path assoluto:

cd <progetto>
node bin/cli.mjs <comando> [opzioni]

(È anche registrata come bin "framework360" nel package.json: se l'utente fa npm link in quella directory, il comando framework360 diventa disponibile globalmente.)

Comandi principali

  • list [testo] — elenca gli endpoint disponibili, filtrabili per parola chiave (path, titolo o descrizione). Usalo per scoprire quale comando corrisponde a una richiesta dell'utente prima di indovinare un path.
  • describe <risorsa azione...> — mostra metodo HTTP, endpoint, descrizione e parametri attesi di un comando specifico. Usalo prima di una chiamata con parametri complessi per non sbagliare i nomi dei campi.
  • <risorsa> <azione...> [opzioni] — scorciatoia che invoca /m/api/<risorsa>/<azione...>. Esempio: customers get chiama /m/api/customers/get, customers labels assign chiama /m/api/customers/labels/assign.
  • call <path> [opzioni] — invoca un endpoint per path esatto, utile se il path non segue lo schema risorsa/azione a due parole.
  • check — scorciatoia per /m/api/check (verifica connessione, nessun parametro, nessun effetto collaterale — sicuro da usare per un test rapido).

Opzioni per passare i parametri

  • -p key=value (ripetibile): un parametro. Il valore viene interpretato come JSON se possibile (quindi -p id=101 diventa numero, -p active=true diventa booleano). Ripetere la stessa chiave produce un array, utile per parametri come customer_ids/label_ids: customers labels assign -p customer_ids=1 -p customer_ids=2 -p label_ids=5.
  • -d '<json>': payload JSON completo, ha priorità sui -p (si sovrappone). Utile per payload nidificati, es. report export.
  • -f <path>: legge il payload da un file JSON.
  • --dry-run: mostra URL/metodo/body che verrebbero inviati senza eseguire la richiesta. Usalo di default quando testi o quando non sei sicuro dell'effetto di una chiamata (soprattutto per azioni che modificano dati: delete, update, create, registration, ecc.), e mostra il risultato all'utente prima di eseguire davvero.
  • --raw: stampa il body della risposta senza provare a formattarlo come JSON.
  • -o <path>: salva il body della risposta in un file invece di stamparlo.
  • --env <path>: usa un file .env alternativo invece di quello del progetto.

Comportamento consigliato

  1. Se non sai il nome esatto del comando, usa prima list <parola chiave>.
  2. Prima di una chiamata che scrive/modifica dati (POST: create, update, delete, registration, login, assign/remove label, ecc.), esegui prima con --dry-run e mostra il risultato, poi chiedi conferma prima di eseguire sul serio — sono azioni con effetti reali sui dati del sito Framework360 di produzione.
  3. Le chiamate GET/lettura (get, list, search, dashboard, report) sono sicure da eseguire direttamente.
  4. Se un comando restituisce una pagina HTML "Sito non trovato" con status 200, significa che il sito associato all'API key/URL in .env non è più disponibile lato Framework360 — non è un errore della CLI: segnalalo all'utente invece di insistere con altre chiamate.
  5. Se manca FRAMEWORK360_API_KEY, la CLI restituisce un errore chiaro: indica all'utente di controllare il file .env di <progetto>.

Esempi

node bin/cli.mjs check
node bin/cli.mjs list customers
node bin/cli.mjs describe customers get
node bin/cli.mjs customers get -p id=101
node bin/cli.mjs customers list -p query=Mario -p limit=15
node bin/cli.mjs customers labels assign -p customer_ids=1 -p customer_ids=2 -p label_ids=5 --dry-run
node bin/cli.mjs report export -d '{"reportName":"sales_summary","format":"csv","dateFrom":"2023-01-01","dateTo":"2023-01-31"}'