From bbf7357e9395105f4f4fbaa43385c3ea22fde60f Mon Sep 17 00:00:00 2001
From: Andreas Hilbig <andreas.hilbig@hilbigit.com>
Date: Fri, 30 Jan 2026 19:04:05 +0100
Subject: [PATCH] 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.
---
 .ai/mcp/mcp.json        |  7 +++
 .gitignore              |  3 ++
 .idea/workspace.xml     | 20 ++++++++-
 .junie/guidelines.md    | 16 ++++++-
 README.md               | 82 +++++++++++++++++-----------------
 docker-compose.yml      | 17 ++++++-
 docs/howtos/README.md   |  1 -
 docs/howtos/cookbook.md | 99 ++++++++++++++++++++++++++++++++++-------
 docs/howtos/mcp.md      | 43 ++++++++++--------
 mcp-config.yaml         |  2 +-
 package.json            |  4 +-
 roadmap.md              | 23 ++++++++++
 12 files changed, 230 insertions(+), 87 deletions(-)
 create mode 100644 .ai/mcp/mcp.json
 create mode 100644 roadmap.md

diff --git a/.ai/mcp/mcp.json b/.ai/mcp/mcp.json
new file mode 100644
index 0000000..fdccbec
--- /dev/null
+++ b/.ai/mcp/mcp.json
@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "zabbix-graphql": {
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 381cdbc..78ded7b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -130,3 +130,6 @@ dist
 .pnp.*
 
 .vscode/settings.json
+
+# Generated schema for MCP
+schema.graphql
diff --git a/.idea/workspace.xml b/.idea/workspace.xml
index 9f7d5a4..c161fad 100644
--- a/.idea/workspace.xml
+++ b/.idea/workspace.xml
@@ -5,8 +5,17 @@
   </component>
   <component name="ChangeListManager">
     <list default="true" id="d7a71994-2699-4ae4-9fd2-ee13b7f33d35" name="Changes" comment="docs: refactor documentation and upgrade to Node.js 24&#10;&#10;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).&#10;&#10;Changes:&#10;- Environment &amp; CI/CD:&#10;  - Set Node.js version to &gt;=24 in package.json and .nvmrc.&#10;  - Updated Dockerfile to use Node 24 base image.&#10;  - Updated @types/node to ^24.10.9.&#10;- Documentation:&#10;  - Refactored README.md with comprehensive technical reference, configuration details, and Zabbix-to-GraphQL mapping.&#10;  - Created docs/howtos/cookbook.md with practical recipes for common tasks and AI test generation.&#10;  - Updated docs/howtos/mcp.md to emphasize GraphQL's advantages for AI agents and Model Context Protocol.&#10;  - Added readme.improvement.plan.md to track documentation evolution.&#10;  - Enhanced all how-to guides with improved cross-references and up-to-date information.&#10;- Guidelines:&#10;  - Updated .junie/guidelines.md with Node 24 requirements and enhanced commit message standards (Conventional Commits 1.0.0).&#10;- Infrastructure &amp; Code:&#10;  - Updated docker-compose.yml with Apollo MCP server integration.&#10;  - Refined configuration and schema handling in src/api/ and src/datasources/.&#10;  - Synchronized generated TypeScript types with schema updates.">
+      <change afterPath="$PROJECT_DIR$/.ai/mcp/mcp.json" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/roadmap.md" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/.idea/workspace.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/workspace.xml" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/.junie/guidelines.md" beforeDir="false" afterPath="$PROJECT_DIR$/.junie/guidelines.md" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/docker-compose.yml" beforeDir="false" afterPath="$PROJECT_DIR$/docker-compose.yml" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/docs/howtos/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/docs/howtos/README.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/docs/howtos/cookbook.md" beforeDir="false" afterPath="$PROJECT_DIR$/docs/howtos/cookbook.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/docs/howtos/mcp.md" beforeDir="false" afterPath="$PROJECT_DIR$/docs/howtos/mcp.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/mcp-config.yaml" beforeDir="false" afterPath="$PROJECT_DIR$/mcp-config.yaml" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/package.json" beforeDir="false" afterPath="$PROJECT_DIR$/package.json" afterDir="false" />
     </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
@@ -17,7 +26,7 @@
     <execution />
   </component>
   <component name="EmbeddingIndexingInfo">
-    <option name="cachedIndexableFilesCount" value="109" />
+    <option name="cachedIndexableFilesCount" value="111" />
     <option name="fileBasedEmbeddingIndicesEnabled" value="true" />
   </component>
   <component name="Git.Settings">
@@ -43,7 +52,13 @@
   </component>
   <component name="McpProjectServerCommands">
     <commands />
-    <urls />
+    <urls>
+      <McpServerConfigurationProperties>
+        <option name="allowedToolsNames" />
+        <option name="enabled" value="true" />
+        <option name="name" value="zabbix-graphql" />
+      </McpServerConfigurationProperties>
+    </urls>
   </component>
   <component name="ProblemsViewState">
     <option name="selectedTabId" value="CurrentFile" />
@@ -200,6 +215,7 @@
       <workItem from="1769699975260" duration="75000" />
       <workItem from="1769700092648" duration="5212000" />
       <workItem from="1769724930397" duration="16056000" />
+      <workItem from="1769789496322" duration="5496000" />
     </task>
     <task id="LOCAL-00001" summary="chore: Update IntelliJ workspace settings and add GitHub Actions workflow for Docker deployment">
       <option name="closed" value="true" />
diff --git a/.junie/guidelines.md b/.junie/guidelines.md
index 80d96a7..5c5ed6f 100644
--- a/.junie/guidelines.md
+++ b/.junie/guidelines.md
@@ -2,9 +2,12 @@
 
 This document provides concise information and best practices for developers working on the Zabbix GraphQL API project.
 
+## Roadmap
+The [Roadmap](../roadmap.md) is to be considered as outlook giving constraints on architectural and design decisions for current work on the project.
+
 ### Environment
-- **Operating System:** Windows with WSL + Ubuntu installed.
-- **Commands:** Always execute Linux commands (e.g. use `ls` instead of `dir`).
+- **Operating System**: Windows with WSL + Ubuntu installed.
+- **Commands**: Always execute Linux commands (e.g. use `ls` instead of `dir`).
 
 
 ## Tech Stack
@@ -41,6 +44,15 @@ This document provides concise information and best practices for developers wor
 - **Testing**: Write reproduction tests for bugs and cover new features with both unit and integration tests in `src/test/`.
 - **Grammar & Style**: Avoid using a comma after "e.g." or "i.e." (e.g. use "e.g. example" instead of "e.g., example").
 
+### Documentation Style
+- **Bullet Points**: Use bullet points instead of enumerations for lists to maintain consistency across all documentation.
+- **Visual Style**: Use icons in headers and bold subjects for primary list items (e.g. `- **Feature**: Description`) to match the `README.md` style.
+    - *Note*: Standardize colon placement (outside bold tags) for primary list items.
+- **Sub-points**: Use indented bullet points for detailed descriptions or additional context.
+    - *Format*: Use the `- *Subject*: Description` format for specific references or categorized sub-items (e.g. `- *Reference*: ...`).
+    - *Format*: Use plain text for general descriptions that follow a primary list item.
+- **Formatting**: Avoid extra blank lines between headers and list items.
+
 ### Git Standards
 - **Commit Messages:** Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) (e.g. `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `refactor:`, `style:`).
     - If a commit is complex and covers different aspects, the message **must** always contain a detailed list of what was changed within the optional "body" section, in addition to the short "description" in the header.
diff --git a/README.md b/README.md
index 2e47315..f17a842 100644
--- a/README.md
+++ b/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.
 
diff --git a/docker-compose.yml b/docker-compose.yml
index f39e29d..ace4fdb 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -18,10 +18,23 @@ services:
       - "3000:8000"
     volumes:
       - ./mcp-config.yaml:/mcp-config.yaml
-      - ./schema.graphql:/schema.graphql
+      - mcp-shared:/mcp-data:ro
       - ./mcp/operations:/mcp/operations
     command: /mcp-config.yaml
     environment:
       - APOLLO_GRAPH_REF=local@main
     depends_on:
-      - zabbix-graphql-api
+      schema-gen:
+        condition: service_completed_successfully
+      zabbix-graphql-api:
+        condition: service_started
+
+  schema-gen:
+    image: alpine
+    volumes:
+      - ./schema:/schema:ro
+      - mcp-shared:/mcp-data
+    command: sh -c "cat /schema/*.graphql > /mcp-data/schema.graphql"
+
+volumes:
+  mcp-shared:
diff --git a/docs/howtos/README.md b/docs/howtos/README.md
index c67e860..3a90dc4 100644
--- 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.
diff --git a/docs/howtos/cookbook.md b/docs/howtos/cookbook.md
index c807958..bb0d812 100644
--- 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).
diff --git a/docs/howtos/mcp.md b/docs/howtos/mcp.md
index 9d089a9..3d2794b 100644
--- 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."
diff --git a/mcp-config.yaml b/mcp-config.yaml
index 389a203..f8f6e7a 100644
--- a/mcp-config.yaml
+++ b/mcp-config.yaml
@@ -10,7 +10,7 @@ operations:
     - /mcp/operations
 schema:
   source: local
-  path: /schema.graphql
+  path: /mcp-data/schema.graphql
 introspection:
   execute:
     enabled: true
diff --git a/package.json b/package.json
index 9a0abae..db51297 100644
--- a/package.json
+++ b/package.json
@@ -6,11 +6,11 @@
   "type": "module",
   "scripts": {
     "compile": "tsc",
-    "start": "nodemon --watch \"src/**\" --watch \"schema.graphql\" --ext \"ts,json\" --exec \"node --import tsx ./src/index.ts\"",
+    "start": "nodemon --watch \"src/**\" --watch \"schema/**\" --ext \"ts,json,graphql\" --exec \"node --import tsx ./src/index.ts\"",
     "prod": "npm run copy-schema && node ./dist/index.js",
     "test": "jest --detectOpenHandles --forceExit --bail",
     "codegen": "graphql-codegen --config codegen.ts --watch",
-    "nodemon": "nodemon --watch \"src/**\" --watch \"schema.graphql\" --ext \"ts,json\" --exec \"tsc",
+    "nodemon": "nodemon --watch \"src/**\" --watch \"schema/**\" --ext \"ts,json,graphql\" --exec \"tsc",
     "copy-schema": "cp -R schema ./dist/"
   },
   "keywords": [],
diff --git a/roadmap.md b/roadmap.md
new file mode 100644
index 0000000..2f142ff
--- /dev/null
+++ b/roadmap.md
@@ -0,0 +1,23 @@
+# 🗺️ Roadmap
+
+This document outlines the achieved milestones and planned enhancements for the Zabbix GraphQL API project.
+
+## ✅ Achieved Milestones
+- **🎯 VCR Product Integration**:
+  - Developed a specialized **GraphQL API** as part of the VCR Product. This enables the use of **Zabbix** as a robust base for monitoring and controlling **IoT devices**.
+  - *First use case*: Control of mobile traffic jam warning installations on **German Autobahns**.
+
+- **🔓 Open Source Extraction & AI Integration**:
+  - Extracted the core functionality of the API to publish it as an **Open Source** project.
+  - Enhanced it with **Model Context Protocol (MCP)** and **AI agent** integration to enable workflow and agent-supported use cases within the VCR or other applications.
+
+## 📅 Planned Enhancements
+- **📦 CI/CD & Package Publishing**:
+  - Build and publish the API as an **npm package** as part of the `.forgejo` workflow to simplify distribution and updates.
+
+- **🧱 Flexible Usage by publishing to [npmjs.com](https://www.npmjs.com/)**:
+  - Transform the package into a versatile tool that can be used either **standalone** or as a **core library**, allowing other projects to include and extend it easily.
+
+- **🧩 Extension Project**: `zabbix-graphql-api-problems`
+  - Create the first official extension, `zabbix-graphql-api-problems`
+  - Add support for **problem and trigger-related** queries. This will leverage **MCP + AI agents** to automatically react to Zabbix problems within external workflows.