chore: add MCP integration and refactor documentation into modular how-to guides

- Moved GraphQL query samples into a new `docs/queries` directory for better organization.
- Added new queries and mutations, including `createHost.graphql` and `GetApiVersion.graphql`.
- Introduced `mcp-config.yaml` and updated `docker-compose.yml` for MCP integration.
- Updated IntelliJ `.idea/workspace.xml` settings to reflect project changes.
- Added new how-to guides (`docs/howtos`) for permissions, tags, MCP integration, and schema usage.
- Enhanced tests by updating file paths and improving sample data locations.
- Refined permissions and host group structures in `zabbix-hostgroups.ts` and `resolvers.ts`.

docs/queries/sample_all_devices_query.graphql

@@ -0,0 +1,21 @@
+### Query
+Use this query to list all devices (hosts with device type and state).
+
+```graphql
+query AllDevices($name_pattern: String, $with_items: Boolean) {
+  allDevices(name_pattern: $name_pattern, with_items: $with_items) {
+    hostid
+    host
+    name
+    deviceType
+  }
+}
+```
+
+### Variables
+```json
+{
+  "name_pattern": "%",
+  "with_items": true
+}
+```

docs/queries/sample_all_host_groups_query.graphql

@@ -0,0 +1,18 @@
+### Query
+# Use this query to list all host groups.
+
+```graphql
+query AllHostGroups($search_name: String) {
+  allHostGroups(search_name: $search_name) {
+    groupid
+    name
+  }
+}
+```
+
+### Variables
+```json
+{
+  "search_name": "Roadwork/*"
+}
+```

docs/queries/sample_all_hosts_query.graphql

@@ -0,0 +1,25 @@
+### Query
+Use this query to list all hosts, filtered by name pattern and/or device type.
+
+```graphql
+query AllHosts($name_pattern: String, $tag_deviceType: [String]) {
+  allHosts(name_pattern: $name_pattern, tag_deviceType: $tag_deviceType) {
+    hostid
+    host
+    name
+    deviceType
+    hostgroups {
+      groupid
+      name
+    }
+  }
+}
+```
+
+### Variables
+```json
+{
+  "name_pattern": "BT_%",
+  "tag_deviceType": ["bt_device_tracker_generic"]
+}
+```

docs/queries/sample_all_template_groups_query.graphql

@@ -0,0 +1,18 @@
+### Query
+Use this query to list all template groups.
+
+```graphql
+query AllTemplateGroups($name_pattern: String) {
+  allTemplateGroups(name_pattern: $name_pattern) {
+    groupid
+    name
+  }
+}
+```
+
+### Variables
+```json
+{
+  "name_pattern": "Templates/Roadwork/*"
+}
+```

docs/queries/sample_delete_template_groups_mutation.graphql

@@ -0,0 +1,30 @@
+### Mutation
+Use this mutation to delete template groups by their numeric IDs or by a name pattern.
+
+```graphql
+mutation DeleteTemplateGroups($groupids: [Int!], $name_pattern: String) {
+  deleteTemplateGroups(groupids: $groupids, name_pattern: $name_pattern) {
+    id
+    message
+    error {
+      message
+      code
+      data
+    }
+  }
+}
+```
+
+### Variables (by ID)
+```json
+{
+  "groupids": [201]
+}
+```
+
+### Variables (by name pattern)
+```json
+{
+  "name_pattern": "Templates/Roadwork/%"
+}
+```

docs/queries/sample_delete_templates_mutation.graphql

@@ -0,0 +1,30 @@
+### Mutation
+Use this mutation to delete templates by their numeric IDs or by a name pattern.
+
+```graphql
+mutation DeleteTemplates($templateids: [Int!], $name_pattern: String) {
+  deleteTemplates(templateids: $templateids, name_pattern: $name_pattern) {
+    id
+    message
+    error {
+      message
+      code
+      data
+    }
+  }
+}
+```
+
+### Variables (by ID)
+```json
+{
+  "templateids": [501]
+}
+```
+
+### Variables (by name pattern)
+```json
+{
+  "name_pattern": "BT_DEVICE_TRACKER%"
+}
+```

docs/queries/sample_export_user_rights_query.graphql

@@ -0,0 +1,28 @@
+### Query
+Use this query to export all user rights (roles and groups).
+
+```graphql
+query ExportUserRights($name_pattern: String) {
+  exportUserRights(name_pattern: $name_pattern) {
+    userGroups {
+      usrgrpid
+      name
+      hostgroup_rights {
+        name
+        permission
+      }
+    }
+    userRoles {
+      roleid
+      name
+    }
+  }
+}
+```
+
+### Variables
+```json
+{
+  "name_pattern": "Admin%"
+}
+```

