@qovva/mcp 0.1.0

package/README.md

@@ -0,0 +1,126 @@
+# @qovva/mcp
+
+Local stdio MCP server for [Qovva](https://qovva.app) — the AI-ready webhook debugger.
+
+Connect Cursor, Claude Desktop, Windsurf, VS Code, or any MCP-aware AI client to your live webhook capture history in seconds. Search webhooks with natural language, replay payloads, inspect anomalies, and debug integration issues — all from your AI assistant.
+
+## Quick start
+
+### 1. Get an API key
+
+Sign in at [qovva.app/dashboard](https://qovva.app/dashboard), open **API key management**, and create a key named after the client you're connecting (e.g. `Cursor work`).
+
+Copy the key immediately — it is shown exactly once.
+
+### 2. Add to your MCP client
+
+#### Cursor / Windsurf / Continue
+
+Add to `.cursor/mcp.json`, `.windsurf/mcp.json`, or your client's equivalent:
+
+```json
+{
+  "mcpServers": {
+    "qovva": {
+      "command": "npx",
+      "args": ["-y", "@qovva/mcp"],
+      "env": {
+        "QOVVA_API_BASE_URL": "https://api.qovva.app",
+        "QOVVA_API_KEY": "qw_live_..."
+      }
+    }
+  }
+}
+```
+
+#### Claude Desktop
+
+Open **Settings → Developer → Edit Config** and add the same block under `mcpServers`.
+
+#### VS Code (GitHub Copilot / MCP extension)
+
+Add to your `settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "qovva": {
+        "command": "npx",
+        "args": ["-y", "@qovva/mcp"],
+        "env": {
+          "QOVVA_API_BASE_URL": "https://api.qovva.app",
+          "QOVVA_API_KEY": "qw_live_..."
+        }
+      }
+    }
+  }
+}
+```
+
+### 3. Ask your assistant
+
+Once connected, you can ask questions in plain English and the assistant will translate them into the right tool calls:
+
+- *"Show me all failed Stripe payments from last week"*
+- *"What did the last POST to my endpoint send in the body?"*
+- *"Are there any anomalies in my recent Shopify webhooks?"*
+- *"Replay the latest checkout event to localhost:3000"*
+- *"List all my endpoints and their webhook URLs"*
+- *"Compare the last two invoice.paid events — did the schema change?"*
+
+## Available tools
+
+| Tool | Description |
+|---|---|
+| `test_qovva_connection` | Verify the API key and return your active plan metadata |
+| `get_recent_webhooks` | Fetch recently captured webhooks with optional pagination and time filters |
+| `get_webhook_by_id` | Fetch full masked detail for a single webhook by its Qovva ID |
+| `search_webhooks` | Search captured webhooks by keyword, HTTP method, endpoint, or time range — supports natural language queries that the assistant decomposes into structured filters |
+| `list_endpoints` | List all your configured catch endpoints with their webhook URLs and custom response settings |
+| `replay_webhook` | Forward a captured webhook's original payload to any URL and get the response status, body, and duration |
+| `get_anomalies` | Retrieve anomalies detected by Qovva's rule-based engine — flags missing fields, type changes, and new fields compared to the baseline for each event type |
+
+## Prompts
+
+| Prompt | Description |
+|---|---|
+| `debug_webhooks` | A guided debugging prompt that teaches the assistant how to decompose natural language questions into multi-step webhook investigations using all available tools |
+
+## Natural language search
+
+The `search_webhooks` tool is designed to work with natural language. When you ask something like *"Show me all failed Stripe payments from last week"*, the assistant breaks it down:
+
+- **query** → `stripe payment_intent.failed` (keywords from the question)
+- **method** → `POST` (webhooks are almost always POST)
+- **since** → ISO 8601 date for 7 days ago
+
+This works out of the box — no special syntax required.
+
+## Anomaly detection
+
+Qovva automatically monitors the structure of your incoming webhook payloads and flags deviations:
+
+- **Missing fields** — a field that was present in the last N events has disappeared
+- **Type changes** — a field changed from `string` to `number` (or any other type shift)
+- **New fields** — a previously unseen field appeared in the payload
+
+Anomalies are surfaced through the `get_anomalies` tool and visible in the dashboard inspector. The detection engine uses stored field baselines per event type and starts flagging after 3+ consistent samples.
+
+## Requirements
+
+- Node.js 20 or later
+- A valid Qovva API key (generated from the dashboard)
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `QOVVA_API_KEY` | Yes | Your Qovva MCP API key |
+| `QOVVA_API_BASE_URL` | No | Qovva API origin (default: `https://api.qovva.app`) |
+
+## Learn more
+
+- [Qovva documentation](https://qovva.app/docs/mcp)
+- [Dashboard](https://qovva.app/dashboard)
+- [Pricing](https://qovva.app/pricing)

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,386 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/schemas.ts
+import { z } from "zod";
+var webhookSummarySchema = z.object({
+  id: z.string().uuid(),
+  method: z.string(),
+  contentType: z.string().nullable(),
+  sizeBytes: z.number().int().nonnegative(),
+  createdAt: z.string(),
+  excerpt: z.string().nullable(),
+  signatureStatus: z.string()
+});
+var maskedHeadersSchema = z.record(
+  z.string(),
+  z.union([z.string(), z.array(z.string())])
+);
+var webhookDetailSchema = webhookSummarySchema.extend({
+  queryParams: z.record(z.string(), z.union([z.string(), z.array(z.string())])),
+  headers: maskedHeadersSchema,
+  bodyText: z.string().nullable(),
+  bodyJson: z.unknown().nullable()
+});
+var paginatedWebhookSchema = z.object({
+  items: z.array(webhookSummarySchema),
+  nextCursor: z.string().nullable()
+});
+var searchWebhooksResponseSchema = z.object({
+  items: z.array(webhookSummarySchema),
+  query: z.string(),
+  nextCursor: z.string().nullable()
+});
+var connectionStatusSchema = z.object({
+  ok: z.literal(true),
+  userId: z.string(),
+  planSlug: z.string(),
+  retentionDays: z.number().int().nonnegative(),
+  apiKeyLimit: z.number().int().nonnegative()
+});
+var endpointSchema = z.object({
+  id: z.string().uuid(),
+  slug: z.string(),
+  label: z.string(),
+  url: z.string(),
+  responseStatus: z.number().int(),
+  responseBody: z.string(),
+  responseContentType: z.string(),
+  responseDelayMs: z.number().int(),
+  hasSigningSecret: z.boolean(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+});
+var endpointsResponseSchema = z.object({
+  items: z.array(endpointSchema)
+});
+var replayResultSchema = z.object({
+  id: z.string().uuid(),
+  webhookId: z.string().uuid(),
+  targetUrl: z.string(),
+  statusCode: z.number().int().nullable(),
+  responseBody: z.string().nullable(),
+  error: z.string().nullable(),
+  durationMs: z.number().int().nullable(),
+  createdAt: z.string()
+});
+var anomalySchema = z.object({
+  id: z.string().uuid(),
+  webhookId: z.string().uuid(),
+  ruleType: z.string(),
+  severity: z.string(),
+  message: z.string(),
+  details: z.unknown().nullable(),
+  createdAt: z.string()
+});
+var anomaliesResponseSchema = z.object({
+  items: z.array(anomalySchema)
+});
+
+// src/index.ts
+import { z as z2 } from "zod";
+var QovvaAPIClient = class {
+  baseURL = process.env.QOVVA_API_BASE_URL ?? "http://localhost:8080";
+  apiKey = process.env.QOVVA_API_KEY ?? "";
+  requireAPIKey() {
+    if (!this.apiKey) {
+      throw new Error("QOVVA_API_KEY is not set");
+    }
+  }
+  async fetchJSON({
+    path,
+    parse
+  }) {
+    this.requireAPIKey();
+    const response = await fetch(`${this.baseURL}${path}`, {
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`
+      },
+      cache: "no-store"
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`Qovva API request failed (${response.status}): ${body}`);
+    }
+    const json = await response.json();
+    const parsed = parse(json);
+    if (!parsed.success || !parsed.data) {
+      throw new Error(`Qovva API returned an invalid payload for ${path}`);
+    }
+    return parsed.data;
+  }
+  async postJSON({
+    path,
+    body,
+    parse
+  }) {
+    this.requireAPIKey();
+    const response = await fetch(`${this.baseURL}${path}`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Qovva API request failed (${response.status}): ${text}`);
+    }
+    const json = await response.json();
+    const parsed = parse(json);
+    if (!parsed.success || !parsed.data) {
+      throw new Error(`Qovva API returned an invalid payload for ${path}`);
+    }
+    return parsed.data;
+  }
+  async connectionStatus() {
+    return this.fetchJSON({
+      path: "/v1/mcp/health",
+      parse: (value) => connectionStatusSchema.safeParse(value)
+    });
+  }
+  async recentWebhooks(args) {
+    const params = new URLSearchParams();
+    if (args.limit) params.set("limit", String(args.limit));
+    if (args.cursor) params.set("cursor", args.cursor);
+    if (args.since) params.set("since", args.since);
+    return this.fetchJSON({
+      path: `/v1/mcp/webhooks${params.size > 0 ? `?${params.toString()}` : ""}`,
+      parse: (value) => paginatedWebhookSchema.safeParse(value)
+    });
+  }
+  async webhookByID(id) {
+    return this.fetchJSON({
+      path: `/v1/mcp/webhooks/${id}`,
+      parse: (value) => webhookDetailSchema.safeParse(value)
+    });
+  }
+  async searchWebhooks(args) {
+    const params = new URLSearchParams();
+    if (args.query) params.set("q", args.query);
+    if (args.endpoint) params.set("endpoint", args.endpoint);
+    if (args.method) params.set("method", args.method);
+    if (args.limit) params.set("limit", String(args.limit));
+    if (args.since) params.set("since", args.since);
+    if (args.cursor) params.set("cursor", args.cursor);
+    return this.fetchJSON({
+      path: `/v1/mcp/webhooks/search?${params.toString()}`,
+      parse: (value) => searchWebhooksResponseSchema.safeParse(value)
+    });
+  }
+  async listEndpoints() {
+    return this.fetchJSON({
+      path: "/v1/mcp/endpoints",
+      parse: (value) => endpointsResponseSchema.safeParse(value)
+    });
+  }
+  async replayWebhook(args) {
+    return this.postJSON({
+      path: `/v1/mcp/webhooks/${args.webhookId}/replay`,
+      body: { targetUrl: args.targetUrl },
+      parse: (value) => replayResultSchema.safeParse(value)
+    });
+  }
+  async listAnomalies(args) {
+    const params = new URLSearchParams();
+    if (args.webhookId) params.set("webhookId", args.webhookId);
+    if (args.limit) params.set("limit", String(args.limit));
+    if (args.since) params.set("since", args.since);
+    return this.fetchJSON({
+      path: `/v1/mcp/anomalies${params.size > 0 ? `?${params.toString()}` : ""}`,
+      parse: (value) => anomaliesResponseSchema.safeParse(value)
+    });
+  }
+};
+function toolResult(payload) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2)
+      }
+    ],
+    structuredContent: payload
+  };
+}
+async function main() {
+  const api = new QovvaAPIClient();
+  const server = new McpServer({
+    name: "qovva",
+    version: "0.0.1"
+  });
+  server.registerTool(
+    "test_qovva_connection",
+    {
+      description: "Validate the Qovva API key and return the active plan metadata.",
+      inputSchema: {}
+    },
+    async () => {
+      const status = await api.connectionStatus();
+      return toolResult(status);
+    }
+  );
+  server.registerTool(
+    "get_recent_webhooks",
+    {
+      description: "Fetch recently captured webhooks from Qovva.",
+      inputSchema: {
+        limit: z2.number().int().positive().max(100).optional(),
+        cursor: z2.string().optional(),
+        since: z2.string().optional()
+      }
+    },
+    async ({ limit, cursor, since }) => {
+      const result = await api.recentWebhooks({ limit, cursor, since });
+      return toolResult(result);
+    }
+  );
+  server.registerTool(
+    "get_webhook_by_id",
+    {
+      description: "Fetch one webhook by its Qovva ID.",
+      inputSchema: {
+        id: z2.string().uuid()
+      }
+    },
+    async ({ id }) => {
+      const result = await api.webhookByID(id);
+      return toolResult(result);
+    }
+  );
+  server.registerTool(
+    "search_webhooks",
+    {
+      description: `Search captured webhooks using structured filters. Supports natural language queries \u2014 decompose user questions into the appropriate parameters:
+
+- query: Free-text search across method, headers, query params, and body content. Use for provider names (e.g. "stripe"), event types (e.g. "checkout.session.completed"), or payload content (e.g. "failed").
+- method: HTTP method filter \u2014 "GET", "POST", "PUT", "PATCH", "DELETE".
+- endpoint: Filter by endpoint UUID. Use list_endpoints to resolve names to IDs.
+- since: ISO 8601 timestamp. For relative time like "last week", compute the actual date.
+- limit: Max results (1-100).
+- cursor: Pagination cursor from a previous response.
+
+Examples of natural language \u2192 parameters:
+  "Show me all failed Stripe payments from last week" \u2192 query:"stripe payment_intent failed", method:"POST", since:"<7 days ago ISO>"
+  "GitHub push events today" \u2192 query:"github push", method:"POST", since:"<today midnight ISO>"
+  "All POST requests to my Shopify endpoint" \u2192 method:"POST", endpoint:"<shopify endpoint ID>"
+
+At least one filter is required.`,
+      inputSchema: {
+        query: z2.string().optional().describe("Free-text search: provider names, event types, payload content, error messages"),
+        endpoint: z2.string().optional().describe("Endpoint UUID \u2014 use list_endpoints to resolve names"),
+        method: z2.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).optional().describe("HTTP method filter"),
+        limit: z2.number().int().positive().max(100).optional(),
+        since: z2.string().optional().describe("ISO 8601 timestamp \u2014 compute from relative expressions like 'last week'"),
+        cursor: z2.string().optional()
+      }
+    },
+    async ({ query, endpoint, method, limit, since, cursor }) => {
+      const result = await api.searchWebhooks({ query, endpoint, method, limit, since, cursor });
+      return toolResult(result);
+    }
+  );
+  server.registerTool(
+    "list_endpoints",
+    {
+      description: "List all webhook endpoints for the authenticated user, including their URL, custom response config, and creation date.",
+      inputSchema: {}
+    },
+    async () => {
+      const result = await api.listEndpoints();
+      return toolResult(result);
+    }
+  );
+  server.registerTool(
+    "replay_webhook",
+    {
+      description: "Replay a previously captured webhook to a target URL. Sends the original method, headers, and body to the specified URL and returns the response status, body, and duration.",
+      inputSchema: {
+        webhookId: z2.string().uuid(),
+        targetUrl: z2.string().url()
+      }
+    },
+    async ({ webhookId, targetUrl }) => {
+      const result = await api.replayWebhook({ webhookId, targetUrl });
+      return toolResult(result);
+    }
+  );
+  server.registerTool(
+    "get_anomalies",
+    {
+      description: `List webhook anomalies detected by Qovva's rule-based pattern matching engine. Anomalies are flagged when an incoming webhook's payload structure deviates from recent events of the same type \u2014 for example, missing fields, unexpected type changes, or new fields.
+
+Use this to:
+- Check if a specific webhook triggered any structural warnings
+- Review recent anomalies across all webhooks
+- Investigate payload inconsistencies from a provider
+
+Parameters:
+- webhookId: Filter anomalies for a specific webhook UUID.
+- limit: Max results (1-50, default 20).
+- since: ISO 8601 timestamp for time-based filtering.`,
+      inputSchema: {
+        webhookId: z2.string().uuid().optional().describe("Filter anomalies for a specific webhook"),
+        limit: z2.number().int().positive().max(50).optional(),
+        since: z2.string().optional().describe("ISO 8601 timestamp")
+      }
+    },
+    async ({ webhookId, limit, since }) => {
+      const result = await api.listAnomalies({ webhookId, limit, since });
+      return toolResult(result);
+    }
+  );
+  server.registerPrompt(
+    "debug_webhooks",
+    {
+      description: "Interactively debug webhook issues using natural language. Describe what you're looking for and the assistant will search, inspect, and analyze your webhook history.",
+      argsSchema: {
+        question: z2.string().describe("Your natural language question about webhooks, e.g. 'Show me all failed Stripe payments from last week'")
+      }
+    },
+    async ({ question }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `You are a webhook debugging assistant with access to the user's Qovva webhook history via the following tools:
+
+- search_webhooks: Search by text query, HTTP method, endpoint, and time range. Decompose natural language into structured parameters.
+- get_webhook_by_id: Fetch full detail (headers, body, query params) for a specific webhook.
+- get_recent_webhooks: List the most recent captured webhooks.
+- list_endpoints: List all the user's webhook endpoints (use to resolve endpoint names to IDs).
+- replay_webhook: Re-send a captured webhook to a target URL.
+- get_anomalies: List structural anomalies detected in webhook payloads (missing fields, type changes, new fields).
+
+When translating natural language to search parameters:
+- Extract provider names (Stripe, GitHub, Shopify) as query text
+- Extract event types (checkout.session.completed, push, order/created) as query text
+- Map time expressions to ISO 8601: "last week" = 7 days ago, "today" = midnight today, "last hour" = 1 hour ago
+- Extract HTTP methods if mentioned
+- If the user mentions an endpoint by name, use list_endpoints first to get the UUID
+
+For anomaly-related questions:
+- Use get_anomalies to find structural deviations
+- Cross-reference with get_webhook_by_id for full context
+- Compare with search_webhooks to find the "normal" baseline
+
+Always show your reasoning, then call the appropriate tools, then summarize findings clearly.
+
+The user's question: ${question}`
+          }
+        }
+      ]
+    })
+  );
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@qovva/mcp",
+  "version": "0.1.0",
+  "description": "Local stdio MCP server for Qovva webhook debugging.",
+  "private": false,
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "bin": {
+    "qovva-mcp": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "eslint": "^9.39.2",
+    "tsup": "^8.5.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "@workspace/eslint-config": "0.0.0",
+    "@workspace/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsx src/index.ts",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
+  }
+}