search-console-mcp 1.12.0 → 1.13.0

package/README.md

@@ -1,7 +1,7 @@
 
 # Search Console MCP
 
-A Model Context Protocol (MCP) server that transforms how you interact with **Google Search Console** and **Bing Webmaster Tools**. Stop exporting CSVs and start asking questions.
+A Model Context Protocol (MCP) server that transforms how you interact with **Google Search Console**, **Bing Webmaster Tools**, and **Google Analytics 4**. Stop exporting CSVs and start asking questions.
 
 [📚 View Documentation](https://searchconsolemcp.mintlify.app/)
 
@@ -12,23 +12,19 @@ A Model Context Protocol (MCP) server that transforms how you interact with **Go
 
 ## Why use this?
 
-### ❌ The Old Way
-1.  Open Google Search Console → Export CSV
-2.  Open Bing Webmaster Tools → Export CSV
-3.  Paste both into a spreadsheet
-4.  Manually compare keywords across engines
-5.  Switch between accounts for different clients
-6.  Repeat weekly
+### ❌ The Old, Broken Way
+*   **Data Silos**: Manually checking Google, then Bing, then GA4.
+*   **Manual Correlation**: Exporting 3 different CSVs and using VLOOKUPs to see if your #1 ranking page actually converts.
+*   **Switching Fatigue**: Logging in and out to manage multiple clients or properties.
+*   **AI Context Limits**: Uploading giant spreadsheets that hit context limits and cause model hallucinations.
 
-### ✅ The New Way
-**Just ask:**
-> "Find low-hanging fruit keywords (positions 11-20) with high impressions that I should optimize."
+### ✅ The Search Console MCP Way
+*   **Platform Synergy**: **GSC + Bing + GA4** in a single context window. Stop exporting, start analyzing.
+*   **Deterministic Intelligence**: The server performs the complex SEO math (cannibalization, Z-score anomalies, striking distance) so your AI agent gets curated insights, not raw data piles.
+*   **Cross-Platform ROI**: Use the **Opportunity Matrix** to prioritize keywords that have high search visibility (GSC) but poor on-site engagement (GA4).
+*   **Zero-Config Multi-Account**: Connect 20+ accounts. The server automatically resolves the correct credentials for every site URL.
 
-> "Compare my Google and Bing performance — where am I leaving Bing traffic on the table?"
-
-> "Run a health check across all my sites and give me 3 actions for next week."
-
-**One server. Both engines. Multiple accounts. Zero spreadsheets.**
+**One Server. Three Platforms. Infinite Accounts. Actionable Intelligence.**
 
 ---
 ## 🎯 Magic Prompts
@@ -62,6 +58,9 @@ Copy and paste these into your MCP client (Claude Desktop, etc.) to see the inte
 #### ⚠️ Google Dependency Check
 > "Am I too dependent on Google? Check my click share across both engines and flag any keywords where over 85% of traffic comes from Google."
 
+#### 💰 The ROI Prioritizer (GSC + GA4)
+> "Run an `opportunity_matrix` for my top 20 pages. Which high-visibility pages have the lowest engagement or conversion rates? These are my conversion optimization priorities."
+
 ---
 
 ## 🔐 Authentication (Desktop Flow)
@@ -124,6 +123,18 @@ To access Bing data, you simply need an API Key.
 
 ---
 
+## 📊 Google Analytics 4 (GA4)
+
+Connect your GA4 properties to correlate ranking data with user behavior.
+
+### Setup:
+1.  **Run Setup**: `npx search-console-mcp setup --engine=ga4`
+2.  **Auth Method**: Choose **Service Account** (JSON Key). This is the recommended method for server-side integrations.
+    *   **Service Account**: You must add the service account email as a user in **GA4 Admin > Property Settings > Property Access Management**.
+3.  **Property Selection**: The tool will automatically fetch all available GA4 properties for your account and let you select one from a list. You can also enter a Property ID manually if needed.
+
+---
+
 ## 👥 Multi-Account Management
 
 Manage multiple Google and Bing accounts from the CLI:
@@ -217,6 +228,29 @@ These are low-level tools designed to be used by other AI agents to build comple
 | `bing_analytics_time_series` | Advanced time series analysis for Bing. |
 | `bing_sitemaps_list` / `bing_sitemaps_submit` | Manage sitemaps in Bing. |
 
+### Google Analytics 4 (GA4)
+| Tool | Description |
+|------|-------------|
+| `analytics_page_performance` | Detailed page metrics (sessions, engagement, views). |
+| `analytics_traffic_sources` | Analyze sessions by Channel, Source, and Medium. |
+| `analytics_organic_landing_pages` | Focused metrics for organic traffic landing pages. |
+| `analytics_content_performance` | Analyze content performance by Content Group in GA4. |
+| `analytics_conversion_funnel` | Top converting pages and events. |
+| `analytics_user_behavior` | Device, Country, and Engagement breakdown. |
+| `analytics_audience_segments` | New vs Returning, Age, and OS analysis. |
+| `analytics_realtime` | Live active user data by page and location. |
+| `analytics_ecommerce` | Product and revenue performance. |
+| `analytics_pagespeed_correlation` | Correlate GA4 metrics with PageSpeed scores. |
+
+### Cross-Platform Intelligence
+| Tool | Description |
+|------|-------------|
+| `opportunity_matrix` | **[Flagship]** Prioritize SEO tasks by combining signals from GSC, GA4, and Bing. |
+| `page_analysis` | Joint analysis of ranking (GSC) vs behavior (GA4) for pages. |
+| `traffic_health_check` | Diagnose tracking gaps by comparing GSC clicks to GA4 organic sessions. |
+| `brand_analysis` | Brand vs Non-Brand split across GSC, Bing, and GA4. |
+| `compare_engines` | Compare keyword performance between Google and Bing. |
+
 
 
 ## License

package/dist/accounts.js

@@ -32,7 +32,8 @@ export async function main(args) {
                     resolution: {
                         command: "search-console-mcp setup",
                         google: "search-console-mcp setup --engine=google",
-                        bing: "search-console-mcp setup --engine=bing"
+                        bing: "search-console-mcp setup --engine=bing",
+                        ga4: "search-console-mcp setup --engine=ga4"
                     },
                     setup_instructions: {
                         google: [
@@ -44,6 +45,11 @@ export async function main(args) {
                             "Run: search-console-mcp setup --engine=bing",
                             "Get your API key from https://www.bing.com/webmasters/settings/api",
                             "Enter the API key when prompted"
+                        ],
+                        ga4: [
+                            "Run: search-console-mcp setup --engine=ga4",
+                            "Choose Service Account (OAuth coming soon)",
+                            "Add the service account email to your GA4 property"
                         ]
                     }
                 }, null, 2));
