# MCP ### Cos'e la competenza nomos MCP? La competenza nomos MCP permette agli assistenti AI come Claude di comunicare direttamente con il nomos system Controller. Utilizzando il protocollo standardizzato **Model Context Protocol (MCP)**, l'AI puo controllare dispositivi, eseguire scene, gestire stanze, creare automazioni e molto altro - il tutto tramite linguaggio naturale. ### Prerequisiti * Un client compatibile con MCP (ad es. Claude Desktop, Claude Code, Cursor, Windsurf) * **Node.js** (versione 18 o superiore) installato sulla Sua macchina * Accesso di rete al nomos system Controller (solo locale, nessun accesso esterno possibile) ### Configurazione #### Passaggio 1: Abilitare il modulo MCP in nomos Il modulo MCP deve essere abilitato nell'interfaccia di configurazione nomos. Navighi su Competenze e si assicuri che il modulo MCP sia attivato. #### Passaggio 2: Creare un token Nell'interfaccia di configurazione nomos, naviga alla sezione MCP e crea un nuovo token. Questo token viene utilizzato per autenticare il client AI con il nomos system Controller. Prenda nota del token - Le servira per la configurazione del client. * A ogni token puo essere assegnato un nome personalizzato (ad es. "Claude Desktop Ufficio") * I token possono essere disabilitati o eliminati in qualsiasi momento * Possono essere creati piu token per diversi client #### Passaggio 3: Configurare il client Esistono due modi per collegare il client MCP al nomos system Controller: * **Opzione A: nomos MCP Bridge** (consigliato) – un proxy dedicato che gestisce le connessioni ai controller tramite una pagina di configurazione. Configurazione piu semplice, supporta piu controller, funziona con tutti i client MCP. * **Opzione B: Connessione diretta** – configurare l'URL del controller e il token direttamente nella configurazione del client. Richiede la gestione manuale dei token. *** **Opzione A: nomos MCP Bridge (Consigliato)** La **nomos MCP Bridge** e un proxy locale leggero che gestisce le connessioni a uno o piu nomos system Controller. Invece di configurare URL e token direttamente, si registrano i controller tramite una pagina di configurazione web. La bridge funziona con qualsiasi client MCP che supporta server basati su stdio. **Claude Desktop** Apra le impostazioni di Claude Desktop e navighi alla sezione "MCP Servers". Aggiunga un nuovo server con la seguente configurazione: ```json { "mcpServers": { "nomos": { "command": "npx", "args": ["-y", "nomos-mcp-bridge"] } } } ``` **Claude Code (CLI)** ```bash claude mcp add nomos -- npx -y nomos-mcp-bridge ``` **Cursor** Aggiunga nelle impostazioni MCP di Cursor (`.cursor/mcp.json`): ```json { "mcpServers": { "nomos": { "command": "npx", "args": ["-y", "nomos-mcp-bridge"] } } } ``` **Windsurf** Aggiunga nella configurazione MCP di Windsurf (`~/.codeium/windsurf/mcp_config.json`): ```json { "mcpServers": { "nomos": { "command": "npx", "args": ["-y", "nomos-mcp-bridge"] } } } ``` **Altri client compatibili con MCP** Qualsiasi client che supporta server MCP basati su stdio puo utilizzare la bridge. Il comando e: ``` npx -y nomos-mcp-bridge ``` **Gestione dei controller** Dopo aver configurato la bridge nel client MCP, puo gestire i controller utilizzando i seguenti comandi AI: | Comando | Descrizione | | ------------------- | --------------------------------------------------------------------------------------------------------------- | | `open_setup` | Apre la pagina di configurazione web nel browser dove puo inserire il nome del controller, l'URL e il token MCP | | `add_controller` | Aggiunge un nuovo controller direttamente tramite AI — fornire nome, URL e token | | `list_controllers` | Elenca tutti i controller registrati e mostra quale e attualmente selezionato | | `select_controller` | Si connette a un controller registrato per nome | | `remove_controller` | Rimuove un controller registrato | *** **Opzione B: Connessione diretta** Se preferisce configurare l'URL del controller e il token direttamente senza utilizzare la bridge, puo utilizzare le seguenti configurazioni. **Claude Desktop** Claude Desktop non supporta nativamente il protocollo di trasporto Streamable HTTP. La connessione viene stabilita tramite il pacchetto `mcp-remote`, che funge da ponte. Apra le impostazioni di Claude Desktop e navighi alla sezione "MCP Servers". Aggiunga un nuovo server con la seguente configurazione: ```json { "mcpServers": { "nomos": { "command": "npx", "args": [ "mcp-remote", "http:///mcp", "--allow-http", "--header", "Authorization: Bearer " ] } } } ``` Sostituisca `` con l'indirizzo IP o il nome host del Suo nomos system Controller e `` con il token creato nel Passaggio 2. > **Nota:** Il parametro `--allow-http` e necessario perche il nomos system Controller e accessibile localmente tramite HTTP (non HTTPS). **Claude Code (CLI)** Claude Code supporta nativamente Streamable HTTP. Aggiunga il server tramite la riga di comando: ```bash claude mcp add nomos \ --transport streamable-http \ "http:///mcp" \ --header "Authorization: Bearer " ``` Oppure lo configuri manualmente in `~/.claude/settings.json`: ```json { "mcpServers": { "nomos": { "type": "streamable-http", "url": "http:///mcp", "headers": { "Authorization": "Bearer " } } } } ``` **Cursor** Cursor supporta nativamente Streamable HTTP. Navighi su `Settings > MCP` e aggiunga un nuovo server: ```json { "mcpServers": { "nomos": { "type": "streamable-http", "url": "http:///mcp", "headers": { "Authorization": "Bearer " } } } } ``` Se la connessione non puo essere stabilita, può utilizzare in alternativa la variante `mcp-remote` come descritto per Claude Desktop. **Windsurf** Windsurf supporta nativamente Streamable HTTP. Apra la configurazione MCP e aggiunga: ```json { "mcpServers": { "nomos": { "type": "streamable-http", "url": "http:///mcp", "headers": { "Authorization": "Bearer " } } } } ``` **Altri client compatibili con MCP** Il server nomos MCP utilizza il protocollo di trasporto **Streamable HTTP**. I client che supportano nativamente questo standard possono essere configurati direttamente: * **URL:** `http:///mcp` * **Autenticazione:** Token Bearer nell'header `Authorization` * **Tipo di trasporto:** Streamable HTTP Per i client che supportano solo server MCP basati su **stdio** (come Claude Desktop), `mcp-remote` puo essere utilizzato come ponte: ```bash npx mcp-remote http:///mcp --allow-http --header "Authorization: Bearer " ``` ### Panoramica delle funzionalita #### Risorse L'AI ha accesso ai dati in tempo reale dal Suo nomos system Controller: * **Tutti i componenti, scene, stanze, piani, timer e automazioni** come elenchi panoramici * **Entita individuali** con informazioni dettagliate (ad es. un dispositivo specifico con tutte le sue proprieta) * **Aggiornamenti in tempo reale:** Le modifiche nel sistema vengono automaticamente segnalate all'AI #### Prompt integrati **Stato e panoramica** | Prompt | Descrizione | | --------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `home_status` | Panoramica completa dello stato attuale dell'intero sistema — tutte le stanze, i componenti e i loro valori | | `room_status` | Stato attuale di tutti i componenti in una stanza specifica (nome della stanza o ID della stanza come parametro) | | `system_health` | Controllo completo del sistema — connettività, dispositivi non raggiungibili, stato del cloud, accesso remoto, notifiche critiche | **Report specifici** | Prompt | Descrizione | | ----------------------- | ---------------------------------------------------------------------------------------------------------------- | | `climate_report` | Riepilogo di temperatura, umidità e climatizzazione in tutte le stanze | | `energy_report` | Riepilogo del consumo energetico e dei dati relativi alla potenza di tutti i componenti | | `security_status` | Riepilogo di tutti i sensori di sicurezza — contatti porta/finestra, rilevatori di movimento, serrature, allarmi | | `notifications_summary` | Riepilogo di tutte le notifiche correnti, raggruppate per priorità e tipo | | `automation_overview` | Panoramica di tutte le automazioni e i timer — stato, trigger e azioni | **Workflow di creazione guidata** | Prompt | Descrizione | | ------------------- | -------------------------------------------------------------------------------------------------------- | | `create_scene` | Workflow guidato per creare una nuova scena basata su una descrizione dello stato desiderato | | `create_automation` | Workflow guidato per creare una nuova automazione basata su una descrizione del comportamento desiderato | | `create_timer` | Workflow guidato per creare una nuova automazione basata su timer | ### Esempi #### Controllo dei dispositivi > "Accendi la luce in soggiorno." > "Regola la lampada del soffitto in camera da letto al 50%." > "Imposta il riscaldamento in bagno a 22 gradi." #### Interrogazione dello stato > "Quali finestre sono attualmente aperte?" > "Mostrami lo stato di tutti i dispositivi in soggiorno." > "Qual e la temperatura attuale in cucina?" #### Gestione delle scene > "Crea una scena chiamata 'Serata cinema' che abbassa le luci del soggiorno e chiude le tapparelle." > "Esegui la scena 'Buongiorno'." #### Creazione di automazioni > "Crea un'automazione che accende le luci esterne al tramonto." > "Mostrami tutti i timer attivi." #### Configurazione KNX > "Quali indirizzi di gruppo KNX sono disponibili nel progetto?" > "Importa il progetto KNX dal file." ### Note importanti e limitazioni note #### Solo accesso locale L'endpoint MCP e **accessibile solo tramite la rete locale**. L'accesso dall'esterno (ad es. tramite internet) e bloccato dal sistema. Il client MCP deve trovarsi nella stessa rete del nomos system Controller. #### Claude Desktop: Riavvio in caso di perdita di connessione **Importante:** Se la connessione tra Claude Desktop e il server nomos MCP viene interrotta (ad es. a causa di un riavvio del nomos system Controller o di problemi di rete), **Claude Desktop deve essere completamente riavviato**. Chiudere e riaprire semplicemente la finestra della chat non e sufficiente - l'applicazione deve essere completamente chiusa e riavviata per ristabilire la connessione MCP. #### Sicurezza dei token * Tratti i token MCP come password * Crei token separati per diversi client * Disabiliti o elimini i token che non sono piu necessari * I token garantiscono accesso completo a tutte le funzioni MCP - non esiste una gestione granulare dei permessi #### Note generali su MCP * **Gestione delle sessioni:** Ogni client riceve la propria sessione. Piu client possono essere collegati contemporaneamente. * **Notifiche automatiche:** Le modifiche nel sistema (ad es. stato dei dispositivi) vengono automaticamente segnalate a tutti i client collegati. Potrebbe esserci un breve ritardo con molte modifiche simultanee (debouncing di 100ms). * **Gestione degli errori:** Se uno strumento restituisce un errore, l'AI generalmente lo riconosce e visualizza un messaggio di errore utile. #### Suggerimenti per l'utilizzo * Sia il piu specifico possibile nelle Sue istruzioni (nomi delle stanze, nomi dei dispositivi) * L'AI puo combinare piu azioni in una singola richiesta * Utilizzi i prompt integrati per le attivita comuni * Per automazioni complesse, si consiglia di costruirle passo dopo passo con l'AI