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.
This commit is contained in:
parent
4ec61ffba1
commit
a01bfabfba
28 changed files with 395 additions and 170 deletions
|
|
@ -4,6 +4,9 @@ This directory contains detailed guides on how to use and extend the Zabbix Grap
|
|||
|
||||
## Available Guides
|
||||
|
||||
### 🍳 [Cookbook](./cookbook.md)
|
||||
Practical, step-by-step recipes for common tasks, designed for both humans and AI-based test generation.
|
||||
|
||||
### 📊 [Schema and Schema Extension](./schema.md)
|
||||
Learn about the GraphQL schema structure, how Zabbix entities map to GraphQL types, and how to use the dynamic schema extension system.
|
||||
|
||||
|
|
@ -16,8 +19,8 @@ Discover how the permission system works, how to define permission levels using
|
|||
### 🏷️ [Zabbix Tags Usage](./tags.md)
|
||||
Learn how Zabbix tags are used for device classification, host categorization, and as metadata within the GraphQL API.
|
||||
|
||||
### 🤖 [MCP Integration](./mcp.md)
|
||||
Discover how to integrate the Zabbix GraphQL API with the Model Context Protocol (MCP) to enable LLMs to interact with your Zabbix data.
|
||||
### 🤖 [MCP & Agent Integration](./mcp.md)
|
||||
Discover how to integrate the Zabbix GraphQL API with the Model Context Protocol (MCP) to enable LLMs and autonomous agents to interact with your Zabbix data efficiently.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
87
docs/howtos/cookbook.md
Normal file
87
docs/howtos/cookbook.md
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
# 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 }
|
||||
])
|
||||
}
|
||||
```
|
||||
|
|
@ -58,8 +58,25 @@ To use this integration with Claude Desktop, add the following configuration to
|
|||
|
||||
**Note**: Ensure the `zabbix-graphql-api` is running and accessible. If running locally, you might need to use `host.docker.internal:4001/graphql` in your `mcp-config.yaml` to allow the containerized MCP server to reach your host.
|
||||
|
||||
### Benefits of GraphQL-enabled MCP
|
||||
### Benefits of GraphQL-enabled MCP over REST
|
||||
|
||||
- **Self-Documenting**: The GraphQL schema provides all necessary metadata for the LLM to understand how to use the tools.
|
||||
- **Efficient**: LLMs can request exactly the data they need, reducing token usage and improving response speed.
|
||||
- **Secure**: Uses the same authentication and permission model as the rest of the API.
|
||||
Integrating via GraphQL offers significant advantages for AI agents and MCP compared to the traditional Zabbix JSON-RPC (REST-like) API:
|
||||
|
||||
- **Introspection & Discovery**: Unlike REST, GraphQL is natively introspectable. An AI agent can query the schema itself to discover all available types, fields, and operations. This allows agents to "learn" the API capabilities without manual documentation parsing.
|
||||
- **Strong Typing**: The schema provides explicit types for every field. AI agents can use this to validate their own generated queries and understand the exact data format expected or returned, reducing errors in agent-driven actions.
|
||||
- **Precision (Over-fetching/Under-fetching)**: In REST, endpoints often return fixed data structures, leading to token waste (over-fetching) or requiring multiple round-trips (under-fetching). With GraphQL, the agent requests exactly the fields it needs, which is crucial for staying within LLM context window limits and reducing latency.
|
||||
- **Single Endpoint**: AI agents only need to know one endpoint. They don't have to manage a complex tree of URL paths and HTTP methods; they simply send their intent as a GraphQL operation.
|
||||
- **Complex Relationships**: Agents can navigate complex Zabbix relationships (e.g. Host -> Items -> History) in a single request, which is much more intuitive for LLMs than orchestrating multiple REST calls.
|
||||
- **Self-Documenting**: Descriptive comments in the SDL are automatically exposed to the agent, providing immediate context for what each field represents.
|
||||
|
||||
### AI-Based Test Generation via Cookbook
|
||||
|
||||
The MCP server can be used in conjunction with the [**Cookbook**](./cookbook.md) to automate the generation of test cases. By providing a cookbook "recipe" to an LLM with access to the `zabbix-graphql` MCP server, the LLM can:
|
||||
|
||||
1. Analyze the step-by-step instructions in the recipe.
|
||||
2. Use the MCP server's tools to inspect the current Zabbix state and schema.
|
||||
3. Generate and execute the necessary GraphQL operations to fulfill the recipe's task.
|
||||
4. Verify the outcome and suggest assertions for a formal test script.
|
||||
|
||||
Example prompt for an LLM:
|
||||
> "Using the `zabbix-graphql` MCP server, follow the 'Provisioning a New Host' recipe from the cookbook. Create a host named 'Test-Host-01' in the 'Linux servers' group and link the 'ICMP Ping' template."
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ query GetUserPermissions {
|
|||
|
||||
### Setting Up Permissions
|
||||
|
||||
1. Create template groups with the prefix `Permissions/` (e.g., `Permissions/hosts`, `Permissions/templates`)
|
||||
1. Create template groups with the prefix `Permissions/` (e.g. `Permissions/hosts`, `Permissions/templates`)
|
||||
2. Assign these template groups to user groups in Zabbix with appropriate permission levels
|
||||
3. Users in those user groups will inherit the permissions
|
||||
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ The `hostType` tag is used to categorize hosts and templates. This allows the AP
|
|||
|
||||
To classify a host or a template, add a tag in Zabbix:
|
||||
* **Tag Name**: `hostType`
|
||||
* **Tag Value**: A string representing the category (e.g., `Roadwork/Devices`, `SmartCity/Sensors`).
|
||||
* **Tag Value**: A string representing the category (e.g. `Roadwork/Devices`, `SmartCity/Sensors`).
|
||||
|
||||
This tag can be defined directly on the host or on a template (where linked hosts will inherit it).
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue