# MCP ### Wat is de nomos MCP Skill? De nomos MCP Skill stelt AI-assistenten zoals Claude in staat om rechtstreeks met de nomos system Controller te communiceren. Via het gestandaardiseerde **Model Context Protocol (MCP)** kan de AI apparaten aansturen, scènes uitvoeren, kamers beheren, automatiseringen aanmaken en nog veel meer – allemaal via natuurlijke taal. ### Vereisten * Een MCP-compatibele client (bijv. Claude Desktop, Claude Code, Cursor, Windsurf) * **Node.js** (versie 18 of hoger) geïnstalleerd op uw computer * Netwerktoegang tot de nomos system Controller (alleen lokaal, geen externe toegang mogelijk) ### Installatie #### Stap 1: MCP-module in nomos activeren De MCP-module moet worden geactiveerd in de nomos-configuratie-interface. Navigeer naar de Skills en zorg ervoor dat de MCP-module is ingeschakeld. #### Stap 2: Token aanmaken In de nomos-configuratie-interface kunt u onder het MCP-gedeelte een nieuw token aanmaken. Dit token wordt gebruikt om de AI-client te authenticeren bij de nomos system Controller. Noteer het token – u hebt het nodig voor de clientconfiguratie. * Elk token kan een eigen naam krijgen (bijv. "Claude Desktop Kantoor") * Tokens kunnen op elk moment worden uitgeschakeld of verwijderd * Er kunnen meerdere tokens worden aangemaakt voor verschillende clients #### Stap 3: Client configureren Er zijn twee manieren om uw MCP-client met de nomos system Controller te verbinden: * **Optie A: nomos MCP Bridge** (aanbevolen) – een speciale proxy die controllerverbindingen beheert via een installatiepagina. Eenvoudigste installatie, ondersteunt meerdere controllers, werkt met alle MCP-clients. * **Optie B: Directe verbinding** – de controller-URL en het token rechtstreeks in de clientconfiguratie invoeren. Vereist handmatig tokenbeheer. *** **Optie A: nomos MCP Bridge (Aanbevolen)** De **nomos MCP Bridge** is een lichtgewicht lokale proxy die verbindingen met een of meer nomos system Controllers beheert. In plaats van URLs en tokens rechtstreeks te configureren, registreert u controllers via een webgebaseerde installatiepagina. De bridge werkt met elke MCP-client die stdio-gebaseerde servers ondersteunt. **Claude Desktop** Open de instellingen van Claude Desktop en navigeer naar het gedeelte "MCP Servers". Voeg een nieuwe server toe met de volgende configuratie: ```json { "mcpServers": { "nomos": { "command": "npx", "args": ["-y", "nomos-mcp-bridge"] } } } ``` **Claude Code (CLI)** ```bash claude mcp add nomos -- npx -y nomos-mcp-bridge ``` **Cursor** Voeg toe aan uw Cursor MCP-instellingen (`.cursor/mcp.json`): ```json { "mcpServers": { "nomos": { "command": "npx", "args": ["-y", "nomos-mcp-bridge"] } } } ``` **Windsurf** Voeg toe aan uw Windsurf MCP-configuratie (`~/.codeium/windsurf/mcp_config.json`): ```json { "mcpServers": { "nomos": { "command": "npx", "args": ["-y", "nomos-mcp-bridge"] } } } ``` **Andere MCP-compatibele clients** Elke client die stdio-gebaseerde MCP-servers ondersteunt, kan de bridge gebruiken. Het commando is: ``` npx -y nomos-mcp-bridge ``` **Controllers beheren** Nadat u de bridge in uw MCP-client hebt geconfigureerd, kunt u uw controllers beheren met de volgende AI-opdrachten: | Opdracht | Beschrijving | | ------------------- | --------------------------------------------------------------------------------------------------------------- | | `open_setup` | Opent de webgebaseerde installatiepagina in uw browser waar u de controllernaam, URL en MCP-token kunt invoeren | | `add_controller` | Voegt een nieuwe controller rechtstreeks toe via AI — geef de naam, URL en token op | | `list_controllers` | Toont alle geregistreerde controllers en welke momenteel is geselecteerd | | `select_controller` | Maakt verbinding met een geregistreerde controller op naam | | `remove_controller` | Verwijdert een geregistreerde controller | *** **Optie B: Directe verbinding** Als u de controller-URL en het token liever rechtstreeks configureert zonder de bridge te gebruiken, kunt u de volgende configuraties gebruiken. **Claude Desktop** Claude Desktop ondersteunt het Streamable HTTP transportprotocol niet native. De verbinding wordt tot stand gebracht via het pakket `mcp-remote`, dat als brug fungeert. Open de instellingen van Claude Desktop en navigeer naar het gedeelte "MCP Servers". Voeg een nieuwe server toe met de volgende configuratie: ```json { "mcpServers": { "nomos": { "command": "npx", "args": [ "mcp-remote", "http:///mcp", "--allow-http", "--header", "Authorization: Bearer " ] } } } ``` Vervang `` door het IP-adres of de hostnaam van uw nomos system Controller en `` door het token dat u in stap 2 hebt aangemaakt. > **Let op:** De parameter `--allow-http` is vereist omdat de nomos system Controller lokaal via HTTP (niet HTTPS) bereikbaar is. **Claude Code (CLI)** Claude Code ondersteunt Streamable HTTP native. Voeg de server toe via de opdrachtregel: ```bash claude mcp add nomos \ --transport streamable-http \ "http:///mcp" \ --header "Authorization: Bearer " ``` Of configureer het handmatig in het bestand `~/.claude/settings.json`: ```json { "mcpServers": { "nomos": { "type": "streamable-http", "url": "http:///mcp", "headers": { "Authorization": "Bearer " } } } } ``` **Cursor** Cursor ondersteunt Streamable HTTP native. Navigeer naar `Settings > MCP` en voeg een nieuwe server toe: ```json { "mcpServers": { "nomos": { "type": "streamable-http", "url": "http:///mcp", "headers": { "Authorization": "Bearer " } } } } ``` Als de verbinding niet tot stand komt, kan als alternatief de `mcp-remote`-variant zoals bij Claude Desktop worden gebruikt. **Windsurf** Windsurf ondersteunt Streamable HTTP native. Open de MCP-configuratie en voeg toe: ```json { "mcpServers": { "nomos": { "type": "streamable-http", "url": "http:///mcp", "headers": { "Authorization": "Bearer " } } } } ``` **Andere MCP-compatibele clients** De nomos MCP-server maakt gebruik van het **Streamable HTTP** transportprotocol. Clients die deze standaard native ondersteunen, kunnen direct worden geconfigureerd: * **URL:** `http:///mcp` * **Authenticatie:** Bearer-token in de `Authorization`-header * **Transporttype:** Streamable HTTP Voor clients die alleen **stdio**-gebaseerde MCP-servers ondersteunen (zoals Claude Desktop), kan `mcp-remote` als brug worden gebruikt: ```bash npx mcp-remote http:///mcp --allow-http --header "Authorization: Bearer " ``` ### Functieoverzicht #### Bronnen De AI heeft toegang tot realtime gegevens van uw nomos system Controller: * **Alle componenten, scènes, kamers, verdiepingen, timers en automatiseringen** als overzichtslijsten * **Individuele entiteiten** met gedetailleerde informatie (bijv. een specifiek apparaat met al zijn eigenschappen) * **Live-updates:** Wijzigingen in het systeem worden automatisch aan de AI gemeld #### Ingebouwde prompts **Status & Overzicht** | Prompt | Beschrijving | | --------------- | ---------------------------------------------------------------------------------------------------------------------- | | `home_status` | Uitgebreid overzicht van de huidige status van het volledige systeem — alle kamers, componenten en hun waarden | | `room_status` | Huidige status van alle componenten in een specifieke kamer (kamernaam of kamer-ID als parameter) | | `system_health` | Uitgebreide systeemcontrole — connectiviteit, onbereikbare apparaten, cloudstatus, externe toegang, kritieke meldingen | **Domeinspecifieke rapporten** | Prompt | Beschrijving | | ----------------------- | ------------------------------------------------------------------------------------------------ | | `climate_report` | Samenvatting van temperatuur, luchtvochtigheid en klimaatregeling in alle kamers | | `energy_report` | Samenvatting van energieverbruik en vermogensgerelateerde gegevens van alle componenten | | `security_status` | Overzicht van alle beveiligingssensoren — deur-/raamcontacten, bewegingsmelders, sloten, alarmen | | `notifications_summary` | Samenvatting van alle huidige meldingen, gegroepeerd op prioriteit en type | | `automation_overview` | Overzicht van alle automatiseringen en timers — hun status, triggers en acties | **Begeleide aanmaakworkflows** | Prompt | Beschrijving | | ------------------- | ----------------------------------------------------------------------------------------------------------------- | | `create_scene` | Begeleid workflow om een nieuwe scène aan te maken op basis van een beschrijving van de gewenste toestand | | `create_automation` | Begeleid workflow om een nieuwe automatisering aan te maken op basis van een beschrijving van het gewenste gedrag | | `create_timer` | Begeleid workflow om een nieuwe timergebaseerde automatisering aan te maken | ### Voorbeelden #### Apparaten aansturen > "Doe het licht in de woonkamer aan." > "Dim de plafondlamp in de slaapkamer naar 50%." > "Zet de verwarming in de badkamer op 22 graden." #### Status opvragen > "Welke ramen staan er momenteel open?" > "Laat me de status zien van alle apparaten in de woonkamer." > "Wat is de huidige temperatuur in de keuken?" #### Scènes beheren > "Maak een scène 'Filmavond' aan die het woonkamerlicht dimt en de rolluiken sluit." > "Voer de scène 'Goedemorgen' uit." #### Automatiseringen aanmaken > "Maak een automatisering aan die de buitenverlichting inschakelt bij zonsondergang." > "Laat me alle actieve timers zien." #### KNX-configuratie > "Welke KNX-groepsadressen zijn beschikbaar in het project?" > "Importeer het KNX-project uit het bestand." ### Belangrijke opmerkingen en bekende beperkingen #### Alleen lokale toegang Het MCP-eindpunt is **uitsluitend toegankelijk via het lokale netwerk**. Toegang van buitenaf (bijv. via internet) wordt door het systeem geblokkeerd. De MCP-client moet zich op hetzelfde netwerk bevinden als de nomos system Controller. #### Claude Desktop: Herstart bij verbindingsverlies **Belangrijk:** Als de verbinding tussen Claude Desktop en de nomos MCP-server wordt onderbroken (bijv. door een herstart van de nomos system Controller of netwerkproblemen), moet **Claude Desktop volledig opnieuw worden opgestart**. Het simpelweg sluiten en opnieuw openen van het chatvenster is niet voldoende – de applicatie moet volledig worden afgesloten en opnieuw worden gestart om de MCP-verbinding te herstellen. #### Tokenbeveiliging * Behandel MCP-tokens als wachtwoorden * Maak afzonderlijke tokens aan voor verschillende clients * Schakel tokens uit of verwijder ze als ze niet meer nodig zijn * Tokens geven volledige toegang tot alle MCP-functies – er is geen fijnmazige rechtenbeheer #### Algemene MCP-opmerkingen * **Sessiebeheer:** Elke client krijgt een eigen sessie. Meerdere clients kunnen tegelijkertijd verbonden zijn. * **Automatische meldingen:** Wijzigingen in het systeem (bijv. apparaatstatus) worden automatisch gemeld aan alle verbonden clients. Bij veel gelijktijdige wijzigingen kan er een korte vertraging optreden (debouncing van 100ms). * **Foutafhandeling:** Als een tool een fout retourneert, zal de AI dit doorgaans herkennen en een nuttige foutmelding weergeven. #### Gebruikstips * Wees zo specifiek mogelijk in uw instructies (kamernamen, apparaatnamen) * De AI kan meerdere acties in één verzoek combineren * Gebruik de ingebouwde prompts voor veelvoorkomende taken * Bij complexe automatiseringen is het aan te raden om deze stap voor stap op te bouwen met de AI