@sealmetrics/mcp 0.1.0 → 1.2.0

package/dist/tools/shared.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Convert a period string (e.g. "30d", "this_month") to start_date / end_date.
+ * Needed for endpoints that don't accept the `period` shorthand.
+ */
+export declare function periodToDateRange(period: string): {
+    start_date: string;
+    end_date: string;
+};
+export declare const PERIOD_SCHEMA: {
+    readonly type: "string";
+    readonly description: "Time period for the report. Examples: \"today\", \"yesterday\", \"7d\", \"30d\", \"90d\", \"this_month\", \"last_month\", \"this_year\". Default: \"30d\".";
+    readonly enum: readonly ["today", "yesterday", "7d", "30d", "90d", "12m", "this_week", "wtd", "last_week", "this_month", "mtd", "last_month", "this_quarter", "qtd", "last_quarter", "this_year", "ytd", "last_year"];
+    readonly default: "30d";
+};
+export declare const COMPARE_SCHEMA: {
+    readonly type: "string";
+    readonly description: "Comparison mode. \"previous\" compares with the prior period of the same length. \"yoy\" compares with the same dates last year.";
+    readonly enum: readonly ["previous", "yoy"];
+};
+export declare const LIMIT_SCHEMA: {
+    readonly type: "number";
+    readonly description: "Maximum number of rows to return (default: 20, max: 100).";
+    readonly default: 20;
+};
+export declare const SORT_ORDER_SCHEMA: {
+    readonly type: "string";
+    readonly description: "Sort direction: \"asc\" or \"desc\" (default: \"desc\").";
+    readonly enum: readonly ["asc", "desc"];
+    readonly default: "desc";
+};
+export declare const PAGE_SCHEMA: {
+    readonly type: "number";
+    readonly description: "Page number for paginated results (default: 1).";
+    readonly default: 1;
+};
+/**
+ * Validate a freeform string input: reject control characters and enforce length limit.
+ */
+export declare function sanitizeInput(value: unknown, name: string, maxLen?: number): string | undefined;
+/**
+ * Resolve site_id from tool args or SEALMETRICS_SITE_ID env var.
+ * Throws if neither is available.
+ */
+export declare function resolveSiteId(args: Record<string, unknown>): string;
+//# sourceMappingURL=shared.d.ts.map

package/dist/tools/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/tools/shared.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CA6E1F;AAED,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;CAKjB,CAAC;AAEX,eAAO,MAAM,YAAY;;;;CAIf,CAAC;AAEX,eAAO,MAAM,iBAAiB;;;;;CAKpB,CAAC;AAEX,eAAO,MAAM,WAAW;;;;CAId,CAAC;AAIX;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,SAAmB,GAAG,MAAM,GAAG,SAAS,CAUzG;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAYnE"}

package/dist/tools/shared.js

