docs: refactor documentation and upgrade to Node.js 24

This commit upgrades the project to Node.js 24 (LTS) and performs a major refactoring of the documentation to support both advanced users and AI-based automation (MCP). Changes: - Environment & CI/CD: - Set Node.js version to >=24 in package.json and .nvmrc. - Updated Dockerfile to use Node 24 base image. - Updated @types/node to ^24.10.9. - Documentation: - Refactored README.md with comprehensive technical reference, configuration details, and Zabbix-to-GraphQL mapping. - Created docs/howtos/cookbook.md with practical recipes for common tasks and AI test generation. - Updated docs/howtos/mcp.md to emphasize GraphQL's advantages for AI agents and Model Context Protocol. - Added readme.improvement.plan.md to track documentation evolution. - Enhanced all how-to guides with improved cross-references and up-to-date information. - Guidelines: - Updated .junie/guidelines.md with Node 24 requirements and enhanced commit message standards (Conventional Commits 1.0.0). - Infrastructure & Code: - Updated docker-compose.yml with Apollo MCP server integration. - Refined configuration and schema handling in src/api/ and src/datasources/. - Synchronized generated TypeScript types with schema updates.
2026-01-30 14:34:09 +01:00 · 2026-01-30 14:34:09 +01:00 · a01bfabfba
commit a01bfabfba
parent 4ec61ffba1
28 changed files with 395 additions and 170 deletions
--- a/README.md
+++ b/README.md
@ -6,37 +6,39 @@ A modern GraphQL interface for Zabbix, providing enhanced features and easier in

 The Zabbix GraphQL API acts as a wrapper and enhancer for the native Zabbix JSON-RPC API. It simplifies complex operations, provides a strongly-typed schema, and adds advanced logic for importing, querying, and managing Zabbix entities like hosts, templates, and user rights.

-## Key Features & Enhancements
+## 🚀 Features

-Compared to the original Zabbix API, this GraphQL API provides several key enhancements:
+- **GraphQL Interface**: Modern GraphQL API wrapping Zabbix functionality
+  - *Reference*: `schema/queries.graphql`, `schema/mutations.graphql`, `src/api/start.ts`

-*   **Mass Import/Export**: Robust support for importing and exporting templates, template groups, hosts, and host groups in bulk.
-*   **Hierarchical Host Groups**: Automatically handles the creation and resolution of nested host group hierarchies (e.g., `Parent/Child/Leaf`).
-*   **Template Management**:
-    *   Full support for template items, including complex preprocessing steps and tags.
-    *   **Dependent Item Support**: Intelligent deferred creation logic to handle item dependencies within a template.
-    *   Linked template resolution by name.
-*   **Advanced Deletion**: Ability to delete templates and template groups not only by ID but also by **name patterns** (supporting Zabbix wildcards like `%`).
-*   **User Rights & Permissions**:
-    *   Integrated management of user roles and user groups.
-    *   Support for importing/exporting user rights with UUID-based matching for cross-instance consistency.
-    *   On-the-fly permission checks (`hasPermissions`, `userPermissions`).
-*   **Improved Error Reporting**: Detailed error data from Zabbix is appended to GraphQL error messages, making debugging significantly easier.
-*   **Strongly Typed Schema**: Leverages GraphQL's type system for clear API documentation and client-side code generation.
-*   **Dynamic Schema Extensibility**: Easily extend the API with custom schema snippets and dynamic resolvers for specialized device types without modifying the core code.
-*   **CI/CD Integration**: Includes a ready-to-use Forgejo/Gitea/GitHub Actions workflow for automated building, testing, and deployment.
-*   **MCP Integration**: Native support for the **Model Context Protocol (MCP)**, enabled by GraphQL's introspectable schema, allowing LLMs to seamlessly interact with Zabbix data.
-*   **Sample Application (VCR)**: Designed to power the **Virtual Control Room**, a professional cockpit for managing thousands of IoT/Edge devices.
+- **Hierarchical Data Mapping**: Automatic mapping of Zabbix items/tags to nested GraphQL objects
+  - *Reference*: `src/api/resolver_helpers.ts`, `schema/device_value_commons.graphql`, `docs/sample_all_devices_query.graphql`
+
+- **Mass Operations**: Import/export capabilities for hosts, templates, and user rights
+  - *Reference*: `schema/mutations.graphql` (importHosts, importTemplates, importUserRights, etc.), `docs/sample_import_*.graphql`
+
+- **Dynamic Schema Extension**: Extend the schema without code changes using environment variables
+  - *Reference*: `src/api/schema.ts`, `schema/extensions/`, `src/common_utils.ts` (ADDITIONAL_SCHEMAS, ADDITIONAL_RESOLVERS)
+
+- **Permission System**: Role-based access control using Zabbix template groups
+  - *Reference*: `schema/api_commons.graphql` (Permission enum, PermissionRequest), `src/api/resolvers.ts` (hasPermissions, userPermissions), `docs/sample_import_permissions_template_groups_mutation.graphql`
+
+- **Type Safety**: Full TypeScript support with generated types
+  - *Reference*: `codegen.ts`, `src/schema/generated/graphql.ts`, `tsconfig.json`, `package.json` (devDependencies for GraphQL Codegen)
+
+- **AI Agent & MCP Enablement**: Native support for Model Context Protocol (MCP) and AI-driven automation. GraphQL's strongly-typed, introspectable nature provides a superior interface for AI agents compared to traditional REST APIs.
+  - *Reference*: `docs/howtos/mcp.md`, `mcp-config.yaml`, `docker-compose.yml` (MCP service)

 ## How-To Guides

 For detailed information on specific topics, please refer to our how-to guides:

