MCP-Server (KI-Schnittstelle)

Das Studio enthält einen integrierten MCP-Server (Model Context Protocol). Damit können KI-Assistenten wie Claude Code, Claude Desktop oder ChatGPT direkt auf ein geöffnetes Projekt zugreifen und es bearbeiten — Seiten anlegen, Widgets platzieren, Funktionsbausteine verbinden, Adressen verwalten und vieles mehr.

Der MCP-Server läuft nur im Studio-Modus (nicht in der App) und lauscht lokal auf einem konfigurierbaren TCP-Port. Er unterstützt zwei HTTP-Transporte:

• Streamable HTTP — POST http://localhost:7420/mcp
• SSE (Server-Sent Events) — GET http://localhost:7420/sse

Für die meisten KI-Clients wird ein mitgeliefertes Python-Proxy-Skript als Brücke verwendet (stdio ↔ HTTP), da nicht alle Clients HTTP-MCP-Server direkt unterstützen.

Einstellungen

Die MCP-Server-Einstellungen finden Sie unter Extras → Einstellungen → Tab „Allgemein“.

Verfügbare Werkzeuge

Der MCP-Server stellt insgesamt 107 Werkzeuge in 17 Gruppen bereit:

1. Basisoperationen (18)
2. Widget-Detail & Adressen (5)
3. Funktionsbaustein-Detail & Update (4)
4. FB-Verbindungen (3)
5. Adressverwaltung & IO-Zuweisung (8)
6. Modbus Master (6)
7. Hilfe-Abruf (2)
8. Block Uhr – Schaltzeiten (7)
9. Bedienelemente – Schaltzeiten, Anwesenheitssimulation & Einstellungen (11)
10. Verbindungen zur Steuerung (5)
11. Laufzeit-Steuerung (8)
12. Steuerungsverbund (5)
13. Diagnose (3)
14. Aufzeichnungen (4)
15. Lua Script (2)
16. Styles & Bilder (9)
17. Projekt-Generator & Raumelemente (7)

Gruppe 1: Basisoperationen (18 Werkzeuge)

Gruppe 2: Widget-Detail & Adressen (5 Werkzeuge)

Gruppe 3: Funktionsbaustein-Detail & Update (4 Werkzeuge)

Gruppe 4: FB-Verbindungen (3 Werkzeuge)

Gruppe 5: Adressverwaltung & IO-Zuweisung (8 Werkzeuge)

Gruppe 6: Modbus Master (6 Werkzeuge)

Gruppe 7: Hilfe-Abruf (2 Werkzeuge)

Gruppe 8: Block Uhr – Schaltzeiten (7 Werkzeuge)

Die Block-Uhr-Werkzeuge lesen und schreiben die Schaltzeiten eines Block-Uhr-Funktionsbausteins. Voraussetzung: Ein Widget_Block_Clock muss auf einer Visualisierungsseite mit dem Baustein verbunden sein (fb_guid = GUID des verknüpften Bausteins). Die Schaltzeiten werden ausschließlich in der Runtime gespeichert — die Schaltzeit-Werkzeuge erfordern daher eine Verbindung zur Runtime und holen vor jeder Änderung den aktuellen Stand von dort.

Gruppe 9: Bedienelemente – Schaltzeiten, Anwesenheitssimulation & Einstellungen (11 Werkzeuge)

Diese Werkzeuge wirken auf die Einstellungen im Bedienelement (Licht, Dimmer, Jalousie, Schalter, Anwesenheit, Szene, Raumregler, Beregnung und weitere) — nicht auf das eigenständige Uhr-Widget der Gruppe 8. Referenziert wird immer über die fb_guid des Funktionsbausteins. Die Werte liegen nur in der Runtime; alle Werkzeuge erfordern daher eine Verbindung zur Runtime. Im uniPRO Portal erscheint eine Änderung erst mit dem nächsten Zyklus (bis zu 60 Sekunden).

Achtung Wochentage: Hier werden die Tage als Liste days angegeben (1 = Montag … 7 = Sonntag), bei den Block-Uhr-Werkzeugen der Gruppe 8 dagegen über die Felder days_mon … days_sun.