@@ -0,0 +1,139 @@
+import { VALID_PERIODS } from "../types.js";
+/**
+ * Convert a period string (e.g. "30d", "this_month") to start_date / end_date.
+ * Needed for endpoints that don't accept the `period` shorthand.
+ */
+export function periodToDateRange(period) {
+    const today = new Date();
+    const fmt = (d) => d.toISOString().slice(0, 10);
+    const end = fmt(today);
+    const sub = (days) => {
+        const d = new Date(today);
+        d.setDate(d.getDate() - days);
+        return fmt(d);
+    };
+    switch (period) {
+        case "today":
+            return { start_date: end, end_date: end };
+        case "yesterday": {
+            const y = sub(1);
+            return { start_date: y, end_date: y };
+        }
+        case "7d":
+            return { start_date: sub(6), end_date: end };
+        case "14d":
+            return { start_date: sub(13), end_date: end };
+        case "30d":
+            return { start_date: sub(29), end_date: end };
+        case "60d":
+            return { start_date: sub(59), end_date: end };
+        case "90d":
+            return { start_date: sub(89), end_date: end };
+        case "180d":
+            return { start_date: sub(179), end_date: end };
+        case "365d":
+            return { start_date: sub(364), end_date: end };
+        case "this_week": {
+            const dow = today.getDay() || 7; // Monday=1
+            return { start_date: sub(dow - 1), end_date: end };
+        }
+        case "last_week": {
+            const dow = today.getDay() || 7;
+            const lastMonday = new Date(today);
+            lastMonday.setDate(today.getDate() - dow - 6);
+            const lastSunday = new Date(lastMonday);
+            lastSunday.setDate(lastMonday.getDate() + 6);
+            return { start_date: fmt(lastMonday), end_date: fmt(lastSunday) };
+        }
+        case "this_month": {
+            const start = new Date(today.getFullYear(), today.getMonth(), 1);
+            return { start_date: fmt(start), end_date: end };
+        }
+        case "last_month": {
+            const start = new Date(today.getFullYear(), today.getMonth() - 1, 1);
+            const e = new Date(today.getFullYear(), today.getMonth(), 0);
+            return { start_date: fmt(start), end_date: fmt(e) };
+        }
+        case "this_quarter": {
+            const q = Math.floor(today.getMonth() / 3) * 3;
+            const start = new Date(today.getFullYear(), q, 1);
+            return { start_date: fmt(start), end_date: end };
+        }
+        case "last_quarter": {
+            const q = Math.floor(today.getMonth() / 3) * 3;
+            const start = new Date(today.getFullYear(), q - 3, 1);
+            const e = new Date(today.getFullYear(), q, 0);
+            return { start_date: fmt(start), end_date: fmt(e) };
+        }
+        case "this_year": {
+            const start = new Date(today.getFullYear(), 0, 1);
+            return { start_date: fmt(start), end_date: end };
+        }
+        case "last_year": {
+            const start = new Date(today.getFullYear() - 1, 0, 1);
+            const e = new Date(today.getFullYear() - 1, 11, 31);
+            return { start_date: fmt(start), end_date: fmt(e) };
+        }
+        default:
+            // Fallback to 30 days
+            return { start_date: sub(29), end_date: end };
+    }
+}
+export const PERIOD_SCHEMA = {
+    type: "string",
+    description: `Time period for the report. Examples: "today", "yesterday", "7d", "30d", "90d", "this_month", "last_month", "this_year". Default: "30d".`,
+    enum: [...VALID_PERIODS],
+    default: "30d",
+};
+export const COMPARE_SCHEMA = {
+    type: "string",
+    description: 'Comparison mode. "previous" compares with the prior period of the same length. "yoy" compares with the same dates last year.',
+    enum: ["previous", "yoy"],
+};
+export const LIMIT_SCHEMA = {
+    type: "number",
+    description: "Maximum number of rows to return (default: 20, max: 100).",
+    default: 20,
+};
+export const SORT_ORDER_SCHEMA = {
+    type: "string",
+    description: 'Sort direction: "asc" or "desc" (default: "desc").',
+    enum: ["asc", "desc"],
+    default: "desc",
+};
+export const PAGE_SCHEMA = {
+    type: "number",
+    description: "Page number for paginated results (default: 1).",
+    default: 1,
+};
+const MAX_INPUT_LENGTH = 256;
+/**
+ * Validate a freeform string input: reject control characters and enforce length limit.
+ */
+export function sanitizeInput(value, name, maxLen = MAX_INPUT_LENGTH) {
+    if (value == null || value === "")
+        return undefined;
+    const s = String(value);
+    if (s.length > maxLen) {
+        throw new Error(`${name} exceeds maximum length of ${maxLen} characters.`);
+    }
+    if (/[\r\n\0]/.test(s)) {
+        throw new Error(`${name} contains invalid characters.`);
+    }
+    return s;
+}
+/**
+ * Resolve site_id from tool args or SEALMETRICS_SITE_ID env var.
+ * Throws if neither is available.
+ */
+export function resolveSiteId(args) {
+    const siteId = args.site_id ?? process.env.SEALMETRICS_SITE_ID;
+    if (!siteId) {
+        throw new Error('site_id is required. Either pass it as a parameter or set the SEALMETRICS_SITE_ID environment variable.');
+    }
+    if (siteId.length > 128 || /[\r\n\0/\\]/.test(siteId)) {
+        throw new Error('Invalid site_id format.');
+    }
+    return siteId;
+}
+//# sourceMappingURL=shared.js.map

