# MCP ### Was ist der nomos MCP Skill? Der nomos MCP Skill ermöglicht es KI-Assistenten wie Claude, direkt mit dem nomos system Controller zu kommunizieren. Über das standardisierte **Model Context Protocol (MCP)** kann die KI Geräte steuern, Szenen ausführen, Räume verwalten, Automationen erstellen und vieles mehr – alles per natürlicher Sprache. ### Voraussetzungen * Ein MCP-kompatibler Client (z.B. Claude Desktop, Claude Code, Cursor, Windsurf) * **Node.js** (ab Version 18) auf dem Rechner installiert * Netzwerkzugang zum nomos system Controller (nur lokal, kein externer Zugriff möglich) ### Einrichtung #### Schritt 1: MCP-Modul in nomos aktivieren Das MCP-Modul muss in der nomos Konfigurationsoberfläche aktiviert sein. Navigieren Sie zu den Skills und stellen Sie sicher, dass das MCP-Modul eingeschaltet ist. #### Schritt 2: Token erstellen In der nomos Konfigurationsoberfläche können Sie unter dem MCP-Bereich einen neuen Token erstellen. Dieser Token dient zur Authentifizierung des KI-Clients am nomos system Controller. Notieren Sie sich den Token – Sie benötigen ihn für die Client-Konfiguration. * Jeder Token kann individuell benannt werden (z.B. "Claude Desktop Büro") * Tokens können jederzeit deaktiviert oder gelöscht werden * Es können mehrere Tokens für verschiedene Clients erstellt werden #### Schritt 3: Client konfigurieren Es gibt zwei Möglichkeiten, Ihren MCP-Client mit dem nomos system Controller zu verbinden: * **Option A: nomos MCP Bridge** (empfohlen) – ein dedizierter Proxy, der Controller-Verbindungen über eine Einrichtungsseite verwaltet. Einfachste Einrichtung, unterstützt mehrere Controller, funktioniert mit allen MCP-Clients. * **Option B: Direktverbindung** – Controller-URL und Token direkt in der Client-Konfiguration eintragen. Erfordert manuelle Token-Verwaltung. *** **Option A: nomos MCP Bridge (Empfohlen)** Die **nomos MCP Bridge** ist ein leichtgewichtiger lokaler Proxy, der Verbindungen zu einem oder mehreren nomos system Controllern verwaltet. Anstatt URLs und Tokens direkt zu konfigurieren, registrieren Sie Controller über eine webbasierte Einrichtungsseite. Die Bridge funktioniert mit jedem MCP-Client, der stdio-basierte Server unterstützt. **Claude Desktop** Öffne die Claude Desktop Einstellungen und navigiere zum Bereich "MCP Servers". Füge einen neuen Server mit folgender Konfiguration hinzu: ```json { "mcpServers": { "nomos": { "command": "npx", "args": ["-y", "nomos-mcp-bridge"] } } } ``` **Claude Code (CLI)** ```bash claude mcp add nomos -- npx -y nomos-mcp-bridge ``` **Cursor** Füge folgendes in die Cursor MCP-Einstellungen (`.cursor/mcp.json`) ein: ```json { "mcpServers": { "nomos": { "command": "npx", "args": ["-y", "nomos-mcp-bridge"] } } } ``` **Windsurf** Füge folgendes in die Windsurf MCP-Konfiguration (`~/.codeium/windsurf/mcp_config.json`) ein: ```json { "mcpServers": { "nomos": { "command": "npx", "args": ["-y", "nomos-mcp-bridge"] } } } ``` **Andere MCP-kompatible Clients** Jeder Client, der stdio-basierte MCP-Server unterstützt, kann die Bridge verwenden. Der Befehl lautet: ``` npx -y nomos-mcp-bridge ``` **Controller verwalten** Nachdem Sie die Bridge in Ihrem MCP-Client konfiguriert haben, können Sie Ihre Controller mit folgenden KI-Befehlen verwalten: | Befehl | Beschreibung | | ------------------- | ------------------------------------------------------------------------------------------------------------------- | | `open_setup` | Öffnet die webbasierte Einrichtungsseite im Browser, auf der Sie Controller-Name, URL und MCP-Token eingeben können | | `add_controller` | Fügt einen neuen Controller direkt per KI hinzu — Name, URL und Token angeben | | `list_controllers` | Listet alle registrierten Controller auf und zeigt den aktuell ausgewählten an | | `select_controller` | Verbindet sich mit einem registrierten Controller anhand des Namens | | `remove_controller` | Entfernt einen registrierten Controller | *** **Option B: Direktverbindung** Wenn Sie es bevorzugen, die Controller-URL und den Token direkt ohne die Bridge zu konfigurieren, können Sie die folgenden Konfigurationen verwenden. **Claude Desktop** Claude Desktop unterstützt das Streamable HTTP Transportprotokoll nicht nativ. Die Verbindung wird über das Paket `mcp-remote` hergestellt, das als Bridge fungiert. Öffne die Claude Desktop Einstellungen und navigiere zum Bereich "MCP Servers". Füge einen neuen Server mit folgender Konfiguration hinzu: ```json { "mcpServers": { "nomos": { "command": "npx", "args": [ "mcp-remote", "http:///mcp", "--allow-http", "--header", "Authorization: Bearer " ] } } } ``` Ersetzen Sie `` durch die IP-Adresse oder den Hostnamen Ihres nomos system Controllers und `` durch den in Schritt 2 erstellten Token. > **Hinweis:** Der Parameter `--allow-http` ist erforderlich, da der nomos system Controller lokal über HTTP (nicht HTTPS) erreichbar ist. **Claude Code (CLI)** Claude Code unterstützt Streamable HTTP nativ. Füge den Server über die Kommandozeile hinzu: ```bash claude mcp add nomos \ --transport streamable-http \ "http:///mcp" \ --header "Authorization: Bearer " ``` Oder konfiguriere ihn manuell in der Datei `~/.claude/settings.json`: ```json { "mcpServers": { "nomos": { "type": "streamable-http", "url": "http:///mcp", "headers": { "Authorization": "Bearer " } } } } ``` **Cursor** Cursor unterstützt Streamable HTTP nativ. Navigiere zu `Settings > MCP` und füge einen neuen Server hinzu: ```json { "mcpServers": { "nomos": { "type": "streamable-http", "url": "http:///mcp", "headers": { "Authorization": "Bearer " } } } } ``` Falls die Verbindung nicht zustande kommt, kann alternativ die `mcp-remote`-Variante wie bei Claude Desktop verwendet werden. **Windsurf** Windsurf unterstützt Streamable HTTP nativ. Öffne die MCP-Konfiguration und füge hinzu: ```json { "mcpServers": { "nomos": { "type": "streamable-http", "url": "http:///mcp", "headers": { "Authorization": "Bearer " } } } } ``` **Andere MCP-kompatible Clients** Der nomos MCP Server nutzt das **Streamable HTTP** Transportprotokoll. Clients, die diesen Standard nativ unterstützen, können direkt konfiguriert werden: * **URL:** `http:///mcp` * **Authentifizierung:** Bearer Token im `Authorization`-Header * **Transporttyp:** Streamable HTTP Für Clients, die nur **stdio**-basierte MCP Server unterstützen (wie Claude Desktop), kann `mcp-remote` als Bridge verwendet werden: ```bash npx mcp-remote http:///mcp --allow-http --header "Authorization: Bearer " ``` ### Funktionsübersicht #### Ressourcen Die KI hat Zugriff auf Echtzeitdaten Ihres nomos system Controllers: * **Alle Komponenten, Szenen, Räume, Etagen, Timer und Automationen** als Übersichtslisten * **Einzelne Entitäten** mit detaillierten Informationen (z.B. ein bestimmtes Gerät mit all seinen Eigenschaften) * **Live-Updates:** Änderungen am System werden automatisch an die KI gemeldet #### Vorgefertigte Prompts **Status & Übersicht** | Prompt | Beschreibung | | --------------- | --------------------------------------------------------------------------------------------------------------------------- | | `home_status` | Umfassender Überblick über den aktuellen Zustand des gesamten Systems – alle Räume, Komponenten und deren Werte | | `room_status` | Aktueller Status aller Komponenten in einem bestimmten Raum (Raumname oder Raum-ID als Parameter) | | `system_health` | Umfassender Systemcheck – Erreichbarkeit, nicht erreichbare Geräte, Cloud-Status, Fernzugriff, kritische Benachrichtigungen | **Bereichsspezifische Berichte** | Prompt | Beschreibung | | ----------------------- | ------------------------------------------------------------------------------------------------------------- | | `climate_report` | Zusammenfassung von Temperatur, Luftfeuchtigkeit und Klimasteuerung über alle Räume hinweg | | `energy_report` | Zusammenfassung des Energieverbrauchs und leistungsbezogener Daten aller Komponenten | | `security_status` | Überblick über alle sicherheitsrelevanten Sensoren – Tür-/Fensterkontakte, Bewegungsmelder, Schlösser, Alarme | | `notifications_summary` | Zusammenfassung aller aktuellen Benachrichtigungen, gruppiert nach Priorität und Typ | | `automation_overview` | Überblick über alle Automationen und Timer – Status, Auslöser und Aktionen | **Geführte Erstellungs-Workflows** | Prompt | Beschreibung | | ------------------- | -------------------------------------------------------------------------------------------------------------------- | | `create_scene` | Geführter Workflow zur Erstellung einer neuen Szene basierend auf einer Beschreibung des gewünschten Zustands | | `create_automation` | Geführter Workflow zur Erstellung einer neuen Automation basierend auf einer Beschreibung des gewünschten Verhaltens | | `create_timer` | Geführter Workflow zur Erstellung einer neuen zeitgesteuerten Automation | ### Beispiele #### Geräte steuern > "Schalte das Licht im Wohnzimmer ein." > "Dimme die Deckenlampe im Schlafzimmer auf 50%." > "Stelle die Heizung im Bad auf 22 Grad." #### Status abfragen > "Welche Fenster sind gerade geöffnet?" > "Zeige mir den Status aller Geräte im Wohnzimmer." > "Wie ist die aktuelle Temperatur in der Küche?" #### Szenen verwalten > "Erstelle eine Szene 'Filmabend', die das Wohnzimmerlicht dimmt und die Rollläden schließt." > "Führe die Szene 'Guten Morgen' aus." #### Automationen erstellen > "Erstelle eine Automation, die das Außenlicht bei Sonnenuntergang einschaltet." > "Zeige mir alle aktiven Timer." #### KNX-Konfiguration > "Welche KNX-Gruppenadressen sind im Projekt vorhanden?" > "Importiere das KNX-Projekt aus der Datei." ### Wichtige Hinweise und bekannte Einschränkungen #### Nur lokaler Zugriff Der MCP-Endpunkt ist **ausschließlich über das lokale Netzwerk** erreichbar. Ein Zugriff von außerhalb (z.B. über das Internet) wird vom System blockiert. Der MCP-Client muss sich im selben Netzwerk wie der nomos system Controller befinden. #### Claude Desktop: Neustart bei Verbindungsverlust **Wichtig:** Wenn die Verbindung zwischen Claude Desktop und dem nomos MCP Server unterbrochen wird (z.B. durch einen Neustart des nomos system Controllers oder Netzwerkprobleme), muss **Claude Desktop vollständig neu gestartet** werden. Ein einfaches Schließen und Öffnen des Chat-Fensters reicht nicht aus – die Anwendung muss komplett beendet und neu gestartet werden, damit die MCP-Verbindung wiederhergestellt wird. #### Token-Sicherheit * Behandeln Sie MCP-Tokens wie Passwörter * Erstellen Sie separate Tokens für verschiedene Clients * Deaktivieren oder löschen Sie Tokens, die nicht mehr benötigt werden * Tokens gewähren vollen Zugriff auf alle MCP-Funktionen – es gibt keine feingranulare Berechtigungsverwaltung #### Allgemeine MCP-Hinweise * **Sitzungsverwaltung:** Jeder Client erhält eine eigene Sitzung. Mehrere Clients können gleichzeitig verbunden sein. * **Automatische Benachrichtigungen:** Änderungen im System (z.B. Gerätestatus) werden automatisch an alle verbundenen Clients gemeldet. Es kann bei sehr vielen gleichzeitigen Änderungen zu einer kurzen Verzögerung kommen (Debouncing von 100ms). * **Fehlerbehandlung:** Wenn ein Werkzeug einen Fehler zurückgibt, wird die KI dies in der Regel erkennen und eine hilfreiche Fehlermeldung anzeigen. #### Tipps zur Nutzung * Seien Sie in Ihren Anweisungen möglichst präzise (Raumnamen, Gerätenamen) * Die KI kann mehrere Aktionen in einer Anfrage kombinieren * Nutzen Sie die vorgefertigten Prompts für häufige Aufgaben * Bei komplexen Automationen empfiehlt es sich, diese schrittweise mit der KI aufzubauen