+*   [**Cookbook**](./docs/howtos/cookbook.md): Practical, step-by-step recipes for quick start and AI test generation.
 *   [**Schema & Extension Overview**](./docs/howtos/schema.md): Detailed explanation of the schema structure and extension mechanism.
 *   [**Hierarchical Data Mapping**](./docs/howtos/hierarchical_data_mapping.md): How Zabbix items are mapped to nested GraphQL fields.
 *   [**Roles & Permissions**](./docs/howtos/permissions.md): Managing user rights through Zabbix template groups.
 *   [**Zabbix Tags Usage**](./docs/howtos/tags.md): Using tags for classification and metadata.
-*   [**MCP Integration**](./docs/howtos/mcp.md): Connecting LLMs to Zabbix via Model Context Protocol.
+*   [**MCP & Agent Integration**](./docs/howtos/mcp.md): Connecting LLMs and autonomous agents to Zabbix via Model Context Protocol.

 See the [How-To Overview](./docs/howtos/README.md) for a complete list of documentation.

@ -44,7 +46,7 @@ See the [How-To Overview](./docs/howtos/README.md) for a complete list of docume

 ### Prerequisites

-*   **Node.js**: Version 18 or higher recommended.
+*   **Node.js**: Version 24 (LTS) or higher recommended.
 *   **Zabbix**: A running Zabbix instance (compatible with Zabbix 6.0+).

 ### Installation
@ -60,19 +62,59 @@ See the [How-To Overview](./docs/howtos/README.md) for a complete list of docume
    npm install
    ```

-### Configuration
+## ⚙️ Configuration
+
+### Environment Variables

 The API is configured via environment variables. Create a `.env` file or set them in your environment:

-| Variable | Description | Default |
-| :--- | :--- | :--- |
-| `ZABBIX_BASE_URL` | URL to your Zabbix API (e.g., `http://zabbix.example.com/zabbix`) | |
-| `ZABBIX_AUTH_TOKEN` | Zabbix Super Admin API token for administrative tasks | |
-| `ZABBIX_EDGE_DEVICE_BASE_GROUP` | Base host group for devices | `Roadwork` |
-| `ZABBIX_PERMISSION_TEMPLATE_GROUP_NAME_PREFIX` | Prefix for template groups used as permissions | `Permissions` |
-| `SCHEMA_PATH` | Path to the directory containing `.graphql` schema files | `./schema/` |
-| `HOST_GROUP_FILTER_DEFAULT` | Default search pattern for `allHostGroups` query | |
-| `HOST_TYPE_FILTER_DEFAULT` | Default value for `tag_hostType` filter in `allHosts` and `allDevices` queries | |
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `ZABBIX_BASE_URL` | URL to your Zabbix server (include `/zabbix` path) | - | Yes |
+| `ZABBIX_PRIVILEGE_ESCALATION_TOKEN` | Zabbix Super Admin API token used for privilege escalation (e.g. during import operations) | - | Yes |
+| `ZABBIX_DEVELOPMENT_TOKEN` | Token used ONLY for local development and isolated testing to simulate a "real end user" | - | No |
+| `ZABBIX_EDGE_DEVICE_BASE_GROUP` | Base group for edge devices | `Roadwork` | No |
+| `ZABBIX_PERMISSION_TEMPLATE_GROUP_NAME_PREFIX` | Prefix for permission template groups (used to identify permission-related template groups in Zabbix) | `Permissions` | No |
+| `SCHEMA_PATH` | Path to schema files | `./schema/` | No |
+| `ADDITIONAL_SCHEMAS` | Comma-separated list of additional schema files | - | No |
+| `ADDITIONAL_RESOLVERS` | Comma-separated list of resolver types to generate | - | No |
+| `LOG_LEVEL` | Log level configuration (e.g. `debug`, `info`, `warn`, `error`) | `info` | No |
+| `HOST_TYPE_FILTER_DEFAULT` | Default filter for host types | - | No |
+| `HOST_GROUP_FILTER_DEFAULT` | Default filter for host groups | - | No |
+
+## 🔐 Authorization
+
+The application operates with different authentication and authorization mechanisms depending on the scenario:
+
+### 1. Production Use
+
+In production environments, the `ZABBIX_DEVELOPMENT_TOKEN` should **always be unset** to ensure proper security.
+
+*   **Zabbix Frontend Widgets**: When accessing the API from widgets embedded in the Zabbix frontend, no static token is needed. Authentication is automatically derived from the `zbx_session` cookie provided by the Zabbix web login, which is forwarded to the Zabbix API.
+*   **Other Production Tools**: For other purposes (e.g. accessing the API from external tools or scripts), a Zabbix session or auth token must be passed via the `zabbix-auth-token` HTTP header.
+
+### 2. Privilege Escalation
+
+*   **`ZABBIX_PRIVILEGE_ESCALATION_TOKEN`**: Certain operations, such as importing hosts, templates, or user rights, require Super Admin access to Zabbix for specific parts of the process. This token allows the API to perform these administrative tasks even when the initiating user does not have Super Admin rights themselves.
+
+### 3. Local Development and Testing
+
+*   **`ZABBIX_DEVELOPMENT_TOKEN`**: This environment variable is intended **only** for local development and isolated testing. It allows developers to "simulate" a Zabbix access token representing a "real end user" without needing to provide the HTTP header in every request. 
+    *   **Warning**: This should be avoided in production as it undermines security by bypassing per-request authentication.
+
+### 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 | Zabbix items become nested fields based on their key names (hierarchical mapping) |
+| Tag | `Tag` | Represents a Zabbix tag associated with a host or template |
+| Inventory | `Location` | Host inventory information maps to location data |

 ### Starting the API