@@ -52,7 +58,7 @@ export async function main(args) {
             const siteRows = [];
             for (const a of accounts) {
                 const alias = a.alias || '[Unnamed]';
-                const engine = a.engine === 'google' ? 'Google' : 'Bing';
+                const engine = a.engine === 'google' ? 'Google' : a.engine === 'bing' ? 'Bing' : 'GA4';
                 if (!a.websites || a.websites.length === 0) {
                     siteRows.push({
                         site: '[All Sites Authorized]',

package/dist/bing/tools/inspection.js

@@ -1,4 +1,5 @@
 import { getBingClient } from '../client.js';
+import { limitConcurrency } from '../../common/concurrency.js';
 /**
  * Get detailed indexing and crawl information for a URL.
  */
@@ -6,3 +7,21 @@ export async function getUrlInfo(siteUrl, url) {
     const client = await getBingClient(siteUrl);
     return client.getUrlInfo(siteUrl, url);
 }
+/**
+ * Inspect multiple URLs for a site in batch (Bing).
+ *
+ * @param siteUrl - The URL of the site as defined in Bing Webmaster Tools.
+ * @param inspectionUrls - The list of URLs to inspect.
+ * @returns An array of results, each containing the URL and its inspection result or error.
+ */
+export async function inspectBatch(siteUrl, inspectionUrls) {
+    return limitConcurrency(inspectionUrls, 5, async (url) => {
+        try {
+            const result = await getUrlInfo(siteUrl, url);
+            return { url, result };
+        }
+        catch (error) {
+            return { url, error: error.message };
+        }
+    });
+}

package/dist/bing/tools/seo-insights.js

@@ -3,8 +3,8 @@ import { getQueryStats, getQueryPageStats } from './analytics.js';
  * Find "low-hanging fruit" keywords in Bing.
  */
 export async function findLowHangingFruit(siteUrl, options = {}) {
-    const { minImpressions = 100, limit = 50 } = options;
-    const rows = await getQueryStats(siteUrl);
+    const { minImpressions = 100, limit = 50, queryStats } = options;
+    const rows = queryStats || await getQueryStats(siteUrl);
     // Filter for low-hanging fruit: position 5-20, high impressions
     const candidates = rows
         .filter(row => {
@@ -36,8 +36,8 @@ export async function findLowHangingFruit(siteUrl, options = {}) {
  * Find keywords ranking just off page 1 in Bing (positions 8-15).
  */
 export async function findStrikingDistance(siteUrl, options = {}) {
-    const { limit = 50 } = options;
-    const rows = await getQueryStats(siteUrl);
+    const { limit = 50, queryStats } = options;
+    const rows = queryStats || await getQueryStats(siteUrl);
     return rows
         .filter(r => r.AvgPosition >= 8 && r.AvgPosition <= 15)
         .sort((a, b) => b.Impressions - a.Impressions)
@@ -47,8 +47,8 @@ export async function findStrikingDistance(siteUrl, options = {}) {
  * Identify queries where the site ranks well but has low CTR in Bing.
  */
 export async function findLowCTROpportunities(siteUrl, options = {}) {
-    const { minImpressions = 500, limit = 50 } = options;
-    const rows = await getQueryStats(siteUrl);
+    const { minImpressions = 500, limit = 50, queryStats } = options;
+    const rows = queryStats || await getQueryStats(siteUrl);
     // Approximate benchmarks for CTR by position (simplified)
     const benchmarks = {
         1: 0.30, 2: 0.15, 3: 0.10, 4: 0.06, 5: 0.04,
@@ -119,10 +119,11 @@ export async function detectCannibalization(siteUrl, options = {}) {
  */
 export async function generateRecommendations(siteUrl) {
     const insights = [];
+    const queryStatsPromise = getQueryStats(siteUrl);
     const [lowHangingFruit, strikingDistance, lowCTR, cannibalization] = await Promise.all([
-        findLowHangingFruit(siteUrl, { limit: 10 }),
-        findStrikingDistance(siteUrl, { limit: 10 }),
-        findLowCTROpportunities(siteUrl, { limit: 10 }),
+        queryStatsPromise.then(stats => findLowHangingFruit(siteUrl, { limit: 10, queryStats: stats })),
+        queryStatsPromise.then(stats => findStrikingDistance(siteUrl, { limit: 10, queryStats: stats })),
+        queryStatsPromise.then(stats => findLowCTROpportunities(siteUrl, { limit: 10, queryStats: stats })),
         detectCannibalization(siteUrl, { limit: 10 })
     ]);
     if (lowHangingFruit.length > 0) {

package/dist/common/concurrency.js

@@ -0,0 +1,22 @@
+/**
+ * Limit the number of concurrent executions of an async mapping function.
+ *
+ * @param items - The array of items to process.
+ * @param limit - The maximum number of concurrent executions.
+ * @param fn - The async function to execute for each item.
+ * @returns A promise that resolves to an array of results.
+ */
+export async function limitConcurrency(items, limit, fn) {
+    const results = [];
+    const executing = new Set();
+    for (const item of items) {
+        const p = fn(item);
+        results.push(p);
+        const e = p.then(() => { executing.delete(e); }, () => { executing.delete(e); });
+        executing.add(e);
+        if (executing.size >= limit) {
+            await Promise.race(executing);
+        }
+    }
+    return Promise.all(results);
+}

package/dist/common/platforms.js

@@ -0,0 +1,19 @@
+import { existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+/**
+ * Detect which search platforms are currently enabled based on environment
+ * variables and credential files. This is evaluated at call time so it
+ * always reflects the current state.
+ */
+export function getEnabledPlatforms() {
+    const hasServiceAccount = !!process.env.GOOGLE_APPLICATION_CREDENTIALS || (!!process.env.GOOGLE_CLIENT_EMAIL && !!process.env.GOOGLE_PRIVATE_KEY);
+    const tokenPath = join(homedir(), '.search-console-mcp-tokens.enc');
+    const configPath = join(homedir(), '.search-console-mcp-config.enc');
+    const hasOAuthTokens = existsSync(tokenPath) || existsSync(configPath);
+    const isGoogleEnabled = hasServiceAccount || hasOAuthTokens;
+    const isBingEnabled = !!process.env.BING_API_KEY;
+    // GA4 needs the config file (for service accounts or oauth)
+    const isGA4Enabled = existsSync(configPath);
+    return { isGoogleEnabled, isBingEnabled, isGA4Enabled };
+}

package/dist/common/tools/compare-engines/ga4-adapters.js

@@ -0,0 +1,12 @@
+export function normalizeGA4Row(row) {
+    return {
+        sessions: Number(row.sessions || 0),
+        bounceRate: Number(row.bounceRate || 0),
+        engagementRate: Number(row.engagementRate || 0),
+        averageSessionDuration: Number(row.averageSessionDuration || 0),
+        conversions: Number(row.conversions || 0),
+        activeUsers: row.activeUsers !== undefined ? Number(row.activeUsers) : undefined,
+        eventCount: row.eventCount !== undefined ? Number(row.eventCount) : undefined,
+        revenue: row.totalRevenue !== undefined ? Number(row.totalRevenue) : undefined
+    };
+}

package/dist/common/tools/compare-engines/ga4-gsc-bing-comparator.js

@@ -0,0 +1,207 @@
+import { queryAnalytics as queryGSC } from '../../../google/tools/analytics.js';
+import { getBingClient } from '../../../bing/client.js';
+import { getOrganicLandingPages } from '../../../ga4/tools/analytics.js';
+import { normalizeGA4Row } from './ga4-adapters.js';
+import { extractUrlPath } from './utils.js';
+export async function getOpportunityMatrix(gscSiteUrl, bingSiteUrl, ga4PropertyId, startDate, endDate, limit = 20, ga4AccountId, gscAccountId, bingAccountId) {
+    const gscPromise = queryGSC({
+        siteUrl: gscSiteUrl,
+        accountId: gscAccountId,
+        startDate,
+        endDate,
+        dimensions: ['page'],
+        limit: limit * 2
+    });
+    const bingPromise = (async () => {
+        try {
+            const client = await getBingClient(bingSiteUrl, bingAccountId);
+            return await client.getPageStats(bingSiteUrl);
+        }
+        catch (e) {
+            console.error("Bing fetch failed:", e);
+            return [];
+        }
+    })();
+    const ga4Promise = getOrganicLandingPages(ga4PropertyId, startDate, endDate, limit * 2, ga4AccountId);
+    const [gscResult, bingResult, ga4Result] = await Promise.allSettled([gscPromise, bingPromise, ga4Promise]);
+    const gscRows = gscResult.status === 'fulfilled' ? gscResult.value : [];
+    const bingRows = bingResult.status === 'fulfilled' ? bingResult.value : [];
+    const ga4Rows = ga4Result.status === 'fulfilled' ? ga4Result.value : [];
+    // Normalize and Join
+    const map = new Map();
+    // Process GSC
+    for (const row of gscRows) {
+        const url = row.keys?.[0] || '';
+        const path = extractUrlPath(url);
+        map.set(path, {
+            url,
+            gsc: {
+                clicks: row.clicks || 0,
+                impressions: row.impressions || 0,
+                ctr: row.ctr || 0,
+                position: row.position || 0
+            },
+            priorityScore: 0,
+            action: '',
+            category: 'Content Fix'
+        });
+    }
+    // Process Bing
+    for (const row of bingRows) {
+        // Bing API returns the URL in the 'Query' field for GetPageStats results
+        const path = extractUrlPath(row.Query);
+        const existing = map.get(path);
+        const bingStats = {
+            clicks: row.Clicks,
+            impressions: row.Impressions,
+            ctr: row.CTR,
+            position: row.AvgPosition
+        };
+        if (existing) {
+            existing.bing = bingStats;
+        }
+        else {
+            map.set(path, {
+                url: row.Query,
+                gsc: { clicks: 0, impressions: 0, ctr: 0, position: 0 },
+                bing: bingStats,
+                priorityScore: 0,
+                action: '',
+                category: 'Bing Opportunity'
+            });
+        }
+    }
+    // Process GA4
+    for (const row of ga4Rows) {
+        const path = row.landingPagePlusQueryString || row.pagePath;
+        if (!path)
+            continue;
+        // Try precise match then path match
+        const existing = map.get(path) || map.get(path.split('?')[0]);
+        const ga4Stats = normalizeGA4Row(row);
+        if (existing) {
+            existing.ga4 = ga4Stats;
+        }
+    }
+    // Classify and Prioritize
+    const results = Array.from(map.values());
+    for (const row of results) {
+        const gscPos = row.gsc.position;
+        const bingPos = row.bing?.position || 100;
+        const engagement = row.ga4?.engagementRate || 0;
+        const bounce = row.ga4?.bounceRate || 0;
+        const impressions = Math.max(row.gsc.impressions, row.bing?.impressions || 0);
+        let score = 0;
+        let category = 'Content Fix';
+        let action = 'Optimize content';
+        if (gscPos > 10 && gscPos < 30 && engagement > 0.5) {
+            category = 'Quick Win';
+            action = 'Improve title/meta description to boost CTR';
+            score = 80 + (engagement * 20);
+        }
+        else if (impressions > 1000 && (engagement < 0.3 || bounce > 0.7)) {
+            category = 'Content Fix';
+            action = 'Improve page content to reduce bounce rate';
+            score = 70 + (Math.log10(impressions) * 5);
+        }
+        else if (bingPos < 10 && gscPos > 20) {
+            category = 'Bing Opportunity';
+            action = 'Analyze Bing success factors and apply to Google';
+            score = 60 + (100 - bingPos);
+        }
+        else {
+            score = (row.gsc.clicks + (row.bing?.clicks || 0)) / 10;
+        }
+        row.category = category;
+        row.action = action;
+        row.priorityScore = parseFloat(score.toFixed(1));
+    }
+    return results.sort((a, b) => b.priorityScore - a.priorityScore).slice(0, limit);
+}
+export async function getBrandAnalysis(brandTerms, gscSiteUrl, bingSiteUrl, ga4PropertyId, startDate, endDate, ga4AccountId, gscAccountId, bingAccountId) {
+    const gscPromise = queryGSC({
+        siteUrl: gscSiteUrl,
+        accountId: gscAccountId,
+        startDate,
+        endDate,
+        dimensions: ['query'],
+        limit: 5000
+    });
+    const bingPromise = (async () => {
+        try {
+            const client = await getBingClient(bingSiteUrl, bingAccountId);
+            return await client.getQueryStats(bingSiteUrl);
+        }
+        catch (e) {
+            console.error("Bing fetch failed:", e);
+            return [];
+        }
+    })();
+    // GA4 doesn't expose query-level brand data. We fetch total organic sessions
+    // as a contextual reference alongside GSC/Bing brand splits.
+    const ga4Promise = getOrganicLandingPages(ga4PropertyId, startDate, endDate, 5000, ga4AccountId);
+    const [gscResult, bingResult, ga4Result] = await Promise.allSettled([gscPromise, bingPromise, ga4Promise]);
+    const gscRows = gscResult.status === 'fulfilled' ? gscResult.value : [];
+    const bingRows = bingResult.status === 'fulfilled' ? bingResult.value : [];
+    const ga4Rows = ga4Result.status === 'fulfilled' ? ga4Result.value : [];
+    const isBrand = (query) => {
+        const q = query.toLowerCase();
+        return brandTerms.some(term => q.includes(term.toLowerCase()));
+    };
+    // GSC Analysis
+    const gscBrand = { clicks: 0, impressions: 0 };
+    const gscNonBrand = { clicks: 0, impressions: 0 };
+    for (const row of gscRows) {
+        const query = row.keys?.[0] || '';
+        if (isBrand(query)) {
+            gscBrand.clicks += row.clicks || 0;
+            gscBrand.impressions += row.impressions || 0;
+        }
+        else {
+            gscNonBrand.clicks += row.clicks || 0;
+            gscNonBrand.impressions += row.impressions || 0;
+        }
+    }
+    // Bing Analysis
+    const bingBrand = { clicks: 0, impressions: 0 };
+    const bingNonBrand = { clicks: 0, impressions: 0 };
+    for (const row of bingRows) {
+        if (isBrand(row.Query)) {
+            bingBrand.clicks += row.Clicks;
+            bingBrand.impressions += row.Impressions;
+        }
+        else {
+            bingNonBrand.clicks += row.Clicks;
+            bingNonBrand.impressions += row.Impressions;
+        }
+    }
+    // GA4: Compute total organic sessions as context.
+    // GA4 does not provide keyword-level brand/non-brand splits.
+    const totalOrganicSessions = ga4Rows.reduce((sum, row) => sum + Number(row.sessions || 0), 0);
+    // Estimate brand session share by applying GSC brand click ratio to GA4 sessions
+    const gscTotalClicks = gscBrand.clicks + gscNonBrand.clicks;
+    const gscBrandRatio = gscTotalClicks > 0 ? gscBrand.clicks / gscTotalClicks : 0;
+    const estimatedBrandSessions = Math.round(totalOrganicSessions * gscBrandRatio);
+    const estimatedNonBrandSessions = totalOrganicSessions - estimatedBrandSessions;
+    const rows = [
+        {
+            platform: 'Google',
+            brandMetrics: gscBrand,
+            nonBrandMetrics: gscNonBrand,
+            brandShare: parseFloat((gscBrand.clicks / ((gscBrand.clicks + gscNonBrand.clicks) || 1)).toFixed(2))
+        },
+        {
+            platform: 'Bing',
+            brandMetrics: bingBrand,
+            nonBrandMetrics: bingNonBrand,
+            brandShare: parseFloat((bingBrand.clicks / ((bingBrand.clicks + bingNonBrand.clicks) || 1)).toFixed(2))
+        },
+        {
+            platform: 'GA4',
+            brandMetrics: { sessions: estimatedBrandSessions },
+            nonBrandMetrics: { sessions: estimatedNonBrandSessions },
+            brandShare: parseFloat(gscBrandRatio.toFixed(2))
+        }
+    ];
+    return rows;
+}

package/dist/common/tools/compare-engines/ga4-gsc-comparator.js

@@ -0,0 +1,110 @@
+import { queryAnalytics as queryGSC } from '../../../google/tools/analytics.js';
+import { getOrganicLandingPages, getTrafficSources } from '../../../ga4/tools/analytics.js';
+import { normalizeGA4Row } from './ga4-adapters.js';
+import { extractUrlPath, extractBasePropertyName } from './utils.js';
+export async function analyzePagesCrossPlatform(gscSiteUrl, ga4PropertyId, startDate, endDate, limit = 50, ga4AccountId, gscAccountId) {
+    // Parallel fetch
+    const [gscResult, ga4Result] = await Promise.allSettled([
+        queryGSC({
+            siteUrl: gscSiteUrl,
+            accountId: gscAccountId,
+            startDate,
+            endDate,
+            dimensions: ['page'],
+            limit: limit * 2 // Fetch more to ensure overlap
+        }),
+        getOrganicLandingPages(ga4PropertyId, startDate, endDate, limit * 2, ga4AccountId)
+    ]);
+    const gscRows = gscResult.status === 'fulfilled' ? gscResult.value : [];
+    const ga4Rows = ga4Result.status === 'fulfilled' ? ga4Result.value : [];
+    // Map GA4 rows by path
+    const ga4Map = new Map();
+    for (const row of ga4Rows) {
+        // row.landingPagePlusQueryString is path
+        const path = row.landingPagePlusQueryString || row.pagePath;
+        if (path) {
+            ga4Map.set(path, row);
+            // Also normalized path (without query string)
+            const basePath = path.split('?')[0];
+            if (basePath !== path) {
+                ga4Map.set(basePath, row);
+            }
+        }
+    }
+    const results = [];
+    for (const gscRow of gscRows) {
+        const url = gscRow.keys?.[0] || '';
+        const path = extractUrlPath(url);
+        // Try exact path match first, then path without query string
+        let ga4Row = ga4Map.get(path);
+        if (!ga4Row) {
+            ga4Row = ga4Map.get(extractBasePropertyName(url));
+        }
+        if (ga4Row || (gscRow.clicks || 0) > 0) { // Only include if relevant
+            const ga4Stats = ga4Row ? normalizeGA4Row(ga4Row) : undefined;
+            const gscStats = {
+                clicks: gscRow.clicks || 0,
+                impressions: gscRow.impressions || 0,
+                ctr: gscRow.ctr || 0,
+                position: gscRow.position || 0
+            };
+            // Derived metrics
+            let clickToSessionRatio = 0;
+            if (gscStats.clicks > 0 && ga4Stats) {
+                clickToSessionRatio = ga4Stats.sessions / gscStats.clicks;
+            }
+            // Opportunity Score
+            const visibilityScore = Math.log10(gscStats.impressions + 1);
+            const engagementScore = ga4Stats ? ga4Stats.engagementRate : 0;
+            const conversionScore = ga4Stats ? Math.log10(ga4Stats.conversions + 1) : 0;
+            const opportunityScore = (visibilityScore * 10) + (engagementScore * 100) + (conversionScore * 20);
+            results.push({
+                url,
+                gsc: gscStats,
+                ga4: ga4Stats,
+                clickToSessionRatio: parseFloat(clickToSessionRatio.toFixed(2)),
+                opportunityScore: parseFloat(opportunityScore.toFixed(2))
+            });
+        }
+    }
+    // Sort by opportunity score
+    return results.sort((a, b) => (b.opportunityScore || 0) - (a.opportunityScore || 0));
+}
+export async function checkTrafficHealth(gscSiteUrl, ga4PropertyId, startDate, endDate, ga4AccountId, gscAccountId) {
+    const [gscRows, ga4Rows] = await Promise.all([
+        queryGSC({
+            siteUrl: gscSiteUrl,
+            accountId: gscAccountId,
+            startDate,
+            endDate,
+            limit: 1 // Total
+        }),
+        getTrafficSources(ga4PropertyId, startDate, endDate, 'Organic Search', 100, ga4AccountId) // Increase limit to capture variants
+    ]);
+    const gscClicks = gscRows.reduce((sum, row) => sum + (row.clicks || 0), 0);
+    const ga4OrganicSessions = ga4Rows.reduce((sum, row) => sum + Number(row.sessions || 0), 0);
+    const ratio = gscClicks > 0 ? ga4OrganicSessions / gscClicks : 0;
+    let classification = 'Healthy';
+    let recommendation = "Traffic tracking looks normal.";
+    if (gscClicks > 0) {
+        if (ratio < 0.6) {
+            classification = 'Tracking Gap';
+            recommendation = "GA4 is capturing significantly fewer sessions than GSC clicks. Check for missing tracking codes, cookie consent issues, or aggressive bot filtering.";
+        }
+        else if (ratio > 1.3) {
+            classification = 'Filter Issue';
+            recommendation = "GA4 reports more organic sessions than GSC clicks. This might indicate direct traffic being misclassified as organic, or GSC property not covering all site variants (http/https/www).";
+        }
+    }
+    else {
+        recommendation = "No GSC clicks recorded.";
+    }
+    return [{
+            date: `${startDate} to ${endDate}`,
+            gscClicks,
+            ga4OrganicSessions,
+            ratio: parseFloat(ratio.toFixed(2)),
+            classification,
+            recommendation
+        }];
+}

package/dist/common/tools/compare-engines/utils.js

@@ -0,0 +1,33 @@
+/**
+ * Shared utilities for cross-platform comparison tools.
+ */
+/**
+ * Normalizes a URL by extracting the pathname and search string.
+ * This ensures consistency when joining data from different platforms
+ * that might report URLs differently (e.g. with or without domain).
+ *
+ * @param url The full URL or path to normalize
+ * @returns The normalized path (pathname + search)
+ */
+export function extractUrlPath(url) {
+    if (!url)
+        return '';
+    try {
+        const urlObj = new URL(url);
+        return urlObj.pathname + urlObj.search;
+    }
+    catch (e) {
+        // Fallback for cases where input is already a path or invalid URL
+        return url;
+    }
+}
+/**
+ * Extracts the base pathname without the query string.
+ *
+ * @param url The full URL or path
+ * @returns The pathname only
+ */
+export function extractBasePropertyName(url) {
+    const path = extractUrlPath(url);
+    return path.split('?')[0];
+}