> For the complete documentation index, see [llms.txt](https://documentation.nomos-system.com/nomos-system/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.nomos-system.com/nomos-system/integratore-it/competenze/mcp.md). # 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. {% hint style="info" %} **Nota:** Il parametro `--allow-http` e necessario perche il nomos system Controller e accessibile localmente tramite HTTP (non HTTPS). {% endhint %} **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 {% hint style="warning" %} **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. {% endhint %} #### 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 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.nomos-system.com/nomos-system/integratore-it/competenze/mcp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.