MCP Tools API#

Referencja techniczna narzędzi MCP udostępnianych przez vCLU. Opis z perspektywy klienta MCP.

Transport#

Endpoint: /mcp
Protokół: HTTP + SSE (Streamable HTTP), JSON-RPC 2.0
Autoryzacja: Authorization: Bearer <api-key>

Narzędzia#

vclu_devices#

Lista urządzeń.

Input Schema:

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "Filter by device type (switch, light, dimmer, cover, sensor, scene, etc.)"
    }
  }
}

Response: {"devices": [Device, ...]}

vclu_device_get#

Szczegóły urządzenia.

Input Schema:

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Device path (e.g., CLU_MAIN.DOU0001)"
    }
  },
  "required": ["path"]
}

Response: DeviceDetail (Device + events, caps)

vclu_device_set#

Ustaw wartość urządzenia.

Input Schema:

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Device path"
    },
    "value": {
      "description": "Value to set (1/0 for switches, 0-100 for dimmers, etc.)"
    }
  },
  "required": ["path", "value"]
}

Response: {"ok": true, "new_state": "0"} lub {"ok": false, "error": "..."}

vclu_device_execute#

Wywołaj metodę na urządzeniu.

Input Schema:

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Device path"
    },
    "method": {
      "type": "string",
      "description": "Method name to execute"
    },
    "args": {
      "type": "array",
      "description": "Optional arguments for the method"
    }
  },
  "required": ["path", "method"]
}

Response: {"ok": true, "result": null} lub {"ok": false, "error": "..."}

vclu_scenes#

Lista scen.

Input Schema:

{
  "type": "object",
  "properties": {}
}

Response: {"scenes": [{"path": "...", "name": "..."}, ...]}

vclu_scene_execute#

Uruchom scenę.

Input Schema:

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Scene path"
    }
  },
  "required": ["path"]
}

Response: {"ok": true} lub {"ok": false, "error": "..."}

Zasoby (Resources)#

vclu://devices#

Snapshot JSON wszystkich widocznych urządzeń (filtrowanych przez ACL).

URI: vclu://devices
MIME: application/json
Typ: static

vclu://device/{path}#

Szczegóły jednego urządzenia.

URI Template: vclu://device/{path}
MIME: application/json
Typ: template

Typy danych#

Device#

{
  "path": "string",
  "type": "string",
  "name": "string",
  "state": "any",
  "readonly": "boolean",
  "methods": ["string"],
  "lastChanged": "number|null"
}

DeviceDetail#

Rozszerzenie Device o:

{
  "events": ["string"],
  "caps": {}
}

Kody błędów#

Kod HTTP	Przyczyna
401	Brak lub nieprawidłowy Bearer token
503	Serwer MCP wyłączony

Błędy na poziomie narzędzi (np. device readonly, device not found) zwracane są w odpowiedzi MCP z isError: true.