@zhook/mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024 Zhook
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# @zhook/mcp-server
+
+The official Model Context Protocol (MCP) server for [Zhook](https://zhook.dev), enabling AI agents to interact with your Zhook webhooks, events, and metrics.
+
+## Features
+
+- **List Hooks**: Retrieve a list of your configured webhooks.
+- **Inspect Events**: View recent events for a specific hook.
+- **Wait for Event**: Pause execution and wait for a specific event to occur.
+- **Metrics**: Access detailed metrics about your webhook performance.
+
+## Installation
+
+You can run this server using `npx` or install it globally.
+
+### Using `npx` (Recommended for Claude Desktop)
+
+Add the following to your MCP configuration (e.g., `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "zhook": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@zhook/mcp-server"
+      ],
+      "env": {
+        "ZHOOK_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Manual Installation
+
+```bash
+npm install -g @zhook/mcp-server
+```
+
+Then run it:
+
+```bash
+zhook-mcp
+```
+
+## Configuration
+
+The server requires a Zhook API key to authenticate requests. You can obtain this key from your Zhook dashboard.
+
+| Environment Variable | Description | Required |
+|----------------------|-------------|----------|
+| `ZHOOK_API_KEY` | Your Zhook API Key | Yes |
+
+## Tools
+
+- `zhook_list_hooks`: List all available hooks in your account.
+- `zhook_get_events`: Get recent events for a hook.
+- `zhook_wait_for_event`: Wait for a specific event trigger.
+
+## License
+
+ISC

package/dist/dry-run.js

@@ -0,0 +1,67 @@
+import { ZhookClient } from './zhook-client.js';
+import * as dotenv from 'dotenv';
+dotenv.config();
+async function main() {
+    console.log("🚀 Starting Zhook MCP Server Dry Run...");
+    const apiKey = process.env.ZHOOK_API_KEY;
+    if (!apiKey) {
+        console.error("❌ Error: ZHOOK_API_KEY is not set in environment or .env file.");
+        process.exit(1);
+    }
+    const client = new ZhookClient();
+    try {
+        // 1. List Hooks
+        console.log("\n1️⃣  Listing Hooks...");
+        const hooks = await client.listHooks();
+        console.log(`   ✅ Found ${hooks.hooks.length} hooks.`);
+        // 2. Create a Test Hook
+        console.log("\n2️⃣  Creating Test Hook...");
+        const newHook = await client.createHook({
+            type: 'standard',
+            deliveryMethod: 'http',
+            metadata: {
+                name: 'MCP Dry Run Hook',
+                test: true
+            }
+        });
+        console.log(`   ✅ Created Hook: ${newHook.hookId} (${newHook.url})`);
+        // 3. Add a Destination
+        console.log("\n3️⃣  Adding Destination...");
+        const destination = await client.createDestination(newHook.hookId, {
+            type: 'http',
+            config: {
+                url: 'https://httpbin.org/post',
+                method: 'POST'
+            },
+            name: 'HttpBin Test'
+        });
+        console.log(`   ✅ Added Destination: ${destination.destinationId}`);
+        // 4. List Destinations
+        console.log("\n4️⃣  Listing Destinations...");
+        const destinations = await client.listDestinations(newHook.hookId);
+        console.log(`   ✅ Found ${destinations.destinations.length} destinations.`);
+        // 5. Create Transformation (JSONata)
+        console.log("\n5️⃣  Creating Transformation...");
+        const transformation = await client.createTransformation(newHook.hookId, {
+            name: 'Simple Pass-through',
+            code: '$'
+        });
+        console.log(`   ✅ Created Transformation: ${transformation.transformationId}`);
+        // 6. Get Metrics (Empty but checks endpoint)
+        console.log("\n6️⃣  Fetching Metrics...");
+        await client.getHookMetrics(newHook.hookId);
+        console.log(`   ✅ Metrics fetched successfully.`);
+        // 7. Clean up
+        console.log("\n7️⃣  Cleaning up (Deleting Hook)...");
+        await client.request('DELETE', `/hooks/${newHook.hookId}`); // Using raw request as deleteHook might not be strictly exposed in top-level tool yet or I missed it in ZhookClient
+        console.log(`   ✅ Hook deleted.`);
+        console.log("\n🎉 Dry Run Completed Successfully!");
+    }
+    catch (error) {
+        console.error("\n❌ Test Failed:", error.message);
+        if (error.response) {
+            console.error("   API Response:", JSON.stringify(error.response.data, null, 2));
+        }
+    }
+}
+main();

package/dist/index.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// 1. SILENCE STDOUT IMMEDIATELY
+// Redirect console.log to console.error to keep stdout pure for JSON-RPC
+const originalLog = console.log;
+console.log = console.error;
+// 2. Imports (Dynamic to ensure silence first)
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { zodToJsonSchema } from "zod-to-json-schema";
+async function main() {
+    // Dynamic imports to prevent top-level side effects from polluting stdout
+    // We import these HERE, after the console override is active.
+    const HookTools = await import('./tools/hooks.js');
+    const EventTools = await import('./tools/events.js');
+    const DestinationTools = await import('./tools/destinations.js');
+    const TransformationTools = await import('./tools/transformations.js');
+    const MetricTools = await import('./tools/metrics.js');
+    const WebhookTools = await import('./tools/webhooks.js');
+    // Create server instance
+    const server = new McpServer({
+        name: "zhook-mcp-server",
+        version: "1.0.0",
+    });
+    // Helper to convert Zod schema to clean JSON Schema for MCP
+    const toMcpSchema = (schema) => {
+        const jsonSchema = zodToJsonSchema(schema);
+        // Remove $schema field as it can cause validation issues in some SDK versions if mismatch
+        if ('$schema' in jsonSchema) {
+            delete jsonSchema['$schema'];
+        }
+        return jsonSchema;
+    };
+    // Register Webhook Test Tool
+    // Register Webhook Test Tool using explicit registerTool structure to avoid ambiguity
+    // and ensuring we pass the Zod schema directly.
+    console.error("Registering trigger_webhook with inputSchema:", WebhookTools.triggerWebhookTool.inputSchema);
+    server.registerTool(WebhookTools.triggerWebhookTool.name, {
+        description: WebhookTools.triggerWebhookTool.description,
+        inputSchema: WebhookTools.triggerWebhookTool.inputSchema,
+    }, WebhookTools.triggerWebhookTool.handler);
+    // Register Hook Tools
+    // Register Hook Tools
+    server.registerTool(HookTools.listHooksTool.name, {
+        description: HookTools.listHooksTool.description,
+        inputSchema: HookTools.listHooksTool.inputSchema,
+    }, HookTools.listHooksTool.handler);
+    server.registerTool(HookTools.createHookTool.name, {
+        description: HookTools.createHookTool.description,
+        inputSchema: HookTools.createHookTool.inputSchema,
+    }, HookTools.createHookTool.handler);
+    server.registerTool(HookTools.getHookTool.name, {
+        description: HookTools.getHookTool.description,
+        inputSchema: HookTools.getHookTool.inputSchema,
+    }, HookTools.getHookTool.handler);
+    // Register Destination Tools
+    server.registerTool(DestinationTools.listDestinationsTool.name, {
+        description: DestinationTools.listDestinationsTool.description,
+        inputSchema: DestinationTools.listDestinationsTool.inputSchema,
+    }, DestinationTools.listDestinationsTool.handler);
+    server.registerTool(DestinationTools.createDestinationTool.name, {
+        description: DestinationTools.createDestinationTool.description,
+        inputSchema: DestinationTools.createDestinationTool.inputSchema,
+    }, DestinationTools.createDestinationTool.handler);
+    server.registerTool(DestinationTools.getDestinationTool.name, {
+        description: DestinationTools.getDestinationTool.description,
+        inputSchema: DestinationTools.getDestinationTool.inputSchema,
+    }, DestinationTools.getDestinationTool.handler);
+    server.registerTool(DestinationTools.updateDestinationTool.name, {
+        description: DestinationTools.updateDestinationTool.description,
+        inputSchema: DestinationTools.updateDestinationTool.inputSchema,
+    }, DestinationTools.updateDestinationTool.handler);
+    server.registerTool(DestinationTools.deleteDestinationTool.name, {
+        description: DestinationTools.deleteDestinationTool.description,
+        inputSchema: DestinationTools.deleteDestinationTool.inputSchema,
+    }, DestinationTools.deleteDestinationTool.handler);
+    // Register Transformation Tools
+    server.registerTool(TransformationTools.listTransformationsTool.name, {
+        description: TransformationTools.listTransformationsTool.description,
+        inputSchema: TransformationTools.listTransformationsTool.inputSchema,
+    }, TransformationTools.listTransformationsTool.handler);
+    server.registerTool(TransformationTools.createTransformationTool.name, {
+        description: TransformationTools.createTransformationTool.description,
+        inputSchema: TransformationTools.createTransformationTool.inputSchema,
+    }, TransformationTools.createTransformationTool.handler);
+    server.registerTool(TransformationTools.updateTransformationTool.name, {
+        description: TransformationTools.updateTransformationTool.description,
+        inputSchema: TransformationTools.updateTransformationTool.inputSchema,
+    }, TransformationTools.updateTransformationTool.handler);
+    server.registerTool(TransformationTools.deleteTransformationTool.name, {
+        description: TransformationTools.deleteTransformationTool.description,
+        inputSchema: TransformationTools.deleteTransformationTool.inputSchema,
+    }, TransformationTools.deleteTransformationTool.handler);
+    // Register Metric Tools
+    server.registerTool(MetricTools.getHookMetricsTool.name, {
+        description: MetricTools.getHookMetricsTool.description,
+        inputSchema: MetricTools.getHookMetricsTool.inputSchema,
+    }, MetricTools.getHookMetricsTool.handler);
+    server.registerTool(MetricTools.getAggregatedHookMetricsTool.name, {
+        description: MetricTools.getAggregatedHookMetricsTool.description,
+        inputSchema: MetricTools.getAggregatedHookMetricsTool.inputSchema,
+    }, MetricTools.getAggregatedHookMetricsTool.handler);
+    // Register Event Tools
+    server.registerTool(EventTools.listEventsTool.name, {
+        description: EventTools.listEventsTool.description,
+        inputSchema: EventTools.listEventsTool.inputSchema,
+    }, EventTools.listEventsTool.handler);
+    server.registerTool(EventTools.getEventTool.name, {
+        description: EventTools.getEventTool.description,
+        inputSchema: EventTools.getEventTool.inputSchema,
+    }, EventTools.getEventTool.handler);
+    server.registerTool(EventTools.waitForEventTool.name, {
+        description: EventTools.waitForEventTool.description,
+        inputSchema: EventTools.waitForEventTool.inputSchema,
+    }, EventTools.waitForEventTool.handler);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    process.exit(1);
+});

package/dist/list-hooks-cli.js

@@ -0,0 +1,24 @@
+import { ZhookClient } from './zhook-client.js';
+import * as dotenv from 'dotenv';
+dotenv.config();
+async function main() {
+    const client = new ZhookClient();
+    try {
+        console.log("Fetching hooks...");
+        const result = await client.listHooks();
+        console.log("--- Your Hooks ---");
+        if (result.hooks && result.hooks.length > 0) {
+            result.hooks.forEach((h) => {
+                console.log(`- [${h.hookId}] ${h.metadata?.name || 'Unnamed'} (${h.url}) - Active: ${h.active}`);
+            });
+        }
+        else {
+            console.log("No hooks found.");
+        }
+        console.log("------------------");
+    }
+    catch (error) {
+        console.error("Error fetching hooks:", error.message);
+    }
+}
+main();

package/dist/tools/destinations.js

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+import { ZhookClient } from '../zhook-client.js';
+const client = new ZhookClient();
+export const listDestinationsTool = {
+    name: "list_destinations",
+    description: "List all destinations configured for a specific webhook.",
+    inputSchema: z.object({
+        hookId: z.string().describe("The ID of the hook to list destinations for")
+    }),
+    handler: async (args) => {
+        const result = await client.listDestinations(args.hookId);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }]
+        };
+    }
+};
+export const getDestinationTool = {
+    name: "get_destination",
+    description: "Get detailed configuration for a specific destination.",
+    inputSchema: z.object({
+        hookId: z.string().describe("The ID of the hook"),
+        destinationId: z.string().describe("The ID of the destination")
+    }),
+    handler: async (args) => {
+        const result = await client.getDestination(args.hookId, args.destinationId);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }]
+        };
+    }
+};
+const destinationConfigSchema = z.object({
+    type: z.enum(['http', 'mqtt', 'email']).describe("Type of destination"),
+    config: z.object({
+        // HTTP
+        url: z.string().url().optional().describe("Target URL (HTTP only)"),
+        method: z.enum(['GET', 'POST', 'PUT', 'PATCH']).optional().default('POST').describe("HTTP Method"),
+        headers: z.record(z.string(), z.string()).optional().describe("HTTP Headers"),
+        // MQTT
+        brokerUrl: z.string().optional().describe("MQTT Broker URL (e.g., mqtt://broker.hivemq.com)"),
+        topic: z.string().optional().describe("MQTT Topic"),
+        qos: z.number().min(0).max(2).optional().default(0),
+        // Email
+        email: z.string().email().optional().describe("Email address to send to")
+    }).describe("Configuration object specific to the destination type"),
+    name: z.string().optional().describe("Friendly name for this destination")
+});
+export const createDestinationTool = {
+    name: "create_destination",
+    description: "Add a new destination to a hook to forward events to.",
+    inputSchema: z.object({
+        hookId: z.string().describe("The ID of the hook"),
+        ...destinationConfigSchema.shape
+    }),
+    handler: async (args) => {
+        const payload = {
+            type: args.type,
+            config: args.config,
+            name: args.name
+        };
+        const result = await client.createDestination(args.hookId, payload);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }]
+        };
+    }
+};
+export const updateDestinationTool = {
+    name: "update_destination",
+    description: "Update an existing destination's configuration.",
+    inputSchema: z.object({
+        hookId: z.string(),
+        destinationId: z.string(),
+        ...destinationConfigSchema.partial().shape,
+        active: z.boolean().optional().describe("Enable or disable this destination")
+    }),
+    handler: async (args) => {
+        const { hookId, destinationId, ...data } = args;
+        const result = await client.updateDestination(hookId, destinationId, data);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }]
+        };
+    }
+};
+export const deleteDestinationTool = {
+    name: "delete_destination",
+    description: "Remove a destination from a hook.",
+    inputSchema: z.object({
+        hookId: z.string(),
+        destinationId: z.string()
+    }),
+    handler: async (args) => {
+        await client.deleteDestination(args.hookId, args.destinationId);
+        return {
+            content: [{
+                    type: "text",
+                    text: `Destination ${args.destinationId} deleted successfully.`
+                }]
+        };
+    }
+};

package/dist/tools/events.js

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+import { ZhookClient } from '../zhook-client.js';
+import { ZhookClient as RealtimeClient } from '@zhook/client';
+const apiClient = new ZhookClient();
+export const listEventsTool = {
+    name: "list_events",
+    description: "List recent events received by a specific hook. Useful for checking what payloads have been delivered.",
+    inputSchema: z.object({
+        hookId: z.string().describe("The ID of the hook to inspect"),
+        limit: z.number().max(50).default(5).describe("Number of events to return (max 50, default 5)")
+    }),
+    handler: async (args) => {
+        const result = await apiClient.listEvents(args.hookId, args.limit);
+        // Summary view to save context tokens
+        const summary = result.events.map((e) => ({
+            eventId: e.eventId,
+            receivedAt: e.receivedAt,
+            method: e.method,
+            contentType: e.contentType,
+            size: e.contentLength
+        }));
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(summary, null, 2)
+                }]
+        };
+    }
+};
+export const getEventTool = {
+    name: "get_event",
+    description: "Get the full JSON payload and details of a specific event.",
+    inputSchema: z.object({
+        hookId: z.string().describe("The hook ID"),
+        eventId: z.string().describe("The event ID to retrieve")
+    }),
+    handler: async (args) => {
+        const result = await apiClient.getEvent(args.hookId, args.eventId);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }]
+        };
+    }
+};
+export const waitForEventTool = {
+    name: "wait_for_event",
+    description: "Connects to the Zhook WebSocket and waits for the NEXT event to arrive on a specific hook. Returns the full event payload immediately. TIMEOUT is 60 seconds.",
+    inputSchema: z.object({
+        hookId: z.string().describe("The hook ID to watch"),
+        timeoutSeconds: z.number().default(60).describe("How long to wait before giving up")
+    }),
+    handler: async (args) => {
+        const apiKey = process.env.ZHOOK_API_KEY;
+        if (!apiKey) {
+            throw new Error("ZHOOK_API_KEY not set");
+        }
+        let wsUrl = process.env.ZHOOK_WS_URL || 'wss://api.zhook.dev/events';
+        // Ensure URL ends with /events if it's the standard API domain
+        if (!wsUrl.endsWith('/events') && !wsUrl.endsWith('/')) {
+            wsUrl += '/events';
+        }
+        // Try to find a subscriber key for this hook
+        let clientKey = apiKey;
+        try {
+            const hookDetails = await apiClient.getHook(args.hookId);
+            if (hookDetails && hookDetails.keys && Array.isArray(hookDetails.keys) && hookDetails.keys.length > 0) {
+                clientKey = hookDetails.keys[0].key || hookDetails.keys[0];
+            }
+            else if (hookDetails && hookDetails.subscriberKey) {
+                clientKey = hookDetails.subscriberKey;
+            }
+        }
+        catch (err) {
+            console.error("Failed to fetch hook details for key lookup, using API Key", err);
+        }
+        return new Promise((resolve, reject) => {
+            // Initialize Realtime Client
+            // Corrected usage: RealtimeClient(clientKey, options)
+            const realtime = new RealtimeClient(clientKey, {
+                wsUrl: wsUrl,
+                project: 'default'
+            });
+            // Setup Timeout
+            const timer = setTimeout(() => {
+                try {
+                    realtime.disconnect(); // Or close() if specific method name
+                    // Based on source code it has 'close()' or 'disconnect' might mean close in logic
+                    // Checking source: it has 'close()'. 'disconnect' is not a method on ZhookClient class.
+                    realtime.close();
+                }
+                catch (e) { /* ignore */ }
+                resolve({
+                    content: [{
+                            type: "text",
+                            text: "Timeout: No event received within " + args.timeoutSeconds + " seconds."
+                        }]
+                });
+            }, args.timeoutSeconds * 1000);
+            // Handle Events
+            const onEvent = (data) => {
+                // We only care about events for THIS hook
+                if (data.hookId === args.hookId) {
+                    clearTimeout(timer);
+                    try {
+                        realtime.close();
+                    }
+                    catch (e) { }
+                    resolve({
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify(data, null, 2)
+                            }]
+                    });
+                }
+            };
+            // Setup Listeners
+            // Source says: onHookCalled(handler) for webhook events
+            // Source says: onConnected(handler), onError(handler)
+            // It does NOT have .on('event', ...). The class does NOT extend EventEmitter.
+            // It has .handlers array and explicit methods.
+            realtime.onHookCalled(onEvent);
+            realtime.onError((err) => {
+                // Silent error handling
+            });
+            // Connect
+            realtime.connect().catch((err) => {
+                clearTimeout(timer);
+                resolve({
+                    content: [{ type: "text", text: "Error connecting to realtime: " + err.message }]
+                });
+            });
+        });
+    }
+};

package/dist/tools/hooks.js

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import { ZhookClient } from '../zhook-client.js';
+const client = new ZhookClient();
+export const listHooksTool = {
+    name: "list_hooks",
+    description: "List all webhooks configured in the Zhook account. Returns hook IDs, URLs, and active status.",
+    inputSchema: z.object({}),
+    handler: async () => {
+        const result = await client.listHooks();
+        // Format for easier reading by LLM
+        const summarized = result.hooks.map((h) => ({
+            id: h.hookId,
+            name: h.metadata?.name || 'Unnamed Hook',
+            url: h.url,
+            type: h.type || 'standard',
+            deliveryMethod: h.deliveryMethod,
+            active: h.active,
+            status: h.status
+        }));
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(summarized, null, 2)
+                }]
+        };
+    }
+};
+export const getHookTool = {
+    name: "get_hook",
+    description: "Get detailed configuration for a specific webhook, including delivery URL, metadata, and recent metrics.",
+    inputSchema: z.object({
+        hookId: z.string().describe("The ID of the hook to retrieve (e.g. hook_abc123)")
+    }),
+    handler: async (args) => {
+        console.error('[GetHook] Args received:', JSON.stringify(args));
+        const result = await client.getHook(args.hookId);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }]
+        };
+    }
+};
+const createHookSchema = z.object({
+    type: z.enum(['standard', 'mqtt']).default('standard').describe("The type of hook to create. Use 'mqtt' to create an MQTT source hook."),
+    deliveryMethod: z.enum(['http', 'websocket', 'both']).default('websocket').describe("How you want to receive events. Defaults to 'websocket' for easy testing."),
+    callbackUrl: z.string().url().optional().describe("Required if deliveryMethod is 'http' or 'both'."),
+    metadata: z.record(z.string(), z.any()).optional().describe("Optional key-value metadata to attach to the hook (name, tags)."),
+    sourceConfig: z.object({
+        topic: z.string().describe("MQTT Topic to subscribe to (required for type=mqtt)"),
+        brokerUrl: z.string().optional().describe("MQTT Broker URL"),
+        username: z.string().optional(),
+        password: z.string().optional()
+    }).optional().describe("Configuration for MQTT source. Required if type is 'mqtt'.")
+});
+export const createHookTool = {
+    name: "create_hook",
+    description: "Create a new webhook or MQTT hook. Returns the new hook ID and its public URL.",
+    inputSchema: createHookSchema,
+    handler: async (args) => {
+        // Basic validation logic that might save an API call
+        if (args.type === 'mqtt' && !args.sourceConfig) {
+            throw new Error("sourceConfig is required when type is 'mqtt'");
+        }
+        // Explicitly handle defaults if Zod doesn't apply them automatically in the handler context
+        const deliveryMethod = args.deliveryMethod || 'websocket';
+        const type = args.type === 'standard' || !args.type ? 'http' : args.type;
+        const payload = {
+            type,
+            deliveryMethod,
+            callbackUrl: args.callbackUrl,
+            metadata: args.metadata,
+            sourceConfig: args.sourceConfig
+        };
+        // Fix for MQTT source config: map brokerUrl -> url
+        if (type === 'mqtt' && payload.sourceConfig && payload.sourceConfig.brokerUrl) {
+            payload.sourceConfig.url = payload.sourceConfig.brokerUrl;
+            delete payload.sourceConfig.brokerUrl;
+        }
+        const result = await client.createHook(payload);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }]
+        };
+    }
+};

package/dist/tools/metrics.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { ZhookClient } from '../zhook-client.js';
+const client = new ZhookClient();
+export const getHookMetricsTool = {
+    name: "get_hook_metrics",
+    description: "Get real-time metrics for a specific hook (request counts, success/failure rates).",
+    inputSchema: z.object({
+        hookId: z.string().describe("The ID of the hook"),
+        timeWindow: z.enum(['hour', 'day', 'week']).default('hour').describe("Time window for metrics")
+    }),
+    handler: async (args) => {
+        const result = await client.getHookMetrics(args.hookId, args.timeWindow);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }]
+        };
+    }
+};
+export const getAggregatedHookMetricsTool = {
+    name: "get_aggregated_hook_metrics",
+    description: "Get historical aggregated metrics for a specific hook with custom date ranges.",
+    inputSchema: z.object({
+        hookId: z.string(),
+        startDate: z.string().optional().describe("ISO date string for start time"),
+        endDate: z.string().optional().describe("ISO date string for end time"),
+        groupBy: z.enum(['hour', 'day']).default('hour').describe("Granularity of aggregation")
+    }),
+    handler: async (args) => {
+        const { hookId, ...query } = args;
+        const result = await client.getAggregatedHookMetrics(args.hookId, query);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }]
+        };
+    }
+};

package/dist/tools/transformations.js

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import { ZhookClient } from '../zhook-client.js';
+const client = new ZhookClient();
+export const listTransformationsTool = {
+    name: "list_transformations",
+    description: "List all transformations configured for a specific webhook.",
+    inputSchema: z.object({
+        hookId: z.string().describe("The ID of the hook")
+    }),
+    handler: async (args) => {
+        const result = await client.listTransformations(args.hookId);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }]
+        };
+    }
+};
+const transformationSchema = z.object({
+    name: z.string().describe("Name of the transformation"),
+    code: z.string().describe("JSONata transformation code"),
+    active: z.boolean().optional().default(true)
+});
+export const createTransformationTool = {
+    name: "create_transformation",
+    description: "Create a new JSONata transformation for a hook.",
+    inputSchema: z.object({
+        hookId: z.string(),
+        ...transformationSchema.shape
+    }),
+    handler: async (args) => {
+        const { hookId, ...data } = args;
+        const result = await client.createTransformation(hookId, data);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }]
+        };
+    }
+};
+export const updateTransformationTool = {
+    name: "update_transformation",
+    description: "Update an existing transformation.",
+    inputSchema: z.object({
+        hookId: z.string(),
+        transformationId: z.string(),
+        ...transformationSchema.partial().shape
+    }),
+    handler: async (args) => {
+        const { hookId, transformationId, ...data } = args;
+        const result = await client.updateTransformation(hookId, transformationId, data);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }]
+        };
+    }
+};
+export const deleteTransformationTool = {
+    name: "delete_transformation",
+    description: "Delete a transformation from a hook.",
+    inputSchema: z.object({
+        hookId: z.string(),
+        transformationId: z.string()
+    }),
+    handler: async (args) => {
+        await client.deleteTransformation(args.hookId, args.transformationId);
+        return {
+            content: [{
+                    type: "text",
+                    text: `Transformation ${args.transformationId} deleted successfully.`
+                }]
+        };
+    }
+};

package/dist/tools/webhooks.js

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import { ZhookClient } from '../zhook-client.js';
+const apiClient = new ZhookClient();
+const triggerWebhookSchema = z.object({
+    hookId: z.string().optional().describe("The ID of the hook to trigger (preferred)"),
+    hook_id: z.string().optional().describe("Alias for hookId"),
+    payload: z.string().describe("The payload to send. Can be a JSON object, a JSON string, or just plain text."),
+    contentType: z.enum(['application/json', 'text/plain']).default('application/json').describe("Content-Type of the webhook (default: application/json)")
+});
+export const triggerWebhookTool = {
+    name: "trigger_webhook",
+    description: "Send a test webhook event to a specific Hook. This mimics a real third-party service sending data to the hook URL.",
+    inputSchema: triggerWebhookSchema,
+    handler: async (args, extra) => {
+        console.error('[TriggerWebhook] First Arg (args):', JSON.stringify(args, null, 2));
+        console.error('[TriggerWebhook] Second Arg (extra):', JSON.stringify(extra, null, 2));
+        // Handle potentially shifted arguments (if args is actually extra, where is args?)
+        // If args has 'signal' etc, it's likely 'extra'.
+        let actualArgs = args;
+        if (args && args.sessionId && args.requestId) {
+            console.error('[TriggerWebhook] First arg looks like context/extra! Args might be missing or shifted.');
+            // If the first arg is extra, maybe the args are undefined/empty?
+            // Or maybe we are using the wrong handler signature for the defined schema?
+        }
+        const normalizedArgs = {};
+        if (actualArgs) {
+            for (const key of Object.keys(actualArgs)) {
+                normalizedArgs[key.toLowerCase()] = actualArgs[key];
+            }
+        }
+        const resolvedHookId = normalizedArgs.hookid || normalizedArgs.hook_id;
+        const resolvedPayload = normalizedArgs.payload;
+        const resolvedContentType = normalizedArgs.contenttype || 'application/json';
+        if (!resolvedHookId) {
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: `Failed to trigger webhook: hookId (or hook_id) is required. Received keys: ${Object.keys(args).join(', ')}`
+                    }]
+            };
+        }
+        try {
+            const result = await apiClient.triggerWebhook(resolvedHookId, resolvedPayload, resolvedContentType);
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            status: result.status,
+                            data: result.data
+                        }, null, 2)
+                    }]
+            };
+        }
+        catch (error) {
+            // Extract request details if available
+            const config = error.config || {};
+            const requestUrl = config.url || 'unknown';
+            const baseURL = config.baseURL || 'unknown';
+            const method = config.method || 'unknown';
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: `Failed to trigger webhook.
+Error: ${error.message}
+Status: ${error.response?.status} ${error.response?.statusText}
+Method: ${method.toUpperCase()}
+Attempted URL: ${requestUrl}
+Base URL: ${baseURL}
+Data: ${JSON.stringify(error.response?.data || {}, null, 2)}`
+                    }]
+            };
+        }
+    }
+};

package/dist/zhook-client.js

@@ -0,0 +1,134 @@
+import axios from 'axios';
+import dotenv from 'dotenv';
+// Load environment variables
+dotenv.config();
+// Zhook API Client
+export class ZhookClient {
+    client;
+    constructor() {
+        const apiKey = process.env.ZHOOK_API_KEY;
+        if (!apiKey) {
+            throw new Error('ZHOOK_API_KEY environment variable is required');
+        }
+        const baseURL = process.env.ZHOOK_API_URL || 'https://api.zhook.dev/api/v1';
+        this.client = axios.create({
+            baseURL,
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+                'User-Agent': 'zhook-mcp-server/1.0.0'
+            }
+        });
+    }
+    // Generic request wrapper
+    async request(method, url, data, params) {
+        try {
+            const response = await this.client.request({
+                method,
+                url,
+                data,
+                params
+            });
+            return response.data;
+        }
+        catch (error) {
+            if (axios.isAxiosError(error) && error.response) {
+                throw new Error(`Zhook API Error: ${error.response.status} ${JSON.stringify(error.response.data)}`);
+            }
+            throw error;
+        }
+    }
+    // Hooks
+    // Destinations
+    async listDestinations(hookId) {
+        return this.request('GET', `/hooks/${hookId}/destinations`);
+    }
+    async createDestination(hookId, data) {
+        return this.request('POST', `/hooks/${hookId}/destinations`, data);
+    }
+    async getDestination(hookId, destinationId) {
+        return this.request('GET', `/hooks/${hookId}/destinations/${destinationId}`);
+    }
+    async updateDestination(hookId, destinationId, data) {
+        return this.request('PUT', `/hooks/${hookId}/destinations/${destinationId}`, data);
+    }
+    async deleteDestination(hookId, destinationId) {
+        return this.request('DELETE', `/hooks/${hookId}/destinations/${destinationId}`);
+    }
+    // Transformations
+    async listTransformations(hookId) {
+        return this.request('GET', `/hooks/${hookId}/transformations`);
+    }
+    async createTransformation(hookId, data) {
+        return this.request('POST', `/hooks/${hookId}/transformations`, data);
+    }
+    async updateTransformation(hookId, transformationId, data) {
+        return this.request('PUT', `/hooks/${hookId}/transformations/${transformationId}`, data);
+    }
+    async deleteTransformation(hookId, transformationId) {
+        return this.request('DELETE', `/hooks/${hookId}/transformations/${transformationId}`);
+    }
+    // Metrics
+    async getHookMetrics(hookId, timeWindow = 'hour') {
+        return this.request('GET', `/metrics/hooks/${hookId}?timeWindow=${timeWindow}`);
+    }
+    async getAggregatedHookMetrics(hookId, query) {
+        const params = new URLSearchParams(query);
+        return this.request('GET', `/metrics/hooks/${hookId}/aggregated?${params.toString()}`);
+    }
+    // Hooks
+    async listHooks() {
+        const result = await this.request('GET', '/hooks');
+        // Legacy domain fix: Ensure URLs use zhook.dev instead of hookr.cloud
+        if (result && result.hooks) {
+            result.hooks.forEach((h) => {
+                if (h.url && h.url.includes('hookr.cloud')) {
+                    h.url = h.url.replace('hookr.cloud', 'zhook.dev');
+                }
+                if (h.callbackUrl && h.callbackUrl.includes('hookr.cloud')) {
+                    h.callbackUrl = h.callbackUrl.replace('hookr.cloud', 'zhook.dev');
+                }
+            });
+        }
+        return result;
+    }
+    async getHook(hookId) {
+        const result = await this.request('GET', `/hooks/${hookId}`);
+        // Legacy domain fix
+        if (result) {
+            if (result.url && result.url.includes('hookr.cloud')) {
+                result.url = result.url.replace('hookr.cloud', 'zhook.dev');
+            }
+            if (result.callbackUrl && result.callbackUrl.includes('hookr.cloud')) {
+                result.callbackUrl = result.callbackUrl.replace('hookr.cloud', 'zhook.dev');
+            }
+        }
+        return result;
+    }
+    async createHook(data) {
+        return this.request('POST', '/hooks', data);
+    }
+    // Events
+    async listEvents(hookId, limit = 10) {
+        return this.request('GET', `/hooks/${hookId}/events`, undefined, { limit });
+    }
+    async getEvent(hookId, eventId) {
+        return this.request('GET', `/hooks/${hookId}/events/${eventId}`);
+    }
+    // Webhooks (Testing)
+    async triggerWebhook(hookId, payload, contentType = 'application/json') {
+        console.error(`[ZhookClient] triggerWebhook called with hookId: ${hookId}, payload: ${JSON.stringify(payload)}`);
+        const config = {
+            headers: {
+                'Content-Type': contentType
+            }
+        };
+        // We need to hit the INGESTION endpoint (/h/:id) which is the public webhook receiver.
+        // /hooks/:id is primarily for GET (details) or requires correct routing in server.js.
+        // The user confirmed /h/:id is the correct path for POSTing webhooks.
+        const baseUrl = this.client.defaults.baseURL || '';
+        const rootUrl = baseUrl.replace(/\/api\/v1\/?$/, '');
+        // Use the short URL /h/:id
+        return this.client.post(`${rootUrl}/h/${hookId}`, payload, config);
+    }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@zhook/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP Server for Zhook - Manage webhooks and inspect events from your AI agent",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "zhook-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "zhook",
+    "webhook",
+    "ai",
+    "agent",
+    "llm",
+    "claude",
+    "chatgpt"
+  ],
+  "author": "Zhook",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhookteam/zhook-mcp.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://zhook.dev",
+  "bugs": {
+    "url": "https://github.com/zhookteam/zhook-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.1",
+    "@zhook/client": "^1.0.0",
+    "axios": "^1.7.9",
+    "dotenv": "^16.4.5",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.25.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist"
+  ]
+}