- Add runSmoketest mutation to automate end-to-end verification.
- Add SmoketestExecutor and HostDeleter to support automated testing and cleanup.
- Extend createHost and importHosts to allow linking templates by name or ID.
- Update docs/howtos/cookbook.md with new recipe steps and AI/MCP guidance.
- Update .junie/guidelines.md with new verification and deployment standards.
- Add src/test/template_link.test.ts and update existing tests to cover new functionality.
- Regenerate GraphQL types to match schema updates.
This commit introduces a comprehensive set of GraphQL query and mutation samples based on the official Zabbix 7.4 API documentation, along with testing and automation improvements.
Changes:
- Documentation:
- Added 21 GraphQL sample files in docs/queries/from_zabbix_docs/ covering various Zabbix API operations.
- Updated docs/howtos/cookbook.md with a new recipe for executing these documentation samples.
- AI & MCP:
- Added mcp/operations/importHostGroups.graphql to enable host group import via MCP tools.
- Testing:
- Added src/test/zabbix_docs_samples.test.ts to automatically validate all documentation samples against the GraphQL schema.
- 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 refines the project documentation by adding result verification steps to all recipes in the cookbook and formalizing documentation standards in the project guidelines.
Changes:
- docs/howtos/cookbook.md:
- Added 'Verify' steps to all recipes using GraphQL queries or agent checks.
- Enhanced 'Extending Schema with a New Device Type' recipe:
- Updated Step 1 with a realistic schema using 'DistanceTrackerDevice' implementing 'Host' and 'Device' interfaces.
- Added mandatory advice for new device types to implement 'Host' and 'Device'.
- Referenced the existing 'location_tracker_devices.graphql' as a prepared real-world sample.
- Split Step 3 into Method A (Manual Creation) and Method B (Automated Import).
- Expanded Step 4 with a host creation step (using importHosts) and a filtered allDevices query using tag_deviceType.
- Standardized icons for preparation (🛠️), configuration (⚙️), execution (🚀), and verification (✅).
- .junie/guidelines.md:
- Added 'Documentation Templates' section defining a formal Recipe Template.
- Standardized icons and step naming to maintain visual consistency across all guides.
- Added 'Review & Approval' rule to prevent automatic commits without user review.
- readme.improvement.plan.md:
- Added and completed 'Priority 7: Standardization & Verification' tasks.
- Updated implementation order to reflect the new standardization phase.
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`.
- Refined IntelliJ IDEA settings in `.idea/workspace.xml`, including updates to `ProblemsViewState` and `PropertiesComponent` for project consistency.
- Renamed and expanded `.junie/guidelines.md` to reflect updated best practices, project structure, and development workflows.
- Added unit tests for schema loader, mocking Config variables and resolvers.
- Added unit tests for Zabbix API configuration, verifying constants derived from Config.
- Mocked relevant modules and filesystem behaviors to enable isolated testing.
- Optimized imports on all files and include this within a new .junie/guidelines.md file
- 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.
- Replaced all direct `process.env` references with `Config` class constants.
- Added `dotenv` package to manage environment variables.
- Updated affected files, including schema loader, Zabbix API, resolvers, logging system, and integration points.
- Improved maintainability and consistency in environment variable handling.
- 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.
- Added comprehensive descriptions to all types, interfaces, and fields in 'schema/api_commons.graphql'.
- Improved documentation for mutations and input/response types in 'schema/mutations.graphql'.
- Added detailed descriptions for all queries and their arguments in 'schema/queries.graphql'.
- Enhanced documentation for core Zabbix types and enums in 'schema/zabbix.graphql'.
- Updated extension schemas under 'schema/extensions/' with proper GraphQL descriptions.
- Verified schema validity via 'graphql-codegen' and ran all tests to ensure consistency.
- 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.
- Added GraphQL sample queries and mutations for host and user rights endpoints in the 'docs' directory.
- Implemented unit tests for all remaining GraphQL endpoints, including hosts, devices, host groups, locations, and user permissions.
- Created dedicated integration tests for host and user rights workflows, utilizing the new sample files.
- Fixed a bug in 'HostImporter.getHostGroupHierarchyNames' to correctly process and sort nested host group hierarchies.
- Refined Zabbix API mocking in tests to improve reliability and support path-based routing.
- Verified all 38 tests across 11 suites pass successfully.
- Implemented GraphQL endpoints for importing, querying, and deleting Zabbix templates and template groups. - Added support for full template data import, including items, preprocessing steps, tags, and linked templates. - Implemented dependent item support by deferred creation logic in the template importer. - Added ability to query templates and template groups with name pattern filtering (supporting Zabbix wildcards). - Implemented batch deletion for templates and template groups by ID or name pattern. - Improved error reporting by including detailed Zabbix API error data in GraphQL responses. - Added comprehensive unit and integration tests covering all new functionality. - Provided GraphQL sample queries and mutations in the 'docs' directory for all new endpoints.
