Andreas Hilbig
a01bfabfba
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.
87 lines
2.5 KiB
Markdown
87 lines
2.5 KiB
Markdown
# Zabbix GraphQL API Cookbook
|
|
|
|
This cookbook provides step-by-step "recipes" for common tasks. These instructions are designed to be easy for humans to follow and structured enough for AI agents (using the MCP server) to generate test cases.
|
|
|
|
## 🤖 AI-Based Test Generation
|
|
|
|
To generate a test case from a recipe:
|
|
1. Start the `zabbix-graphql` MCP server.
|
|
2. Provide the recipe to your AI agent.
|
|
3. Ask the agent to "Implement a test case for this recipe using the Zabbix GraphQL API".
|
|
4. The agent will use the MCP server to explore the schema and generate appropriate GraphQL operations.
|
|
|
|
---
|
|
|
|
## 🍳 Recipe: Extending Schema with a New Device Type
|
|
|
|
This recipe shows how to add support for a new specialized device type without modifying the core API code.
|
|
|
|
### Prerequisites
|
|
- Zabbix Template Group `Templates/Roadwork/Devices` exists.
|
|
- Zabbix GraphQL API is running.
|
|
|
|
### Step 1: Define the Schema Extension
|
|
Create a new `.graphql` file in `schema/extensions/` (e.g. `distance_tracker.graphql`):
|
|
```graphql
|
|
type DistanceTrackerDevice {
|
|
id: String
|
|
name: String
|
|
location: Location
|
|
distance: Float
|
|
batteryLevel: Float
|
|
lastSeen: DateTime
|
|
}
|
|
```
|
|
|
|
### Step 2: Configure Environment Variables
|
|
Add the new schema and resolver to your `.env` file:
|
|
```env
|
|
ADDITIONAL_SCHEMAS=./schema/extensions/distance_tracker.graphql
|
|
ADDITIONAL_RESOLVERS=DistanceTrackerDevice
|
|
```
|
|
Restart the API server.
|
|
|
|
### Step 3: Import the Template
|
|
Execute the `importTemplates` mutation to create the template in Zabbix. Use Zabbix item keys that match your GraphQL fields (e.g. `distance.current` for `distance`).
|
|
|
|
---
|
|
|
|
## 🍳 Recipe: Provisioning a New Host
|
|
|
|
### Prerequisites
|
|
- A target Host Group exists in Zabbix.
|
|
- At least one Template exists in Zabbix.
|
|
|
|
### Step 1: Prepare the Host Object
|
|
Define the host name, groups, and templates to link.
|
|
|
|
### Step 2: Execute `createHost` Mutation
|
|
```graphql
|
|
mutation CreateNewHost($host: String!, $groups: [Int!]!, $templates: [Int!]!) {
|
|
createHost(host: $host, hostgroupids: $groups, templateids: $templates) {
|
|
hostids
|
|
error {
|
|
message
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🍳 Recipe: Managing User Permissions
|
|
|
|
### Step 1: Create Permission Template Group
|
|
Create a template group with the prefix `Permissions/` in Zabbix (e.g. `Permissions/Read-Only-Access`).
|
|
|
|
### Step 2: Assign to User Group
|
|
In Zabbix, give a User Group `Read` access to this template group.
|
|
|
|
### Step 3: Verify via API
|
|
```graphql
|
|
query CheckMyPermissions {
|
|
hasPermissions(permissions: [
|
|
{ objectName: "Read-Only-Access", permission: READ }
|
|
])
|
|
}
|
|
```
|