growtics-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Growtics
+
+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,181 @@
+# growtics-mcp
+
+> Talk to your Growtics analytics with any AI assistant.
+
+**`growtics-mcp`** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects your Growtics analytics data to AI assistants like Claude Desktop, Cursor, and Windsurf.
+
+Ask natural-language questions powered by your real data:
+
+- *"Why did traffic drop this week?"*
+- *"What should I improve next for SEO?"*
+- *"Which pages are losing conversions?"*
+- *"Analyze my latest release and its impact."*
+
+---
+
+## Quick Start
+
+**No installation needed.** Add this to your AI client's MCP config and you're done:
+
+```json
+{
+  "mcpServers": {
+    "growtics": {
+      "command": "npx",
+      "args": ["-y", "growtics-mcp"],
+      "env": {
+        "GROWTICS_API_KEY": "gt_live_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+**Get your API key:** Growtics Dashboard → Settings → API Keys  
+Required scopes: `analytics:read`, `sites:read`, `realtime:read`
+
+---
+
+## Available Tools
+
+| Tool | Answers |
+|------|---------|
+| `list-sites` | What sites are in my account? |
+| `get-traffic-overview` | How is my traffic doing? |
+| `get-top-pages` | Which pages get the most traffic? |
+| `get-referrers` | Where does my traffic come from? |
+| `get-realtime` | Who is on my site right now? |
+| `get-goals` | What are my conversion rates? |
+| `get-funnels` | Where do users drop off? |
+| `get-releases` | Did my last release affect traffic? |
+| `get-seo-suggestions` | What should I fix for SEO? |
+| `analyze-traffic-drop` | Why did traffic drop? |
+
+---
+
+## Client Setup
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "growtics": {
+      "command": "npx",
+      "args": ["-y", "growtics-mcp"],
+      "env": {
+        "GROWTICS_API_KEY": "gt_live_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Look for the 🔨 tools icon to confirm it connected.
+
+### Cursor
+
+Edit `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "growtics": {
+      "command": "npx",
+      "args": ["-y", "growtics-mcp"],
+      "env": {
+        "GROWTICS_API_KEY": "gt_live_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Edit `~/.windsurf/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "growtics": {
+      "command": "npx",
+      "args": ["-y", "growtics-mcp"],
+      "env": {
+        "GROWTICS_API_KEY": "gt_live_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+### Any `.mcp.json`
+
+Drop this at the root of any project:
+
+```json
+{
+  "mcpServers": {
+    "growtics": {
+      "command": "npx",
+      "args": ["-y", "growtics-mcp"],
+      "env": {
+        "GROWTICS_API_KEY": "gt_live_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `GROWTICS_API_KEY` | ✅ Yes | — | Your Growtics API key (`gt_live_...`) |
+| `GROWTICS_API_URL` | No | `https://growtics.io` | Override for self-hosted Growtics |
+
+---
+
+## Example Conversation
+
+```
+You: Why did traffic drop this week on my site?
+
+Claude: [calls analyze-traffic-drop]
+
+Traffic is down 23% vs the previous 7-day period.
+
+Key findings:
+1. Organic search dropped 41% — Google traffic fell significantly  
+2. Twitter/X referrals are down 60%
+3. The /pricing page saw a 35% decline in the same period
+
+Recommended actions:
+1. Check Google Search Console for crawl issues or ranking changes
+2. Review recent posts on X — a high-traffic post from last week
+   is no longer sending referrals
+```
+
+---
+
+## Security
+
+- **Read-only** — the MCP server can only query data, never modify it
+- **Local process** — runs on your machine; data goes directly to `growtics.io`, not through any third party
+- **Scoped keys** — create a dedicated read-only API key for MCP usage
+
+---
+
+## Links
+
+- [Growtics](https://growtics.io) — Website growth analytics
+- [Full Setup Guide](https://growtics.io/docs/mcp)
+- [MCP Protocol](https://modelcontextprotocol.io)
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * Growtics Analytics MCP Server
+ *
+ * Exposes your Growtics analytics data as MCP tools consumable by
+ * Claude Desktop, Cursor, Windsurf, and any other MCP-compatible AI assistant.
+ *
+ * Usage:
+ *   GROWTICS_API_KEY=gt_live_... GROWTICS_API_URL=https://growtics.io node index.js
+ *
+ * Or configure in your AI client's MCP settings (see MCP_GUIDE.md).
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+// ── Tool modules ──────────────────────────────────────────────────────────────
+import * as listSites           from './tools/list-sites.js';
+import * as getTrafficOverview  from './tools/get-traffic-overview.js';
+import * as getTopPages         from './tools/get-top-pages.js';
+import * as getReferrers        from './tools/get-referrers.js';
+import * as getRealtime         from './tools/get-realtime.js';
+import * as getGoals            from './tools/get-goals.js';
+import * as getFunnels          from './tools/get-funnels.js';
+import * as getReleases         from './tools/get-releases.js';
+import * as getSeoSuggestions   from './tools/get-seo-suggestions.js';
+import * as analyzeTrafficDrop  from './tools/analyze-traffic-drop.js';
+
+// ── Configuration ─────────────────────────────────────────────────────────────
+const API_KEY  = process.env.GROWTICS_API_KEY;
+const API_URL  = (process.env.GROWTICS_API_URL || 'https://growtics.io').replace(/\/$/, '');
+
+if (!API_KEY) {
+  process.stderr.write(
+    '[growtics-mcp] ERROR: GROWTICS_API_KEY environment variable is required.\n' +
+    'Get your API key from: Settings → API Keys in the Growtics dashboard.\n'
+  );
+  process.exit(1);
+}
+
+// ── API Client ────────────────────────────────────────────────────────────────
+const apiClient = {
+  async get(path) {
+    const url = `${API_URL}${path}`;
+    const response = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${API_KEY}`,
+        'Content-Type': 'application/json',
+        'User-Agent':   'growtics-mcp/1.0.0',
+      },
+    });
+
+    if (!response.ok) {
+      let errMsg = `HTTP ${response.status}`;
+      try {
+        const body = await response.json();
+        errMsg = body?.error?.message || body?.error || errMsg;
+      } catch {}
+      throw new Error(`Growtics API error: ${errMsg}`);
+    }
+
+    return response.json();
+  },
+};
+
+// ── Tool Registry ─────────────────────────────────────────────────────────────
+const TOOLS = [
+  listSites,
+  getTrafficOverview,
+  getTopPages,
+  getReferrers,
+  getRealtime,
+  getGoals,
+  getFunnels,
+  getReleases,
+  getSeoSuggestions,
+  analyzeTrafficDrop,
+];
+
+const TOOL_MAP = Object.fromEntries(TOOLS.map(t => [t.definition.name, t]));
+
+// ── MCP Server ────────────────────────────────────────────────────────────────
+const server = new Server(
+  {
+    name:    'growtics-mcp',
+    version: '1.0.0',
+  },
+  {
+    capabilities: { tools: {} },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map(t => ({
+    name:        t.definition.name,
+    description: t.definition.description,
+    inputSchema: t.definition.inputSchema,
+  })),
+}));
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  const tool = TOOL_MAP[name];
+  if (!tool) {
+    return {
+      content: [{ type: 'text', text: `Unknown tool: "${name}"` }],
+      isError: true,
+    };
+  }
+
+  try {
+    const result = await tool.run({ args: args || {}, apiClient });
+    return {
+      content: [{ type: 'text', text: result.text }],
+    };
+  } catch (err) {
+    const message = err?.message || 'An unexpected error occurred.';
+    process.stderr.write(`[growtics-mcp] Tool "${name}" error: ${message}\n`);
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `❌ Error running \`${name}\`:\n\n${message}\n\nMake sure your API key has the correct scopes and the siteId is valid.`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// ── Start ─────────────────────────────────────────────────────────────────────
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write(`[growtics-mcp] Server started. Connected to ${API_URL}\n`);
+}
+
+main().catch((err) => {
+  process.stderr.write(`[growtics-mcp] Fatal error: ${err.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "growtics-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Growtics Analytics — ask your AI assistant questions about your website traffic, SEO, conversions, and releases.",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "growtics-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "tools/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "prepublishOnly": "node --check index.js && echo '✅ Syntax OK'"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "growtics",
+    "analytics",
+    "ai",
+    "claude",
+    "cursor",
+    "windsurf",
+    "seo",
+    "web-analytics"
+  ],
+  "license": "MIT",
+  "homepage": "https://growtics.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/growtics/growtics-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/growtics/growtics-mcp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/tools/analyze-traffic-drop.js

@@ -0,0 +1,228 @@
+/**
+ * analyze-traffic-drop tool
+ * Smart composite analysis: compares current vs previous period to surface
+ * traffic drop causes across multiple dimensions simultaneously.
+ */
+export const definition = {
+  name: 'analyze-traffic-drop',
+  description:
+    'Perform a comprehensive traffic drop analysis by comparing the current period against the ' +
+    'previous equivalent period. Surfaces the root cause across traffic volume, referral sources, ' +
+    'top pages, devices, and countries — all in one intelligent report. ' +
+    'Use this to answer "Why did traffic drop this week?" or "What changed vs last month?"',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      siteId: {
+        type: 'string',
+        description: 'The Growtics site UUID (get it from list-sites)',
+      },
+      period: {
+        type: 'string',
+        enum: ['7d', '28d', 'mtd', 'lastmonth', '91d', '12m'],
+        description:
+          'Current period to analyze. The tool will automatically compare it against ' +
+          'the equivalent previous period. Default: 7d',
+      },
+    },
+    required: ['siteId'],
+  },
+};
+
+// Map a period to the equivalent "previous" period for comparison
+const COMPARE_PERIODS = {
+  '7d':        ['7d',        '28d'],   // current 7d vs prev 7d (use 28d, take second half)
+  '28d':       ['28d',       '91d'],
+  'mtd':       ['mtd',       'lastmonth'],
+  'lastmonth': ['lastmonth', '28d'],
+  '91d':       ['91d',       '12m'],
+  '12m':       ['12m',       'all'],
+};
+
+export async function run({ args, apiClient }) {
+  const { siteId, period = '7d' } = args;
+
+  // Fetch current and previous period overviews in parallel
+  const [current, previous, referrersCurrent, referrersPrev, goalsCurrent] = await Promise.all([
+    apiClient.get(`/api/v1/analytics?siteId=${siteId}&period=${period}&type=overview`),
+    apiClient.get(`/api/v1/analytics?siteId=${siteId}&period=${COMPARE_PERIODS[period]?.[1] || '28d'}&type=overview`),
+    apiClient.get(`/api/v1/analytics?siteId=${siteId}&period=${period}&type=referrals`),
+    apiClient.get(`/api/v1/analytics?siteId=${siteId}&period=${COMPARE_PERIODS[period]?.[1] || '28d'}&type=referrals`),
+    apiClient.get(`/api/v1/analytics?siteId=${siteId}&period=${period}&type=goals`).catch(() => null),
+  ]);
+
+  const meta     = current.meta;
+  const cur      = current.data.stats;
+  const prev     = previous.data.stats;
+
+  // Core metric deltas
+  const viewsDelta    = prev.pageviews    > 0 ? Math.round(((cur.pageviews    - prev.pageviews)    / prev.pageviews)    * 100) : null;
+  const visitorsDelta = prev.uniqueVisitors > 0 ? Math.round(((cur.uniqueVisitors - prev.uniqueVisitors) / prev.uniqueVisitors) * 100) : null;
+  const bounceDelta   = (cur.bounceRate - prev.bounceRate).toFixed(1);
+
+  function arrow(delta, higherIsBad = false) {
+    if (delta === null) return '—';
+    const isGood = higherIsBad ? delta < 0 : delta > 0;
+    const icon   = isGood ? '🟢' : delta === 0 ? '⚪' : '🔴';
+    const ar     = delta > 0 ? '▲' : delta < 0 ? '▼' : '→';
+    return `${icon} ${ar} ${Math.abs(delta)}%`;
+  }
+
+  const lines = [
+    `## Traffic Analysis — ${meta.siteName} (${meta.domain})`,
+    `**Comparing:** \`${period}\` (current) vs \`${COMPARE_PERIODS[period]?.[1] || '28d'}\` (previous)\n`,
+
+    `### 📊 Core Metrics Comparison`,
+    `| Metric | Current | Previous | Change |`,
+    `|--------|---------|----------|--------|`,
+    `| Page Views | **${cur.pageviews.toLocaleString()}** | ${prev.pageviews.toLocaleString()} | ${arrow(viewsDelta)} |`,
+    `| Unique Visitors | **${cur.uniqueVisitors.toLocaleString()}** | ${prev.uniqueVisitors.toLocaleString()} | ${arrow(visitorsDelta)} |`,
+    `| Bounce Rate | **${cur.bounceRate}%** | ${prev.bounceRate}% | ${parseFloat(bounceDelta) > 2 ? '🔴' : parseFloat(bounceDelta) < -2 ? '🟢' : '⚪'} ${bounceDelta > 0 ? '+' : ''}${bounceDelta}pp |`,
+    `| Active Now | **${cur.activeVisitors}** | — | — |`,
+  ];
+
+  // Overall verdict
+  const verdict = viewsDelta === null ? null :
+    viewsDelta <= -20 ? '🚨 **Significant drop** detected — traffic is materially lower than the previous period.' :
+    viewsDelta <= -10 ? '⚠️ **Moderate drop** detected — worth investigating the sources below.' :
+    viewsDelta <= -5  ? '📉 **Slight decline** — minor movement, possibly normal variance.' :
+    viewsDelta >= 10  ? '🚀 **Strong growth** — traffic is up significantly!' :
+    '✅ Traffic is relatively stable compared to the previous period.';
+
+  if (verdict) lines.push(`\n> ${verdict}`);
+
+  // ── Referrer source analysis ──────────────────────────────────────────────
+  lines.push('\n### 🔗 Traffic Source Changes');
+
+  const curRefs  = Object.fromEntries((referrersCurrent.data?.referrers || []).map(r => [r.domain, r.pageviews]));
+  const prevRefs = Object.fromEntries((referrersPrev.data?.referrers    || []).map(r => [r.domain, r.pageviews]));
+  const allDomains = new Set([...Object.keys(curRefs), ...Object.keys(prevRefs)]);
+
+  const refChanges = [...allDomains].map(domain => {
+    const c = curRefs[domain]  || 0;
+    const p = prevRefs[domain] || 0;
+    const delta = p > 0 ? Math.round(((c - p) / p) * 100) : (c > 0 ? 100 : 0);
+    return { domain, current: c, previous: p, delta };
+  }).sort((a, b) => (a.delta - b.delta)); // most dropped first
+
+  const bigDroppers = refChanges.filter(r => r.delta < -20 && r.previous > 10).slice(0, 5);
+  const bigGainers  = refChanges.filter(r => r.delta > 20  && r.previous > 0).slice(0, 3);
+  const newSources  = refChanges.filter(r => r.previous === 0 && r.current > 5).slice(0, 3);
+
+  if (bigDroppers.length > 0) {
+    lines.push('\n**📉 Sources that dropped significantly:**');
+    lines.push('| Source | Current | Previous | Change |');
+    lines.push('|--------|---------|----------|--------|');
+    for (const r of bigDroppers) {
+      lines.push(`| **${r.domain || '(direct)'}** | ${r.current.toLocaleString()} | ${r.previous.toLocaleString()} | 🔴 ▼ ${Math.abs(r.delta)}% |`);
+    }
+  }
+
+  if (bigGainers.length > 0) {
+    lines.push('\n**📈 Sources that grew:**');
+    for (const r of bigGainers) {
+      lines.push(`- **${r.domain}**: ${r.previous.toLocaleString()} → ${r.current.toLocaleString()} (🟢 ▲ ${r.delta}%)`);
+    }
+  }
+
+  if (newSources.length > 0) {
+    lines.push('\n**🆕 New traffic sources this period:**');
+    for (const r of newSources) {
+      lines.push(`- **${r.domain}**: ${r.current.toLocaleString()} visits (new)`);
+    }
+  }
+
+  // ── Page-level changes ───────────────────────────────────────────────────
+  const curPages  = current.data.topPages  || [];
+  const prevPages = previous.data.topPages || [];
+
+  if (curPages.length > 0) {
+    lines.push('\n### 📄 Top Pages — Current Period');
+    lines.push('| Page | Views |');
+    lines.push('|------|-------|');
+    curPages.slice(0, 5).forEach(p => {
+      const prev = prevPages.find(pp => pp.path === p.path);
+      const delta = prev ? Math.round(((p.pageviews - prev.pageviews) / prev.pageviews) * 100) : null;
+      const changeStr = delta !== null ? (delta > 0 ? ` 🟢▲${delta}%` : delta < 0 ? ` 🔴▼${Math.abs(delta)}%` : '') : ' 🆕';
+      lines.push(`| \`${p.path}\` | ${p.pageviews.toLocaleString()}${changeStr} |`);
+    });
+  }
+
+  // ── Device breakdown ─────────────────────────────────────────────────────
+  const curDevices  = current.data.topDevices  || [];
+  const prevDevices = previous.data.topDevices || [];
+  if (curDevices.length > 0) {
+    lines.push('\n### 📱 Device Breakdown');
+    lines.push('| Device | Current | Previous | Change |');
+    lines.push('|--------|---------|----------|--------|');
+    for (const d of curDevices) {
+      const p  = prevDevices.find(x => x.device === d.device);
+      const pd = p?.pageviews || 0;
+      const delta = pd > 0 ? Math.round(((d.pageviews - pd) / pd) * 100) : null;
+      const changeStr = delta !== null ? (delta > 0 ? `🟢 ▲ ${delta}%` : delta < 0 ? `🔴 ▼ ${Math.abs(delta)}%` : '⚪ flat') : '🆕 new';
+      lines.push(`| ${d.device} | ${d.pageviews.toLocaleString()} | ${pd.toLocaleString()} | ${changeStr} |`);
+    }
+  }
+
+  // ── Goal conversions ─────────────────────────────────────────────────────
+  if (goalsCurrent?.data?.goals?.length > 0) {
+    lines.push('\n### 🎯 Conversion Goals');
+    lines.push('| Goal | Completions | Conv. Rate |');
+    lines.push('|------|-------------|------------|');
+    for (const g of goalsCurrent.data.goals) {
+      const rate = parseFloat(g.conversionRate);
+      const health = rate >= 5 ? '🟢' : rate >= 1 ? '🟡' : '🔴';
+      lines.push(`| **${g.name}** | ${g.completions.toLocaleString()} | ${health} ${rate}% |`);
+    }
+  }
+
+  // ── AI Summary & Recommendations ─────────────────────────────────────────
+  lines.push('\n---\n### 🤖 Analysis Summary');
+
+  const findings = [];
+
+  if (viewsDelta !== null && viewsDelta <= -10) {
+    findings.push(`Traffic dropped **${Math.abs(viewsDelta)}%** compared to the previous period.`);
+  }
+  if (bigDroppers.length > 0) {
+    findings.push(`The biggest source drops came from: ${bigDroppers.map(r => `**${r.domain || '(direct)'}** (−${Math.abs(r.delta)}%)`).join(', ')}.`);
+  }
+  if (parseFloat(bounceDelta) > 5) {
+    findings.push(`Bounce rate increased by **${bounceDelta} percentage points** — visitors may not be finding what they expect on landing.`);
+  }
+  if (curDevices.find(d => d.device === 'mobile')?.pageviews < (prevDevices.find(d => d.device === 'mobile')?.pageviews || 0)) {
+    findings.push('Mobile traffic in particular has declined — check mobile page speed and UX.');
+  }
+  if (newSources.length > 0) {
+    findings.push(`New traffic sources appeared: ${newSources.map(r => `**${r.domain}**`).join(', ')}.`);
+  }
+
+  if (findings.length === 0 && (viewsDelta === null || Math.abs(viewsDelta) < 5)) {
+    findings.push('Traffic metrics are stable. No significant drops or anomalies detected in this period.');
+  }
+
+  findings.forEach((f, i) => lines.push(`${i + 1}. ${f}`));
+
+  // Recommendations
+  const recs = [];
+  if (bigDroppers.some(r => /google\.|bing\.com|yahoo\.com|duckduckgo/.test(r.domain || ''))) {
+    recs.push('Organic search dropped — check Google Search Console for crawl issues or ranking changes. Review open SEO suggestions in Growtics.');
+  }
+  if (bigDroppers.some(r => /t\.co|twitter\.com|x\.com|facebook\.com|instagram\.com|linkedin\.com/.test(r.domain || ''))) {
+    recs.push('Social traffic dropped — check if recent social posts underperformed or if a high-traffic post from the previous period is no longer driving clicks.');
+  }
+  if (parseFloat(bounceDelta) > 5) {
+    recs.push('High bounce rate increase — review the top landing pages for content relevance and page speed.');
+  }
+  if (recs.length === 0 && viewsDelta !== null && viewsDelta < -10) {
+    recs.push('Run `get-seo-suggestions` for actionable improvement ideas.');
+    recs.push('Check `get-releases` to see if any recent change correlated with the drop.');
+  }
+
+  if (recs.length > 0) {
+    lines.push('\n**🔧 Recommended Actions:**');
+    recs.forEach((r, i) => lines.push(`${i + 1}. ${r}`));
+  }
+
+  return { text: lines.join('\n') };
+}

package/tools/get-funnels.js

@@ -0,0 +1,86 @@
+/**
+ * get-funnels tool
+ * Runs a funnel analysis for a set of page paths.
+ */
+export const definition = {
+  name: 'get-funnels',
+  description:
+    'Analyze a conversion funnel: given a sequence of page paths, calculate how many visitors ' +
+    'progress through each step. Use this to identify where visitors drop off. ' +
+    'Example: "/,/pricing,/signup,/dashboard" shows the homepage-to-dashboard signup funnel.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      siteId: {
+        type: 'string',
+        description: 'The Growtics site UUID (get it from list-sites)',
+      },
+      steps: {
+        type: 'string',
+        description:
+          'Comma-separated list of page paths defining the funnel steps. ' +
+          'Minimum 2, maximum 10. Example: "/,/pricing,/signup"',
+      },
+      period: {
+        type: 'string',
+        enum: ['today', 'yesterday', '24h', '7d', '28d', '91d', 'mtd', 'lastmonth', 'ytd', '12m', 'all'],
+        description: 'Time period for the report. Default: 7d',
+      },
+    },
+    required: ['siteId', 'steps'],
+  },
+};
+
+export async function run({ args, apiClient }) {
+  const { siteId, steps, period = '7d' } = args;
+  const data = await apiClient.get(
+    `/api/v1/analytics?siteId=${siteId}&period=${period}&type=funnels&steps=${encodeURIComponent(steps)}`
+  );
+
+  const { steps: funnelSteps } = data.data;
+  const meta = data.meta;
+
+  if (!funnelSteps?.length) {
+    return { text: `No funnel data found for the given steps on **${meta.siteName}**.` };
+  }
+
+  const topCount = funnelSteps[0]?.visitors || 0;
+
+  const lines = [
+    `## Funnel Analysis — ${meta.siteName}`,
+    `**Period:** ${period}  |  **Steps:** ${steps}\n`,
+    `| Step | Page | Visitors | Drop-off | Conv. Rate |`,
+    `|------|------|----------|----------|------------|`,
+  ];
+
+  for (let i = 0; i < funnelSteps.length; i++) {
+    const step = funnelSteps[i];
+    const prev = i > 0 ? funnelSteps[i - 1].visitors : step.visitors;
+    const dropoff = prev > 0 ? Math.round(((prev - step.visitors) / prev) * 100) : 0;
+    const overallRate = topCount > 0 ? ((step.visitors / topCount) * 100).toFixed(1) : '0.0';
+    const dropoffStr = i === 0 ? '—' : `${dropoff}% lost`;
+    const emoji = i === 0 ? '' : dropoff > 50 ? ' 🔴' : dropoff > 25 ? ' 🟡' : ' 🟢';
+
+    lines.push(
+      `| ${step.step} | \`${step.path}\` | ${step.visitors.toLocaleString()} | ${dropoffStr}${emoji} | ${overallRate}% |`
+    );
+  }
+
+  // Find the biggest drop
+  let maxDrop = 0, maxDropStep = null;
+  for (let i = 1; i < funnelSteps.length; i++) {
+    const prev = funnelSteps[i - 1].visitors;
+    const curr = funnelSteps[i].visitors;
+    const drop = prev > 0 ? ((prev - curr) / prev) * 100 : 0;
+    if (drop > maxDrop) { maxDrop = drop; maxDropStep = funnelSteps[i]; }
+  }
+
+  if (maxDropStep && maxDrop > 20) {
+    lines.push(
+      `\n> 🚨 **Biggest drop-off point:** Step ${maxDropStep.step} (\`${maxDropStep.path}\`) — **${Math.round(maxDrop)}% of visitors** leave at this step. ` +
+      `This is the highest-impact place to optimize.`
+    );
+  }
+
+  return { text: lines.join('\n') };
+}

package/tools/get-goals.js

@@ -0,0 +1,69 @@
+/**
+ * get-goals tool
+ * Returns conversion goals and their completion rates.
+ */
+export const definition = {
+  name: 'get-goals',
+  description:
+    'Get all conversion goals configured for a site and their completion rates for a period. ' +
+    'Use this to answer "Which pages are losing conversions?", ' +
+    '"What is my signup conversion rate?", or "Are my goals performing well?"',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      siteId: {
+        type: 'string',
+        description: 'The Growtics site UUID (get it from list-sites)',
+      },
+      period: {
+        type: 'string',
+        enum: ['today', 'yesterday', '24h', '7d', '28d', '91d', 'mtd', 'lastmonth', 'ytd', '12m', 'all'],
+        description: 'Time period for the report. Default: 7d',
+      },
+    },
+    required: ['siteId'],
+  },
+};
+
+export async function run({ args, apiClient }) {
+  const { siteId, period = '7d' } = args;
+  const data = await apiClient.get(`/api/v1/analytics?siteId=${siteId}&period=${period}&type=goals`);
+
+  const { baseline, goals } = data.data;
+  const meta = data.meta;
+
+  if (!goals?.length) {
+    return {
+      text:
+        `## Conversion Goals — ${meta.siteName}\n\n` +
+        `No goals are configured for this site yet.\n` +
+        `Add goals in the Growtics dashboard under **Analytics → Goals**.`,
+    };
+  }
+
+  // Sort by conversion rate desc
+  const sorted = [...goals].sort((a, b) => b.conversionRate - a.conversionRate);
+
+  const lines = [
+    `## Conversion Goals — ${meta.siteName}`,
+    `**Period:** ${period}  |  **Total unique visitors (baseline):** ${baseline.toLocaleString()}\n`,
+    `| Goal | Target | Completions | Conv. Rate | Health |`,
+    `|------|--------|-------------|------------|--------|`,
+    ...sorted.map(g => {
+      const rate = parseFloat(g.conversionRate);
+      const health = rate >= 5 ? '🟢 Good' : rate >= 1 ? '🟡 Average' : '🔴 Low';
+      return `| **${g.name}** | \`${g.targetPath}\` | ${g.completions.toLocaleString()} | **${rate}%** | ${health} |`;
+    }),
+  ];
+
+  // Highlight worst performer
+  const worst = sorted[sorted.length - 1];
+  if (worst && parseFloat(worst.conversionRate) < 1) {
+    lines.push(
+      `\n> ⚠️ **"${worst.name}"** has a very low conversion rate of **${worst.conversionRate}%**. ` +
+      `Consider reviewing the page \`${worst.targetPath}\` for UX or copy improvements.`
+    );
+  }
+
+  return { text: lines.join('\n') };
+}

package/tools/get-realtime.js

@@ -0,0 +1,58 @@
+/**
+ * get-realtime tool
+ * Returns currently active visitors and recent pageviews (last 5 minutes).
+ */
+export const definition = {
+  name: 'get-realtime',
+  description:
+    'Get real-time data: how many visitors are on your site right now, ' +
+    'which pages they are viewing, and their geographic breakdown. ' +
+    'Use this to monitor live events, campaigns, or to check if a page is being visited.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      siteId: {
+        type: 'string',
+        description: 'The Growtics site UUID (get it from list-sites)',
+      },
+    },
+    required: ['siteId'],
+  },
+};
+
+export async function run({ args, apiClient }) {
+  const { siteId } = args;
+  const data = await apiClient.get(`/api/v1/analytics?siteId=${siteId}&type=realtime`);
+
+  const { activeVisitors, recentPageviews, countryBreakdown } = data.data;
+  const meta = data.meta;
+
+  const lines = [
+    `## Real-Time — ${meta.siteName}`,
+    `*Snapshot at ${new Date().toLocaleTimeString()}*\n`,
+    `### 🟢 ${activeVisitors} Active Visitor${activeVisitors !== 1 ? 's' : ''} (last 5 min)\n`,
+  ];
+
+  if (recentPageviews.length > 0) {
+    lines.push('### Recent Pageviews');
+    lines.push('| Time | Page | Country | Device |');
+    lines.push('|------|------|---------|--------|');
+    for (const pv of recentPageviews.slice(0, 10)) {
+      const time = new Date(pv.timestamp).toLocaleTimeString();
+      lines.push(`| ${time} | \`${pv.path}\` | ${pv.country || '—'} | ${pv.device || '—'} |`);
+    }
+  } else {
+    lines.push('_No pageviews in the last 5 minutes._');
+  }
+
+  if (countryBreakdown.length > 0) {
+    lines.push('\n### Visitors by Country (last 30 min)');
+    lines.push(
+      countryBreakdown.slice(0, 8)
+        .map(c => `- **${c.country || 'Unknown'}**: ${c.count} visitor${c.count !== 1 ? 's' : ''}`)
+        .join('\n')
+    );
+  }
+
+  return { text: lines.join('\n') };
+}

package/tools/get-referrers.js

@@ -0,0 +1,89 @@
+/**
+ * get-referrers tool
+ * Returns traffic referrer sources for a given period.
+ */
+export const definition = {
+  name: 'get-referrers',
+  description:
+    'Get the top traffic sources (referrers) for your website — which domains, ' +
+    'search engines, or social networks are sending you visitors. ' +
+    'Use this to answer "Where is my traffic coming from?" or ' +
+    '"Which channel dropped this week?"',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      siteId: {
+        type: 'string',
+        description: 'The Growtics site UUID (get it from list-sites)',
+      },
+      period: {
+        type: 'string',
+        enum: ['today', 'yesterday', '24h', '7d', '28d', '91d', 'mtd', 'lastmonth', 'ytd', '12m', 'all'],
+        description: 'Time period for the report. Default: 7d',
+      },
+    },
+    required: ['siteId'],
+  },
+};
+
+// Simple channel classification from a referrer domain
+function classifyChannel(domain) {
+  if (!domain) return 'Direct / Unknown';
+  const d = domain.toLowerCase();
+  if (/google\.|bing\.com|yahoo\.com|duckduckgo|yandex\.|baidu\.com|ecosia\./.test(d))
+    return '🔍 Organic Search';
+  if (/t\.co|twitter\.com|x\.com|facebook\.com|instagram\.com|linkedin\.com|youtube\.com|pinterest\.com|reddit\.com|tiktok\.com/.test(d))
+    return '📱 Organic Social';
+  if (/chatgpt\.com|openai\.com|claude\.ai|anthropic\.com|gemini\.google|perplexity\.ai/.test(d))
+    return '🤖 AI / LLM';
+  return '🔗 Referral';
+}
+
+export async function run({ args, apiClient }) {
+  const { siteId, period = '7d' } = args;
+  const data = await apiClient.get(`/api/v1/analytics?siteId=${siteId}&period=${period}&type=referrals`);
+
+  const { referrers } = data.data;
+  const meta = data.meta;
+
+  if (!referrers?.length) {
+    return { text: `No referrer data found for **${meta.siteName}** in the period \`${period}\`.` };
+  }
+
+  const total = referrers.reduce((s, r) => s + r.pageviews, 0);
+
+  // Group by channel
+  const channels = {};
+  for (const r of referrers) {
+    const ch = classifyChannel(r.domain);
+    if (!channels[ch]) channels[ch] = { pageviews: 0, domains: [] };
+    channels[ch].pageviews += r.pageviews;
+    channels[ch].domains.push(r);
+  }
+
+  const lines = [
+    `## Traffic Sources — ${meta.siteName}`,
+    `**Period:** ${period}  |  **Total referred visits:** ${total.toLocaleString()}\n`,
+  ];
+
+  // Channel summary
+  const sortedChannels = Object.entries(channels).sort((a, b) => b[1].pageviews - a[1].pageviews);
+  lines.push('### By Channel');
+  lines.push('| Channel | Views | Share |');
+  lines.push('|---------|-------|-------|');
+  for (const [ch, info] of sortedChannels) {
+    const share = total > 0 ? ((info.pageviews / total) * 100).toFixed(1) : '0.0';
+    lines.push(`| ${ch} | ${info.pageviews.toLocaleString()} | ${share}% |`);
+  }
+
+  // Top individual referrers
+  lines.push('\n### Top Individual Sources');
+  lines.push('| # | Domain | Views | Channel |');
+  lines.push('|---|--------|-------|---------|');
+  referrers.slice(0, 15).forEach((r, i) => {
+    const share = total > 0 ? ((r.pageviews / total) * 100).toFixed(1) : '0.0';
+    lines.push(`| ${i + 1} | **${r.domain || '(direct)'}** | ${r.pageviews.toLocaleString()} (${share}%) | ${classifyChannel(r.domain)} |`);
+  });
+
+  return { text: lines.join('\n') };
+}

package/tools/get-releases.js

@@ -0,0 +1,118 @@
+/**
+ * get-releases tool
+ * Returns recent releases with matched-window pre/post impact metrics.
+ */
+export const definition = {
+  name: 'get-releases',
+  description:
+    'Get your recent website releases (features, bug fixes, marketing changes) with ' +
+    'matched-window pre/post analytics: traffic, visitor, revenue, and goal completion changes ' +
+    'before vs after each release. ' +
+    'Use this to answer "What impact did my last release have?" or ' +
+    '"Did the new feature increase signups?"',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      siteId: {
+        type: 'string',
+        description: 'The Growtics site UUID (get it from list-sites)',
+      },
+      period: {
+        type: 'string',
+        enum: ['24h', '7d', '14d', '30d'],
+        description: 'Comparison window size. Default: 7d',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of releases to return (default: 5, max: 50)',
+      },
+    },
+    required: ['siteId'],
+  },
+};
+
+function pct(pre, post) {
+  if (pre === 0 && post === 0) return null;
+  if (pre === 0) return null;
+  return Math.round(((post - pre) / pre) * 100);
+}
+
+function formatChange(pre, post, unit = '') {
+  const change = pct(pre, post);
+  if (change === null) return '—';
+  const arrow = change > 0 ? '▲' : change < 0 ? '▼' : '→';
+  const color = change > 0 ? '🟢' : change < 0 ? '🔴' : '⚪';
+  return `${color} ${arrow} ${Math.abs(change)}%${unit}`;
+}
+
+export async function run({ args, apiClient }) {
+  const { siteId, period = '7d', limit = 5 } = args;
+  const data = await apiClient.get(
+    `/api/v1/releases?siteId=${siteId}&period=${period}&limit=${limit}`
+  );
+
+  const { releases } = data.data;
+  const meta = data.meta;
+
+  if (!releases?.length) {
+    return {
+      text:
+        `## Releases — ${meta.siteName}\n\n` +
+        `No releases logged yet.\n` +
+        `Log releases in the Growtics dashboard to track their impact.`,
+    };
+  }
+
+  const lines = [
+    `## Release Impact Analysis — ${meta.siteName}`,
+    `**Comparison window:** ${period} before vs after each release\n`,
+  ];
+
+  for (const rel of releases) {
+    const { pre, post, goals } = rel.impact;
+    const windowHours = Math.round(rel.windowSeconds / 3600);
+
+    lines.push(`---\n### ${rel.category === 'feature' ? '✨' : rel.category === 'bugfix' ? '🐛' : rel.category === 'marketing' ? '📣' : '🚀'} ${rel.title}`);
+    lines.push(`**Released:** ${new Date(rel.releasedAt).toLocaleDateString('en-US', { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' })}`);
+    lines.push(`**Category:** ${rel.category}  |  **Comparison window:** ±${windowHours}h\n`);
+
+    if (rel.description) {
+      lines.push(`> ${rel.description}\n`);
+    }
+
+    if (rel.windowSeconds === 0) {
+      lines.push('_Release is too recent — impact data will be available shortly._\n');
+      continue;
+    }
+
+    lines.push('| Metric | Before | After | Change |');
+    lines.push('|--------|--------|-------|--------|');
+    lines.push(`| Page Views | ${pre.views.toLocaleString()} | ${post.views.toLocaleString()} | ${formatChange(pre.views, post.views)} |`);
+    lines.push(`| Unique Visitors | ${pre.visitors.toLocaleString()} | ${post.visitors.toLocaleString()} | ${formatChange(pre.visitors, post.visitors)} |`);
+
+    if (pre.revenue > 0 || post.revenue > 0) {
+      lines.push(`| Revenue | $${pre.revenue.toFixed(2)} | $${post.revenue.toFixed(2)} | ${formatChange(pre.revenue, post.revenue)} |`);
+    }
+
+    if (pre.errors > 0 || post.errors > 0) {
+      // For errors, an increase is bad (red), decrease is good (green)
+      const errChange = pct(pre.errors, post.errors);
+      const errStr = errChange === null ? '—'
+        : errChange > 0 ? `🔴 ▲ ${errChange}% more errors`
+        : errChange < 0 ? `🟢 ▼ ${Math.abs(errChange)}% fewer errors`
+        : '⚪ No change';
+      lines.push(`| Errors | ${pre.errors} | ${post.errors} | ${errStr} |`);
+    }
+
+    if (goals?.length > 0) {
+      lines.push('\n**Goal Conversions:**');
+      for (const g of goals) {
+        lines.push(`- **${g.name}**: ${g.preCompletions} → ${g.postCompletions} ${formatChange(g.preCompletions, g.postCompletions)}`);
+      }
+    }
+
+    lines.push('');
+  }
+
+  return { text: lines.join('\n') };
+}

package/tools/get-seo-suggestions.js

@@ -0,0 +1,104 @@
+/**
+ * get-seo-suggestions tool
+ * Returns AI-generated SEO and UX improvement suggestions from Growtics.
+ */
+export const definition = {
+  name: 'get-seo-suggestions',
+  description:
+    'Get AI-generated SEO, UX, and performance improvement suggestions for your website. ' +
+    'Each suggestion has an impact level (High/Medium/Low) and a status (Open/Solving/Solved). ' +
+    'Use this to answer "What should I improve next for SEO?" or ' +
+    '"What are my most important open issues?"',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      siteId: {
+        type: 'string',
+        description: 'The Growtics site UUID (get it from list-sites)',
+      },
+      status: {
+        type: 'string',
+        enum: ['Open', 'Verifying', 'Solved', 'Failed'],
+        description: 'Filter by status. Leave empty to get all.',
+      },
+      category: {
+        type: 'string',
+        enum: ['SEO', 'UX', 'HTML', 'Errors', 'Journey'],
+        description: 'Filter by category. Leave empty to get all.',
+      },
+    },
+    required: ['siteId'],
+  },
+};
+
+const IMPACT_EMOJI = { High: '🔴', Medium: '🟡', Low: '🟢' };
+const CATEGORY_EMOJI = { SEO: '🔍', UX: '🎨', HTML: '📄', Errors: '⚠️', Journey: '🗺️' };
+
+export async function run({ args, apiClient }) {
+  const { siteId, status, category } = args;
+
+  const params = new URLSearchParams({ siteId });
+  if (status)   params.set('status',   status);
+  if (category) params.set('category', category);
+
+  const data = await apiClient.get(`/api/v1/suggestions?${params.toString()}`);
+
+  const { suggestions, summary } = data.data;
+  const meta = data.meta;
+
+  if (!suggestions?.length) {
+    const qualifier = status ? ` with status "${status}"` : '';
+    return {
+      text:
+        `## SEO & UX Suggestions — ${meta.siteName}\n\n` +
+        `No suggestions found${qualifier}. Growtics generates suggestions automatically ` +
+        `as it analyzes your site — check back soon!`,
+    };
+  }
+
+  const lines = [
+    `## SEO & UX Suggestions — ${meta.siteName}`,
+    `**Domain:** ${meta.domain}  |  **Total:** ${summary.total}\n`,
+  ];
+
+  // Summary by impact
+  if (summary.byStatus) {
+    const parts = Object.entries(summary.byStatus).map(([s, n]) => `${s}: ${n}`).join('  |  ');
+    lines.push(`**By Status:** ${parts}`);
+  }
+  if (summary.byCategory) {
+    const parts = Object.entries(summary.byCategory).map(([c, n]) => `${CATEGORY_EMOJI[c] || '📌'} ${c}: ${n}`).join('  ·  ');
+    lines.push(`**By Category:** ${parts}\n`);
+  }
+
+  // Group by category for readability
+  const grouped = {};
+  for (const s of suggestions) {
+    if (!grouped[s.category]) grouped[s.category] = [];
+    grouped[s.category].push(s);
+  }
+
+  for (const [cat, items] of Object.entries(grouped)) {
+    lines.push(`### ${CATEGORY_EMOJI[cat] || '📌'} ${cat}`);
+    for (const s of items) {
+      const imp = IMPACT_EMOJI[s.impact] || '⚪';
+      const statusBadge = s.status === 'Solved' ? '✅' : s.status === 'Verifying' ? '🔄' : s.status === 'Failed' ? '❌' : '📋';
+      lines.push(`\n**${imp} [${s.impact}] ${s.title}** ${statusBadge} ${s.status}`);
+      lines.push(`> ${s.description}`);
+    }
+    lines.push('');
+  }
+
+  // Prioritized action list
+  const highImpactOpen = suggestions.filter(s => s.impact === 'High' && s.status === 'Open');
+  if (highImpactOpen.length > 0) {
+    lines.push('---');
+    lines.push('### 🎯 Recommended Next Actions (High Impact, Open)');
+    highImpactOpen.forEach((s, i) => {
+      lines.push(`${i + 1}. **${s.title}** (${s.category})`);
+      lines.push(`   ${s.description}`);
+    });
+  }
+
+  return { text: lines.join('\n') };
+}