Gruppe 10: Verbindungen zur Steuerung (5 Werkzeuge)

Diese Werkzeuge verwalten die im Projekt hinterlegten Verbindungen, über die das Studio (und connect_runtime) die Steuerung erreicht. Nach einer Änderung muss das Projekt gespeichert werden, damit sie erhalten bleibt.

Gruppe 11: Laufzeit-Steuerung (8 Werkzeuge)

Diese Werkzeuge bauen die Verbindung zur Runtime auf, übertragen das Programm und senden Werte direkt an die verbundene Runtime (z. B. Licht schalten, Dimmen, Solltemperatur setzen). Voraussetzung: PT2020-Studio ist über die Netzwerkverbindung mit einer laufenden Runtime verbunden. Die Adressen finden sich im Werkzeug list_addresses (Felder main, middle, sub).

Das Werkzeug list_addresses gibt zusätzlich die Felder value und value_str je Adresse aus, sodass der aktuelle Zustand aller Adressen auf einen Blick sichtbar ist.

Gruppe 12: Steuerungsverbund (5 Werkzeuge)

Ein Projekt kann auf mehreren Steuerungen laufen. Die Steuerungsliste und die Zuordnung der Programmseiten gehören zu den Projektdaten und wirken erst nach write_project_to_controller.

Gruppe 13: Diagnose (3 Werkzeuge)

Gruppe 14: Aufzeichnungen (4 Werkzeuge)

Diese Werkzeuge bearbeiten die Aufzeichnungen des Projekts (Menü Aufzeichnung). Sie gehören zu den Projektdaten und wirken auf der Steuerung erst nach write_project_to_controller.

Gruppe 15: Lua Script (2 Werkzeuge)

Diese Werkzeuge ermöglichen das Schreiben und Lesen von Lua-Skriptcode für den Lua Interpreter-Funktionsbaustein (Typ 0x0384). Das Werkzeug get_lua_api_reference liefert die vollständige API-Referenz mit Callbacks, IO-Variablen und allen sys_*-Funktionen — so kann der KI-Assistent direkt korrekten Lua-Code erzeugen.

Gruppe 16: Styles & Bilder (9 Werkzeuge)

Das Projekt hat genau 20 feste Style-Slots (Designs der Visualisierung, Index 0–19). Ein neuer Style entsteht, indem ein freier Slot befüllt wird. Farben werden im Format #rrggbb angegeben.

Gruppe 17: Projekt-Generator & Raumelemente (7 Werkzeuge)

Diese Werkzeuge nutzen das Regelwerk des Projekt-Generators: Aus den Gruppenadressen wird eine Raumstruktur (Geschoss → Raum → Element → Adresse) abgeleitet, korrigiert und daraus das Projekt erzeugt. Einzelne Raumelemente lassen sich auch direkt anlegen.

Einbindung in Claude Code (empfohlen)

Claude Code ist das KI-Werkzeug von Anthropic für die Kommandozeile (Terminal). Die Einbindung erfolgt über das Python-Proxy-Skript und den Befehl claude mcp add.

Voraussetzungen

• Python 3.x installiert (unter Windows ab Version 10 verfügbar)
• Das Proxy-Skript uni_pro_mcp_proxy.py im gewünschten Verzeichnis ablegen (z.B. C:\Users\<Benutzer>\)

Proxy-Skript

Das Skript leitet stdio-Nachrichten an den HTTP-MCP-Server des Studios weiter:

import sys, json, urllib.request, urllib.error MCP_URL = "http://localhost:7420/mcp" def send_error(id_, msg): sys.stdout.write(json.dumps({"jsonrpc":"2.0","id":id_,"error":{"code":-32603,"message":msg}})+"\n") sys.stdout.flush() def main(): for line in sys.stdin: line = line.strip() if not line: continue try: id_ = json.loads(line).get("id") except: id_ = None try: req = urllib.request.Request(MCP_URL, data=line.encode(), headers={"Content-Type":"application/json"}) with urllib.request.urlopen(req, timeout=10) as r: body = r.read().decode().strip() if body and body != "{}": sys.stdout.write(body+"\n"); sys.stdout.flush() except urllib.error.URLError as e: send_error(id_, "Studio nicht erreichbar: "+str(e.reason)) except Exception as e: send_error(id_, str(e)) if __name__ == "__main__": main()

