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/howtos/README.md

@@ -0,0 +1,24 @@
+# How-To Guides
+
+This directory contains detailed guides on how to use and extend the Zabbix GraphQL API.
+
+## Available Guides
+
+### 📊 [Schema and Schema Extension](./schema.md)
+Learn about the GraphQL schema structure, how Zabbix entities map to GraphQL types, and how to use the dynamic schema extension system.
+
+### 🗂️ [Hierarchical Data Mapping](./hierarchical_data_mapping.md)
+Understand how the API automatically maps flat Zabbix item keys into nested GraphQL objects using hierarchical resolvers and type hinting.
+
+### 🔐 [Roles and Permissions Extension](./permissions.md)
+Discover how the permission system works, how to define permission levels using Zabbix template groups, and how to query user permissions.
+
+### 🏷️ [Zabbix Tags Usage](./tags.md)
+Learn how Zabbix tags are used for device classification, host categorization, and as metadata within the GraphQL API.
+
+### 🤖 [MCP Integration](./mcp.md)
+Discover how to integrate the Zabbix GraphQL API with the Model Context Protocol (MCP) to enable LLMs to interact with your Zabbix data.
+
+---
+
+For practical examples of GraphQL operations, check the [Sample Queries](../queries/) directory.

docs/howtos/hierarchical_data_mapping.md

@@ -0,0 +1,41 @@
+## 🗂️ Hierarchical Data Mapping
+
+The API automatically maps Zabbix items to nested GraphQL objects using the `createHierarchicalValueFieldResolver` function.
+
+### How it Works
+
+Zabbix item keys are used to define the structure in GraphQL. A dot (`.`) acts as a separator to represent nested object structures.
+
+**Example:**
+Zabbix item key `state.current.values.temperature` is automatically mapped to:
+```json
+{
+  "state": {
+    "current": {
+      "values": {
+        "temperature": 25.5
+      }
+    }
+  }
+}
+```
+
+### Type Hinting
+
+You can guide the type conversion by prepending a type hint and an underscore to the last token of the Zabbix item key:
+
+*   `json_`: Parses the value as a JSON object (useful for complex types).
+*   `str_`: Forces the value to be treated as a string.
+*   `bool_`: Forces the value to be treated as a boolean.
+*   `float_`: Forces the value to be treated as a number.
+
+### Preconditions
+
+1.  **Key Naming**: Zabbix item keys (or tags) must match the GraphQL field names.
+2.  **Dot Separation**: Use dots to represent the desired hierarchy.
+
+The `createHierarchicalValueFieldResolver` function (found in `../../src/api/resolver_helpers.ts`) dynamically creates these resolvers, eliminating the need for manual resolver definitions for each hierarchical field.
+
+For more information, see the comments in `../../schema/device_value_commons.graphql` and `../../src/api/resolver_helpers.ts`.
+
+See `../queries/sample_all_devices_query.graphql` for examples of hierarchical data in query results.

docs/howtos/mcp.md

