Aggiungere gli strumenti MCP a Reachy Mini
Che cosa è uno strumento?
Quando parli con il robot, l'output non è solo una voce, ma un sistema che reagisce alla conversazione. Il robot può muoversi e rispondere in maniera non verbale, dove appropriato. Il focus qui è lo strumento che rende questo possibile.
Uno strumento è qualcosa che il modello può eseguire durante una conversazione: esprimere un'emozione, muovere la testa, guardare con la telecamera. Ogni strumento ha un nome e una breve descrizione. Il modello legge queste informazioni e decide quando è utile chiamare uno strumento, utilizzando l'output che riceve.
Attualmente tutti gli strumenti sono locali e distribuiti all'interno dell'app. Molti di essi riguardano il corpo del robot:
- giocare un'emozione
- muovere la testa
- guardare con la camera
- ecc.
Un nome non incluso in `tools.txt` non è chiamabile dal modello.
Profilo e configurazione
Per configurare gli strumenti che possono essere utilizzati, si utilizza un profilo, una cartella che contiene due file: `instructions.txt` (contiene il prompt) e `tools.txt` (elenco degli strumenti abilitati).
Il controllo principale è affidato a `tools.txt`. Un nome non incluso in questo file non è eseguibile.
È anche possibile creare nuovi strumenti: basta aggiungere un file Python alla cartella del profilo (o in `external_tools/`), assegnargli un nome e una descrizione, ed elencarlo in `tools.txt`.
Oggi abbiamo strumenti integrati e strumenti locali personalizzati, selezionati tramite `tools.txt`, che funziona bene per il corpo del robot e mantiene il nucleo fidato limitato.
Strumenti remoti e MCP
Prima, ogni strumento doveva essere in locale in Python. Per `movehead` o `playemotion` era corretto, perché parlano con l’hardware. Tuttavia, per funzioni come la ricerca web o la verifica del meteo, mantenere tutto localmente creava ostacoli.
Gli strumenti remoti aggiungono una terza opzione, insieme agli integrati e ai locali, per capacità che possono essere pubblicate, condivise e aggiornate autonomamente:
I due strumenti iniziali
Abbiamo lanciato con due strumenti da "canary", piccoli strumenti di test per esercitare il nuovo flusso:
- Ricerca web
- Verifica meteo
Ciascuno è sufficiente per esercitare l’intera funzione: installazione dal Hub, scoperta degli strumenti remoti, attivazione per profilo, e chiamata in tempo reale esattamente come gli strumenti integrati.
Oggi i profili sono diversi
Per utilizzare entrambi gli strumenti contemporaneamente, si aggiunge ciascun Space e i relativi strumenti nello stesso profilo:
- Il robot può cercare su Internet e controllare il meteo nello stesso dialogo.
- Ciò esattamente avviene con il profilo `canarywebsearch_weather`.
`add` effettua la validazione dello Space su Hugging Face, esplora l’endpoint MCP, scopre i suoi strumenti e per default aggiunge gli ID degli strumenti al file `tools.txt` del profilo attività.
Naming e sicurezza
`tools.txt` è la chiave: uno strumento remoto è attivo solo se il suo ID appare nel `tools.txt` del profilo, insieme agli strumenti integrati che desideri utilizzare.
Ogni Space installato riceve un alias locale derivato dallo "slug" con trattini, punti e barre sostituiti da underscore:
Gli strumenti remoti sono quindi organizzati con un doppio underscore:
Questo schema mantiene i nomi di strumenti remoti distinti da quelli integrati e permette la coesistenza di più Spaces nello stesso profilo.
L’implementazione rimuove, quando possibile, prefissi ripetitivi del nome dello Space, trasformando nomi lunghi in ID locali più puliti. Tuttavia, in caso di collisione, si utilizza il nome totalmente qualificato.
C’è anche un controllo di sicurezza: i nomi degli strumenti devono essere unici in tutto l’insieme combinato; l'app fallirà immediatamente se due strumenti hanno lo stesso nome.
Gli strumenti remoti in pratica
Per testare la funzione MCP abbiamo creato due profili focalizzati:
- Il primo include pochi strumenti espressivi (emozioni, movimento della testa) e aggiunge ricerca web.
- Il secondo è identico, ma aggiunge anche il controllo del meteo accanto alla ricerca.
Questa scelta di strumenti consentisce a Reachy Mini di reagire in modo espressivo mentre risponde a domande attuali.
Prompts e logica di utilizzo
Il cablaggio degli strumenti remoti li introduce nel modello, ma i prompt decidono il loro utilizzo.
Questa logica è ben visibile nel profilo "search-plus-weather". Una domanda complessa:
Ci sono almeno tre modi per gestirla: prima il meteo, poi la ricerca; viceversa; o entrambi alla stessa volta. Se il prompt è ambiguo, il modello serializza le chiamate, creando ritardi. Ecco perché i prompt dei canari sono diventati parte della funzione, non solo configurazioni di supporto.
Raccomandazioni per gli sviluppatori
Ci sono due punti importanti da tenere a mente:
- Lo spazio deve comportarsi come un server MCP; se la scoperta degli strumenti fallisce, l’installazione fallisce.
- I prompt possono incoraggiare chiamata parallela, ma non garantirne il funzionamento. Se l’ordine è critico, questa logica deve passare dai prompt al codice.
Se desideri condividere il tuo strumento con gli altri, pubblicalo come Gradio Space pubblico, esponendo l’endpoint MCP standard e mantieni gli strumenti senza stato per un funzionamento affidabile attraverso la rete.
I tag non sono richiesti per l’installazione, ma aiutano gli utenti a trovare strumenti compatibili:
L’app ora ha tre tipi di strumenti che condividono una sola registry: integrati, personalizzati locali e remoti MCP, dove i profili decidono quali strumenti sono accessibili a ogni assistente. Un nucleo piccolo e fidato rimane al centro, mentre le capacità aggiuntive possono essere attivate o sostituite senza modificare l’app.
Meno che un suggerimento
Quello che ci aspettiamo con maggior interesse è proprio ciò che gli utenti inizieranno a costruire. Se pubblichi uno spazio strumento, etichettalo con `reachy-mini-tool` e `mcp`, in modo che altri possano trovarlo facilmente. Saremmo felici di vedere che cosa Reachy Mini potrà fare con le nuove funzionalità!