Server registrieren

Einmalig in einem Terminal ausführen (ersetzt die manuelle Konfiguration der settings.json):

claude mcp add --scope user uni-pro python "C:/Users/<Benutzer>/uni_pro_mcp_proxy.py"

Verbindung prüfen

1. Studio starten und Projekt öffnen.
2. Neues Terminal öffnen, claude starten.
3. /mcp eingeben — uni-pro sollte als verbunden erscheinen.

Einbindung in Claude Desktop

Claude Desktop ist die Desktop-Anwendung von Anthropic. Die Konfigurationsdatei befindet sich unter:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Folgenden Abschnitt in die Konfigurationsdatei einfügen:

{ "mcpServers": { "uni-pro": { "command": "python", "args": ["C:/Users/<Benutzer>/uni_pro_mcp_proxy.py"] } } }

Claude Desktop anschließend neu starten. Im Chat-Eingabefeld erscheint ein Werkzeug-Symbol — beim Anklicken werden die verfügbaren MCP-Werkzeuge angezeigt.

Hinweis: Studio muss vor Claude Desktop gestartet werden, damit der Proxy beim ersten Verbindungsversuch den HTTP-Server erreichen kann.

Einbindung in ChatGPT Desktop

ChatGPT Desktop (Windows/macOS) unterstützt MCP-Server ebenfalls über das stdio-Proxy-Skript.

1. Studio starten.
2. In ChatGPT Desktop: Einstellungen → Verbundene Apps / MCP-Server aufrufen.
3. Neuen Server hinzufügen:
   • Befehl: python
   • Argumente: C:/Users/<Benutzer>/uni_pro_mcp_proxy.py
   • Name: uni-pro
4. ChatGPT Desktop neu starten.

Hinweis: Die genaue Konfiguration hängt von der installierten ChatGPT-Desktop-Version ab. Aktuelle Informationen finden Sie in der OpenAI-Dokumentation.

Testen mit curl

Die Verbindung kann ohne KI-Anwendung direkt mit curl getestet werden. Öffnen Sie eine Eingabeaufforderung und führen Sie folgende Befehle aus (Studio muss laufen):

1. Handshake (Verbindung prüfen)

curl -X POST http://localhost:7420/mcp ^ -H "Content-Type: application/json" ^ -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"0\"}}}"

Erwartete Antwort (gekürzt):

{"jsonrpc":"2.0","id":1,"result":{"serverInfo":{"name":"PT2020-Studio-MCP","version":"1.0"},...}}

2. Werkzeugliste abrufen

curl -X POST http://localhost:7420/mcp ^ -H "Content-Type: application/json" ^ -d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}"

3. Projektinfo abrufen

curl -X POST http://localhost:7420/mcp ^ -H "Content-Type: application/json" ^ -d "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"get_project_info\",\"arguments\":{}}}"

Tipp: Unter Windows steht curl ab Windows 10 (Build 1803) in der Eingabeaufforderung zur Verfügung.

Praxisbeispiele

Die folgenden Beispiele zeigen typische Anfragen, die Sie dem KI-Assistenten stellen können. Der Assistent ruft dabei automatisch die passenden MCP-Werkzeuge auf.

Projekt überblicken

„Welche Visualisierungsseiten hat das aktuelle Projekt?“

„Zeige mir alle KNX-Adressen im Projekt.“

„Was ist der Projektname und welche Version wird verwendet?“

Visualisierungsseiten erstellen

„Erstelle eine neue Visualisierungsseite mit dem Namen ‘Hauptmenü’ in der Größe 1024×768 Pixel.“

