search-console-mcp 1.9.2 → 1.9.3

package/README.md

@@ -87,7 +87,7 @@ We take your data security seriously. This tool is designed to be **local-first*
 First, use the interactive wizard to validate your credentials and get your configuration:
 
 ```bash
-npx search-console-mcp-setup
+npx -y search-console-mcp setup
 ```
 
 The wizard will guide you through:
@@ -155,6 +155,7 @@ These are low-level tools designed to be used by other AI agents to build comple
 |------|-------------|
 | `sites_list` | List all verified sites. |
 | `sites_add` / `sites_delete` | Manage properties. |
+| `sites_health_check` | **[NEW]** Run a health check on one or all sites. Checks WoW performance, sitemaps, and anomalies. |
 | `sitemaps_list` / `sitemaps_submit` | Manage sitemaps. |
 
 ### Inspection & Validation

package/dist/docs/algorithm-updates.js

@@ -1,18 +1,59 @@
 export const algorithmUpdatesDocs = `
 # Google Algorithm Updates Reference
 
-The \`analytics_drop_attribution\` tool correlates traffic drops with major known Google Algorithm Updates. The following updates are currently supported:
+The \`analytics_drop_attribution\` tool correlates traffic drops with major known Google Algorithm Updates. The following updates are currently tracked (source: [Search Engine Journal](https://www.searchenginejournal.com/google-algorithm-history/)):
+
+## 2026
+
+| Date | Update Name | Impact Area |
+|------|-------------|-------------|
+| 2026-02-05 | February 2026 Discover Core Update | Discover Feed |
+
+## 2025
+
+| Date | Update Name | Impact Area |
+|------|-------------|-------------|
+| 2025-12-11 | December 2025 Core Update | General Ranking |
+| 2025-08-26 | August 2025 Spam Update | Spam / Content Quality |
+| 2025-06-30 | June 2025 Core Update | General Ranking |
+| 2025-03-13 | March 2025 Core Update | General Ranking |
+
+## 2024
 
 | Date | Update Name | Impact Area |
 |------|-------------|-------------|
-| 2025-01-15 | January 2025 Core Update | General Ranking |
+| 2024-12-19 | December 2024 Spam Update | Spam / Content Quality |
+| 2024-12-12 | December 2024 Core Update | General Ranking |
 | 2024-11-11 | November 2024 Core Update | General Ranking |
-| 2024-08-15 | August 2024 Core Update | General Ranking |
+| 2024-08-15 | August 2024 Core Update | General Ranking / Quality |
 | 2024-06-20 | June 2024 Spam Update | Content Quality / Spam |
+| 2024-05-14 | AI Overviews Rollout | Search Features / SERP |
+| 2024-05-06 | Site Reputation Abuse (Manual Actions) | Parasite SEO / Spam |
 | 2024-03-05 | March 2024 Core Update | General Ranking / Quality |
+
+## 2023
+
+| Date | Update Name | Impact Area |
+|------|-------------|-------------|
+| 2023-11-08 | November 2023 Reviews Update | Review Content |
 | 2023-11-02 | November 2023 Core Update | General Ranking |
 | 2023-10-05 | October 2023 Core Update | General Ranking |
+| 2023-10-04 | October 2023 Spam Update | Spam / Multi-language |
 | 2023-09-14 | September 2023 Helpful Content Update | Quality / Value |
+| 2023-08-22 | August 2023 Core Update | General Ranking |
+| 2023-04-12 | April 2023 Reviews Update | Review Content |
+| 2023-03-15 | March 2023 Core Update | General Ranking |
+| 2023-02-21 | February 2023 Product Reviews Update | Product Reviews |
+
+## 2022
+
+| Date | Update Name | Impact Area |
+|------|-------------|-------------|
+| 2022-12-14 | December 2022 Link Spam Update | Link Spam / SpamBrain |
+| 2022-12-05 | December 2022 Helpful Content Update | Quality / Value |
+| 2022-10-19 | October 2022 Spam Update | Spam |
+| 2022-09-20 | September 2022 Product Review Update | Product Reviews |
+| 2022-09-12 | September 2022 Core Update | General Ranking |
 
 ## How Attribution Works
 When a traffic drop is detected, the system checks if it occurred within **+/- 2 days** of any of these dates. If it matches, the update is flagged as a potential primary cause of the drop.

package/dist/index.js

@@ -11,6 +11,7 @@ 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 * as sitesHealth from "./tools/sites-health.js";
 import { formatError } from "./errors.js";
 const server = new McpServer({
     name: "search-console-mcp",
@@ -61,6 +62,19 @@ server.tool("sites_get", "Get information about a specific site", { siteUrl: z.s
         return formatError(error);
     }
 });
+server.tool("sites_health_check", "Run a health check on one or all verified sites. Checks week-over-week performance, sitemap status, and traffic anomalies. Returns a structured report with an overall status (healthy/warning/critical) per site.", {
+    siteUrl: z.string().optional().describe("Optional. The URL of a specific site to check. If omitted, checks all verified sites.")
+}, async ({ siteUrl }) => {
+    try {
+        const result = await sitesHealth.healthCheck(siteUrl);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+    }
+    catch (error) {
+        return formatError(error);
+    }
+});
 // Sitemaps Tools
 server.tool("sitemaps_list", "List sitemaps for a site", { siteUrl: z.string().describe("The URL of the site") }, async ({ siteUrl }) => {
     try {
@@ -740,14 +754,48 @@ Provide a summary with actionable recommendations.`
             }
         }]
 }));
