# IPS Automation MCP Server

Ein **Model Context Protocol (MCP) Server**, der Claude (oder andere MCP-Clients) direkten
Zugriff auf die JSON-RPC API von [IP-Symcon](https://www.symcon.de) gibt. Damit kann Claude
deine PHP-Skripte **lesen, analysieren, optimieren, neu erstellen und ausführen** – die
Automatisierungs-Entwicklung wird dadurch zum Dialog.

> ⚠️ Dieser Server greift **direkt** über die native JSON-RPC API (Port 3777) auf IP-Symcon zu.
> Es muss **kein** zusätzliches PHP-Modul in IP-Symcon installiert werden – nur der Fernzugriff
> muss aktiviert sein.

---

## Was kann der Server?

Claude bekommt 13 Tools, mit denen es eigenständig in deinem IPS-System arbeiten kann:

### Skript-Tools (Kernfunktion)
| Tool | Beschreibung |
|------|-------------|
| `script_list` | Alle Skripte auflisten (Name, ID, Status, letzter Lauf), optional mit Suchfilter |
| `script_read` | PHP-Quellcode eines Skripts lesen + Metadaten |
| `script_write` | Code überschreiben (mit Typ-Prüfung als Sicherheitsnetz) |
| `script_create` | Neues Skript anlegen + Code setzen (mit Rollback bei Fehler) |
| `script_execute` | Skript ausführen + Ergebnis/Laufzeit zurückgeben |
| `script_delete` | Skript löschen |
| `php_eval` | PHP-Code direkt testen (über temporäres Skript, wird automatisch aufgeräumt) |
| `cleanup_eval_scripts` | Verwaiste Temp-Skripte aufräumen (mit Vorschau-Modus) |

### Kontext-Tools
| Tool | Beschreibung |
|------|-------------|
| `object_search` | Objekte/Variablen nach Name suchen → liefert IDs für neue Skripte |
| `variable_read` | Variable lesen (Wert + Metadaten) |
| `variable_set` | Variable setzen / Aktion auslösen (RequestAction oder SetValue) |
| `object_children` | Objektbaum navigieren |

### System-Tools
| Tool | Beschreibung |
|------|-------------|
| `system_info` | IPS Version + Laufzeit |
| `system_log` | Fehlerlog lesen – ideal zur Diagnose nach einem Skript-Fehler |

---

## Architektur

```
┌─────────────────┐   stdio    ┌──────────────────┐   JSON-RPC    ┌──────────────┐
│  Claude Desktop │ ─────────► │  MCP Server      │ ────────────► │  IP-Symcon   │
│  (dein PC)      │            │  (Node.js)       │   Port 3777   │              │
└─────────────────┘            └──────────────────┘               └──────────────┘
```

Der MCP-Server läuft **auf demselben PC wie Claude Desktop** und verbindet sich übers
Netzwerk mit IP-Symcon. Geschrieben in TypeScript mit dem offiziellen
[`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol).

---

## Voraussetzungen

- **Node.js 18+** ([nodejs.org](https://nodejs.org), LTS-Version)
- **IP-Symcon** mit aktiviertem Fernzugriff
- **Claude Desktop** (oder ein anderer MCP-Client)

---

## Installation

### 1. Fernzugriff in IP-Symcon aktivieren

Die JSON-RPC API ist durch den Fernzugriff abgesichert.

1. IP-Symcon Verwaltungskonsole öffnen
2. **Einstellungen → Fernzugriff**
3. Ein **Passwort** vergeben und speichern

Notiere dir drei Werte:
- **Host/IP** deines IP-Symcon Servers (z.B. `192.168.1.100`)
- **Benutzer** = deine **Lizenz-E-Mail-Adresse** (nicht der Account-Name!)
- **Passwort** = das eben gesetzte Fernzugriff-Passwort

### 2. Repository klonen & bauen

```bash
git clone https://github.com/badfrog18/ips-automation-mcp.git
cd ips-automation-mcp
npm install
npm run build
```

> **Windows / PowerShell:** Falls `npm install` mit einem Fehler
> *"die Ausführung von Skripts ist deaktiviert"* abbricht, nutze stattdessen
> `npm.cmd install` und `npm.cmd run build` – oder gib einmalig die Execution Policy frei:
> `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned`

### 3. Verbindung testen (empfohlen)

Bevor du Claude konfigurierst, prüfe ob die Verbindung steht:

**Windows (CMD):**
```cmd
set IPS_HOST=192.168.1.100 && set IPS_USER=deine@email.de && set IPS_PASS=deinPasswort && node test-connection.mjs
```

**Windows (PowerShell):**
```powershell
$env:IPS_HOST="192.168.1.100"; $env:IPS_USER="deine@email.de"; $env:IPS_PASS="deinPasswort"; node test-connection.mjs
```

**macOS/Linux:**
```bash
IPS_HOST=192.168.1.100 IPS_USER=deine@email.de IPS_PASS=deinPasswort node test-connection.mjs
```

Bei Erfolg zeigt das Skript deine IP-Symcon-Version und die Anzahl deiner Skripte/Objekte.

### 4. Claude Desktop konfigurieren

Öffne in Claude Desktop: **Einstellungen → Entwickler → Konfiguration bearbeiten**.
Das öffnet (bzw. erstellt) die Datei `claude_desktop_config.json`.

Füge den `mcpServers`-Block hinzu (Pfad und Zugangsdaten anpassen):

```json
{
  "mcpServers": {
    "ips-automation": {
      "command": "node",
      "args": ["C:/Tools/ips-automation-mcp/dist/server.js"],
      "env": {
        "IPS_HOST": "192.168.1.100",
        "IPS_PORT": "3777",
        "IPS_USER": "deine@email.de",
        "IPS_PASS": "deinPasswort"
      }
    }
  }
}
```

> **Windows-Pfade:** Im JSON entweder Schrägstriche `/` oder doppelte Backslashes `\\`
> verwenden – einfache Backslashes brechen die Datei.

> **Bestehende Config:** Falls schon andere MCP-Server eingetragen sind, füge nur den
> `"ips-automation"`-Block innerhalb von `"mcpServers"` hinzu, statt die Datei zu ersetzen.

### 5. Claude Desktop neu starten

**Komplett beenden** (Windows: Rechtsklick aufs Tray-Icon → Beenden) und neu öffnen.
Ein einfaches Schließen des Fensters reicht nicht.

### 6. Testen

Frag Claude:

> „Zeige mir alle meine IP-Symcon Skripte"

Claude ruft dann `script_list` auf und listet deine Skripte.

---

## Umgebungsvariablen

| Variable | Standard | Beschreibung |
|----------|----------|-------------|
| `IPS_HOST` | `127.0.0.1` | IP-Symcon Hostname/IP |
| `IPS_PORT` | `3777` | JSON-RPC Port |
| `IPS_USER` | – | Lizenz-E-Mail (Pflicht) |
| `IPS_PASS` | – | Fernzugriff-Passwort (Pflicht) |
| `IPS_HTTPS` | `false` | HTTPS statt HTTP |
| `IPS_TIMEOUT` | `30000` | Timeout pro Anfrage in ms – auf langsamen/großen Systemen (Raspi, große DB) höher setzen |

---

## Beispiel-Workflows

```
"Zeig alle Skripte mit 'Pool' im Namen"
 → script_list (gefiltert)

"Lies das Poolpumpen-Skript und erkläre, was es macht"
 → script_read + Analyse

"Optimiere das Skript und schreib die verbesserte Version zurück"
 → script_read → script_write

"Erstelle eine Automation, die bei PV-Überschuss die Poolpumpe einschaltet"
 → object_search (IDs finden) → script_create → script_execute

"Das Skript wirft einen Fehler – finde und behebe ihn"
 → script_execute → system_log → script_write
```

---

## Sicherheitshinweis

Der Server hat **vollen Lese- und Schreibzugriff** (inkl. Löschen und Ausführen) auf deine
IPS-Skripte. Die `claude_desktop_config.json` enthält dein Fernzugriff-Passwort im Klartext –
behandle sie entsprechend vertraulich und committe sie **niemals** in ein öffentliches Repo
(sie ist in der `.gitignore` ausgeschlossen).

---

## Changelog

### v2.2.0
- **Performance:** `object_search`, `script_list` und `object_children` laufen jetzt vollständig **serverseitig in IP-Symcon** (ein einziger RPC-Call statt tausender Einzelanfragen). Damit funktionieren sie auch auf großen Systemen (>10.000 Objekte) zuverlässig, ohne Timeout. Behebt „Failed to call tool object_search" / „MCP-Server reagiert nicht".
- **Konfigurierbarer Timeout** über `IPS_TIMEOUT` (Standard jetzt 30s statt 15s) – für langsame Hosts wie Raspberry Pi
- Interne `evalPhp`-Hilfsfunktion für zuverlässige serverseitige Ausführung mit echtem JSON-Rückgabewert

### v2.1.0
- **Fix:** Temporäre `php_eval`-Skripte werden jetzt zuverlässig gelöscht (inkl. PHP-Datei auf der Platte). Ursache war der fehlende zweite Parameter `delete_file` bei `IPS_DeleteScript`.
- Automatisches Aufräumen verwaister `__claude_eval_`-Skripte beim Serverstart
- Neues Tool `cleanup_eval_scripts` (mit Vorschau-Modus) zum manuellen Aufräumen
- `script_delete` nutzt jetzt ebenfalls robustes Löschen + Typprüfung

### v2.0.0
- Erste Veröffentlichung mit 13 Tools für Skript-Automatisierung

---

## Lizenz

MIT – siehe [LICENSE](LICENSE).

## Haftungsausschluss

Dieses Projekt steht in keiner Verbindung zur Symcon GmbH.

**Die Nutzung erfolgt vollständig auf eigene Gefahr und eigene Verantwortung.** Der Autor
übernimmt **keinerlei Haftung** für direkte oder indirekte Schäden, Datenverluste,
Fehlfunktionen, Ausfälle oder sonstige Folgen, die aus der Installation, Konfiguration oder
Nutzung dieser Software entstehen – gleich aus welchem Rechtsgrund.

Zu beachten ist insbesondere, dass Claude **eigenständig Skripte ändern, ausführen und
löschen** kann. Vor dem produktiven Einsatz wird dringend ein **vollständiges Backup** des
IP-Symcon Systems empfohlen. Jeder Nutzer ist selbst dafür verantwortlich, Änderungen vor
dem Übernehmen zu prüfen.

Die Software wird „wie besehen" („as is") ohne jegliche Gewährleistung bereitgestellt, wie
in der [MIT-Lizenz](LICENSE) ausgeführt.