feat: implement history push mutation and enhanced MCP logging

- Implement pushHistory mutation to support pushing telemetry data to Zabbix trapper items.

- Add VERBOSITY and MCP_LOG_* environment variables for controllable request/response logging in both API and MCP server.

- Enhance ZabbixRESTDataSource with better session handling and error logging.

- Update ZabbixHistory datasource to support history push operations.

- Expand documentation with new cookbook recipes and MCP integration guides.

- Add integration tests for history pushing (src/test/history_push*).

- Reorganize documentation, moving technical product info PDF to docs/use-cases/.

- Update GraphQL generated types and VCR templates.

src/test/history_push.test.ts

@@ -0,0 +1,66 @@
+import {ZabbixHistoryPushParams, ZabbixHistoryPushRequest} from "../datasources/zabbix-history.js";
+import {zabbixAPI} from "../datasources/zabbix-api.js";
+import {GraphQLError} from "graphql";
+
+// Mocking ZabbixAPI
+jest.mock("../datasources/zabbix-api.js", () => ({
+    zabbixAPI: {
+        post: jest.fn(),
+    }
+}));
+
+describe("ZabbixHistoryPushRequest", () => {
+    let request: ZabbixHistoryPushRequest;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        request = new ZabbixHistoryPushRequest("token");
+    });
+
+    test("createZabbixParams - transformation", () => {
+        const values = [
+            { timestamp: "2024-01-01T10:00:00Z", value: { key: "value" } },
+            { timestamp: "2024-01-01T10:00:01.500Z", value: "simple value" }
+        ];
+        const params = new ZabbixHistoryPushParams(values, "1", "item.key", "host.name");
+        const zabbixParams = request.createZabbixParams(params);
+
+        expect(zabbixParams).toHaveLength(2);
+        expect(zabbixParams[0]).toEqual({
+            itemid: "1",
+            value: JSON.stringify({ key: "value" }),
+            clock: 1704103200,
+            ns: 0
+        });
+        expect(zabbixParams[1]).toEqual({
+            itemid: "1",
+            value: "simple value",
+            clock: 1704103201,
+            ns: 500000000
+        });
+    });
+
+    test("createZabbixParams - transformation without itemid", () => {
+        const values = [
+            { timestamp: "2024-01-01T10:00:00Z", value: { key: "value" } }
+        ];
+        const params = new ZabbixHistoryPushParams(values, undefined, "item.key", "host.name");
+        const zabbixParams = request.createZabbixParams(params);
+
+        expect(zabbixParams).toHaveLength(1);
+        expect(zabbixParams[0]).toEqual({
+            host: "host.name",
+            key: "item.key",
+            value: JSON.stringify({ key: "value" }),
+            clock: 1704103200,
+            ns: 0
+        });
+    });
+
+    test("prepare - throw error if item missing", async () => {
+        const values = [{ timestamp: "2024-01-01T10:00:00Z", value: "val" }];
+        const params = new ZabbixHistoryPushParams(values, undefined, undefined, "host.name");
+
+        await expect(request.prepare(zabbixAPI, params)).rejects.toThrow("if itemid is empty both key and host must be filled");
+    });
+});

src/test/history_push_integration.test.ts

@@ -0,0 +1,127 @@
+import {ApolloServer} from '@apollo/server';
+import {schema_loader} from '../api/schema.js';
+import {zabbixAPI} from '../datasources/zabbix-api.js';
+
+// Mocking ZabbixAPI
+jest.mock("../datasources/zabbix-api.js", () => ({
+    zabbixAPI: {
+        post: jest.fn(),
+    }
+}));
+
+describe("History Push Integration Tests", () => {
+    let server: ApolloServer;
+
+    beforeAll(async () => {
+        const schema = await schema_loader();
+        server = new ApolloServer({
+            schema,
+        });
+    });
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    test("Mutation pushHistory - success with itemid", async () => {
+        const mutation = `
+            mutation PushHistory($itemid: Int, $values: [HistoryPushInput!]!) {
+                pushHistory(itemid: $itemid, values: $values) {
+                    message
+                    data {
+                        itemid
+                    }
+                }
+            }
+        `;
+
+        const variables = {
+            itemid: 1,
+            values: [
+                { timestamp: "2024-01-01T10:00:00Z", value: { foo: "bar" } }
+            ]
+        };
+
+        (zabbixAPI.post as jest.Mock).mockResolvedValueOnce({
+            response: "success",
+            data: [{ itemid: "1" }]
+        });
+
+        const response = await server.executeOperation({
+            query: mutation,
+            variables: variables,
+        }, {
+            contextValue: { zabbixAuthToken: 'test-token', dataSources: { zabbixAPI: zabbixAPI } }
+        });
+
+        expect(response.body.kind).toBe('single');
+        // @ts-ignore
+        const result = response.body.singleResult;
+        expect(result.errors).toBeUndefined();
+        expect(result.data.pushHistory.data[0].itemid).toBe("1");
+
+        expect(zabbixAPI.post).toHaveBeenCalledWith("history.push", expect.objectContaining({
+            body: expect.objectContaining({
+                method: "history.push",
+                params: expect.arrayContaining([
+                    expect.objectContaining({
+                        itemid: "1",
+                        value: JSON.stringify({ foo: "bar" })
+                    })
+                ])
+            })
+        }));
+    });
+
+    test("Mutation pushHistory - success with key and host", async () => {
+        const mutation = `
+            mutation PushHistory($key: String, $host: String, $values: [HistoryPushInput!]!) {
+                pushHistory(key: $key, host: $host, values: $values) {
+                    message
+                    data {
+                        itemid
+                    }
+                }
+            }
+        `;
+
+        const variables = {
+            key: "item.key",
+            host: "host.name",
+            values: [
+                { timestamp: "2024-01-01T10:00:00Z", value: { message: "plain value" } }
+            ]
+        };
+
+        // Mock history.push
+        (zabbixAPI.post as jest.Mock).mockResolvedValueOnce({
+            response: "success",
+            data: [{ itemid: "1" }]
+        });
+
+        const response = await server.executeOperation({
+            query: mutation,
+            variables: variables,
+        }, {
+            contextValue: { zabbixAuthToken: 'test-token', dataSources: { zabbixAPI: zabbixAPI } }
+        });
+
+        expect(response.body.kind).toBe('single');
+        // @ts-ignore
+        const result = response.body.singleResult;
+        expect(result.errors).toBeUndefined();
+        expect(result.data.pushHistory.data[0].itemid).toBe("1");
+
+        expect(zabbixAPI.post).toHaveBeenCalledWith("history.push", expect.objectContaining({
+            body: expect.objectContaining({
+                method: "history.push",
+                params: expect.arrayContaining([
+                    expect.objectContaining({
+                        host: "host.name",
+                        key: "item.key"
+                    })
+                ])
+            })
+        }));
+    });
+});