package/dist/tools/shared.js.map

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

package/dist/tools/sites.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDef } from "./index.js";
+export declare const listSitesTool: ToolDef;
+export declare const getSiteTool: ToolDef;
+//# sourceMappingURL=sites.d.ts.map

package/dist/tools/sites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sites.d.ts","sourceRoot":"","sources":["../../src/tools/sites.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,eAAO,MAAM,aAAa,EAAE,OAiB3B,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,OAiBzB,CAAC"}

package/dist/tools/sites.js

@@ -0,0 +1,36 @@
+import { resolveSiteId } from "./shared.js";
+export const listSitesTool = {
+    name: "list_sites",
+    description: "List all sites (web properties) accessible with your API key. Returns site IDs, names, and domains. Use this to find the site_id needed for other tools.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+    },
+    handler: async (client) => {
+        const data = await client.request("/sites");
+        return data.sites.map((s) => ({
+            site_id: s.id,
+            name: s.name,
+            domains: s.domains,
+            timezone: s.timezone,
+        }));
+    },
+};
+export const getSiteTool = {
+    name: "get_site",
+    description: "Get detailed information about a specific site: name, domains, timezone, configuration, and tracking status. Use list_sites first to find available site IDs.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            site_id: {
+                type: "string",
+                description: "Site ID. Optional if SEALMETRICS_SITE_ID env var is set.",
+            },
+        },
+    },
+    handler: async (client, args) => {
+        const siteId = resolveSiteId(args);
+        return client.request(`/sites/${encodeURIComponent(siteId)}`);
+    },
+};
+//# sourceMappingURL=sites.js.map

package/dist/tools/sites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sites.js","sourceRoot":"","sources":["../../src/tools/sites.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,MAAM,CAAC,MAAM,aAAa,GAAY;IACpC,IAAI,EAAE,YAAY;IAClB,WAAW,EACT,0JAA0J;IAC5J,WAAW,EAAE;QACX,IAAI,EAAE,QAAiB;QACvB,UAAU,EAAE,EAAE;KACf;IACD,OAAO,EAAE,KAAK,EAAE,MAAyB,EAAE,EAAE;QAC3C,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,CAAmB,QAAQ,CAAC,CAAC;QAC9D,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC5B,OAAO,EAAE,CAAC,CAAC,EAAE;YACb,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,QAAQ,EAAE,CAAC,CAAC,QAAQ;SACrB,CAAC,CAAC,CAAC;IACN,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAY;IAClC,IAAI,EAAE,UAAU;IAChB,WAAW,EACT,+JAA+J;IACjK,WAAW,EAAE;QACX,IAAI,EAAE,QAAiB;QACvB,UAAU,EAAE;YACV,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,0DAA0D;aACxE;SACF;KACF;IACD,OAAO,EAAE,KAAK,EAAE,MAAyB,EAAE,IAA6B,EAAE,EAAE;QAC1E,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QACnC,OAAO,MAAM,CAAC,OAAO,CAAU,UAAU,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;CACF,CAAC"}

package/dist/tools/tracking.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDef } from "./index.js";
+export declare const getTrackingCodeTool: ToolDef;
+//# sourceMappingURL=tracking.d.ts.map

package/dist/tools/tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking.d.ts","sourceRoot":"","sources":["../../src/tools/tracking.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAoN1C,eAAO,MAAM,mBAAmB,EAAE,OA+BjC,CAAC"}

package/dist/tools/tracking.js