package/tools/get-top-pages.js

@@ -0,0 +1,53 @@
+/**
+ * get-top-pages tool
+ * Returns top pages by page views for a given period.
+ */
+export const definition = {
+  name: 'get-top-pages',
+  description:
+    'Get the top-performing pages on your website ranked by page views. ' +
+    'Use this to answer "Which pages are getting the most traffic?" or ' +
+    '"Which pages are losing conversions?" when combined with goals data.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      siteId: {
+        type: 'string',
+        description: 'The Growtics site UUID (get it from list-sites)',
+      },
+      period: {
+        type: 'string',
+        enum: ['today', 'yesterday', '24h', '7d', '28d', '91d', 'mtd', 'lastmonth', 'ytd', '12m', 'all'],
+        description: 'Time period for the report. Default: 7d',
+      },
+    },
+    required: ['siteId'],
+  },
+};
+
+export async function run({ args, apiClient }) {
+  const { siteId, period = '7d' } = args;
+  const data = await apiClient.get(`/api/v1/analytics?siteId=${siteId}&period=${period}&type=overview`);
+
+  const { topPages } = data.data;
+  const meta = data.meta;
+
+  if (!topPages?.length) {
+    return { text: `No page data found for **${meta.siteName}** in the period \`${period}\`.` };
+  }
+
+  const total = topPages.reduce((s, p) => s + p.pageviews, 0);
+
+  const lines = [
+    `## Top Pages — ${meta.siteName}`,
+    `**Period:** ${period}  |  **Total across top pages:** ${total.toLocaleString()} views\n`,
+    `| # | Page | Views | Share |`,
+    `|---|------|-------|-------|`,
+    ...topPages.map((p, i) => {
+      const share = total > 0 ? ((p.pageviews / total) * 100).toFixed(1) : '0.0';
+      return `| ${i + 1} | \`${p.path}\` | ${p.pageviews.toLocaleString()} | ${share}% |`;
+    }),
+  ];
+
+  return { text: lines.join('\n') };
+}

