This commit comprehensive updates the API to ensure full compatibility across all major Zabbix versions (6.0 LTS, 6.2, 6.4, and 7.0 LTS) and introduces a local development environment for multi-version testing.
Verified Zabbix Versions:
- Zabbix 7.0 (LTS): Full support, including native `history.push` for telemetry.
- Zabbix 6.4: Supported (excluding `history.push`); uses `hostgroup.propagate` and UUID-based matching.
- Zabbix 6.2: Supported (excluding `history.push`); uses `hostgroup.propagate` and `templategroup.*` methods.
- Zabbix 6.0 (LTS): Supported (excluding `history.push`); includes specific fallbacks:
- JSON-RPC: Restored `auth` field in request body for versions lacking Bearer token support.
- Permissions: Implemented name-based fallback for host/template groups (no UUIDs in 6.0).
- Group Expansion: Automatic manual expansion of group rights during import.
- API Methods: Fallback from `templategroup.*` to `hostgroup.*` methods.
Key Technical Changes:
- Local Development: Added `zabbix-local` Docker Compose profile to launch a complete Zabbix stack (Server, Web, Postgres) from scratch with dynamic versioning via `ZABBIX_VERSION`.
- Query Optimization: Refined dynamic field selection to handle implied fields and ensure consistent output regardless of initial Zabbix parameters.
- Documentation:
- New `local_development.md` HOWTO guide.
- Updated `README.md` with detailed version compatibility matrix.
- Expanded `roadmap.md` with achieved milestones.
- Testing:
- Updated entire Jest test suite (23 suites, 96 tests) to be version-aware and robust against naming collisions.
- Enhanced Smoketest and Regression Test executors with better cleanup and error reporting.
This commit introduces several improvements to ensure the API works seamlessly across Zabbix 6.0, 6.4, and 7.0+, while also optimizing data fetching performance.
Key changes:
- Zabbix Version Compatibility:
- Added Zabbix version detection and static caching in ZabbixAPI.
- Implemented name-based fallback for host/template group permissions to support Zabbix 6.0 (which lacks UUIDs for host groups).
- Added manual host group expansion for Zabbix versions < 6.2.0 during user group import.
- Added version-based guards for history.push (7.0+) and hostgroup.propagate (6.2+).
- Updated documentation with detailed version compatibility notes.
- Added src/test/zabbix_6_0_compatibility.test.ts to verify compatibility logic.
- Query Optimization:
- Implemented dynamic output selection in ZabbixRequest to fetch only fields requested in GraphQL queries.
- Added GraphqlParamsToNeededZabbixOutput to map GraphQL selections to Zabbix API output parameters.
- Moved "Query Optimization" to achieved milestones in roadmap.md.
- Other:
- Updated various tests to support the new version-aware logic.
- Optimized imports and synchronized IDE settings.
- Implement pushHistory mutation to support pushing telemetry data to Zabbix trapper items.
- Add VERBOSITY and MCP_LOG_* environment variables for controllable request/response logging in both API and MCP server.
- Enhance ZabbixRESTDataSource with better session handling and error logging.
- Update ZabbixHistory datasource to support history push operations.
- Expand documentation with new cookbook recipes and MCP integration guides.
- Add integration tests for history pushing (src/test/history_push*).
- Reorganize documentation, moving technical product info PDF to docs/use-cases/.
- Update GraphQL generated types and VCR templates.
- Implement query optimization (reduced output, parameter skipping) to minimize Zabbix API traffic.
- Add indirect dependency handling: deviceType implies tags and state implies items.
- Move schema extensions to samples/extensions/ to clarify their role as samples.
- Enhance DistanceTrackerDevice with String time fields to support optional date portions.
- Ensure allDevices strictly filters by deviceType and populates the field in results.
- Refactor runAllRegressionTests mutation to use internal unique names and improve stability.
- Fix unnecessary Zabbix API calls for item preprocessing during template and host imports.
- Update documentation including cookbook recipes, test specifications, and optimization guides.
- Add extensive unit, integration, and regression tests covering all implemented changes.
- Update docker-compose.yml to mount the samples/ directory as a volume.
- Update IntelliJ .idea run configurations to reflect the new sample extension paths.
- Established a centralized test specification in docs/tests.md that defines test categories, cases, and a coverage checklist to ensure consistent quality and maintainability across the project.
- Implemented RegressionTestExecutor for managing automated regression tests on a live Zabbix system.
- Updated GraphQL schema and resolvers with a generic runAllRegressionTests mutation.
- Enhanced MCP integration with new operation files and detailed documentation for AI-driven automation.
- Updated README.md and How-To guides (Cookbook, Maintenance, MCP) to reflect the new testing framework and MCP capabilities.
- Verified all changes with a full Jest suite (74 tests) and live end-to-end smoketests.
- Add mcp/operations/importHosts.graphql for flexible, name-based host provisioning.
- Split schema verification operations into createVerificationHost.graphql and verifySchemaExtension.graphql to support Apollo MCP server requirements.
- Improve mcp/operations/createHost.graphql with better type mapping and error message retrieval.
- Fix syntax error in importHosts.graphql by replacing unsupported triple-quote docstrings with standard comments.
- Add src/test/mcp_operations_validation.test.ts to automatically validate MCP operations against the GraphQL schema.
- Update docs/howtos/cookbook.md with 🤖 AI/MCP guidance and refined recipe steps for schema extension verification.
- Update README.md, docs/howtos/mcp.md, and .junie/guidelines.md to:
- Add Docker (v27+) and Docker Compose (v2.29+) version requirements to the Tech Stack.
- Enforce the use of docker compose (without hyphen) for all commands in the Environment guidelines.
- Replace legacy docker-compose references across all documentation with the new command format.
This commit introduces several improvements to the project's documentation,
roadmap, and AI agent integration (MCP).
Key changes:
- Created and styled roadmap.md to track project milestones and future plans.
- Updated .junie/guidelines.md with strict documentation style standards.
- Automated GraphQL schema concatenation for the MCP server using a schema-gen init-container.
- Updated MCP setup recipes in cookbook.md and mcp.md to reflect the new automation.
- Added .ai/mcp/mcp.json for connecting to existing MCP services via HTTP.
- Improved development workflow by updating package.json to watch .graphql files.
- Cleaned up the root directory by moving schema.graphql to .gitignore and removing redundant files.
- Standardized visual style and formatting across all markdown files.
This commit finalizes the documentation improvement plan by:
- Centralizing reference material in README.md.
- Creating a dedicated Technical Maintenance guide (docs/howtos/maintenance.md).
- Creating a categorized Sample Queries & Mutations overview (docs/queries/README.md).
- Eliminating redundant information across the doc set (DRY principle).
- Optimizing cross-references between reference documentation and the Cookbook.
- Updating the improvement plan to reflect all tasks as completed.
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.
- 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`.
- Introduced `HOST_TYPE_FILTER_DEFAULT` and `HOST_GROUP_FILTER_DEFAULT` constants in the `Config` class.
- Updated resolvers to use these defaults when `tag_hostType` or `search_name` arguments are not provided.
- Added corresponding tests to verify default behavior in host and host group queries.
- Added documentation on overriding 'HOST_GROUP_FILTER_DEFAULT' by explicitly setting the 'search_name' argument in the 'allHostGroups' query.
- Explained the usage of the '*' wildcard in 'search_name' with a concrete example for subgroup matching.
- Added a new section describing the Virtual Control Room (VCR) as a sample application.
- Explained how VCR utilizes key API features like hierarchical mapping, dynamic authorization, mass provisioning, and data visualization.
- Included a link to the technical product information PDF in the docs folder.
- Added VCR to the Key Features list.
- Removed 'Permissions/Library' and 'Permissions/Library/Item' from README.md hierarchy examples.
- Updated 'docs/sample_import_permissions_template_groups_mutation.graphql' to remove these groups from the sample import.
- Removed these groups from the 'TEMPLATEGROUP_EXPORT_DUMMY_TEMPLATE' in 'src/testdata/templates/zbx_default_templates_vcr.yaml'.
- Verified all 38 tests pass successfully.
- Added instructions for building and running the API with Docker.
- Added 'CI/CD Integration' to the key features list.
- Included 'docker pull' instructions for using pre-built images from the Forgejo registry.
(cherry picked from commit f6e790db6a)
- Added TSDoc for 'createHierarchicalValueFieldResolver'.
- Updated README with 'Extending the Schema' guide and Zabbix preconditions.
- Migrated all MQTT items to Agent 2 'mqtt.get' format across documentation and test data.
- Added 'docs/sample_import_distance_tracker_template.graphql' as a schema extension example.
- Verified all 38 tests pass.
(cherry picked from commit bff9ee6d2e)
- Created README.md with project purpose, features, installation guide, and usage samples.
- Added LICENSE file with GNU Affero General Public License v3.0 to match Zabbix license.
- Added license field to package.json.