docs/queries/sample_import_distance_tracker_template.graphql

@@ -0,0 +1,125 @@
+### Mutation
+Use this mutation to import a template specifically designed to work with the `DistanceTrackerDevice` type provided in the `location_tracker_devices.graphql` schema extension.
+
+This template uses Zabbix Agent 2 MQTT keys (`mqtt.get`) to subscribe to a broker and retrieve device data, which is then parsed into a hierarchical structure compatible with the GraphQL API's dynamic resolvers.
+
+```graphql
+mutation ImportDistanceTrackerTemplate($templates: [CreateTemplate!]!) {
+  importTemplates(templates: $templates) {
+    host
+    templateid
+    message
+    error {
+      message
+      code
+      data
+    }
+  }
+}
+```
+
+### Variables
+The following sample defines the `DISTANCE_TRACKER` template. Note the `deviceType` tag set to `DistanceTrackerDevice`, which instructs the GraphQL API to resolve this host using the specialized `DistanceTrackerDevice` type.
+
+The item keys use the `json_` prefix where appropriate (e.g., `state.current.json_distances`) to ensure that the JSON strings received from Zabbix are automatically parsed into objects/arrays by the GraphQL resolver.
+
+```json
+{
+  "templates": [
+    {
+      "host": "DISTANCE_TRACKER",
+      "name": "Distance Tracker Device Template",
+      "groupNames": ["Templates/Roadwork/Devices"],
+      "templates": [
+        { "name": "ROADWORK_DEVICE" }
+      ],
+      "tags": [
+        { "tag": "class", "value": "roadwork" },
+        { "tag": "deviceType", "value": "DistanceTrackerDevice" }
+      ],
+      "items": [
+        {
+          "name": "MQTT Master Data",
+          "type": 0,
+          "key": "mqtt.get[\"tcp://mqtt-broker:1883\",\"device/distance_tracker/data\"]",
+          "value_type": 4,
+          "history": "0",
+          "description": "Master item receiving full JSON payload via MQTT Agent 2"
+        },
+        {
+          "name": "Device Count",
+          "type": 18,
+          "key": "state.current.count",
+          "value_type": 3,
+          "history": "7d",
+          "master_item": {
+            "key": "mqtt.get[\"tcp://mqtt-broker:1883\",\"device/distance_tracker/data\"]"
+          },
+          "preprocessing": [
+            {
+              "type": 12,
+              "params": ["$.count"]
+            }
+          ]
+        },
+        {
+          "name": "Time From",
+          "type": 18,
+          "key": "state.current.timeFrom",
+          "value_type": 4,
+          "history": "7d",
+          "master_item": {
+            "key": "mqtt.get[\"tcp://mqtt-broker:1883\",\"device/distance_tracker/data\"]"
+          },
+          "preprocessing": [
+            {
+              "type": 12,
+              "params": ["$.timeFrom"]
+            }
+          ]
+        },
+        {
+          "name": "Time Until",
+          "type": 18,
+          "key": "state.current.timeUntil",
+          "value_type": 4,
+          "history": "7d",
+          "master_item": {
+            "key": "mqtt.get[\"tcp://mqtt-broker:1883\",\"device/distance_tracker/data\"]"
+          },
+          "preprocessing": [
+            {
+              "type": 12,
+              "params": ["$.timeUntil"]
+            }
+          ]
+        },
+        {
+          "name": "Nearby Distances",
+          "type": 18,
+          "key": "state.current.json_distances",
+          "value_type": 4,
+          "history": "7d",
+          "master_item": {
+            "key": "mqtt.get[\"tcp://mqtt-broker:1883\",\"device/distance_tracker/data\"]"
+          },
+          "preprocessing": [
+            {
+              "type": 12,
+              "params": ["$.distances"]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Technical Note: Hierarchical Mapping
+The `DistanceTrackerDevice` type in the schema extension is mapped using `createHierarchicalValueFieldResolver`. This resolver expects Zabbix items to follow a naming convention that mirrors the GraphQL structure:
+
+- `state.current.count` maps to `state { current { count } }`
+- `state.current.json_distances` maps to `state { current { distances } }` (with automatic JSON parsing due to the `json_` prefix)
+
+The `mqtt.get` keys replace the older `mqtt.trap` style, leveraging the Zabbix Agent 2 MQTT plugin for active topic subscriptions.

docs/queries/sample_import_host_groups_mutation.graphql

@@ -0,0 +1,28 @@
+### Mutation
+Use this mutation to import host groups.
+
+```graphql
+mutation ImportHostGroups($hostGroups: [CreateHostGroup!]!) {
+  importHostGroups(hostGroups: $hostGroups) {
+    groupName
+    groupid
+    message
+    error {
+      message
+      code
+      data
+    }
+  }
+}
+```
+
+### Variables
+```json
+{
+  "hostGroups": [
+    {
+      "groupName": "ConstructionSite/Test"
+    }
+  ]
+}
+```

docs/queries/sample_import_host_template_groups_mutation.graphql

@@ -0,0 +1,55 @@
+### Mutation
+Use this mutation to import template groups for hosts and templates.
+
+```graphql
+mutation ImportTemplateGroups($templateGroups: [CreateTemplateGroup!]!) {
+  importTemplateGroups(templateGroups: $templateGroups) {
+    groupName
+    groupid
+    message
+    error {
+      message
+      code
+      data
+    }
+  }
+}
+```
+
+### Variables
+This sample data is based on the `template_groups` from `src/testdata/templates/zbx_default_templates_vcr.yaml`, excluding the permission groups.
+
+```json
+{
+  "templateGroups": [
+    {
+      "uuid": "376524057e094c07aaa0cf7f524849dc",
+      "groupName": "Templates/Roadwork/Controller"
+    },
+    {
+      "uuid": "7d83c76454564390bb0e34600780eaec",
+      "groupName": "Templates/Roadwork/Device-Capabilities"
+    },
+    {
+      "uuid": "48d5d2a18a08448c96a931b63bb2c97d",
+      "groupName": "Templates/Roadwork/Device-Capabilities/FLASH_ATTACHABLE"
+    },
+    {
+      "uuid": "785986b84892468ea2e92d912747b1d3",
+      "groupName": "Templates/Roadwork/Device-Capabilities/GEOLOCALIZABLE"
+    },
+    {
+      "uuid": "a4b79479e97a4b48972dcb476d45e55a",
+      "groupName": "Templates/Roadwork/Device-Capabilities/HAS_OPERATIONAL_DATA"
+    },
+    {
+      "uuid": "3604af8102644bee9dcaf0f9c1ee93a1",
+      "groupName": "Templates/Roadwork/Devices"
+    },
+    {
+      "uuid": "5ad0bd9e42a4487e869e9e41b38fe553",
+      "groupName": "Templates/Roadwork/DisplayLibrary"
+    }
+  ]
+}
+```

docs/queries/sample_import_hosts_mutation.graphql

@@ -0,0 +1,36 @@
+### Mutation
+Use this mutation to import hosts and assign them to host groups.
+
+```graphql
+mutation ImportHosts($hosts: [CreateHost!]!) {
+  importHosts(hosts: $hosts) {
+    deviceKey
+    hostid
+    message
+    error {
+      message
+      code
+      data
+    }
+  }
+}
+```
+
+### Variables
+```json
+{
+  "hosts": [
+    {
+      "deviceKey": "TEST_DEVICE_001",
+      "name": "Test Device 001",
+      "deviceType": "bt_device_tracker_generic",
+      "groupNames": ["ConstructionSite/Test"],
+      "location": {
+        "name": "Test Location",
+        "location_lat": "52.5200",
+        "location_lon": "13.4050"
+      }
+    }
+  ]
+}
+```

docs/queries/sample_import_permissions_template_groups_mutation.graphql

@@ -0,0 +1,38 @@
+### Mutation
+Use this mutation to import template groups used for permission management.
+
+```graphql
+mutation ImportTemplateGroups($templateGroups: [CreateTemplateGroup!]!) {
+  importTemplateGroups(templateGroups: $templateGroups) {
+    groupName
+    groupid
+    message
+    error {
+      message
+      code
+      data
+    }
+  }
+}
+```
+
+### Variables
+This sample data contains template groups used to model application-level permissions on the Zabbix side.
+The data is based on the `Permissions/` groups from `src/testdata/templates/zbx_default_templates_vcr.yaml`.
+
+```json
+{
+  "templateGroups": [
+    {
+      "uuid": "43aab460fe444f18886b19948413b7e3",
+      "groupName": "Permissions/ConstructionSite"
+    },
+    {
+      "groupName": "Permissions/Automatism"
+    },
+    {
+      "groupName": "Permissions/Automatism/Status"
+    }
+  ]
+}
+```

docs/queries/sample_import_templates_mutation.graphql

@@ -0,0 +1,98 @@
+### Mutation
+Use this mutation to import templates along with their items, tags, and linked templates.
+
+```graphql
+mutation ImportTemplates($templates: [CreateTemplate!]!) {
+  importTemplates(templates: $templates) {
+    host
+    templateid
+    message
+    error {
+      message
+      code
+      data
+    }
+  }
+}
+```
+
+### Variables
+This sample data is based on the `BT_DEVICE_TRACKER` template from `src/testdata/templates/zbx_default_templates_vcr.yaml`.
+
+```json
+{
+  "templates": [
+    {
+      "uuid": "27474f627cb344b782a81c16d7e0c7d1",
+      "host": "BT_DEVICE_TRACKER",
+      "name": "BT_DEVICE_TRACKER",
+      "groupNames": ["Templates/Roadwork/Devices"],
+      "templates": [
+        { "name": "ROADWORK_DEVICE" }
+      ],
+      "tags": [
+        { "tag": "class", "value": "roadwork" },
+        { "tag": "deviceType", "value": "bt_device_tracker_generic" }
+      ],
+      "items": [
+        {
+          "uuid": "d4d3ec9f3ca940a39a721b6cfd2f3471",
+          "name": "location",
+          "type": 18,
+          "key": "location",
+          "value_type": 4,
+          "history": "2d",
+          "preprocessing": [
+            {
+              "type": 21,
+              "params": [
+                "var obj=JSON.parse(value);\n\nif (obj[\"isFiltered\"]) {\n  throw \"Result is filtered\";\n  return \"filtered\";\n}\n\nreturn value;"
+              ]
+            },
+            {
+              "type": 15,
+              "params": ["filtered"],
+              "error_handler": 1
+            }
+          ],
+          "master_item": {
+            "key": "mqtt.get[\"tcp://mqtt-broker:1883\",\"deviceValue/location\"]"
+          }
+        },
+        {
+          "uuid": "380c4a7d752848cba3b5a59a0f9b13c0",
+          "name": "MQTT_LOCATION",
+          "type": 0,
+          "key": "mqtt.get[\"tcp://mqtt-broker:1883\",\"deviceValue/location\"]",
+          "value_type": 4,
+          "history": "0"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Mapping Reference
+When converting from Zabbix YAML/XML exports, use the following numeric mappings for items and preprocessing:
+
+#### Item Type (`type`)
+- `0`: ZABBIX_AGENT
+- `2`: ZABBIX_TRAP (TRAP)
+- `18`: DEPENDANT_ITEM (DEPENDENT)
+- `21`: SIMULATOR_JAVASCRIPT (JAVASCRIPT)
+
+#### Value Type (`value_type`)
+- `0`: Float
+- `3`: Int (Numeric unsigned)
+- `4`: Text
+
+#### Preprocessing Type (`type`)
+- `12`: JSONPATH
+- `15`: NOT_MATCHES_REGEX
+- `21`: JAVASCRIPT
+
+#### Error Handler (`error_handler`)
+- `1`: DISCARD_VALUE
+- `2`: SET_VALUE
+- `3`: SET_ERROR

docs/queries/sample_import_user_rights_mutation.graphql

@@ -0,0 +1,50 @@
+### Mutation
+Use this mutation to import user rights (roles and groups).
+
+```graphql
+mutation ImportUserRights($input: UserRightsInput!, $dryRun: Boolean) {
+  importUserRights(input: $input, dryRun: $dryRun) {
+    userRoles {
+      id
+      name
+      message
+    }
+    userGroups {
+      id
+      name
+      message
+    }
+  }
+}
+```
+
+### Variables
+```json
+{
+  "input": {
+    "userRoles": [
+      {
+        "name": "Test Role",
+        "type": 1,
+        "rules": {
+          "api_access": 1,
+          "api": ["host.get", "item.get"]
+        }
+      }
+    ],
+    "userGroups": [
+      {
+        "name": "Test Group",
+        "gui_access": 0,
+        "hostgroup_rights": [
+          {
+            "name": "ConstructionSite/Test",
+            "permission": "READ_WRITE"
+          }
+        ]
+      }
+    ]
+  },
+  "dryRun": false
+}
+```

docs/queries/sample_templates_query.graphql

@@ -0,0 +1,18 @@
+### Query
+Use this query to verify the results of the template import.
+
+```graphql
+query GetTemplates($name_pattern: String) {
+  templates(name_pattern: $name_pattern) {
+    templateid
+    name
+  }
+}
+```
+
+### Variables
+```json
+{
+  "name_pattern": "BT_DEVICE_TRACKER"
+}
+```