Narzędzia (Tools)#

vCLU udostępnia 6 narzędzi MCP, które AI wykorzystuje do interakcji z inteligentnym domem. Narzędzia dzielą się na dwie kategorie: odczyt (nie wymagają uprawnień sterowania) i sterowanie (wymagają pełnego dostępu).

Przegląd#

vclu_devices#

Zwraca listę wszystkich widocznych urządzeń z ich aktualnym stanem.

Parametry#

Przykład odpowiedzi#

{
  "devices": [
    {
      "path": "CLU_SALON.DOU0001",
      "type": "switch",
      "name": "Salon Kanapa",
      "state": "0",
      "readonly": false,
      "methods": ["toggle", "switchOn", "switchOff"]
    },
    {
      "path": "CLU_SALON.DOU0002",
      "type": "switch",
      "name": "Salon Stół",
      "state": "1",
      "readonly": false,
      "methods": ["toggle", "switchOn", "switchOff"]
    },
    {
      "path": "CLU_KUCHNIA.DIMM0001",
      "type": "dimmer",
      "name": "Kuchnia LED",
      "state": "75",
      "readonly": false,
      "methods": ["toggle", "switchOn", "switchOff"]
    }
  ]
}

Użycie z filtrem#

Wywołanie vclu_devices(type: "cover") zwróci tylko rolety:

{
  "devices": [
    {
      "path": "CLU_SALON.ROL0001",
      "type": "cover",
      "name": "Roleta Salon",
      "state": "100",
      "readonly": false,
      "methods": ["open", "close", "stop"]
    }
  ]
}

Jak AI używa tego narzędzia#

Gdy powiesz “co jest włączone?”, AI wywoła vclu_devices, przejrzy pole state każdego urządzenia i odpowie naturalnym językiem:

AI:  Włączone urządzenia:
     - Salon Stół (switch)
     - Kuchnia LED (dimmer, jasność 75%)
     Reszta jest wyłączona.

vclu_device_get#

Zwraca szczegółowe informacje o jednym urządzeniu, włącznie z dostępnymi zdarzeniami i możliwościami (capabilities).

Parametry#

Przykład odpowiedzi#

{
  "path": "CLU_SALON.DOU0001",
  "type": "switch",
  "name": "Salon Kanapa",
  "state": "1",
  "readonly": false,
  "methods": ["toggle", "switchOn", "switchOff"],
  "events": ["onSwitchChange"],
  "caps": {
    "min": 0,
    "max": 1
  }
}

vclu_device_set#

Ustawia wartość urządzenia. Używane do włączania/wyłączania przełączników, ustawiania jasności dimmerów, pozycji rolet itp.

Parametry#

Wartości zależą od typu urządzenia#

Przykład odpowiedzi#

{
  "ok": true,
  "new_state": "0"
}

Błąd - urządzenie readonly#

{
  "ok": false,
  "error": "device is read-only"
}

vclu_device_execute#

Wywołuje metodę na urządzeniu. Metody są specyficzne dla typu urządzenia.

Parametry#

Popularne metody#

Przykład odpowiedzi#

{
  "ok": true,
  "result": null
}

Kiedy set a kiedy execute?#

• set - gdy znasz docelową wartość: “ustaw jasność na 50%”, “włącz światło”
• execute - gdy chcesz wywołać akcję: “przełącz” (toggle), “zatrzymaj roletę” (stop)

AI automatycznie wybiera odpowiednie narzędzie na podstawie Twojej komendy.

vclu_scenes#

Zwraca listę wszystkich scen zdefiniowanych w vCLU.

Parametry#

Brak.

Przykład odpowiedzi#

{
  "scenes": [
    {
      "path": "vclu.tryb_filmowy",
      "name": "Tryb filmowy"
    },
    {
      "path": "vclu.dobranoc",
      "name": "Dobranoc"
    },
    {
      "path": "vclu.poranek",
      "name": "Poranek"
    }
  ]
}

vclu_scene_execute#

Uruchamia scenę. Scena wykonuje predefiniowany zestaw akcji (np. zgaś światła, zamknij rolety, ustaw dimmer).

Parametry#

Przykład odpowiedzi#

{
  "ok": true
}

Zasoby (Resources)#

Oprócz narzędzi, vCLU udostępnia zasoby MCP - statyczne dane, które AI może odczytać jako kontekst.

vclu://devices#

Snapshot JSON wszystkich widocznych urządzeń. AI może go użyć, żeby zrozumieć układ domu bez wywoływania narzędzia.

vclu://device/{path}#

Szczegóły konkretnego urządzenia (template URI). AI podstawia ścieżkę urządzenia, np. vclu://device/CLU_SALON.DOU0001.

Flaga readonly#

Urządzenia z flagą readonly: true są widoczne, ale nie można ich sterować. Próba użycia vclu_device_set lub vclu_device_execute na takim urządzeniu zwróci błąd.

Readonly może wynikać z dwóch źródeł:

1. expose() z opcją readonly: true - ustawione w kodzie Lua
2. AccessControl - administrator ograniczył dostęp MCP do odczytu

AI widzi flagę readonly i informuje użytkownika zamiast próbować sterować:

Ty:   "Włącz lampę w salonie"
AI:   Lampa w salonie jest oznaczona jako tylko do odczytu
      - nie mogę jej sterować przez MCP.
      Aktualny stan: wyłączona.

Następny krok#

Model bezpieczeństwa - jak vCLU chroni dostęp do urządzeń