AI & MCP

Progettare un tool MCP: nome, schema e output citabile

Un tool MCP è una funzione pubblica per un modello: nome che dice il verbo, schema stretto e output che si può citare. Ecco le scelte che contano.

In sintesi

  • Il nome dichiara il verbo e il tipo di ritorno: search, get, list, compose.
  • Solo i campi necessari sono obbligatori; ogni campo libero ha una descrizione con esempi.
  • Un risultato va scritto per essere citato: conteggio, identificatore, URL e comando.

Un tool MCP si progetta come una funzione pubblica: un nome che dice il verbo, uno schema che rifiuta gli argomenti ambigui e un output che il modello può citare senza riscaricare la pagina. Il resto è contorno.

Il nome è l'interfaccia

search_components cerca, get_component legge un record, list_categories elenca. Un modello sceglie in base al nome prima di leggere lo schema, quindi un nome generico come query perde contro uno che dichiara oggetto e verbo.

Uno schema stretto

In search_components solo query è obbligatoria: le altre proprietà hanno una descrizione e un esempio, come pricing table o modal with focus trap. Il limite è un intero tra 1 e 30, quindi il server non deve gestire valori impossibili.

Una chiamata reale

curl -s https://ui.eneawork.it/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_components","arguments":{"query":"pricing table","limit":5}}}'

La risposta comincia con il numero di corrispondenze e quante ne mostra. Ogni riga porta nome, libreria, licenza, URL della pagina e comando di installazione: quattro dati che il modello può incollare in una risposta senza inventare nulla.

Fallire in modo utile

Quando non c'è nulla, il testo dice No components matched e suggerisce list_categories. Quando l'identificatore è sbagliato, dice di usare prima search_components. Un errore che indica il passo successivo vale più di uno stack trace.

Quanti strumenti servono

Nove bastano per un catalogo: ricerca, lettura, elenco, composizione e pagina. list_design_systems e list_categories hanno uno schema vuoto perché non prendono argomenti. Ogni strumento in più occupa contesto in ogni richiesta, quindi conviene aggiungerne uno solo se risponde a una domanda che gli altri non coprono.

Un risultato tipico è rainbow button di Magic UI, licenza MIT e 2.130 stelle dichiarate a monte. I blocchi stanno su 1.556 sezioni e le icone su 12.808 icone; il server completo è descritto su /mcp.

La limitazione

La descrizione di un tool è testo che finisce nel prompt, quindi è anche una superficie di iniezione: un server ostile può nascondere istruzioni in una descrizione o in un risultato. Un tool in sola lettura riduce il danno, ma il comando di installazione che restituisce viene eseguito dall'agente, e il rischio si sposta sulla shell.

Dove continuare

Il protocollo e il trasporto sono in come costruire un server MCP e in che cos'è MCP. Per la scelta tra server pronti leggi i migliori server MCP per il frontend, e per il confronto tra copiare codice e installare un pacchetto leggi copy-paste o headless.

Domande frequenti

Quanti strumenti deve esporre un server MCP?

Solo quelli che coprono domande diverse. EneUI ne espone 9 per un catalogo di 111.985 componenti: ricerca, lettura, elenco, composizione e pagina. Ogni strumento aggiuntivo consuma contesto in ogni richiesta.

Meglio un tool generico o uno specifico?

Specifico. Un nome come search_components dice al modello cosa ottiene; un tool chiamato query lo costringe a leggere lo schema e a indovinare. La specificità riduce le chiamate sbagliate.

Come si descrive un argomento di testo?

Con un esempio tra virgolette nella descrizione, come pricing table o modal with focus trap. Un campo libero senza esempio produce ricerche vaghe e risultati vuoti.

Cosa deve contenere l'output di un tool?

Il dato che il modello userà: identificatore, URL e comando, più il conteggio dei risultati. EneUI restituisce anche licenza e libreria, così la risposta può citare la fonte senza una seconda chiamata.

Un tool in sola lettura è sicuro?

Riduce il rischio, non lo elimina. Il server non scrive nulla, ma restituisce un comando di installazione che l'agente esegue: la sicurezza dipende dai permessi del client, non dal tool.