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.
2026-01-30 19:04:05 +01:00 · 2026-01-30 19:04:05 +01:00 · bbf7357e93
commit bbf7357e93
parent 91a1523d71
12 changed files with 230 additions and 87 deletions
--- a/docs/howtos/README.md
+++ b/docs/howtos/README.md
@ -25,6 +25,5 @@ Discover how to integrate with the Model Context Protocol (MCP) to enable LLMs a
 ---

 ## 🔍 Additional Resources
-
 - **[Sample Queries](../queries/README.md)**: Categorized list of practical GraphQL operation examples.
 - **[Main README](../../README.md)**: Technical reference, configuration, and environment setup.
--- a/docs/howtos/cookbook.md
+++ b/docs/howtos/cookbook.md
@ -5,10 +5,10 @@ This cookbook provides step-by-step "recipes" for common tasks. These instructio
 ## 🤖 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.
+- Start the `zabbix-graphql` MCP server.
+- Provide the recipe to your AI agent.
+- Ask the agent to "Implement a test case for this recipe using the Zabbix GraphQL API".
+- The agent will use the MCP server to explore the schema and generate appropriate GraphQL operations.

 ---

@ -16,11 +16,11 @@ To generate a test case from a recipe:

 This recipe shows how to add support for a new specialized device type without modifying the core API code.

-### Prerequisites
+### 📋 Prerequisites
 - Zabbix Template Group `Templates/Roadwork/Devices` exists.
 - Zabbix GraphQL API is running.

-### Step 1: Define the Schema Extension
+### 🛠️ Step 1: Define the Schema Extension
 Create a new `.graphql` file in `schema/extensions/` (e.g. `distance_tracker.graphql`):
 ```graphql
 type DistanceTrackerDevice {
@ -33,7 +33,7 @@ type DistanceTrackerDevice {
 }
 ```

-### Step 2: Configure Environment Variables
+### ⚙️ Step 2: Configure Environment Variables
 Add the new schema and resolver to your `.env` file:
 ```env
 ADDITIONAL_SCHEMAS=./schema/extensions/distance_tracker.graphql
@ -41,7 +41,7 @@ ADDITIONAL_RESOLVERS=DistanceTrackerDevice
 ```
 Restart the API server.