package/tools/get-traffic-overview.js

@@ -0,0 +1,84 @@
+/**
+ * get-traffic-overview tool
+ * Returns the core traffic stats + time-series for a site.
+ */
+export const definition = {
+  name: 'get-traffic-overview',
+  description:
+    'Get a complete traffic overview for a Growtics site: total page views, unique visitors, ' +
+    'active visitors right now, bounce rate, and a daily/hourly time-series breakdown. ' +
+    'Use this to answer questions like "How is my traffic doing?" or "Why did traffic drop this week?"',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      siteId: {
+        type: 'string',
+        description: 'The Growtics site UUID (get it from list-sites)',
+      },
+      period: {
+        type: 'string',
+        enum: ['today', 'yesterday', '24h', '7d', '28d', '91d', 'mtd', 'lastmonth', 'ytd', '12m', 'all'],
+        description: 'Time period for the report. Default: 7d',
+      },
+    },
+    required: ['siteId'],
+  },
+};
+
+export async function run({ args, apiClient }) {
+  const { siteId, period = '7d' } = args;
+  const data = await apiClient.get(`/api/v1/analytics?siteId=${siteId}&period=${period}&type=overview`);
+
+  const { stats, timeSeries, topPages, topReferrers, topDevices, topCountries } = data.data;
+  const meta = data.meta;
+
+  // Trend: compare first half vs second half of time-series
+  let trendNote = '';
+  if (timeSeries.length >= 4) {
+    const mid   = Math.floor(timeSeries.length / 2);
+    const first = timeSeries.slice(0, mid).reduce((s, d) => s + d.pageviews, 0);
+    const last  = timeSeries.slice(mid).reduce((s, d)  => s + d.pageviews, 0);
+    const pct   = first > 0 ? Math.round(((last - first) / first) * 100) : 0;
+    if (pct > 5)       trendNote = `📈 Traffic is **up ${pct}%** in the second half of this period.`;
+    else if (pct < -5) trendNote = `📉 Traffic is **down ${Math.abs(pct)}%** in the second half of this period.`;
+    else               trendNote = `➡️ Traffic is **relatively stable** across this period.`;
+  }
+
+  const lines = [
+    `## Traffic Overview — ${meta.siteName} (${meta.domain})`,
+    `**Period:** ${period}  |  **Generated:** ${new Date(meta.generatedAt).toLocaleString()}\n`,
+
+    `### Core Metrics`,
+    `| Metric | Value |`,
+    `|--------|-------|`,
+    `| Page Views | **${stats.pageviews.toLocaleString()}** |`,
+    `| Unique Visitors | **${stats.uniqueVisitors.toLocaleString()}** |`,
+    `| Active Visitors (now) | **${stats.activeVisitors}** |`,
+    `| Bounce Rate | **${stats.bounceRate}%** |`,
+
+    trendNote ? `\n${trendNote}` : '',
+
+    `\n### Time Series (${timeSeries.length} data points)`,
+    timeSeries.length
+      ? timeSeries.map(d => `- ${d.time}: ${d.pageviews.toLocaleString()} views, ${d.uniqueVisitors.toLocaleString()} visitors`).join('\n')
+      : 'No data available.',
+
+    `\n### Top Pages`,
+    topPages.length
+      ? topPages.slice(0, 5).map((p, i) => `${i + 1}. \`${p.path}\` — ${p.pageviews.toLocaleString()} views`).join('\n')
+      : 'No page data.',
+
+    `\n### Top Referrers`,
+    topReferrers.length
+      ? topReferrers.slice(0, 5).map((r, i) => `${i + 1}. **${r.domain || '(direct)'}** — ${r.pageviews.toLocaleString()} views`).join('\n')
+      : 'No referrer data.',
+
+    `\n### Top Devices`,
+    topDevices.map(d => `- ${d.device}: ${d.pageviews.toLocaleString()} views`).join('\n') || 'No device data.',
+
+    `\n### Top Countries`,
+    topCountries.slice(0, 5).map(c => `- ${c.country}: ${c.pageviews.toLocaleString()} views`).join('\n') || 'No country data.',
+  ];
+
+  return { text: lines.filter(Boolean).join('\n') };
+}

package/tools/list-sites.js

@@ -0,0 +1,37 @@
+/**
+ * list-sites tool
+ * Lists all sites belonging to the authenticated Growtics account.
+ */
+export const definition = {
+  name: 'list-sites',
+  description:
+    'List all websites registered in your Growtics account. ' +
+    'Returns each site\'s ID, name, domain, and creation date. ' +
+    'Use this first to get siteId values needed by other tools.',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+    required: [],
+  },
+};
+
+export async function run({ apiClient }) {
+  const data = await apiClient.get('/api/v1/sites');
+
+  if (!data?.data?.length) {
+    return { text: 'No sites found in your Growtics account.' };
+  }
+
+  const lines = [
+    `## Your Growtics Sites (${data.meta.total} total)\n`,
+    ...data.data.map(
+      (s, i) =>
+        `**${i + 1}. ${s.name}**\n` +
+        `   - Site ID: \`${s.id}\`\n` +
+        `   - Domain: ${s.domain}\n` +
+        `   - Added: ${new Date(s.createdAt).toLocaleDateString()}`
+    ),
+  ];
+
+  return { text: lines.join('\n') };
+}