@sealmetrics/mcp 0.1.0 → 1.2.0

package/README.md

@@ -0,0 +1,149 @@
+# @sealmetrics/mcp-server
+
+MCP server for querying [SealMetrics](https://sealmetrics.com) analytics from Claude Code, Claude Desktop, or any MCP-compatible client.
+
+## Setup
+
+### 1. Get an API key
+
+Go to **Settings > API Tokens** in your SealMetrics dashboard and generate a new API key.
+
+### 2. Configure your MCP client
+
+Add to your project's `.mcp.json` or `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "sealmetrics": {
+      "command": "npx",
+      "args": ["-y", "@sealmetrics/mcp-server"],
+      "env": {
+        "SEALMETRICS_API_KEY": "sm_xxxx...",
+        "SEALMETRICS_SITE_ID": "my-site"
+      }
+    }
+  }
+}
+```
+
+### Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SEALMETRICS_API_KEY` | Yes | Your API key (starts with `sm_`) |
+| `SEALMETRICS_SITE_ID` | No | Default site ID (skips needing to pass `site_id` to every tool) |
+| `SEALMETRICS_BASE_URL` | No | API base URL (default: `https://my.sealmetrics.com/api/v1`) |
+
+## Available tools
+
+### list_sites
+
+List all sites accessible with your API key.
+
+### get_overview
+
+Dashboard KPIs: pageviews, entrances, bounce rate, conversions, revenue. Includes time series data and optional period comparison.
+
+**Parameters:** `site_id`, `period`, `compare`
+
+### get_traffic_sources
+
+Traffic broken down by source (utm_source): google, facebook, direct, etc.
+
+**Parameters:** `site_id`, `period`, `compare`, `limit`, `sort_by`, `sort_order`
+
+### get_traffic_mediums
+
+Traffic broken down by medium (utm_medium): organic, cpc, email, referral, etc.
+
+**Parameters:** `site_id`, `period`, `compare`, `limit`, `sort_by`, `sort_order`
+
+### get_campaigns
+
+Campaign performance (utm_campaign) with entrances, conversions, and revenue.
+
+**Parameters:** `site_id`, `period`, `compare`, `limit`, `sort_by`, `sort_order`, `utm_source`, `utm_medium`
+
+### get_pages
+
+Metrics per page URL path: pageviews, entrances, conversions.
+
+**Parameters:** `site_id`, `period`, `compare`, `limit`, `sort_by`, `sort_order`, `path_filter`
+
+### get_landing_pages
+
+Landing page performance: entrances, bounce rate, conversions.
+
+**Parameters:** `site_id`, `period`, `compare`, `limit`, `sort_by`, `sort_order`, `path_filter`
+
+### get_conversions
+
+Conversions by type (purchase, signup) with count, revenue, and average order value.
+
+**Parameters:** `site_id`, `period`, `compare`, `limit`, `sort_by`, `sort_order`, `utm_source`, `utm_medium`, `country`
+
+### get_microconversions
+
+Microconversions (add_to_cart, newsletter_signup, etc.) by type with counts.
+
+**Parameters:** `site_id`, `period`, `compare`, `limit`, `sort_by`, `sort_order`, `conversion_type`
+
+### get_countries
+
+Traffic by country with entrances, conversions, and revenue.
+
+**Parameters:** `site_id`, `period`, `compare`, `limit`, `sort_by`, `sort_order`
+
+### get_devices
+
+Device type (desktop/mobile/tablet), browser, and OS breakdown in a single call.
+
+**Parameters:** `site_id`, `period`, `compare`
+
+### get_funnel
+
+Funnel analysis with step-by-step conversion rates and dropoff.
+
+**Parameters:** `site_id`, `period`, `country`
+
+### get_tracking_code
+
+Get the tracking pixel code for a site and the full JavaScript API reference for implementing pageviews, conversions, microconversions, and content grouping. Use this when you need to install tracking on a website.
+
+**Parameters:** `site_id`
+
+## Common parameters
+
+| Parameter | Values | Default | Description |
+|-----------|--------|---------|-------------|
+| `site_id` | string | `$SEALMETRICS_SITE_ID` | Site to query |
+| `period` | `today`, `yesterday`, `7d`, `30d`, `90d`, `this_month`, `last_month`, `this_year`, etc. | `30d` | Time period |
+| `compare` | `previous`, `yoy` | none | Comparison mode |
+| `limit` | 1-100 | 20 | Max rows returned |
+| `page` | number | 1 | Page number for paginated results |
+| `sort_by` | varies per tool | varies | Sort field |
+| `sort_order` | `asc`, `desc` | `desc` | Sort direction |
+
+## Example usage
+
+Once configured, you can ask Claude:
+
+- "Show me an overview of my site for the last 7 days"
+- "What are the top traffic sources this month?"
+- "Compare this month's conversions with last month"
+- "Which landing pages have the highest bounce rate?"
+- "Show me revenue by country for Q1"
+
+## Development
+
+```bash
+npm install
+npm run build      # Compile TypeScript
+npm test           # Run tests
+npm run dev        # Run with tsx (dev mode)
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,45 @@
+/** Raw JSON response from the API before envelope unwrapping. */
+export interface RawAPIResponse {
+    success: boolean;
+    data: unknown;
+    total?: number;
+    page?: number;
+    page_size?: number;
+    has_next?: boolean;
+    has_prev?: boolean;
+    comparison?: unknown;
+    totals?: unknown;
+    [key: string]: unknown;
+}
+export declare class SealMetricsClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(apiKey: string, baseUrl: string);
+    /**
+     * Send an authenticated GET request. Unwraps the API envelope
+     * and returns just the `data` field.
+     */
+    request<T>(path: string, params?: Record<string, string | undefined>): Promise<T>;
+    /**
+     * Send an authenticated GET request and return the full JSON body
+     * without unwrapping. Use this for endpoints that don't use the
+     * standard APIResponse envelope (e.g. alerts, webhooks).
+     */
+    requestDirect<T>(path: string, params?: Record<string, string | undefined>): Promise<T>;
+    /**
+     * Send an authenticated GET request and return the full response
+     * including pagination fields (total, page, has_next, etc.).
+     * Use this for paginated endpoints.
+     */
+    requestPaginated<T>(path: string, params?: Record<string, string | undefined>): Promise<{
+        data: T[];
+        total: number;
+        page: number;
+        page_size: number;
+        has_next: boolean;
+        comparison?: unknown;
+        totals?: unknown;
+    }>;
+    private requestRaw;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAMA,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IAEd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IAK3C;;;OAGG;IACG,OAAO,CAAC,CAAC,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC1C,OAAO,CAAC,CAAC,CAAC;IAKb;;;;OAIG;IACG,aAAa,CAAC,CAAC,EACnB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC1C,OAAO,CAAC,CAAC,CAAC;IAKb;;;;OAIG;IACG,gBAAgB,CAAC,CAAC,EACtB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC1C,OAAO,CAAC;QACT,IAAI,EAAE,CAAC,EAAE,CAAC;QACV,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,OAAO,CAAC;QAClB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;YAsBY,UAAU;CAkGzB"}

package/dist/client.js

@@ -0,0 +1,136 @@
+import { mapHttpError, SealMetricsAPIError } from "./errors.js";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_RETRIES = 2;
+const RETRY_BASE_MS = 1_000;
+export class SealMetricsClient {
+    apiKey;
+    baseUrl;
+    constructor(apiKey, baseUrl) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+    }
+    /**
+     * Send an authenticated GET request. Unwraps the API envelope
+     * and returns just the `data` field.
+     */
+    async request(path, params) {
+        const raw = await this.requestRaw(path, params);
+        return raw.data;
+    }
+    /**
+     * Send an authenticated GET request and return the full JSON body
+     * without unwrapping. Use this for endpoints that don't use the
+     * standard APIResponse envelope (e.g. alerts, webhooks).
+     */
+    async requestDirect(path, params) {
+        const raw = await this.requestRaw(path, params);
+        return raw;
+    }
+    /**
+     * Send an authenticated GET request and return the full response
+     * including pagination fields (total, page, has_next, etc.).
+     * Use this for paginated endpoints.
+     */
+    async requestPaginated(path, params) {
+        const raw = await this.requestRaw(path, params);
+        const result = {
+            data: raw.data,
+            total: raw.total ?? 0,
+            page: raw.page ?? 1,
+            page_size: raw.page_size ?? 0,
+            has_next: raw.has_next ?? false,
+        };
+        if (raw.comparison != null)
+            result.comparison = raw.comparison;
+        if (raw.totals != null)
+            result.totals = raw.totals;
+        return result;
+    }
+    async requestRaw(path, params) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                if (value !== undefined && value !== "") {
+                    url.searchParams.set(key, value);
+                }
+            }
+        }
+        let lastError;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            if (attempt > 0) {
+                const delay = RETRY_BASE_MS * Math.pow(2, attempt - 1);
+                await sleep(delay);
+            }
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+            try {
+                const response = await fetch(url.toString(), {
+                    method: "GET",
+                    headers: {
+                        "X-API-Key": this.apiKey,
+                        Accept: "application/json",
+                    },
+                    signal: controller.signal,
+                });
+                if (response.ok) {
+                    const text = await response.text();
+                    try {
+                        return JSON.parse(text);
+                    }
+                    catch {
+                        throw new SealMetricsAPIError(response.status, "API returned invalid JSON.", text.slice(0, 500));
+                    }
+                }
+                const body = await response.text();
+                // Retry on 429 (respect Retry-After) or 5xx
+                if (response.status === 429 || response.status >= 500) {
+                    if (response.status === 429) {
+                        const retryAfter = parseRetryAfter(response.headers.get("Retry-After"));
+                        if (retryAfter > 0) {
+                            await sleep(retryAfter);
+                        }
+                    }
+                    lastError = mapHttpError(response.status, body);
+                    continue;
+                }
+                // Non-retryable error
+                const siteId = params?.["site_id"] ?? params?.["account_id"] ?? undefined;
+                throw mapHttpError(response.status, body, siteId);
+            }
+            catch (error) {
+                if (error instanceof SealMetricsAPIError) {
+                    throw error;
+                }
+                if (error instanceof Error &&
+                    error.name === "AbortError") {
+                    lastError = new SealMetricsAPIError(0, "Request timed out after 30 seconds.");
+                    continue;
+                }
+                lastError =
+                    error instanceof Error
+                        ? error
+                        : new Error("Unknown error occurred");
+                // Network errors are retryable
+                continue;
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }
+        throw (lastError ??
+            new SealMetricsAPIError(0, "Request failed after retries."));
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function parseRetryAfter(header) {
+    if (!header)
+        return 0;
+    const seconds = parseInt(header, 10);
+    if (!isNaN(seconds) && seconds > 0 && seconds <= 120) {
+        return seconds * 1000;
+    }
+    return 0;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+/** SealMetrics API error with user-friendly message. */
+export declare class SealMetricsAPIError extends Error {
+    readonly statusCode: number;
+    readonly userMessage: string;
+    readonly detail?: string | undefined;
+    constructor(statusCode: number, userMessage: string, detail?: string | undefined);
+}
+/** Map HTTP status codes to user-friendly error messages. */
+export declare function mapHttpError(status: number, body: string, siteId?: string): SealMetricsAPIError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,UAAU,EAAE,MAAM;aAClB,WAAW,EAAE,MAAM;aACnB,MAAM,CAAC,EAAE,MAAM;gBAFf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM,YAAA;CAKlC;AAED,6DAA6D;AAC7D,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,mBAAmB,CAkDrB"}

package/dist/errors.js

@@ -0,0 +1,55 @@
+/** SealMetrics API error with user-friendly message. */
+export class SealMetricsAPIError extends Error {
+    statusCode;
+    userMessage;
+    detail;
+    constructor(statusCode, userMessage, detail) {
+        super(userMessage);
+        this.statusCode = statusCode;
+        this.userMessage = userMessage;
+        this.detail = detail;
+        this.name = "SealMetricsAPIError";
+    }
+}
+/** Map HTTP status codes to user-friendly error messages. */
+export function mapHttpError(status, body, siteId) {
+    switch (status) {
+        case 401:
+            return new SealMetricsAPIError(401, "Invalid API key. Generate one at Settings > API Tokens in your SealMetrics dashboard.", body);
+        case 403:
+            return new SealMetricsAPIError(403, siteId
+                ? `Access denied to site "${siteId}". Your API key may not have access to this site.`
+                : "Access denied. Your API key does not have the required permissions.", body);
+        case 404:
+            return new SealMetricsAPIError(404, siteId
+                ? `Site "${siteId}" not found. Use list_sites to see available sites.`
+                : "Resource not found.", body);
+        case 422:
+            return new SealMetricsAPIError(422, `Invalid request parameters: ${extractValidationMessage(body)}`, body);
+        case 429:
+            return new SealMetricsAPIError(429, "Rate limit exceeded. Please wait a moment before retrying.", body);
+        default:
+            if (status >= 500) {
+                return new SealMetricsAPIError(status, "SealMetrics API is temporarily unavailable. Please try again later.", body);
+            }
+            return new SealMetricsAPIError(status, `API request failed with status ${status}.`, body);
+    }
+}
+function extractValidationMessage(body) {
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed.detail) {
+            if (Array.isArray(parsed.detail)) {
+                return parsed.detail
+                    .map((d) => `${d.loc?.join(".") ?? "field"}: ${d.msg ?? "invalid"}`)
+                    .join("; ");
+            }
+            return String(parsed.detail);
+        }
+        return body;
+    }
+    catch {
+        return body;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAE1B;IACA;IACA;IAHlB,YACkB,UAAkB,EAClB,WAAmB,EACnB,MAAe;QAE/B,KAAK,CAAC,WAAW,CAAC,CAAC;QAJH,eAAU,GAAV,UAAU,CAAQ;QAClB,gBAAW,GAAX,WAAW,CAAQ;QACnB,WAAM,GAAN,MAAM,CAAS;QAG/B,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,6DAA6D;AAC7D,MAAM,UAAU,YAAY,CAC1B,MAAc,EACd,IAAY,EACZ,MAAe;IAEf,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,GAAG;YACN,OAAO,IAAI,mBAAmB,CAC5B,GAAG,EACH,uFAAuF,EACvF,IAAI,CACL,CAAC;QACJ,KAAK,GAAG;YACN,OAAO,IAAI,mBAAmB,CAC5B,GAAG,EACH,MAAM;gBACJ,CAAC,CAAC,0BAA0B,MAAM,mDAAmD;gBACrF,CAAC,CAAC,qEAAqE,EACzE,IAAI,CACL,CAAC;QACJ,KAAK,GAAG;YACN,OAAO,IAAI,mBAAmB,CAC5B,GAAG,EACH,MAAM;gBACJ,CAAC,CAAC,SAAS,MAAM,qDAAqD;gBACtE,CAAC,CAAC,qBAAqB,EACzB,IAAI,CACL,CAAC;QACJ,KAAK,GAAG;YACN,OAAO,IAAI,mBAAmB,CAC5B,GAAG,EACH,+BAA+B,wBAAwB,CAAC,IAAI,CAAC,EAAE,EAC/D,IAAI,CACL,CAAC;QACJ,KAAK,GAAG;YACN,OAAO,IAAI,mBAAmB,CAC5B,GAAG,EACH,4DAA4D,EAC5D,IAAI,CACL,CAAC;QACJ;YACE,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;gBAClB,OAAO,IAAI,mBAAmB,CAC5B,MAAM,EACN,qEAAqE,EACrE,IAAI,CACL,CAAC;YACJ,CAAC;YACD,OAAO,IAAI,mBAAmB,CAC5B,MAAM,EACN,kCAAkC,MAAM,GAAG,EAC3C,IAAI,CACL,CAAC;IACN,CAAC;AACH,CAAC;AAED,SAAS,wBAAwB,CAAC,IAAY;IAC5C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClB,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;gBACjC,OAAO,MAAM,CAAC,MAAM;qBACjB,GAAG,CACF,CAAC,CAAmC,EAAE,EAAE,CACtC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,OAAO,KAAK,CAAC,CAAC,GAAG,IAAI,SAAS,EAAE,CAC1D;qBACA,IAAI,CAAC,IAAI,CAAC,CAAC;YAChB,CAAC;YACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -1,8 +1,3 @@
 #!/usr/bin/env node
-/**
- * SealMetrics MCP Server
- *
- * A Model Context Protocol server that provides access to SealMetrics analytics data.
- * Allows AI assistants to query traffic, conversions, sales, and generate tracking pixels.
- */
 export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}