@@ -0,0 +1,65 @@
+## 🤖 Model Context Protocol (MCP) Integration
+
+The Zabbix GraphQL API supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), enabling Large Language Models (LLMs) to interact directly with your Zabbix data through a standardized interface.
+
+### Overview
+
+By leveraging GraphQL, the API provides a strongly-typed and introspectable interface that is ideal for MCP. This allows LLMs to:
+- Discover available queries and mutations.
+- Understand the data structures (hosts, items, templates, etc.).
+- Execute operations to retrieve or modify Zabbix data based on natural language prompts.
+
+### Running Apollo MCP Server with Docker Compose
+
+You can start both the Zabbix GraphQL API and the Apollo MCP Server using Docker Compose. This setup uses a local `mcp-config.yaml` and a generated `schema.graphql`.
+
+1.  **Prerequisites**: Ensure you have a `.env` file with the required Zabbix connection details.
+2.  **Generate Schema**: Generate the combined schema file required by the MCP server:
+    ```bash
+    cat schema/*.graphql > schema.graphql
+    ```
+3.  **Prepare Operations**: Create the operations directory if it doesn't exist:
+    ```bash
+    mkdir -p mcp/operations
+    ```
+4.  **Start Services**:
+    ```bash
+    docker-compose up -d
+    ```
+
+This will:
+- Start the `zabbix-graphql-api` on `http://localhost:4001/graphql` (internal port 4000).
+- Start the `apollo-mcp-server` on `http://localhost:3000/mcp` (mapped from internal port 8000), configured to connect to the local API via `mcp-config.yaml`.
+
+### Using with Claude Desktop
+
+To use this integration with Claude Desktop, add the following configuration to your Claude Desktop config file (typically `appflowy.json` or similar depending on OS, but usually `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "zabbix-graphql": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-v", "/path/to/your/project/mcp-config.yaml:/mcp-config.yaml",
+        "-v", "/path/to/your/project/schema.graphql:/schema.graphql",
+        "-v", "/path/to/your/project/mcp/operations:/mcp/operations",
+        "-e", "APOLLO_GRAPH_REF=local@main",
+        "ghcr.io/apollographql/apollo-mcp-server:latest",
+        "/mcp-config.yaml"
+      ]
+    }
+  }
+}
+```
+
+**Note**: Ensure the `zabbix-graphql-api` is running and accessible. If running locally, you might need to use `host.docker.internal:4001/graphql` in your `mcp-config.yaml` to allow the containerized MCP server to reach your host.
+
+### Benefits of GraphQL-enabled MCP
+
+- **Self-Documenting**: The GraphQL schema provides all necessary metadata for the LLM to understand how to use the tools.
+- **Efficient**: LLMs can request exactly the data they need, reducing token usage and improving response speed.
+- **Secure**: Uses the same authentication and permission model as the rest of the API.

docs/howtos/permissions.md

@@ -0,0 +1,49 @@
+## 🔐 Roles and Permissions Extension
+
+The API implements a permission system using Zabbix template groups:
+
+### Permission Template Groups
+
+- Template groups with prefix `Permissions/` (configurable via `ZABBIX_PERMISSION_TEMPLATE_GROUP_NAME_PREFIX`) are used for permissions
+- Users gain permissions by being assigned to user groups that have access to these permission template groups
+
+### Available Permissions
+
+The system supports three permission levels defined in `../../schema/api_commons.graphql`:
+
+- `DENY`: Explicitly denies access (supersedes other permissions)
+- `READ`: Allows viewing/reading access
+- `READ_WRITE`: Allows both reading and writing (implies READ permission)
+
+### Permission Object Names
+
+Permission object names map to Zabbix template group paths: `Permissions/{objectName}`
+
+### GraphQL Permission Queries
+
+```graphql
+# Check if current user has specific permissions
+query HasPermissions {
+  hasPermissions(permissions: [
+    { objectName: "hosts", permission: READ },
+    { objectName: "templates", permission: READ_WRITE }
+  ])
+}
+
+# Get all user permissions
+query GetUserPermissions {
+  userPermissions(objectNames: ["hosts", "templates"])
+}
+```
+
+### Setting Up Permissions
+
+1. Create template groups with the prefix `Permissions/` (e.g., `Permissions/hosts`, `Permissions/templates`)
+2. Assign these template groups to user groups in Zabbix with appropriate permission levels
+3. Users in those user groups will inherit the permissions
+
+### Detailed Permission Usage Examples
+
+For comprehensive examples of permission usage patterns, see `../../schema/api_commons.graphql` which contains detailed documentation in the `PermissionRequest` input type comments, including real-world examples of how to model permissions for buttons, status controls, and application features.
+
+See also `../queries/sample_import_permissions_template_groups_mutation.graphql` for examples of importing permission template groups.

docs/howtos/schema.md

@@ -0,0 +1,62 @@
+## 📊 Schema and Schema Extension
+
+### Main Schema Structure
+
+The GraphQL schema is located in the `../../schema/` directory and consists of:
+
+- `queries.graphql` - Query definitions (see detailed documentation in file comments)
+- `mutations.graphql` - Mutation definitions (see detailed documentation in file comments)
+- `devices.graphql` - Device-related types (see detailed documentation in file comments)
+- `zabbix.graphql` - Zabbix-specific types (see detailed documentation in file comments)
+- `device_value_commons.graphql` - Common value types (see detailed documentation in file comments)
+- `api_commons.graphql` - Common API types and permission system (see detailed documentation in file comments)
+- `extensions/` - Custom device type extensions
+
+For comprehensive understanding of each operation, read the detailed comments in the respective schema files.
+
+### Zabbix to GraphQL Mapping
+
+The API maps Zabbix entities to GraphQL types as follows:
+
+| Zabbix Entity | GraphQL Type | Description |
+|---------------|--------------|-------------|
+| Host | `Host` / `Device` | Represents a Zabbix host; `Device` is a specialized `Host` with a `deviceType` tag |
+| Host Group | `HostGroup` | Represents a Zabbix host group |
+| Template | `Template` | Represents a Zabbix template |
+| Template Group | `HostGroup` | Represents a Zabbix template group |
+| Item | Nested fields in `Device` | Zabbix items become nested fields in the device based on their key names |
+| Tag | `Tag` | Represents a Zabbix tag associated with a host or template |
+| Inventory | `Location` | Host inventory information maps to location data |
+
+### Zabbix Entity Relationships
+
+- **Host Groups**: Organize hosts and templates hierarchically; represented as `HostGroup` objects in GraphQL
+- **Templates**: Contain items and other configuration that can be applied to hosts; linked via template groups
+- **Items**: Individual metrics collected from hosts; automatically mapped to nested GraphQL fields based on their key names
+- **Tags**: Metadata associated with hosts/templates; used for classification and filtering
+
+### Location Type Usage
+
+The `Location` type represents geographical information from Zabbix host inventory:
+
+- **Fields**: Includes `name`, `location_lat`, `location_lon`, and other inventory attributes
+- **Usage**: Available through the `locations` query and as part of host/device objects
+- **Access**: Retrieved via the `getLocations` method in the Zabbix API datasource
+
+### Dynamic Schema Extension
+
+Extend the schema without code changes using environment variables:
+
+```bash
+ADDITIONAL_SCHEMAS=./schema/extensions/display_devices.graphql,./schema/extensions/location_tracker_devices.graphql
+ADDITIONAL_RESOLVERS=SinglePanelDevice,FourPanelDevice,DistanceTrackerDevice
+```
+
+This enables runtime schema extension for custom device types without modifying the core code.
+
+### Sample Operations
+
+For practical examples of schema usage, see the sample files in the `../queries/` directory:
+- `../queries/sample_all_devices_query.graphql` - Example of querying all devices
+- `../queries/sample_import_templates_mutation.graphql` - Example of importing templates
+- `../queries/sample_import_host_groups_mutation.graphql` - Example of importing host groups

docs/howtos/tags.md

@@ -0,0 +1,36 @@
+## 🏷️ Zabbix Tags Usage
+
+Zabbix tags are used for:
+
+- Device classification (`deviceType` tag)
+- Host categorization (`hostType` tag)
+- Custom metadata storage
+- Permission assignment through template groups
+
+### The `hostType` Tag
+
+The `hostType` tag is used to categorize hosts and templates. This allows the API to provide default filters for specific application domains or device categories.
+
+To classify a host or a template, add a tag in Zabbix:
+*   **Tag Name**: `hostType`
+*   **Tag Value**: A string representing the category (e.g., `Roadwork/Devices`, `SmartCity/Sensors`).
+
+This tag can be defined directly on the host or on a template (where linked hosts will inherit it).
+
+### Default Filtering with `HOST_TYPE_FILTER_DEFAULT`
+
+By configuring the `HOST_TYPE_FILTER_DEFAULT` environment variable, you can set a global default for the `allHosts` and `allDevices` queries. 
+
+*   If `HOST_TYPE_FILTER_DEFAULT=Roadwork/Devices` is set, `allHosts` will only return hosts with that tag value.
+*   This default can be overridden in the GraphQL query by passing the `tag_hostType` argument.
+
+### Search Filtering with `HOST_GROUP_FILTER_DEFAULT`
+
+The `HOST_GROUP_FILTER_DEFAULT` variable provides a default search pattern for the `allHostGroups` query, useful for restricting the visible host group hierarchy.
+
+*   **Overriding**: Providing the `search_name` argument in the `allHostGroups` query overrides this default.
+*   **Wildcards**: The `search_name` parameter supports the `*` wildcard. For example, `Roadwork/Devices/*` finds all subgroups within that path.
+
+For more information, see the comments in `../../schema/devices.graphql` and `../../schema/zabbix.graphql`.
+
+See `../queries/sample_all_hosts_query.graphql` and `../queries/sample_all_devices_query.graphql` for examples.