@@ -0,0 +1,220 @@
+import { resolveSiteId } from "./shared.js";
+const JS_API_REFERENCE = {
+    pageview: {
+        description: "Tracked automatically on load and SPA navigation. Manual call rarely needed.",
+        signatures: [
+            { call: "sealmetrics()", description: "Manual pageview" },
+            {
+                call: "sealmetrics({ group: 'blog' })",
+                description: "Pageview with content grouping",
+            },
+        ],
+    },
+    conversion: {
+        description: "Track conversions with monetary value. Use for purchases, signups, leads.",
+        signatures: [
+            {
+                call: "sealmetrics.conv('purchase', 99.99)",
+                description: "Basic conversion",
+            },
+            {
+                call: "sealmetrics.conv('purchase', 149.99, { currency: 'EUR' })",
+                description: "Conversion with properties",
+            },
+            {
+                call: "sealmetrics.conv('lead', 0, { source: 'contact_form' })",
+                description: "Lead without monetary value",
+            },
+        ],
+    },
+    microconversion: {
+        description: "Track funnel steps and engagement events. Use for add_to_cart, scroll milestones, video plays, newsletter signups.",
+        signatures: [
+            {
+                call: "sealmetrics.micro('add_to_cart')",
+                description: "Basic microconversion",
+            },
+            {
+                call: "sealmetrics.micro('add_to_cart', { product_id: 'SKU-123', price: 49.99 })",
+                description: "Microconversion with properties",
+            },
+        ],
+    },
+};
+const IMPLEMENTATION_GUIDE = {
+    installation: [
+        "Add the <script> tag in the <head> of every page, before </head>.",
+        "Use the 'defer' attribute — the script loads async and never blocks rendering.",
+        "Pageviews are tracked automatically on load and SPA navigation (pushState, replaceState, popstate).",
+        "No cookies, no localStorage, no consent banner needed (GDPR-friendly).",
+    ],
+    content_grouping: {
+        description: "Categorize pages into sections for better analysis. Add via URL param or JS call.",
+        via_url_param: '<script src="https://t.sealmetrics.com/t.js?id=SITE_ID&group=blog" defer></script>',
+        via_js: "sealmetrics({ group: 'blog' })",
+        recommended_groups: [
+            "blog",
+            "product",
+            "category",
+            "checkout",
+            "docs",
+            "app",
+            "landing",
+            "support",
+        ],
+    },
+    naming_conventions: [
+        "Use snake_case for conversion and microconversion types: 'add_to_cart', not 'addToCart'.",
+        "Use descriptive names: 'begin_checkout', not 'step2'.",
+        "Do NOT include order IDs or user IDs in the type name — use properties instead.",
+        "Keep types stable — changing names breaks historical data continuity.",
+    ],
+    spa_support: "Automatic. Works with React Router, Vue Router, Next.js, Nuxt, Angular, and any History API-based routing. No extra config.",
+    debugging: "Add ?debug=1 to any page URL to enable console logging of all tracking events.",
+};
+const EXAMPLES = {
+    ecommerce: {
+        description: "E-commerce site with product pages, cart, and checkout",
+        code: `<!-- In <head> of all pages -->
+<script src="https://t.sealmetrics.com/t.js?id=SITE_ID&group=product" defer></script>
+
+<script>
+// Add to cart button
+document.querySelector('.add-to-cart').addEventListener('click', function() {
+  sealmetrics.micro('add_to_cart', {
+    product_id: this.dataset.productId,
+    price: parseFloat(this.dataset.price)
+  });
+});
+
+// Begin checkout
+document.querySelector('.checkout-btn').addEventListener('click', function() {
+  sealmetrics.micro('begin_checkout', { cart_value: getCartTotal() });
+});
+</script>
+
+<!-- On thank-you page (group=checkout) -->
+<script src="https://t.sealmetrics.com/t.js?id=SITE_ID&group=checkout" defer></script>
+<script>
+sealmetrics.conv('purchase', 189.99, {
+  currency: 'EUR',
+  payment_method: 'credit_card'
+});
+</script>`,
+    },
+    saas: {
+        description: "SaaS / lead generation site",
+        code: `<!-- In <head> -->
+<script src="https://t.sealmetrics.com/t.js?id=SITE_ID&group=marketing" defer></script>
+
+<script>
+// Demo request form
+document.querySelector('#demo-form').addEventListener('submit', function() {
+  sealmetrics.conv('lead', 0, { form_name: 'demo_request' });
+});
+
+// Newsletter signup
+document.querySelector('#newsletter').addEventListener('submit', function() {
+  sealmetrics.micro('newsletter_signup', { position: 'footer' });
+});
+</script>
+
+<!-- On signup success page -->
+<script>
+sealmetrics.conv('signup', 0, { plan: 'trial' });
+</script>
+
+<!-- On upgrade/payment -->
+<script>
+sealmetrics.conv('purchase', 49, { plan: 'pro_monthly', currency: 'USD' });
+</script>`,
+    },
+    blog_media: {
+        description: "Blog or media site with content engagement tracking",
+        code: `<!-- In <head> -->
+<script src="https://t.sealmetrics.com/t.js?id=SITE_ID&group=blog" defer></script>
+
+<script>
+// Video engagement
+document.querySelector('video')?.addEventListener('play', function() {
+  sealmetrics.micro('video_play', { video_id: this.dataset.videoId });
+});
+document.querySelector('video')?.addEventListener('ended', function() {
+  sealmetrics.micro('video_complete', { video_id: this.dataset.videoId });
+});
+
+// Scroll depth milestones
+var tracked = {};
+window.addEventListener('scroll', function() {
+  var pct = Math.round(window.scrollY / (document.body.scrollHeight - window.innerHeight) * 100);
+  [25, 50, 75, 100].forEach(function(m) {
+    if (pct >= m && !tracked[m]) {
+      tracked[m] = true;
+      sealmetrics.micro('scroll_' + m);
+    }
+  });
+});
+</script>`,
+    },
+    react_nextjs: {
+        description: "React / Next.js application",
+        code: `// In layout.tsx or _app.tsx — add the script tag
+import Script from 'next/script';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <head>
+        <Script
+          src="https://t.sealmetrics.com/t.js?id=SITE_ID"
+          strategy="afterInteractive"
+        />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+
+// In any component — track conversions/microconversions
+function CheckoutButton({ total, currency }) {
+  const handlePurchase = () => {
+    window.sealmetrics?.conv('purchase', total, { currency });
+  };
+  return <button onClick={handlePurchase}>Complete Purchase</button>;
+}
+
+// Track microconversions
+function AddToCartButton({ productId, price }) {
+  const handleClick = () => {
+    window.sealmetrics?.micro('add_to_cart', { product_id: productId, price });
+  };
+  return <button onClick={handleClick}>Add to Cart</button>;
+}`,
+    },
+};
+export const getTrackingCodeTool = {
+    name: "get_tracking_code",
+    description: "Get the tracking pixel code for a site and the full JavaScript API reference for implementing pageviews, conversions, microconversions, and content grouping. Returns the site-specific <script> tag plus implementation guide with examples for e-commerce, SaaS, blog, and React/Next.js.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            site_id: {
+                type: "string",
+                description: "Site ID. Optional if SEALMETRICS_SITE_ID env var is set.",
+            },
+        },
+    },
+    handler: async (client, args) => {
+        const siteId = resolveSiteId(args);
+        const pixel = await client.request(`/sites/${encodeURIComponent(siteId)}/pixel`);
+        return {
+            site_id: pixel.site_id ?? pixel.account_id,
+            script_tag: pixel.script_tag,
+            tracker_url: pixel.tracker_url,
+            js_api: JS_API_REFERENCE,
+            implementation_guide: IMPLEMENTATION_GUIDE,
+            examples: EXAMPLES,
+        };
+    },
+};
+//# sourceMappingURL=tracking.js.map

package/dist/tools/tracking.js.map

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

package/dist/tools/traffic.d.ts

@@ -0,0 +1,10 @@
+import type { ToolDef } from "./index.js";
+export declare const getTrafficSourcesTool: ToolDef;
+export declare const getTrafficMediumsTool: ToolDef;
+export declare const getCampaignsTool: ToolDef;
+export declare const getTermsTool: ToolDef;
+export declare const getTopSourcesTool: ToolDef;
+export declare const getTopCampaignsTool: ToolDef;
+export declare const getTopTermsTool: ToolDef;
+export declare const getTopReferrersTool: ToolDef;
+//# sourceMappingURL=traffic.d.ts.map

package/dist/tools/traffic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traffic.d.ts","sourceRoot":"","sources":["../../src/tools/traffic.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAqB1C,eAAO,MAAM,qBAAqB,EAAE,OAsBnC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,OAsBnC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,OAiC9B,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,OA2C1B,CAAC;AAYF,eAAO,MAAM,iBAAiB,EAAE,OA6B/B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,OAkCjC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,OAuC7B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,OAwBjC,CAAC"}