mcp-server-zignal 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Zignal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# Zignal MCP Server
+
+MCP server for [Zignal](https://zignal.dev) - AI agent analytics and signal detection.
+
+This server allows AI assistants like Claude to track conversations, detect signals (user frustration, task failures, feature requests, etc.), and retrieve analytics in real-time.
+
+## Features
+
+- **Create Events**: Track AI conversations and interactions
+- **List Events**: Search and filter tracked events
+- **List Signals**: Retrieve detected signals (issues, risks, feedback)
+
+## Installation
+
+```bash
+cd mcp-server-zignal
+npm install
+npm run build
+```
+
+## Configuration
+
+### 1. Get your Zignal API key
+
+Sign up at [zignal.dev](https://zignal.dev) and create a project to get your API key.
+
+### 2. Configure Claude Desktop
+
+Add the server to your Claude Desktop configuration:
+
+**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "zignal": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/zignal/mcp-server-zignal/dist/index.js"
+      ],
+      "env": {
+        "ZIGNAL_API_KEY": "zk_proj_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### 3. Restart Claude Desktop
+
+The Zignal tools will now be available in Claude Desktop.
+
+## Environment Variables
+
+- `ZIGNAL_API_KEY` (required): Your Zignal API key
+- `ZIGNAL_BASE_URL` (optional): API base URL (defaults to `https://kanshi-production.up.railway.app`)
+
+## Available Tools
+
+### `zignal_create_events`
+
+Create one or more events for AI signal classification.
+
+**Example:**
+```json
+{
+  "events": [
+    {
+      "user_id": "user_123",
+      "event": "ai.conversation",
+      "properties": {
+        "session_id": "sess_xyz"
+      },
+      "ai_data": {
+        "model": "claude-3",
+        "convo_id": "conv_abc",
+        "input": "I can't figure out how to export my data",
+        "output": "I'll help you export your data..."
+      }
+    }
+  ]
+}
+```
+
+### `zignal_list_events`
+
+List and search events with filters.
+
+**Parameters:**
+- `limit`: Number of events (1-100, default 50)
+- `cursor`: Pagination cursor
+- `user_id`: Filter by user
+- `convo_id`: Filter by conversation
+- `event`: Filter by event type
+- `has_signals`: Filter events with/without signals
+- `signal_type`: Filter by signal type (issue, risk, feedback)
+
+### `zignal_list_signals`
+
+List detected signals across events.
+
+**Parameters:**
+- `limit`: Number of signals (1-1000, default 100)
+- `type`: Filter by type (issue, risk, feedback, or all)
+- `name`: Filter by signal name (partial match)
+
+## Signal Types
+
+Events with `ai_data.input` and `ai_data.output` are automatically analyzed for:
+
+| Signal | Type | Description |
+|--------|------|-------------|
+| User Frustration | issue | User expresses anger or dissatisfaction |
+| Task Failure | issue | AI failed to complete the request |
+| Escalation Needed | risk | Requires human intervention |
+| Confusion | issue | User doesn't understand the response |
+| Feature Request | feedback | User requests new capability |
+| Positive Feedback | feedback | User expresses satisfaction |
+| Bug Report | issue | User reports unexpected behavior |
+
+## Example Usage in Claude
+
+Once configured, you can ask Claude:
+
+> "Track this conversation in Zignal and check for any signals"
+
+> "Show me the last 10 events where signals were detected"
+
+> "List all user frustration signals from today"
+
+Claude will use the Zignal MCP server to track conversations and retrieve analytics automatically.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+// Configuration from environment
+const ZIGNAL_API_KEY = process.env.ZIGNAL_API_KEY;
+const ZIGNAL_BASE_URL = process.env.ZIGNAL_BASE_URL || "https://kanshi-production.up.railway.app";
+if (!ZIGNAL_API_KEY) {
+    console.error("Error: ZIGNAL_API_KEY environment variable is required");
+    process.exit(1);
+}
+// Helper function to make Zignal API requests
+async function zignalRequest(method, path, body) {
+    const url = `${ZIGNAL_BASE_URL}${path}`;
+    const headers = {
+        Authorization: `Bearer ${ZIGNAL_API_KEY}`,
+        "Content-Type": "application/json",
+    };
+    const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Zignal API error (${response.status}): ${error}`);
+    }
+    return response.json();
+}
+// Create MCP server
+const server = new Server({
+    name: "mcp-server-zignal",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "zignal_create_events",
+                description: "Create one or more events in Zignal for AI signal classification. Use this to track conversations, user interactions, or AI completions. Events with ai_data (input/output) will be automatically analyzed for signals like user frustration, task failure, confusion, etc.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        events: {
+                            type: "array",
+                            description: "Array of 1-100 events to create",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    user_id: {
+                                        type: "string",
+                                        description: "User identifier (email, user ID, or anonymous ID)",
+                                    },
+                                    event: {
+                                        type: "string",
+                                        description: 'Event type (e.g., "ai.conversation", "ai.completion")',
+                                    },
+                                    properties: {
+                                        type: "object",
+                                        description: "Custom metadata (session_id, page, plan, etc.)",
+                                    },
+                                    ai_data: {
+                                        type: "object",
+                                        description: "AI conversation data for signal detection",
+                                        properties: {
+                                            model: {
+                                                type: "string",
+                                                description: 'AI model name (e.g., "gpt-4", "claude-3")',
+                                            },
+                                            convo_id: {
+                                                type: "string",
+                                                description: "Conversation/thread ID",
+                                            },
+                                            input: {
+                                                type: "string",
+                                                description: "User's message or prompt",
+                                            },
+                                            output: {
+                                                type: "string",
+                                                description: "AI's response",
+                                            },
+                                        },
+                                    },
+                                },
+                                required: ["user_id", "event"],
+                            },
+                        },
+                    },
+                    required: ["events"],
+                },
+            },
+            {
+                name: "zignal_list_events",
+                description: "List and search events with optional filters. Use this to retrieve tracked conversations, filter by user, conversation ID, event type, or whether signals were detected.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        limit: {
+                            type: "number",
+                            description: "Number of events to return (1-100, default 50)",
+                            default: 50,
+                        },
+                        cursor: {
+                            type: "string",
+                            description: "Pagination cursor from previous response",
+                        },
+                        user_id: {
+                            type: "string",
+                            description: "Filter by user ID",
+                        },
+                        convo_id: {
+                            type: "string",
+                            description: "Filter by conversation ID",
+                        },
+                        event: {
+                            type: "string",
+                            description: "Filter by event type",
+                        },
+                        has_signals: {
+                            type: "boolean",
+                            description: "Filter events with/without signals",
+                        },
+                        signal_type: {
+                            type: "string",
+                            description: 'Filter by signal type ("issue", "risk", "feedback")',
+                        },
+                    },
+                },
+            },
+            {
+                name: "zignal_list_signals",
+                description: "List detected signals across all events. Signals represent important patterns like user frustration, task failures, feature requests, etc. Use this to monitor conversation quality and identify issues.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        limit: {
+                            type: "number",
+                            description: "Number of signals to return (1-1000, default 100)",
+                            default: 100,
+                        },
+                        type: {
+                            type: "string",
+                            description: 'Filter by signal type ("issue", "risk", "feedback", or "all")',
+                            default: "all",
+                        },
+                        name: {
+                            type: "string",
+                            description: "Filter by signal name (partial match)",
+                        },
+                    },
+                },
+            },
+        ],
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "zignal_create_events": {
+                const { events } = args;
+                const result = await zignalRequest("POST", "/v1/events", events);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "zignal_list_events": {
+                const params = new URLSearchParams();
+                const { limit, cursor, user_id, convo_id, event, has_signals, signal_type, } = args;
+                if (limit)
+                    params.append("limit", limit);
+                if (cursor)
+                    params.append("cursor", cursor);
+                if (user_id)
+                    params.append("user_id", user_id);
+                if (convo_id)
+                    params.append("convo_id", convo_id);
+                if (event)
+                    params.append("event", event);
+                if (has_signals !== undefined)
+                    params.append("has_signals", String(has_signals));
+                if (signal_type)
+                    params.append("signal_type", signal_type);
+                const queryString = params.toString();
+                const path = `/v1/events${queryString ? `?${queryString}` : ""}`;
+                const result = await zignalRequest("GET", path);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "zignal_list_signals": {
+                const params = new URLSearchParams();
+                const { limit, type, name: signalName } = args;
+                if (limit)
+                    params.append("limit", limit);
+                if (type)
+                    params.append("type", type);
+                if (signalName)
+                    params.append("name", signalName);
+                const queryString = params.toString();
+                const path = `/v1/signals${queryString ? `?${queryString}` : ""}`;
+                const result = await zignalRequest("GET", path);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${errorMessage}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Zignal MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "mcp-server-zignal",
+  "version": "1.0.0",
+  "description": "MCP server for Zignal - AI agent analytics and signal detection",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-server-zignal": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "zignal",
+    "analytics",
+    "ai",
+    "signals",
+    "conversation-analytics",
+    "claude",
+    "anthropic"
+  ],
+  "author": "Zignal",
+  "license": "MIT",
+  "homepage": "https://zignal.dev",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}