- Pin `apollo-mcp-server` image to v1.7.0 and make version configurable via `APOLLO_MCP_SERVER_VERSION`.
- Refactor API logging: rename `MCP_LOG_*` variables to `VERBOSITY_*` for clarity and deprecate unsupported fields.
- Ensure v1.7.0 compatibility by updating `mcp-config.yaml` and removing obsolete fields.
- Update documentation and configuration files to reflect these changes.
This update enhances compatibility across multiple Zabbix versions and introduces tools for easier local development and testing.
Key improvements and verified version support:
- Verified Zabbix version support: 6.2, 6.4, 7.0, and 7.4.
- Version-specific feature handling:
- `history.push` is enabled only for Zabbix 7.0+; older versions skip it with a clear error or notice.
- Conditional JSON-RPC authentication: the `auth` field is automatically added to the request body for versions older than 6.4.
- Implemented static Zabbix version caching in the datasource to minimize redundant API calls.
- Query optimization refinements:
- Added mapping for implied fields (e.g., `state` -> `items`, `deviceType` -> `tags`).
- Automatically prune unnecessary Zabbix parameters (like `selectItems` or `selectTags`) when not requested.
- Local development environment:
- Added a new `zabbix-local` Docker Compose profile that includes PostgreSQL, Zabbix Server, and Zabbix Web.
- Supports testing different versions by passing the `ZABBIX_VERSION` environment variable (e.g., 6.2, 6.4, 7.0, 7.4).
- Provided a sample environment file at `samples/zabbix-local.env`.
- Documentation and Roadmap:
- Updated README with a comprehensive version compatibility matrix and local environment instructions.
- Created a new guide: `docs/howtos/local_development.md`.
- Updated maintenance guides and added "Local Development Environment" as an achieved milestone in the roadmap.
- Test suite enhancements:
- Improved Smoketest and RegressionTest executors with more reliable resource cleanup and error reporting.
- Made tests version-aware to prevent failures on older Zabbix instances.
BREAKING CHANGE: Dropped Zabbix 6.0 specific workarounds; the minimum supported version is now 6.2.
- 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.