„Lege drei Seiten an: ‘Erdgeschoss’, ‘Obergeschoss’ und ‘Keller’, jeweils 1280×800 Pixel.“

Widgets platzieren und konfigurieren

„Füge auf der Seite ‘Hauptmenü’ oben links einen Button (Typ 100) mit der Beschriftung ‘Licht ein’ hinzu, 200×80 Pixel groß.“

„Platziere auf der Seite ‘Erdgeschoss’ vier Schalter nebeneinander, je 150×60 Pixel, für die Jalousien im Wohnzimmer.“

„Verschiebe den Button mit ID 42 auf der Seite ‘Hauptmenü’ nach rechts unten (Position 800, 600).“

„Zeige mir alle Parameter und Adressen des Widgets mit ID 15 auf der Seite ‘Erdgeschoss’.“

„Weise dem ersten IO-Slot des Widgets 15 die KNX-Adresse 1/2/10 zu.“

Programmlogik aufbauen und verbinden

„Erstelle eine neue Programmseite namens ‘Lichtsteuerung’ und füge einen AND-Funktionsbaustein sowie einen Timer hinzu.“

„Welche Funktionsbausteine sind auf der Seite ‘Heizung’ vorhanden?“

„Zeige mir alle Parameter und Eingänge des Funktionsbausteins mit der GUID ‘abc-123’.“

„Verbinde den Ausgang 0 des AND-Bausteins mit dem Eingang 0 des Timers auf der Seite ‘Lichtsteuerung’.“

„Welche Verbindungen existieren auf der Programmseite ‘Lichtsteuerung’?“

„Trenne die Verbindung am Eingang 0 des Timers.“

„Setze den Kommentar des Funktionsbausteins ‘abc-123’ auf ‘Prüft Anwesenheit und Helligkeit’.“

KNX-Adressen verwalten

„Lege eine neue KNX-Adresse 1/2/50 mit dem Kommentar ‘Licht Wohnzimmer’ an.“

„Aktualisiere den Kommentar der Adresse 1/2/50 auf ‘Licht Wohnzimmer Haupt’.“

„Lösche die Adresse 1/2/99 aus der Adressliste.“

„Weise dem Ausgang 0 des Funktionsbausteins ‘abc-123’ die KNX-Adresse 1/2/50 zu.“

„Sind alle KNX-Adressen im Projekt zugewiesen? Liste nicht verwendete Adressen auf.“

Strukturanalyse und Refactoring

„Analysiere die Struktur aller Visualisierungsseiten und erstelle eine Übersicht der verwendeten Widget-Typen.“

„Prüfe alle Funktionsbausteine auf der Seite ‘Heizung’ auf nicht verbundene Eingänge und Ausgänge.“

„Kopiere die Struktur der Seite ‘Erdgeschoss’ und erstelle daraus eine neue Seite ‘Obergeschoss’ mit denselben Widget-Positionen.“

Projekt speichern

„Speichere das Projekt.“

„Führe alle Änderungen durch und speichere das Projekt anschließend.“

Fehlerbehebung

• uni-pro erscheint nicht in /mcp: Claude Code neu starten (neues Terminal öffnen). Den Befehl claude mcp add müssen Sie nur einmalig ausführen.
• „Studio nicht erreichbar“: Studio starten und Projekt öffnen. Der Port 7420 muss in den Einstellungen konfiguriert sein (nicht 0).
• „Kein Projekt geöffnet“: Im Studio ein Projekt öffnen oder neu erstellen.
• Port bereits belegt: In den Einstellungen einen anderen Port wählen (z.B. 7421) und das Studio neu starten. Das Proxy-Skript anschließend anpassen (MCP_URL = "http://localhost:7421/mcp").
• Firewall: Der Server lauscht nur auf localhost (127.0.0.1) — keine Firewall-Regeln nötig.
• Werkzeugaufrufe nachverfolgen: Unter Extras → Einstellungen → MCP-Server Debug → An werden alle Verbindungen und Werkzeugaufrufe im Anwendungsprotokoll sichtbar. Kein Neustart erforderlich.