+server.prompt("site-health-check", {
+    siteUrl: z.string().optional().describe("Optional. The URL of a specific site to check. If omitted, checks all verified sites.")
+}, ({ siteUrl }) => ({
+    messages: [{
+            role: "user",
+            content: {
+                type: "text",
+                text: `Run a comprehensive health check${siteUrl ? ` for ${siteUrl}` : ' across all my verified sites'}.
+
+Use the 'sites_health_check' tool${siteUrl ? ` with siteUrl '${siteUrl}'` : ' without a siteUrl to check all sites'}.
+
+Then for each site in the results:
+
+1. **Summarize the status** (healthy / warning / critical) with a clear visual indicator.
+2. **Performance:** Report the week-over-week changes in clicks, impressions, CTR, and position.
+3. **Sitemaps:** Note any missing sitemaps, errors, or warnings.
+4. **Anomalies:** Highlight any traffic anomaly drops detected.
+
+If any site has a 'critical' or 'warning' status:
+- List the specific issues found.
+- For critical traffic drops, use 'analytics_drop_attribution' to check if a Google algorithm update is the likely cause.
+- For sitemap errors, use 'sitemaps_list' to get detailed error information.
+- Provide 3 prioritized action items for each affected site.
+
+End with an overall portfolio summary and the single most important action to take right now.`
+            }
+        }]
+}));
 async function main() {
+    // Allow `npx search-console-mcp setup` to launch the setup wizard
+    if (process.argv[2] === 'setup') {
+        const { main: setupMain } = await import('./setup.js');
+        await setupMain();
+        return;
+    }
     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('   npx -y 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');

package/dist/setup.js

@@ -38,7 +38,10 @@ function printInfo(text) {
 function validateKeyFile(path) {
     try {
         const sanitizedPath = path.trim().replace(/\0/g, '');
-        const fullPath = resolve(sanitizedPath.replace('~', homedir()));
+        const expandedPath = sanitizedPath.startsWith('~')
+            ? sanitizedPath.replace('~', homedir())
+            : sanitizedPath;
+        const fullPath = resolve(expandedPath);
         if (!existsSync(fullPath)) {
             printError(`File not found: ${fullPath}`);
             return null;
@@ -145,7 +148,7 @@ export function resolveRepo(dirname) {
     }
     return repo;
 }
-async function main() {
+export async function main() {
     printHeader();
     console.log('This wizard will help you set up Search Console MCP.');
     console.log('You will need a Google Cloud service account with Search Console access.\n');
@@ -215,16 +218,17 @@ async function main() {
     }
     // Step 5: Support the project
     printStep(5, 'Support this project');
-    const answer = await ask('Would you like to star the repo on GitHub? (y/n): ');
-    if (answer.toLowerCase().startsWith('y')) {
+    const answer = await ask('Would you like to star the repo on GitHub? (Y/n): ');
+    if (answer === '' || answer.toLowerCase().startsWith('y')) {
         try {
             const repo = resolveRepo(__dirname);
-            if (repo && repo.includes('/')) {
+            // Harden against command injection: ensure repo is in 'owner/repo' format
+            if (repo && /^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(repo)) {
                 execSync(`gh api -X PUT /user/starred/${repo}`, { stdio: 'ignore' });
                 printSuccess('Thanks for your support! ⭐');
             }
             else {
-                throw new Error('Could not resolve repo');
+                throw new Error('Invalid repository format');
             }
         }
         catch (error) {

package/dist/tools/advanced-analytics.js

@@ -3,14 +3,38 @@ import { queryAnalytics, detectAnomalies } from './analytics.js';
  * Historical Google Algorithm Update dates (recent notable ones)
  */
 const ALGORITHM_UPDATES = [
+    // 2022
+    { date: '2022-09-12', name: 'September 2022 Core Update' },
+    { date: '2022-09-20', name: 'September 2022 Product Review Update' },
+    { date: '2022-10-19', name: 'October 2022 Spam Update' },
+    { date: '2022-12-05', name: 'December 2022 Helpful Content Update' },
+    { date: '2022-12-14', name: 'December 2022 Link Spam Update' },
+    // 2023
+    { date: '2023-02-21', name: 'February 2023 Product Reviews Update' },
+    { date: '2023-03-15', name: 'March 2023 Core Update' },
+    { date: '2023-04-12', name: 'April 2023 Reviews Update' },
+    { date: '2023-08-22', name: 'August 2023 Core Update' },
     { date: '2023-09-14', name: 'September 2023 Helpful Content Update' },
+    { date: '2023-10-04', name: 'October 2023 Spam Update' },
     { date: '2023-10-05', name: 'October 2023 Core Update' },
     { date: '2023-11-02', name: 'November 2023 Core Update' },
+    { date: '2023-11-08', name: 'November 2023 Reviews Update' },
+    // 2024
     { date: '2024-03-05', name: 'March 2024 Core Update' },
+    { date: '2024-05-06', name: 'Site Reputation Abuse (Manual Actions)' },
+    { date: '2024-05-14', name: 'AI Overviews Rollout' },
     { 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' }
+    { date: '2024-12-12', name: 'December 2024 Core Update' },
+    { date: '2024-12-19', name: 'December 2024 Spam Update' },
+    // 2025
+    { date: '2025-03-13', name: 'March 2025 Core Update' },
+    { date: '2025-06-30', name: 'June 2025 Core Update' },
+    { date: '2025-08-26', name: 'August 2025 Spam Update' },
+    { date: '2025-12-11', name: 'December 2025 Core Update' },
+    // 2026
+    { date: '2026-02-05', name: 'February 2026 Discover Core Update' },
 ];
 /**
  * Identify the cause of a significant traffic drop by analyzing device distribution and algorithm updates.

package/dist/tools/seo-insights.js

@@ -1,4 +1,5 @@
 import { queryAnalytics } from './analytics.js';
+import { safeTestBatch } from '../utils/regex.js';
 /**
  * Find "low-hanging fruit" keywords: high impressions, low CTR, and positions in striking distance.
  *
@@ -284,18 +285,18 @@ export async function analyzeBrandVsNonBrand(siteUrl, brandRegexString, options
         dimensions: ['query'],
         limit: 10000
     });
-    const brandRegex = new RegExp(brandRegexString, 'i');
+    const queries = rows.map(row => row.keys?.[0] ?? '');
+    const isBrandResults = safeTestBatch(brandRegexString, 'i', queries);
     const brandStats = { clicks: 0, impressions: 0, ctr: 0, position: 0, queryCount: 0, weightedPos: 0 };
     const nonBrandStats = { clicks: 0, impressions: 0, ctr: 0, position: 0, queryCount: 0, weightedPos: 0 };
-    for (const row of rows) {
-        const query = row.keys?.[0] ?? '';
-        const isBrand = brandRegex.test(query);
+    rows.forEach((row, index) => {
+        const isBrand = isBrandResults[index];
         const stats = isBrand ? brandStats : nonBrandStats;
         stats.clicks += row.clicks ?? 0;
         stats.impressions += row.impressions ?? 0;
         stats.weightedPos += (row.position ?? 0) * (row.impressions ?? 0);
         stats.queryCount++;
-    }
+    });
     const calc = (stats, segment) => ({
         segment,
         clicks: stats.clicks,

package/dist/tools/seo-primitives.js

@@ -1,6 +1,4 @@
-/**
- * SEO Primitives: Atomic functions for building higher-level SEO agents.
- */
+import { safeTest } from '../utils/regex.js';
 /**
  * Categorize a ranking position into a discrete bucket (Top 3, Page 1, etc.).
  *
@@ -63,19 +61,12 @@ export function calculateTrafficDelta(current, previous) {
  * @returns A brand detection result.
  */
 export function isBrandQuery(query, brandRegexString) {
-    try {
-        const regex = new RegExp(brandRegexString, 'i');
-        const isBrand = regex.test(query);
-        return {
-            query,
-            isBrand,
-            matchedPattern: isBrand ? brandRegexString : undefined
-        };
-    }
-    catch (e) {
-        // Invalid regex fallback
-        return { query, isBrand: false };
-    }
+    const isBrand = safeTest(brandRegexString, 'i', query);
+    return {
+        query,
+        isBrand,
+        matchedPattern: isBrand ? brandRegexString : undefined
+    };
 }
 /**
  * Check if two pages are potentially cannibalizing each other for the same query.

package/dist/tools/sites-health.js

@@ -0,0 +1,135 @@
+import * as sites from './sites.js';
+import * as sitemaps from './sitemaps.js';
+import * as analytics from './analytics.js';
+/**
+ * Run a health check on a single site, returning a structured report.
+ *
+ * @param siteUrl - The site URL to check.
+ * @returns A health report for the site.
+ */
+async function checkSite(siteUrl) {
+    const issues = [];
+    // Run all checks in parallel
+    const [siteInfo, sitemapList, comparison, anomalies] = await Promise.all([
+        sites.getSite(siteUrl).catch(() => null),
+        sitemaps.listSitemaps(siteUrl).catch(() => []),
+        getWeekOverWeekComparison(siteUrl),
+        analytics.detectAnomalies(siteUrl, { days: 14, threshold: 2.5 }).catch(() => []),
+    ]);
+    const permissionLevel = siteInfo?.permissionLevel ?? 'unknown';
+    // --- Analyze performance ---
+    const { period1, period2, changes } = comparison;
+    if (changes.clicksPercent <= -30) {
+        issues.push(`Critical traffic drop: clicks down ${Math.abs(changes.clicksPercent).toFixed(1)}% week-over-week`);
+    }
+    else if (changes.clicksPercent <= -15) {
+        issues.push(`Traffic declining: clicks down ${Math.abs(changes.clicksPercent).toFixed(1)}% week-over-week`);
+    }
+    if (changes.impressionsPercent <= -30) {
+        issues.push(`Critical visibility drop: impressions down ${Math.abs(changes.impressionsPercent).toFixed(1)}% week-over-week`);
+    }
+    else if (changes.impressionsPercent <= -15) {
+        issues.push(`Visibility declining: impressions down ${Math.abs(changes.impressionsPercent).toFixed(1)}% week-over-week`);
+    }
+    if (changes.position > 3) {
+        issues.push(`Average position worsened by ${changes.position.toFixed(1)} positions`);
+    }
+    if (period1.clicks === 0 && period1.impressions === 0) {
+        issues.push('No traffic data for the current period — site may not be receiving any search traffic');
+    }
+    // --- Analyze sitemaps ---
+    let sitemapsWithErrors = 0;
+    let sitemapsWithWarnings = 0;
+    const sitemapDetails = sitemapList.map(sm => {
+        const hasErrors = (Number(sm.errors) || 0) > 0;
+        const isPending = sm.isPending ?? false;
+        if (hasErrors)
+            sitemapsWithErrors++;
+        if ((Number(sm.warnings) || 0) > 0)
+            sitemapsWithWarnings++;
+        return {
+            path: sm.path ?? 'unknown',
+            type: sm.type ?? undefined,
+            isPending,
+            hasErrors,
+            lastDownloaded: sm.lastDownloaded ?? undefined,
+        };
+    });
+    if (sitemapList.length === 0) {
+        issues.push('No sitemaps submitted — consider submitting a sitemap for better crawling');
+    }
+    if (sitemapsWithErrors > 0) {
+        issues.push(`${sitemapsWithErrors} sitemap(s) have errors`);
+    }
+    if (sitemapsWithWarnings > 0) {
+        issues.push(`${sitemapsWithWarnings} sitemap(s) have warnings`);
+    }
+    // --- Analyze anomalies ---
+    const drops = anomalies.filter(a => a.type === 'drop');
+    if (drops.length > 0) {
+        issues.push(`${drops.length} traffic anomaly drop(s) detected in the last 14 days`);
+    }
+    // --- Determine overall status ---
+    let status = 'healthy';
+    if (issues.some(i => i.startsWith('Critical') || i.includes('No traffic data'))) {
+        status = 'critical';
+    }
+    else if (issues.length > 0) {
+        status = 'warning';
+    }
+    return {
+        siteUrl,
+        status,
+        permissionLevel,
+        performance: {
+            current: period1,
+            previous: period2,
+            changes,
+        },
+        sitemaps: {
+            total: sitemapList.length,
+            withErrors: sitemapsWithErrors,
+            withWarnings: sitemapsWithWarnings,
+            details: sitemapDetails,
+        },
+        anomalies,
+        issues,
+    };
+}
+/**
+ * Get a week-over-week performance comparison for a site.
+ */
+async function getWeekOverWeekComparison(siteUrl) {
+    const DATA_DELAY_DAYS = 3;
+    const now = new Date();
+    const period1End = new Date(now);
+    period1End.setDate(period1End.getDate() - DATA_DELAY_DAYS);
+    const period1Start = new Date(period1End);
+    period1Start.setDate(period1Start.getDate() - 7);
+    const period2End = new Date(period1Start);
+    period2End.setDate(period2End.getDate() - 1);
+    const period2Start = new Date(period2End);
+    period2Start.setDate(period2Start.getDate() - 7);
+    const fmt = (d) => d.toISOString().split('T')[0];
+    return analytics.comparePeriods(siteUrl, fmt(period1Start), fmt(period1End), fmt(period2Start), fmt(period2End));
+}
+/**
+ * Run a health check on one or all verified sites.
+ *
+ * @param siteUrl - Optional. If provided, check only this site. If omitted, check all verified sites.
+ * @returns An array of health reports.
+ */
+export async function healthCheck(siteUrl) {
+    if (siteUrl) {
+        const report = await checkSite(siteUrl);
+        return [report];
+    }
+    const allSites = await sites.listSites();
+    if (allSites.length === 0) {
+        return [];
+    }
+    const reports = await Promise.all(allSites.map(site => checkSite(site.siteUrl)));
+    // Sort: critical first, then warning, then healthy
+    const order = { critical: 0, warning: 1, healthy: 2 };
+    return reports.sort((a, b) => order[a.status] - order[b.status]);
+}

package/dist/utils/regex.js

@@ -0,0 +1,41 @@
+import RE2 from 're2';
+/**
+ * Executes a regex test using Google's RE2 engine to prevent ReDoS.
+ * RE2 uses a DFA-based approach that guarantees linear time execution.
+ *
+ * @param pattern The regex pattern string
+ * @param flags The regex flags (e.g., 'i', 'g')
+ * @param text The text to test
+ * @returns boolean indicating if the pattern matches the text
+ */
+export function safeTest(pattern, flags, text) {
+    try {
+        const re = new RE2(pattern, flags);
+        return re.test(text);
+    }
+    catch (e) {
+        console.warn(`Regex evaluation failed for pattern: ${pattern}. Error: ${e}`);
+        return false;
+    }
+}
+/**
+ * Executes a regex test on multiple strings using RE2.
+ *
+ * @param pattern The regex pattern string
+ * @param flags The regex flags
+ * @param texts Array of strings to test
+ * @returns Array of booleans indicating matches
+ */
+export function safeTestBatch(pattern, flags, texts) {
+    if (texts.length === 0)
+        return [];
+    try {
+        const re = new RE2(pattern, flags);
+        return texts.map(t => re.test(t));
+    }
+    catch (e) {
+        console.warn(`Batch regex evaluation failed for pattern: ${pattern}. Error: ${e}`);
+        // Default to no matches if it fails
+        return new Array(texts.length).fill(false);
+    }
+}

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "search-console-mcp",
-  "version": "1.9.2",
+  "version": "1.9.3",
   "mcpName": "io.github.saurabhsharma2u/search-console-mcp",
   "description": "MCP server for Google Search Console API",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "search-console-mcp": "./dist/index.js",
-    "search-console-mcp-setup": "./dist/setup.js"
+    "search-console-mcp": "./dist/index.js"
   },
   "files": [
     "dist",
@@ -35,13 +34,15 @@
     "cheerio": "^1.2.0",
     "dotenv": "^17.2.3",
     "googleapis": "^171.0.0",
+    "re2": "^1.23.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^25.2.0",
+    "@types/re2": "^1.10.0",
     "@vitest/coverage-v8": "^4.0.18",
     "typedoc": "^0.28.16",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   }
-}
+}