@ -107,7 +149,7 @@ docker run -d \
  --name zabbix-graphql-api \
  -p 4000:4000 \
  -e ZABBIX_BASE_URL=http://your-zabbix-instance/zabbix \
-  -e ZABBIX_AUTH_TOKEN=your-super-admin-token \
+  -e ZABBIX_PRIVILEGE_ESCALATION_TOKEN=your-super-admin-token \
  forgejo.tooling.hilbigit.com/zabbix/zabbix-graphql-api:latest
 ```

@ -126,7 +168,7 @@ If you prefer to build the image yourself using the provided `Dockerfile`:
      --name zabbix-graphql-api \
      -p 4000:4000 \
      -e ZABBIX_BASE_URL=http://your-zabbix-instance/zabbix \
-      -e ZABBIX_AUTH_TOKEN=your-super-admin-token \
+      -e ZABBIX_PRIVILEGE_ESCALATION_TOKEN=your-super-admin-token \
      zabbix-graphql-api
    ```

@ -136,7 +178,7 @@ The **Virtual Control Room (VCR)** is a professional cockpit and control center

 ### How VCR uses the GraphQL API:

-*   **Unified Cockpit**: VCR utilizes the API's **hierarchical mapping** to provide a unified view of diverse device types. It maps Zabbix items and tags directly to structured GraphQL objects (e.g., `operational` telemetry and `current` business state).
+*   **Unified Cockpit**: VCR utilizes the API's **hierarchical mapping** to provide a unified view of diverse device types. It maps Zabbix items and tags directly to structured GraphQL objects (e.g. `operational` telemetry and `current` business state).
 *   **Dynamic Authorization**: The `hasPermissions` query is used to implement a **Dynamic UI**. Buttons, controls, and status indicators are shown or enabled only if the user has the required `READ` or `READ_WRITE` permissions for that specific object.
 *   **Mass Provisioning**: VCR leverages the **mass import** capabilities to provision thousands of devices and templates in a single operation, significantly reducing manual configuration effort in Zabbix.
 *   **Data Visualization**: It uses the `exportHostValueHistory` endpoint to power dashboards showing historical trends, such as traffic density, battery levels, or sensor readings over time.
@ -151,7 +193,7 @@ Below is a complete example of a `.env` file showing all available configuration
 ```env
 # Zabbix Connection
 ZABBIX_BASE_URL=http://your-zabbix-instance/zabbix
-ZABBIX_AUTH_TOKEN=your-super-admin-token-here
+ZABBIX_PRIVILEGE_ESCALATION_TOKEN=your-super-admin-token-here

 # General Configuration
 ZABBIX_EDGE_DEVICE_BASE_GROUP=Roadwork
@ -188,6 +230,14 @@ The `docs/queries` directory contains several sample GraphQL queries and mutatio
    *   [Export User Rights](docs/queries/sample_export_user_rights_query.graphql)
    *   [Import User Rights](docs/queries/sample_import_user_rights_mutation.graphql)

+## 🔄 API Version
+
+The API version is automatically set during the Docker build process based on the Git tag or commit hash. This version information is embedded into the Docker image and becomes accessible through the `API_VERSION` environment variable at runtime.
+
+### Zabbix Version Compatibility
+
+This API is designed to work with Zabbix 7.4, which is the version it runs productively with. While it may work with earlier versions (like 6.0+), 7.4 is the officially supported and tested version.
+
 ## License

 This project is licensed under the **GNU Affero General Public License v3.0**. See the [LICENSE](LICENSE) file for details.