search-console-mcp 1.9.0 → 1.9.2

package/dist/index.js

@@ -8,7 +8,9 @@ import * as analytics from "./tools/analytics.js";
 import * as inspection from "./tools/inspection.js";
 import * as pagespeed from "./tools/pagespeed.js";
 import * as seoInsights from "./tools/seo-insights.js";
+import * as seoPrimitives from "./tools/seo-primitives.js";
 import * as schemaValidator from "./tools/schema-validator.js";
+import * as advancedAnalytics from "./tools/advanced-analytics.js";
 import { formatError } from "./errors.js";
 const server = new McpServer({
     name: "search-console-mcp",
@@ -119,8 +121,10 @@ server.tool("analytics_query", "Query search analytics data with optional pagina
     startDate: z.string().describe("Start date (YYYY-MM-DD)"),
     endDate: z.string().describe("End date (YYYY-MM-DD)"),
     dimensions: z.array(z.string()).optional().describe("Dimensions to group by (date, query, page, country, device, searchAppearance)"),
-    type: z.string().optional().describe("Search type (web, image, video, news, discover, googleNews)"),
-    limit: z.number().optional().describe("Max number of rows (default: 1000, max: 25000)"),
+    type: z.enum(["web", "image", "video", "news", "discover", "googleNews"]).optional().describe("Search type (default: web)"),
+    aggregationType: z.enum(["auto", "byProperty", "byPage"]).optional().describe("How to aggregate data (default: auto)"),
+    dataState: z.enum(["final", "all"]).optional().describe("Include fresh data? 'all' includes fresh (preliminary) data (default: final)"),
+    limit: z.number().optional().describe("Max rows to return (default: 1000)"),
     startRow: z.number().optional().describe("Starting row for pagination (0-based)"),
     filters: z.array(z.object({
         dimension: z.string(),
@@ -201,6 +205,122 @@ server.tool("analytics_top_pages", "Get top performing pages by clicks or impres
         return formatError(error);
     }
 });
+server.tool("analytics_by_country", "Get performance breakdown by country for the last N days.", {
+    siteUrl: z.string().describe("The URL of the site"),
+    days: z.number().optional().describe("Number of days to look back (default: 28)"),
+    limit: z.number().optional().describe("Number of countries to return (default: 250)"),
+    sortBy: z.enum(["clicks", "impressions"]).optional().describe("Sort by clicks or impressions (default: clicks)")
+}, async ({ siteUrl, days, limit, sortBy }) => {
+    try {
+        const result = await analytics.getPerformanceByCountry(siteUrl, { days, limit, sortBy });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+    }
+    catch (error) {
+        return formatError(error);
+    }
+});
+server.tool("analytics_search_appearance", "Get performance breakdown by search appearance type for the last N days.", {
+    siteUrl: z.string().describe("The URL of the site"),
+    days: z.number().optional().describe("Number of days to look back (default: 28)"),
+    limit: z.number().optional().describe("Number of types to return (default: 50)"),
+    sortBy: z.enum(["clicks", "impressions"]).optional().describe("Sort by clicks or impressions (default: clicks)")
+}, async ({ siteUrl, days, limit, sortBy }) => {
+    try {
+        const result = await analytics.getPerformanceBySearchAppearance(siteUrl, { days, limit, sortBy });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+    }
+    catch (error) {
+        return formatError(error);
+    }
+});
+server.tool("analytics_trends", "Detect traffic trends (rising/declining) for queries or pages.", {
+    siteUrl: z.string().describe("The URL of the site"),
+    dimension: z.enum(["query", "page"]).optional().describe("Dimension to analyze (default: query)"),
+    days: z.number().optional().describe("Number of days to analyze (default: 28)"),
+    threshold: z.number().optional().describe("Minimum percentage change to consider (default: 10)"),
+    minClicks: z.number().optional().describe("Minimum clicks required to be considered (default: 100)"),
+    limit: z.number().optional().describe("Max results to return (default: 20)")
+}, async ({ siteUrl, dimension, days, threshold, minClicks, limit }) => {
+    try {
+        const result = await analytics.detectTrends(siteUrl, { dimension, days, threshold, minClicks, limit });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+    }
+    catch (error) {
+        return formatError(error);
+    }
+});
+server.tool("analytics_anomalies", "Identify unusual daily spikes or drops in traffic.", {
+    siteUrl: z.string().describe("The URL of the site"),
+    days: z.number().optional().describe("Number of days to look back for baseline (default: 30)"),
+    threshold: z.number().optional().describe("Sensitivity threshold (Standard Deviations, default: 2.5)")
+}, async ({ siteUrl, days, threshold }) => {
+    try {
+        const result = await analytics.detectAnomalies(siteUrl, { days, threshold });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+    }
+    catch (error) {
+        return formatError(error);
+    }
+});
+server.tool("analytics_drop_attribution", "Analyze a significant traffic drop to identify if it was caused by specific devices (mobile/desktop) or coincides with known Google algorithm updates.", {
+    siteUrl: z.string().describe("The URL of the site"),
+    days: z.number().optional().describe("Number of days to look back (default: 30)"),
+    threshold: z.number().optional().describe("Sensitivity threshold for drop detection (Standard Deviations, default: 2.0)")
+}, async ({ siteUrl, days, threshold }) => {
+    try {
+        const result = await advancedAnalytics.analyzeDropAttribution(siteUrl, { days, threshold });
+        return {
+            content: [{ type: "text", text: result ? JSON.stringify(result, null, 2) : "No significant traffic drop detected in the specified period." }]
+        };
+    }
+    catch (error) {
+        return formatError(error);
+    }
+});
+server.tool("analytics_time_series", "Get advanced time series data including rolling averages, seasonality strength, and trend forecasting. Supports multi-dimensional analysis, metrics selection, and custom granularities.", {
+    siteUrl: z.string().describe("The URL of the site"),
+    days: z.number().optional().describe("Number of days of history to analyze (default: 60)"),
+    startDate: z.string().optional().describe("Start date (YYYY-MM-DD)"),
+    endDate: z.string().optional().describe("End date (YYYY-MM-DD)"),
+    dimensions: z.array(z.string()).optional().describe("Dimensions to group by (default: ['date'])"),
+    metrics: z.array(z.enum(["clicks", "impressions", "ctr", "position"])).optional().describe("Metrics to analyze (default: ['clicks'])"),
+    granularity: z.enum(["daily", "weekly"]).optional().describe("Granularity of the data (default: daily)"),
+    filters: z.array(z.object({
+        dimension: z.string(),
+        operator: z.string(),
+        expression: z.string()
+    })).optional().describe("Filter groups to apply"),
+    window: z.number().optional().describe("Window size for rolling average in days/weeks (default: 7)"),
+    forecastDays: z.number().optional().describe("Number of units (days/weeks) to forecast into the future (default: 7)")
+}, async ({ siteUrl, days, startDate, endDate, dimensions, metrics, granularity, filters, window, forecastDays }) => {
+    try {
+        const result = await advancedAnalytics.getTimeSeriesInsights(siteUrl, {
+            days,
+            startDate,
+            endDate,
+            dimensions,
+            metrics,
+            granularity,
+            filters,
+            window,
+            forecastDays
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+    }
+    catch (error) {
+        return formatError(error);
+    }
+});
 // Inspection Tools
 server.tool("inspection_inspect", "Inspect a URL to check its indexing status, crawl info, and mobile usability", {
     siteUrl: z.string().describe("The URL of the property (must match a verified property in Search Console)"),
@@ -292,6 +412,67 @@ server.tool("seo_cannibalization", "Detect keyword cannibalization - multiple pa
         return formatError(error);
     }
 });
+server.tool("seo_low_ctr_opportunities", "Find queries ranking in positions 1-10 with low CTR (< 60% of benchmark). Great for title tag optimization.", {
+    siteUrl: z.string().describe("The site URL"),
+    days: z.number().optional().describe("Number of days to analyze (default: 28)"),
+    minImpressions: z.number().optional().describe("Minimum impressions threshold (default: 500)"),
+    limit: z.number().optional().describe("Max results to return (default: 50)")
+}, async ({ siteUrl, days, minImpressions, limit }) => {
+    try {
+        const result = await seoInsights.findLowCTROpportunities(siteUrl, { days, minImpressions, limit });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+    }
+    catch (error) {
+        return formatError(error);
+    }
+});
+server.tool("seo_striking_distance", "Find keywords ranking in positions 8-15. These are high-priority targets to push to Page 1.", {
+    siteUrl: z.string().describe("The site URL"),
+    days: z.number().optional().describe("Number of days to analyze (default: 28)"),
+    limit: z.number().optional().describe("Max results to return (default: 50)")
+}, async ({ siteUrl, days, limit }) => {
+    try {
+        const result = await seoInsights.findStrikingDistance(siteUrl, { days, limit });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+    }
+    catch (error) {
+        return formatError(error);
+    }
+});
+server.tool("seo_lost_queries", "Identify queries that lost all traffic (or dropped >80%) compared to the previous period.", {
+    siteUrl: z.string().describe("The site URL"),
+    days: z.number().optional().describe("Number of days to compare (default: 28)"),
+    limit: z.number().optional().describe("Max results to return (default: 50)")
+}, async ({ siteUrl, days, limit }) => {
+    try {
+        const result = await seoInsights.findLostQueries(siteUrl, { days, limit });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+    }
+    catch (error) {
+        return formatError(error);
+    }
+});
+server.tool("seo_brand_vs_nonbrand", "Analyze performance split between Brand and Non-Brand queries using a regex.", {
+    siteUrl: z.string().describe("The site URL"),
+    brandRegex: z.string().describe("Regex to match brand keywords (e.g. 'acme|acme corp')"),
+    days: z.number().optional().describe("Number of days to analyze (default: 28)")
+}, async ({ siteUrl, brandRegex, days }) => {
+    try {
+        const result = await seoInsights.analyzeBrandVsNonBrand(siteUrl, brandRegex, { days });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+    }
+    catch (error) {
+        return formatError(error);
+    }
+});
 server.tool("seo_quick_wins", "Find pages with queries ranking on page 2 (positions 11-20) that could be pushed to page 1", {
     siteUrl: z.string().describe("The site URL"),
     days: z.number().optional().describe("Number of days to analyze (default: 28)"),
@@ -308,6 +489,43 @@ server.tool("seo_quick_wins", "Find pages with queries ranking on page 2 (positi
         return formatError(error);
     }
 });
+// SEO Primitives (Atoms)
+server.tool("seo_primitive_ranking_bucket", "primitive: Get the ranking bucket for a specific position (e.g. Top 3, Page 1).", { position: z.number().describe("The ranking position") }, async ({ position }) => {
+    return {
+        content: [{ type: "text", text: JSON.stringify(seoPrimitives.getRankingBucket(position), null, 2) }]
+    };
+});
+server.tool("seo_primitive_traffic_delta", "primitive: Calculate the delta between two traffic metrics (absolute and percentage).", {
+    current: z.number().describe("Current value"),
+    previous: z.number().describe("Previous value")
+}, async ({ current, previous }) => {
+    return {
+        content: [{ type: "text", text: JSON.stringify(seoPrimitives.calculateTrafficDelta(current, previous), null, 2) }]
+    };
+});
+server.tool("seo_primitive_is_brand", "primitive: Check if a query is a brand query based on a regex pattern.", {
+    query: z.string().describe("The search query"),
+    brandRegex: z.string().describe("Regex pattern to identify brand terms")
+}, async ({ query, brandRegex }) => {
+    return {
+        content: [{ type: "text", text: JSON.stringify(seoPrimitives.isBrandQuery(query, brandRegex), null, 2) }]
+    };
+});
+server.tool("seo_primitive_is_cannibalized", "primitive: Check if two pages are competing for the same query based on their metrics.", {
+    query: z.string().describe("The search query"),
+    pageA_position: z.number(),
+    pageA_impressions: z.number(),
+    pageA_clicks: z.number(),
+    pageB_position: z.number(),
+    pageB_impressions: z.number(),
+    pageB_clicks: z.number()
+}, async ({ query, pageA_position, pageA_impressions, pageA_clicks, pageB_position, pageB_impressions, pageB_clicks }) => {
+    const pageA = { position: pageA_position, impressions: pageA_impressions, clicks: pageA_clicks };
+    const pageB = { position: pageB_position, impressions: pageB_impressions, clicks: pageB_clicks };
+    return {
+        content: [{ type: "text", text: JSON.stringify(seoPrimitives.isCannibalized(query, pageA, pageB), null, 2) }]
+    };
+});
 // Schema Validator Tools
 server.tool("schema_validate", "Validate Schema.org structured data (JSON-LD) from a URL, HTML snippet, or JSON object.", {
     type: z.enum(["url", "html", "json"]).describe("The type of input provided"),
@@ -323,6 +541,19 @@ server.tool("schema_validate", "Validate Schema.org structured data (JSON-LD) fr
         return formatError(error);
     }
 });
+// Support Tools
+server.tool("util_star_repo", "Star the GitHub repository to support the project. Uses GitHub CLI if available, or opens a browser.", {}, async () => {
+    try {
+        const { starRepository } = await import("./tools/support.js");
+        const result = await starRepository();
+        return {
+            content: [{ type: "text", text: result }]
+        };
+    }
+    catch (error) {
+        return formatError(error);
+    }
+});
 // Resources
 server.resource("sites", "sites://list", async (uri) => {
     const result = await sites.listSites();
@@ -357,7 +588,7 @@ server.resource("analytics-summary", "analytics://summary/{siteUrl}", async (uri
     };
 });
 // Documentation Resources
-import { dimensionsDocs, filtersDocs, searchTypesDocs, patternsDocs } from "./docs/index.js";
+import { dimensionsDocs, filtersDocs, searchTypesDocs, patternsDocs, algorithmUpdatesDocs } from "./docs/index.js";
 server.resource("docs-dimensions", "docs://dimensions", async (uri) => ({
     contents: [{
             uri: uri.href,
@@ -386,6 +617,13 @@ server.resource("docs-patterns", "docs://patterns", async (uri) => ({
             mimeType: "text/markdown"
         }]
 }));
+server.resource("docs-algorithm-updates", "docs://algorithm-updates", async (uri) => ({
+    contents: [{
+            uri: uri.href,
+            text: algorithmUpdatesDocs,
+            mimeType: "text/markdown"
+        }]
+}));
 // Prompts
 server.prompt("analyze-site-performance", { siteUrl: z.string().describe("The URL of the site to analyze") }, ({ siteUrl }) => ({
     messages: [{
@@ -503,6 +741,17 @@ Provide a summary with actionable recommendations.`
         }]
 }));
 async function main() {
+    if (!process.env.GOOGLE_APPLICATION_CREDENTIALS) {
+        console.error('\n╔══════════════════════════════════════════════════════════════╗');
+        console.error('║          🚀 Google Search Console MCP Server                 ║');
+        console.error('╚══════════════════════════════════════════════════════════════╝\n');
+        console.error('❌ GOOGLE_APPLICATION_CREDENTIALS environment variable is not set.\n');
+        console.error('💡 To set up the server, run the setup wizard:');
+        console.error('   npx search-console-mcp-setup\n');
+        console.error('Alternatively, set the variable manually:');
+        console.error('   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/key.json\n');
+        console.error('─'.repeat(64) + '\n');
+    }
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("Google Search Console MCP Server running on stdio");

package/dist/setup.js

@@ -1,8 +1,12 @@
 #!/usr/bin/env node
-import { readFileSync, existsSync } from 'fs';
-import { resolve } from 'path';
+import { readFileSync, existsSync, statSync } from 'fs';
+import { resolve, dirname, extname } from 'path';
 import { createInterface } from 'readline';
 import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
 const rl = createInterface({
     input: process.stdin,
     output: process.stdout
@@ -33,11 +37,25 @@ function printInfo(text) {
 }
 function validateKeyFile(path) {
     try {
-        const fullPath = resolve(path.replace('~', homedir()));
+        const sanitizedPath = path.trim().replace(/\0/g, '');
+        const fullPath = resolve(sanitizedPath.replace('~', homedir()));
         if (!existsSync(fullPath)) {
             printError(`File not found: ${fullPath}`);
             return null;
         }
+        const stats = statSync(fullPath);
+        if (!stats.isFile()) {
+            printError(`Not a regular file: ${fullPath}`);
+            return null;
+        }
+        if (extname(fullPath).toLowerCase() !== '.json') {
+            printError(`Invalid file type. Please provide a .json file.`);
+            return null;
+        }
+        if (stats.size > 1024 * 1024) {
+            printError(`File too large. Service account keys are typically small JSON files.`);
+            return null;
+        }
         const content = readFileSync(fullPath, 'utf-8');
         const key = JSON.parse(content);
         const required = ['type', 'project_id', 'client_email', 'private_key'];
@@ -103,6 +121,30 @@ function showConfigSnippets(credentialsPath) {
     }, null, 2));
     console.log('─'.repeat(60));
 }
+export function resolveRepo(dirname) {
+    let repo = '';
+    try {
+        const url = execSync('git remote get-url origin', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        repo = url
+            .replace(/^git@github\.com:|^https:\/\/github\.com\//, '')
+            .replace(/\.git$/, '');
+    }
+    catch {
+        // Fallback to package.json
+        const pkgPath = resolve(dirname, '../package.json');
+        if (existsSync(pkgPath)) {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+            if (pkg.repository?.url) {
+                repo = pkg.repository.url.replace(/.*github\.com\//, '').replace(/\.git$/, '');
+            }
+            else if (pkg.mcpName && pkg.mcpName.includes('/')) {
+                // Handle io.github.owner/repo or owner/repo
+                repo = pkg.mcpName.replace(/^io\.github\./, '').split('/').slice(-2).join('/');
+            }
+        }
+    }
+    return repo;
+}
 async function main() {
     printHeader();
     console.log('This wizard will help you set up Search Console MCP.');
@@ -176,13 +218,18 @@ async function main() {
     const answer = await ask('Would you like to star the repo on GitHub? (y/n): ');
     if (answer.toLowerCase().startsWith('y')) {
         try {
-            const { execSync } = await import('child_process');
-            execSync('gh repo star saurabhsharma2u/search-console-mcp', { stdio: 'inherit' });
-            printSuccess('Thanks for your support! ⭐');
+            const repo = resolveRepo(__dirname);
+            if (repo && repo.includes('/')) {
+                execSync(`gh api -X PUT /user/starred/${repo}`, { stdio: 'ignore' });
+                printSuccess('Thanks for your support! ⭐');
+            }
+            else {
+                throw new Error('Could not resolve repo');
+            }
         }
         catch (error) {
-            printInfo('Could not auto-star the repo (GitHub CLI might be missing).');
-            console.log('Please star us manually at: https://github.com/saurabhsharma2u/search-console-mcp');
+            console.log('\nCould not star automatically. Please star us manually if you like:');
+            console.log('🔗 https://github.com/saurabhsharma2u/search-console-mcp');
         }
     }
     else {
@@ -191,7 +238,10 @@ async function main() {
     rl.close();
 }
 // Run if called directly
-main().catch((error) => {
-    console.error('Setup failed:', error);
-    process.exit(1);
-});
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1]);
+if (isMain) {
+    main().catch((error) => {
+        console.error('Setup failed:', error);
+        process.exit(1);
+    });
+}

package/dist/tools/advanced-analytics.js

@@ -0,0 +1,246 @@
+import { queryAnalytics, detectAnomalies } from './analytics.js';
+/**
+ * Historical Google Algorithm Update dates (recent notable ones)
+ */
+const ALGORITHM_UPDATES = [
+    { date: '2023-09-14', name: 'September 2023 Helpful Content Update' },
+    { date: '2023-10-05', name: 'October 2023 Core Update' },
+    { date: '2023-11-02', name: 'November 2023 Core Update' },
+    { date: '2024-03-05', name: 'March 2024 Core Update' },
+    { date: '2024-06-20', name: 'June 2024 Spam Update' },
+    { date: '2024-08-15', name: 'August 2024 Core Update' },
+    { date: '2024-11-11', name: 'November 2024 Core Update' },
+    { date: '2025-01-15', name: 'January 2025 Core Update' }
+];
+/**
+ * Identify the cause of a significant traffic drop by analyzing device distribution and algorithm updates.
+ *
+ * @param siteUrl - The URL of the site to analyze.
+ * @param options - Configuration including the lookback period and anomaly threshold.
+ * @returns A detailed attribution object or null if no significant drop is found.
+ */
+export async function analyzeDropAttribution(siteUrl, options = {}) {
+    const anomalies = await detectAnomalies(siteUrl, { days: options.days ?? 30, threshold: options.threshold ?? 2.0 });
+    // Find the most recent 'drop'
+    const mostRecentDrop = anomalies.find(a => a.type === 'drop');
+    if (!mostRecentDrop)
+        return null;
+    const dropDate = mostRecentDrop.date;
+    const previousWeekStart = new Date(dropDate);
+    previousWeekStart.setDate(previousWeekStart.getDate() - 7);
+    const previousWeekEnd = new Date(dropDate);
+    previousWeekEnd.setDate(previousWeekEnd.getDate() - 1);
+    const [dropDayStats, baselineStats] = await Promise.all([
+        queryAnalytics({
+            siteUrl,
+            startDate: dropDate,
+            endDate: dropDate,
+            dimensions: ['device']
+        }),
+        queryAnalytics({
+            siteUrl,
+            startDate: previousWeekStart.toISOString().split('T')[0],
+            endDate: previousWeekEnd.toISOString().split('T')[0],
+            dimensions: ['device']
+        })
+    ]);
+    const dropMap = new Map(dropDayStats.map(r => [r.keys?.[0]?.toLowerCase(), r.clicks ?? 0]));
+    const baselineMap = new Map();
+    baselineStats.forEach(r => {
+        const device = r.keys?.[0]?.toLowerCase();
+        const current = baselineMap.get(device) || 0;
+        baselineMap.set(device, current + (r.clicks ?? 0) / 7);
+    });
+    const impacts = { mobile: 0, desktop: 0, tablet: 0 };
+    let primaryDevice = 'unknown';
+    let maxDeficit = 0;
+    ['mobile', 'desktop', 'tablet'].forEach(device => {
+        const baseline = baselineMap.get(device) || 0;
+        const actual = dropMap.get(device) || 0;
+        const deficit = baseline - actual;
+        impacts[device] = parseFloat(deficit.toFixed(2));
+        if (deficit > maxDeficit) {
+            maxDeficit = deficit;
+            primaryDevice = device;
+        }
+    });
+    // Check for algorithm updates within 2 days of the drop
+    const possibleUpdate = ALGORITHM_UPDATES.find(u => {
+        const uDate = new Date(u.date);
+        const dDate = new Date(dropDate);
+        const diff = Math.abs(dDate.getTime() - uDate.getTime()) / (1000 * 60 * 60 * 24);
+        return diff <= 2;
+    });
+    return {
+        date: dropDate,
+        metric: mostRecentDrop.metric,
+        totalDrop: mostRecentDrop.value - mostRecentDrop.expectedValue,
+        deviceImpact: impacts,
+        primaryCause: primaryDevice !== 'unknown' ? `Disproportionate drop on ${primaryDevice}` : 'Uniform drop across devices',
+        possibleAlgorithmUpdate: possibleUpdate?.name
+    };
+}
+/**
+ * Advanced time series analysis for smoothing, seasonality, and forecasting.
+ * Supports dynamic dimensions, multiple metrics, granularities, and custom filtering.
+ *
+ * @param siteUrl - The URL of the site to analyze.
+ * @param options - Analysis configuration including metrics, granularity, and forecast length.
+ * @returns Historical data points with rolling averages and a forecast object.
+ */
+export async function getTimeSeriesInsights(siteUrl, options = {}) {
+    const metrics = options.metrics || ['clicks'];
+    const granularity = options.granularity || 'daily';
+    const windowSize = options.window || 7;
+    const forecastDays = options.forecastDays ?? 7;
+    const dimensions = options.dimensions || ['date'];
+    // Ensure 'date' is included in dimensions for time series if not already there
+    if (!dimensions.includes('date')) {
+        dimensions.unshift('date');
+    }
+    let startDate;
+    let endDate;
+    if (options.startDate && options.endDate) {
+        startDate = options.startDate;
+        endDate = options.endDate;
+    }
+    else {
+        const days = options.days ?? 60;
+        const end = new Date();
+        end.setDate(end.getDate() - 3); // GSC delay
+        const start = new Date(end);
+        start.setDate(start.getDate() - days);
+        startDate = start.toISOString().split('T')[0];
+        endDate = end.toISOString().split('T')[0];
+    }
+    const rows = await queryAnalytics({
+        siteUrl,
+        startDate,
+        endDate,
+        dimensions,
+        filters: options.filters
+    });
+    // Handle data parsing and grouping
+    let data = rows.map(r => {
+        const dimObj = {};
+        dimensions.forEach((d, i) => {
+            if (d !== 'date')
+                dimObj[d] = r.keys?.[i] || '';
+        });
+        const metricObj = {};
+        metrics.forEach(m => {
+            metricObj[m] = r[m] ?? 0;
+        });
+        return {
+            date: r.keys?.[dimensions.indexOf('date')] || '',
+            dimensions: dimObj,
+            metrics: metricObj
+        };
+    }).sort((a, b) => a.date.localeCompare(b.date));
+    // Support weekly granularity
+    if (granularity === 'weekly') {
+        const weeklyData = {};
+        data.forEach(d => {
+            const date = new Date(d.date);
+            const day = date.getDay();
+            const diff = date.getDate() - day + (day === 0 ? -6 : 1); // Adjust to Monday
+            const monday = new Date(date.setDate(diff));
+            const weekKey = monday.toISOString().split('T')[0];
+            if (!weeklyData[weekKey]) {
+                weeklyData[weekKey] = {
+                    date: weekKey,
+                    dimensions: d.dimensions,
+                    metrics: { ...d.metrics }
+                };
+            }
+            else {
+                metrics.forEach(m => {
+                    if (m === 'position') {
+                        // For average position, we might need a weighted average, but simple average for now
+                        weeklyData[weekKey].metrics[m] = (weeklyData[weekKey].metrics[m] + d.metrics[m]) / 2;
+                    }
+                    else if (m === 'ctr') {
+                        weeklyData[weekKey].metrics[m] = (weeklyData[weekKey].metrics[m] + d.metrics[m]) / 2;
+                    }
+                    else {
+                        weeklyData[weekKey].metrics[m] += d.metrics[m];
+                    }
+                });
+            }
+        });
+        data = Object.values(weeklyData).sort((a, b) => a.date.localeCompare(b.date));
+    }
+    // 1. Calculate Rolling Averages for EACH metric
+    const history = data.map((d, i) => {
+        const win = data.slice(Math.max(0, i - (windowSize - 1)), i + 1);
+        const rollingAvgObj = {};
+        metrics.forEach(m => {
+            const avg = win.reduce((sum, curr) => sum + curr.metrics[m], 0) / win.length;
+            rollingAvgObj[m] = parseFloat(avg.toFixed(2));
+        });
+        return {
+            date: granularity === 'daily' ? d.date : undefined,
+            week: granularity === 'weekly' ? d.date : undefined,
+            dimensions: Object.keys(d.dimensions).length > 0 ? d.dimensions : undefined,
+            metrics: d.metrics,
+            rollingAverages: rollingAvgObj,
+            isSeasonalPeak: false
+        };
+    });
+    // 2. Identify Seasonality (only makes sense for daily data)
+    let seasonalityStrength = 0;
+    if (granularity === 'daily' && data.length >= 14) {
+        const firstMetric = metrics[0];
+        const dowStats = [[], [], [], [], [], [], []];
+        data.forEach(d => {
+            const day = new Date(d.date).getDay();
+            dowStats[day].push(d.metrics[firstMetric]);
+        });
+        const dowAverages = dowStats.map(vals => vals.length > 0 ? vals.reduce((a, b) => a + b, 0) / vals.length : 0);
+        const globalAvg = dowAverages.reduce((a, b) => a + b, 0) / 7;
+        const variance = dowAverages.reduce((a, b) => a + Math.pow(b - globalAvg, 2), 0) / 7;
+        const stdDev = Math.sqrt(variance);
+        seasonalityStrength = parseFloat(Math.min(1, stdDev / (globalAvg || 1)).toFixed(2));
+        const peakDay = dowAverages.indexOf(Math.max(...dowAverages));
+        history.forEach(h => {
+            if (h.date && new Date(h.date).getDay() === peakDay)
+                h.isSeasonalPeak = true;
+        });
+    }
+    // 3. Simple Linear Regression for Forecasting for EACH metric
+    const forecastResults = {};
+    let overallTrend = 'stable';
+    metrics.forEach(m => {
+        const n = data.length;
+        if (n < 2) {
+            forecastResults[m] = [];
+            return;
+        }
+        let sumX = 0, sumY = 0, sumXY = 0, sumXX = 0;
+        for (let i = 0; i < n; i++) {
+            sumX += i;
+            sumY += data[i].metrics[m];
+            sumXY += i * data[i].metrics[m];
+            sumXX += i * i;
+        }
+        const slope = (n * sumXY - sumX * sumY) / (n * sumXX - sumX * sumX);
+        const intercept = (sumY - slope * sumX) / n;
+        if (m === metrics[0]) {
+            overallTrend = slope > 0.05 ? 'up' : (slope < -0.05 ? 'down' : 'stable');
+        }
+        const forecastPoints = [];
+        for (let i = n; i < n + forecastDays; i++) {
+            const rawForecast = slope * i + intercept;
+            forecastPoints.push(Math.max(0, Math.round(rawForecast)));
+        }
+        forecastResults[m] = forecastPoints;
+    });
+    return {
+        history,
+        forecast: {
+            currentTrend: overallTrend,
+            forecastedValues: forecastResults,
+            seasonalityStrength
+        }
+    };
+}