docs: enhance documentation and automate MCP setup
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 is contained in:
parent
91a1523d71
commit
bbf7357e93
12 changed files with 230 additions and 87 deletions
82
README.md
82
README.md
|
|
@ -27,18 +27,20 @@ The Zabbix GraphQL API acts as a wrapper and enhancer for the native Zabbix JSON
|
|||
- *Reference*: `codegen.ts`, `src/schema/generated/graphql.ts`, `tsconfig.json`, `package.json` (devDependencies for GraphQL Codegen)
|
||||
|
||||
- **AI Agent & MCP Enablement**: Native support for Model Context Protocol (MCP) and AI-driven automation. GraphQL's strongly-typed, introspectable nature provides a superior interface for AI agents compared to traditional REST APIs.
|
||||
- *Reference*: `docs/howtos/mcp.md`, `mcp-config.yaml`, `docker-compose.yml` (MCP service)
|
||||
- *Reference*: `docs/howtos/mcp.md`, `.ai/mcp/mcp.json` (Sample Config), `mcp-config.yaml`, `docker-compose.yml` (MCP service)
|
||||
|
||||
> **Planned features**: For an overview of achieved milestones and planned enhancements have a look at the [**Roadmap**](./roadmap.md).
|
||||
|
||||
## How-To Guides
|
||||
|
||||
For detailed information on specific topics and practical step-by-step instructions, please refer to our guides:
|
||||
|
||||
* [**Cookbook**](./docs/howtos/cookbook.md): Practical, task-oriented recipes for quick start and AI test generation.
|
||||
* [**Schema & Extension Overview**](./docs/howtos/schema.md): Detailed explanation of the schema structure and extension mechanism.
|
||||
* [**Hierarchical Data Mapping**](./docs/howtos/hierarchical_data_mapping.md): How Zabbix items are mapped to nested GraphQL fields.
|
||||
* [**Roles & Permissions**](./docs/howtos/permissions.md): Managing user rights through Zabbix template groups.
|
||||
* [**Technical Maintenance**](./docs/howtos/maintenance.md): Guide on code generation, testing, and Docker maintenance.
|
||||
* [**MCP & Agent Integration**](./docs/howtos/mcp.md): Connecting LLMs and autonomous agents via Model Context Protocol.
|
||||
- [**Cookbook**](./docs/howtos/cookbook.md): Practical, task-oriented recipes for quick start and AI test generation.
|
||||
- [**Schema & Extension Overview**](./docs/howtos/schema.md): Detailed explanation of the schema structure and extension mechanism.
|
||||
- [**Hierarchical Data Mapping**](./docs/howtos/hierarchical_data_mapping.md): How Zabbix items are mapped to nested GraphQL fields.
|
||||
- [**Roles & Permissions**](./docs/howtos/permissions.md): Managing user rights through Zabbix template groups.
|
||||
- [**Technical Maintenance**](./docs/howtos/maintenance.md): Guide on code generation, testing, and Docker maintenance.
|
||||
- [**MCP & Agent Integration**](./docs/howtos/mcp.md): Connecting LLMs and autonomous agents via Model Context Protocol.
|
||||
|
||||
See the [How-To Overview](./docs/howtos/README.md) for a complete list of documentation.
|
||||
|
||||
|
|
@ -47,24 +49,22 @@ See the [How-To Overview](./docs/howtos/README.md) for a complete list of docume
|
|||
### 📋 Prerequisites
|
||||
Before you begin, ensure you have met the following requirements:
|
||||
|
||||
* **Node.js**: Version 24 (LTS) or higher recommended.
|
||||
* **Zabbix**: A running Zabbix instance (compatible with Zabbix 6.0+).
|
||||
with API access
|
||||
* **Zabbix Super Admin Token** (for full functionality / privilege escalation)
|
||||
* **Zabbix User Access** (groups and roles depending on your use case)
|
||||
- **Node.js**: Version 24 (LTS) or higher recommended.
|
||||
- **Zabbix**: A running Zabbix instance (compatible with Zabbix 6.0+) with API access.
|
||||
- **Zabbix Super Admin Token** (for full functionality / privilege escalation).
|
||||
- **Zabbix User Access** (groups and roles depending on your use case).
|
||||
|
||||
### 🛠️ Installation
|
||||
- Clone the repository:
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd zabbix-graphql-api
|
||||
```
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd zabbix-graphql-api
|
||||
```
|
||||
|
||||
2. Install dependencies:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
- Install dependencies:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
### Starting the API
|
||||
|
||||
#### Development Mode
|
||||
|
|
@ -105,25 +105,25 @@ The API is configured via environment variables. Create a `.env` file or set the
|
|||
|
||||
The application operates with different authentication and authorization mechanisms depending on the scenario:
|
||||
|
||||
### 1. Production Use
|
||||
### 🛡️ Production Use
|
||||
|
||||
In production environments, the `ZABBIX_DEVELOPMENT_TOKEN` should **always be unset** to ensure proper security.
|
||||
|
||||
* **Zabbix Frontend Widgets**: When accessing the API from widgets embedded in the Zabbix frontend, no static token is needed. Authentication is automatically derived from the `zbx_session` cookie provided by the Zabbix web login, which is forwarded to the Zabbix API.
|
||||
* **Other Production Tools**: For other purposes (e.g. accessing the API from external tools or scripts), a Zabbix session or auth token must be passed via the `zabbix-auth-token` HTTP header.
|
||||
- **Zabbix Frontend Widgets**: When accessing the API from widgets embedded in the Zabbix frontend, no static token is needed. Authentication is automatically derived from the `zbx_session` cookie provided by the Zabbix web login, which is forwarded to the Zabbix API.
|
||||
- **Other Production Tools**: For other purposes (e.g. accessing the API from external tools or scripts), a Zabbix session or auth token must be passed via the `zabbix-auth-token` HTTP header.
|
||||
|
||||
> **Recipe**: See [Managing User Permissions](./docs/howtos/cookbook.md#recipe-managing-user-permissions) for setup instructions.
|
||||
|
||||
### 2. Privilege Escalation
|
||||
### 🔑 Privilege Escalation
|
||||
|
||||
* **`ZABBIX_PRIVILEGE_ESCALATION_TOKEN`**: Certain operations, such as importing hosts, templates, or user rights, require Super Admin access to Zabbix for specific parts of the process. This token allows the API to perform these administrative tasks even when the initiating user does not have Super Admin rights themselves.
|
||||
- **`ZABBIX_PRIVILEGE_ESCALATION_TOKEN`**: Certain operations, such as importing hosts, templates, or user rights, require Super Admin access to Zabbix for specific parts of the process. This token allows the API to perform these administrative tasks even when the initiating user does not have Super Admin rights themselves.
|
||||
|
||||
### 3. Local Development and Testing
|
||||
### 🧪 Local Development and Testing
|
||||
|
||||
* **`ZABBIX_DEVELOPMENT_TOKEN`**: This environment variable is intended **only** for local development and isolated testing. It allows developers to "simulate" a Zabbix access token representing a "real end user" without needing to provide the HTTP header in every request.
|
||||
* **Warning**: This should be avoided in production as it undermines security by bypassing per-request authentication.
|
||||
- **`ZABBIX_DEVELOPMENT_TOKEN`**: This environment variable is intended **only** for local development and isolated testing. It allows developers to "simulate" a Zabbix access token representing a "real end user" without needing to provide the HTTP header in every request.
|
||||
- **Warning**: This should be avoided in production as it undermines security by bypassing per-request authentication.
|
||||
|
||||
### Zabbix to GraphQL Mapping
|
||||
### 🗺️ Zabbix to GraphQL Mapping
|
||||
|
||||
The API maps Zabbix entities to GraphQL types as follows:
|
||||
|
||||
|
|
@ -142,7 +142,7 @@ The API maps Zabbix entities to GraphQL types as follows:
|
|||
|
||||
## Running with Docker
|
||||
|
||||
### Using the Pre-built Image
|
||||
### 📦 Using the Pre-built Image
|
||||
|
||||
You can run the API without building it locally by pulling the latest image from the Hilbig IT Forgejo infrastructure:
|
||||
|
||||
|
|
@ -161,16 +161,16 @@ docker run -d \
|
|||
forgejo.tooling.hilbigit.com/zabbix/zabbix-graphql-api:latest
|
||||
```
|
||||
|
||||
### Building Locally
|
||||
### 🏗️ Building Locally
|
||||
|
||||
If you prefer to build the image yourself using the provided `Dockerfile`:
|
||||
|
||||
1. Build the image (ensure you provide an `API_VERSION`):
|
||||
* Build the image (ensure you provide an `API_VERSION`):
|
||||
```bash
|
||||
docker build -t zabbix-graphql-api --build-arg API_VERSION=1.0.0 .
|
||||
```
|
||||
|
||||
2. Run the container:
|
||||
* Run the container:
|
||||
```bash
|
||||
docker run -d \
|
||||
--name zabbix-graphql-api \
|
||||
|
|
@ -184,12 +184,12 @@ If you prefer to build the image yourself using the provided `Dockerfile`:
|
|||
|
||||
The **Virtual Control Room (VCR)** is a professional cockpit and control center application designed for monitoring and managing large-scale deployments of IoT and Edge devices, such as traffic management systems, roadwork safety equipment, and environmental sensors.
|
||||
|
||||
### How VCR uses the GraphQL API:
|
||||
### 🧩 How VCR uses the GraphQL API
|
||||
|
||||
* **Unified Cockpit**: VCR utilizes the API's **hierarchical mapping** to provide a unified view of diverse device types. It maps Zabbix items and tags directly to structured GraphQL objects (e.g. `operational` telemetry and `current` business state).
|
||||
* **Dynamic Authorization**: The `hasPermissions` query is used to implement a **Dynamic UI**. Buttons, controls, and status indicators are shown or enabled only if the user has the required `READ` or `READ_WRITE` permissions for that specific object.
|
||||
* **Mass Provisioning**: VCR leverages the **mass import** capabilities to provision thousands of devices and templates in a single operation, significantly reducing manual configuration effort in Zabbix.
|
||||
* **Data Visualization**: It uses the `exportHostValueHistory` endpoint to power dashboards showing historical trends, such as traffic density, battery levels, or sensor readings over time.
|
||||
- **Unified Cockpit**: VCR utilizes the API's **hierarchical mapping** to provide a unified view of diverse device types. It maps Zabbix items and tags directly to structured GraphQL objects (e.g. `operational` telemetry and `current` business state).
|
||||
- **Dynamic Authorization**: The `hasPermissions` query is used to implement a **Dynamic UI**. Buttons, controls, and status indicators are shown or enabled only if the user has the required `READ` or `READ_WRITE` permissions for that specific object.
|
||||
- **Mass Provisioning**: VCR leverages the **mass import** capabilities to provision thousands of devices and templates in a single operation, significantly reducing manual configuration effort in Zabbix.
|
||||
- **Data Visualization**: It uses the `exportHostValueHistory` endpoint to power dashboards showing historical trends, such as traffic density, battery levels, or sensor readings over time.
|
||||
|
||||
For more detailed information about the VCR product, please refer to the technical presentation:
|
||||
[VCR - Technical product information](docs/VCR%20-%20Technical%20product%20information.pdf)
|
||||
|
|
@ -228,7 +228,7 @@ The `docs/queries` directory contains several sample GraphQL queries and mutatio
|
|||
|
||||
The API version is automatically set during the Docker build process based on the Git tag or commit hash. This version information is embedded into the Docker image and becomes accessible through the `API_VERSION` environment variable at runtime.
|
||||
|
||||
### Zabbix Version Compatibility
|
||||
### 🔧 Zabbix Version Compatibility
|
||||
|
||||
This API is designed to work with Zabbix 7.4, which is the version it runs productively with. While it may work with earlier versions (like 6.0+), 7.4 is the officially supported and tested version.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue