# 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 --- # Agent Instructions: 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: ``` GET https://documentation.nomos-system.com/nomos-system/integrator-nl/skills/mcp.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.