-### Step 3: Import the Template
+### 🚀 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`).

 > **Reference**: See how items map to fields in the [Zabbix to GraphQL Mapping](../../README.md#zabbix-to-graphql-mapping).
@ -50,14 +50,14 @@ Execute the `importTemplates` mutation to create the template in Zabbix. Use Zab

 ## 🍳 Recipe: Provisioning a New Host

-### Prerequisites
+### 📋 Prerequisites
 - A target Host Group exists in Zabbix.
 - At least one Template exists in Zabbix.

-### Step 1: Prepare the Host Object
+### 🛠️ Step 1: Prepare the Host Object
 Define the host name, groups, and templates to link.

-### Step 2: Execute `createHost` Mutation
+### 🚀 Step 2: Execute `createHost` Mutation
 For more details on the input fields, see the [Reference: createHost](../../schema/mutations.graphql).

 ```graphql
@ -75,13 +75,13 @@ mutation CreateNewHost($host: String!, $groups: [Int!]!, $templates: [Int!]!) {

 ## 🍳 Recipe: Managing User Permissions

-### Step 1: Create Permission Template Group
+### 🛠️ 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
+### ⚙️ Step 2: Assign to User Group
 In Zabbix, give a User Group `Read` access to this template group.

-### Step 3: Verify via API
+### 🚀 Step 3: Verify via API
 ```graphql
 query CheckMyPermissions {
  hasPermissions(permissions: [
@ -96,13 +96,13 @@ query CheckMyPermissions {

 This recipe guides you through performing a mass import of multiple templates and hosts in a single operation.

-### Step 1: Prepare Template Import
+### 🛠️ Step 1: Prepare Template Import
 Use the `importTemplates` mutation. You can provide multiple template definitions in the `templates` array.

-### Step 2: Prepare Host Import
+### ⚙️ Step 2: Prepare Host Import
 Use the `importHosts` mutation. Link them to the newly imported templates using their names or IDs.

-### Step 3: Combined Operation (Optional)
+### 🚀 Step 3: Combined Operation (Optional)
 You can execute both mutations in a single GraphQL request to ensure atomic-like provisioning of your infrastructure.

 ```graphql
@ -121,3 +121,68 @@ mutation BulkProvisioning($templates: [CreateTemplate!]!, $hosts: [CreateHost!]!
 ```

 For detailed examples of the input structures, refer to [Sample Import Templates](../../docs/queries/sample_import_templates_mutation.graphql) and [Sample Import Hosts](../../docs/queries/sample_import_hosts_mutation.graphql).
+
+---
+
+## 🍳 Recipe: Setting up GraphQL MCP for AI Agents
+
+This recipe guides you through setting up the Model Context Protocol (MCP) server to enable AI agents like **Junie** or **Claude** to interact with your Zabbix data through the GraphQL API.
+
+### 📋 Prerequisites
+- **Zabbix GraphQL API**: Ensure the API is running (e.g. `npm run start`).
+- **Docker**: Installed and running for the MCP server container.
+
+### 🛠️ Setup A: JetBrains IDE (AI Chat & Junie)
+Configure the IDE to use the GraphQL MCP server for both the built-in AI Chat and the **Junie agent**.
+- **Prerequisite**: Generate the combined schema file (run this in your project root):
+  ```bash
+  cat schema/*.graphql > schema.graphql
+  ```
+- **Open Settings**: Navigate to `File` > `Settings` (Windows/Linux) or `IntelliJ IDEA` > `Settings` (macOS).
+- **Navigate to MCP**: Go to `Tools` > `AI Assistant` > `MCP Servers`.
+- **Add Server**: Click the **+** button and configure:
+  - **Name**: `Zabbix GraphQL`
+  - **Type**: `Command`
+  - **Command**: `docker`
+  - **Arguments**:
+    ```text
+    run -i --rm -v ${PROJECT_DIR}/mcp-config.yaml:/mcp-config.yaml -v ${PROJECT_DIR}/schema.graphql:/mcp-data/schema.graphql:ro -v ${PROJECT_DIR}/mcp/operations:/mcp/operations -e APOLLO_GRAPH_REF=local@main ghcr.io/apollographql/apollo-mcp-server:latest /mcp-config.yaml
+    ```
+- **Verify**: Ask the AI Chat or Junie: "Use MCP to list the configured Zabbix hosts".
+
+### 🛠️ Setup B: Claude Desktop
+Connect Claude Desktop to the Zabbix GraphQL API by referring to the [Apollo GraphQL MCP Documentation](https://github.com/apollographql/apollo-mcp-server).
+- **Prerequisite**: Generate the combined schema file (run this in your project root):
+  ```bash
+  cat schema/*.graphql > schema.graphql
+  ```
+- **Edit Configuration**: Open the Claude Desktop configuration file (e.g. `%APPDATA%\Claude\claude_desktop_config.json` on Windows).
+- **Add to mcpServers**: Insert the following configuration in the `mcpServers` section:
+  ```json
+  {
+    "mcpServers": {
+      "zabbix-graphql": {
+        "command": "docker",
+        "args": [
+          "run",
+          "-i",
+          "--rm",
+          "-v", "C:/path/to/your/project/mcp-config.yaml:/mcp-config.yaml",
+          "-v", "C:/path/to/your/project/schema.graphql:/mcp-data/schema.graphql:ro",
+          "-v", "C:/path/to/your/project/mcp/operations:/mcp/operations",
+          "-e", "APOLLO_GRAPH_REF=local@main",
+          "ghcr.io/apollographql/apollo-mcp-server:latest",
+          "/mcp-config.yaml"
+        ]
+      }
+    }
+  }
+  ```
+- **Restart Claude**: Fully restart the Claude Desktop application to apply the changes.
+
+### 💡 Alternative: Using Pre-running MCP Server
+If you already have the MCP server running locally (e.g. via `docker-compose.yml`), you can use a simpler configuration.
+- **Sample Configuration**: See [.ai/mcp/mcp.json](../../.ai/mcp/mcp.json) for a sample that connects to a running MCP server via HTTP.
+- **Usage**: Use this `url`-based configuration in your Claude Desktop or IDE settings instead of the `command`-based setup if you prefer to manage the MCP server lifecycle separately.
+
+> **Reference**: For more details on the benefits of GraphQL for MCP, see the [MCP & Agent Integration Guide](./mcp.md).
--- a/docs/howtos/mcp.md
+++ b/docs/howtos/mcp.md
@ -13,19 +13,15 @@ By leveraging GraphQL, the API provides a strongly-typed and introspectable inte

 You can start both the Zabbix GraphQL API and the Apollo MCP Server using Docker Compose. This setup uses a local `mcp-config.yaml` and a generated `schema.graphql`.

-1.  **Prerequisites**: Ensure you have a `.env` file with the required Zabbix connection details.
-2.  **Generate Schema**: Generate the combined schema file required by the MCP server:
-    ```bash
-    cat schema/*.graphql > schema.graphql
-    ```
-3.  **Prepare Operations**: Create the operations directory if it doesn't exist:
-    ```bash
-    mkdir -p mcp/operations
-    ```
-4.  **Start Services**:
-    ```bash
-    docker-compose up -d
-    ```
+- **Prerequisites**: Ensure you have a `.env` file with the required Zabbix connection details.
+- **Prepare Operations**: Create the operations directory if it doesn't exist:
+  ```bash
+  mkdir -p mcp/operations
+  ```
+- **Start Services**:
+  ```bash
+  docker-compose up -d
+  ```

 This will:
 - Start the `zabbix-graphql-api` on `http://localhost:4001/graphql` (internal port 4000).
@ -33,8 +29,14 @@ This will:

 ### Using with Claude Desktop

-To use this integration with Claude Desktop, add the following configuration to your Claude Desktop config file (typically `appflowy.json` or similar depending on OS, but usually `claude_desktop_config.json`):
+To use this integration with Claude Desktop, add the following configuration to your Claude Desktop config file (typically `claude_desktop_config.json`).

+- **Prerequisite**: Generate the combined schema file in your project root:
+  ```bash
+  cat schema/*.graphql > schema.graphql
+  ```
+
+- **Configuration**:
 ```json
 {
  "mcpServers": {
@ -45,7 +47,7 @@ To use this integration with Claude Desktop, add the following configuration to
        "-i",
        "--rm",
        "-v", "/path/to/your/project/mcp-config.yaml:/mcp-config.yaml",
-        "-v", "/path/to/your/project/schema.graphql:/schema.graphql",
+        "-v", "/path/to/your/project/schema.graphql:/mcp-data/schema.graphql:ro",
        "-v", "/path/to/your/project/mcp/operations:/mcp/operations",
        "-e", "APOLLO_GRAPH_REF=local@main",
        "ghcr.io/apollographql/apollo-mcp-server:latest",
@ -58,6 +60,9 @@ 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.

+#### 💡 Sample Configuration (Alternative)
+If you prefer to run the MCP server manually or via Docker Compose (as described above), you can use a HTTP-based configuration instead of the `command` execution. See [.ai/mcp/mcp.json](../../.ai/mcp/mcp.json) for a sample configuration that connects to the server running on `localhost:3000`.
+
 ### Benefits of GraphQL-enabled MCP over REST

 Integrating via GraphQL offers significant advantages for AI agents and MCP compared to the traditional Zabbix JSON-RPC (REST-like) API:
@ -73,10 +78,10 @@ Integrating via GraphQL offers significant advantages for AI agents and MCP comp

 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.
+- Analyze the step-by-step instructions in the recipe.
+- Use the MCP server's tools to inspect the current Zabbix state and schema.
+- Generate and execute the necessary GraphQL operations to fulfill the recipe's task.
+- 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."