search-console-mcp 1.9.0 → 1.9.2

package/README.md

@@ -1,295 +1,175 @@
 # Google Search Console MCP Server
 
-A Model Context Protocol (MCP) server that provides AI agents with access to Google Search Console data.
+A Model Context Protocol (MCP) server that transforms how you interact with Google Search Console. Stop exporting CSVs and start asking questions.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[📚 View Documentation](https://searchconsolemcp.mintlify.app/)
 
-## Quick Start
+---
 
-For users with an MCP-compatible client (like Claude Desktop):
-
-```bash
-npx search-console-mcp
-```
+### [🏠 Overview](#) | [🎯 Prompts](#-magic-prompts) | [🚀 Quick Start](#-quick-start) | [🛠️ Tools](#-tools-reference)
 
 ---
 
-## Table of Contents
-
-- [Features](#features)
-- [Installation](#installation)
-- [Google Cloud Setup](#google-cloud-setup)
-- [MCP Client Configuration](#mcp-client-configuration)
-- [Local Development](#local-development)
-- [Tools Reference](#tools-reference)
-- [Resources](#resources)
-- [Prompts](#prompts)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://github.com/saurabhsharma2u/search-console-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/saurabhsharma2u/search-console-mcp/actions/workflows/ci.yml)
 
----
+## Why use this?
 
-## Features
+### ❌ The Old Way
+1.  Open Search Console -> Performance Tab
+2.  Filter by "Last 28 days"
+3.  Export to CSV
+4.  Open in Excel/Sheets
+5.  Create a filter for "Position > 10" AND "Impressions > 1000"
+6.  Analyze manually to find opportunities
 
-- **Sites Management**: List, add, and delete sites
-- **Sitemaps**: List, submit, get, and delete sitemaps
-- **Search Analytics**: Query performance data with advanced filtering and pagination
-- **Period Comparison**: Compare metrics between two date ranges
-- **Top Queries/Pages**: Get top performing queries and pages
-- **URL Inspection**: Check indexing status of specific URLs
-- **AI Documentation**: Built-in docs for AI agents to understand GSC concepts
+### ✅ The New Way
+**Just ask:**
+> "Find low-hanging fruit keywords (positions 11-20) with high impressions that I should optimize."
 
 ---
 
-## Installation
+## 🎯 Magic Prompts
 
-### Option 1: Use with npx (Recommended)
+Copy and paste these into your MCP client (Claude Desktop, etc.) to see the intelligence engine in action:
 
-No installation needed. Configure your MCP client to run:
+#### �️ The Traffic Detective
+> "My traffic dropped this week compared to last. Use the anomaly detection and time-series tools to find exactly when the drop started and which pages are responsible."
 
-```bash
-npx search-console-mcp
-```
+#### 🎯 The "Striking Distance" Hunter
+> "Find keywords for https://example.com where I'm ranking in positions 8-15 but have at least 1,000 impressions. These are my best opportunities for a quick traffic boost."
 
-### Option 2: Global Install
+#### ⚔️ The Cannibalization Cleaner
+> "Check for keyword cannibalization. Are there any queries where two or more of my pages are competing and splitting the traffic? Suggest which one should be the primary authority."
 
-```bash
-npm install -g search-console-mcp
-search-console-mcp
-```
+#### 📈 The SEO Opportunity Scoreboard
+> "Analyze my top 50 keywords for the last 90 days. Rank them by a custom 'Opportunity Score' (Impressions / Position). Give me the top 5 specific pages to focus on."
 
-### Option 3: Clone for Development
+#### 📊 The Executive Health Check
+> "Run a full SEO health check for my site. Segment the results by Brand vs. Non-Brand and give me 3 high-impact actions for the upcoming week."
 
-```bash
-git clone https://github.com/saurabhsharma2u/search-console-mcp.git
-cd search-console-mcp
-npm install
-npm run build
-node dist/index.js
-```
+#### ⚡ The Speed vs. Ranking Correlator
+> "Fetch the top 5 pages by impressions. For these pages, run a PageSpeed audit. Is there any correlation between low performance scores and recently declining positions?"
 
 ---
 
-## Google Cloud Setup
-
-### Step 1: Create a Google Cloud Project
-
-1. Go to [Google Cloud Console](https://console.cloud.google.com/)
-2. Create a new project or select an existing one
-3. Enable the **Google Search Console API**:
-   - Go to **APIs & Services** > **Library**
-   - Search for "Google Search Console API"
-   - Click **Enable**
+## 🔒 Security & Privacy
 
-### Step 2: Create a Service Account
+We take your data security seriously. This tool is designed to be **local-first** and **secure by default**.
 
-1. Go to **APIs & Services** > **Credentials**
-2. Click **Create Credentials** > **Service Account**
-3. Fill in the details and click **Create**
-4. Skip the optional steps and click **Done**
-5. Click on the service account email to open it
-6. Go to the **Keys** tab > **Add Key** > **Create new key**
-7. Select **JSON** and download the key file
+*   **Credentials Never Logged**: Your Google Service Account keys are used *only* in memory to authenticate with Google APIs. They are never written to disk, logs, or sent to any third-party server.
+*   **Local Execution**: The code runs entirely on your local machine (or wherever you host your MCP server).
+*   **Path Traversal Protection**: The setup wizard implements strict validation for file paths, including null-byte removal, extension enforcement (.json), and size limits (1MB) to prevent unauthorized file access.
+*   **Direct Communication**: All API calls go directly from your machine to Google's servers (`googleapis.com`). There is no middleman or proxy server.
+*   **Open Source**: The code is fully open source. You can audit exactly how your credentials are used in `src/google-client.ts`.
 
-### Step 3: Grant Access in Search Console
+---
 
-1. Go to [Google Search Console](https://search.google.com/search-console/)
-2. Select your property
-3. Go to **Settings** > **Users and permissions**
-4. Click **Add user**
-5. Enter the service account email (e.g., `my-service@project.iam.gserviceaccount.com`)
-6. Set permission to **Full** (for write operations) or **Restricted** (read-only)
+## Features
 
-### Step 4: Configure Credentials
+- **Advanced Analytics**: Query performance data with powerful filters (Regex supported).
+    - *New*: Support for 'News', 'Discover', 'Image' search types.
+    - *New*: 'Fresh' data support for real-time monitoring.
+    - *New*: **Drop Attribution** to identify device-level traffic losses.
+    - *New*: **Time Series Insights** with rolling averages and trend forecasting.
+- **Trend Detection**: Automatically identify rising or falling trends in your traffic.
+- **Anomaly Detection**: Spot unusual spikes or drops that need attention.
+- **Sitemaps Management**: List, submit, and validte sitemaps.
+- **URL Inspection**: Check real-time indexing status and mobile usability.
+- **PageSpeed Insights**: Integrated performance and Core Web Vitals analysis.
+- **Schema Validation**: Validate JSON-LD structured data.
 
-**Option A: File-based (Local Development)**
+---
 
-```bash
-export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"
-```
+## Quick Start
 
-**Option B: Environment Variables (Serverless/Cloudflare)**
+### 1. Run the Setup Wizard
+First, use the interactive wizard to validate your credentials and get your configuration:
 
 ```bash
-export GOOGLE_CLIENT_EMAIL="your-service-account@project.iam.gserviceaccount.com"
-export GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
+npx search-console-mcp-setup
 ```
 
----
+The wizard will guide you through:
+- Creating a Google Service Account.
+- Adding the account to Search Console.
+- Validating your JSON key file.
+- Generating the configuration for your MCP client.
 
-## MCP Client Configuration
+### 2. Connect to an MCP Client
 
-### Claude Desktop
+**Note:** The server uses `stdio` to communicate. Do not run `npx search-console-mcp` directly in your terminal; it is meant to be run by an MCP client like Claude Desktop or Cursor.
 
-Add to your `claude_desktop_config.json`:
+#### Claude Desktop Configuration
+Add this to your `claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
     "google-search-console": {
       "command": "npx",
-      "args": ["search-console-mcp"],
+      "args": ["-y", "search-console-mcp"],
       "env": {
-        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json"
+        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/your/service-account-key.json"
       }
     }
   }
 }
 ```
 
-### Generic MCP Client
-
-```json
-{
-  "name": "google-search-console",
-  "command": "npx",
-  "args": ["search-console-mcp"],
-  "env": {
-    "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json"
-  }
-}
-```
-
----
-
-## Local Development
-
-### Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/saurabhsharma2u/search-console-mcp.git
-cd search-console-mcp
-
-# Install dependencies
-npm install
-
-# Create .env file
-cp .env.example .env
-# Edit .env with your credentials
-
-# Build
-npm run build
-
-# Run tests
-npm test
-
-# Run the server
-node dist/index.js
-```
-
-### Project Structure
-
-```
-src/
-├── index.ts          # MCP server entry point
-├── google-client.ts  # Google API authentication
-├── errors.ts         # Error handling utilities
-├── docs/             # Embedded documentation for AI
-│   ├── dimensions.ts
-│   ├── filters.ts
-│   ├── search-types.ts
-│   └── patterns.ts
-└── tools/            # Tool implementations
-    ├── sites.ts
-    ├── sitemaps.ts
-    ├── analytics.ts
-    └── inspection.ts
-```
-
 ---
 
 ## Tools Reference
 
-### Sites
-
-| Tool | Description | Arguments |
-|------|-------------|-----------|
-| `sites_list` | List all sites | none |
-| `sites_add` | Add a site | `siteUrl` |
-| `sites_delete` | Delete a site | `siteUrl` |
-| `sites_get` | Get site details | `siteUrl` |
-
-### Sitemaps
-
-| Tool | Description | Arguments |
-|------|-------------|-----------|
-| `sitemaps_list` | List sitemaps | `siteUrl` |
-| `sitemaps_get` | Get sitemap details | `siteUrl`, `feedpath` |
-| `sitemaps_submit` | Submit sitemap | `siteUrl`, `feedpath` |
-| `sitemaps_delete` | Delete sitemap | `siteUrl`, `feedpath` |
-
 ### Analytics
-
-| Tool | Description | Arguments |
-|------|-------------|-----------|
-| `analytics_query` | Query search analytics with filters | `siteUrl`, `startDate`, `endDate`, `dimensions?`, `type?`, `limit?`, `startRow?`, `filters?` |
-| `analytics_performance_summary` | Get aggregate metrics for N days | `siteUrl`, `days?` |
-| `analytics_compare_periods` | Compare two date ranges | `siteUrl`, `period1Start`, `period1End`, `period2Start`, `period2End` |
-| `analytics_top_queries` | Get top queries | `siteUrl`, `days?`, `limit?`, `sortBy?` |
-| `analytics_top_pages` | Get top pages | `siteUrl`, `days?`, `limit?`, `sortBy?` |
-
-### Inspection
-
-| Tool | Description | Arguments |
-|------|-------------|-----------|
-| `inspection_inspect` | Inspect URL index status | `siteUrl`, `inspectionUrl`, `languageCode?` |
-
-### PageSpeed Insights
-
-| Tool | Description | Arguments |
-|------|-------------|-----------|
-| `pagespeed_analyze` | PageSpeed Insights scores (performance, accessibility, SEO) | `url`, `strategy?` (mobile/desktop) |
-| `pagespeed_core_web_vitals` | Core Web Vitals for mobile & desktop (LCP, FID, CLS, etc.) | `url` |
-
-### SEO Insights
-
-| Tool | Description | Arguments |
-|------|-------------|-----------|
-| `seo_recommendations` | Generate actionable SEO recommendations | `siteUrl`, `days?` |
-| `seo_low_hanging_fruit` | Find keywords at positions 5-20 with high impressions | `siteUrl`, `days?`, `minImpressions?`, `limit?` |
-| `seo_cannibalization` | Detect pages competing for the same keywords | `siteUrl`, `days?`, `minImpressions?`, `limit?` |
-| `seo_quick_wins` | Find pages close to page 1 (positions 11-20) | `siteUrl`, `days?`, `minImpressions?`, `limit?` |
-
----
-
-## Resources
-
-AI agents can read these built-in documentation and data resources:
-
-| URI | Description |
-|-----|-------------|
-| `sites://list` | List of all sites (JSON) |
-| `sitemaps://list/{siteUrl}` | Sitemaps for a specific site (JSON) |
-| `analytics://summary/{siteUrl}` | Performance summary for a site (JSON) |
-| `docs://dimensions` | Available dimensions reference |
-| `docs://filters` | Filter operators and examples |
-| `docs://search-types` | Search types (web, image, video, etc.) |
-| `docs://patterns` | Common usage patterns and recipes |
-
----
-
-## Prompts
-
-Pre-configured analysis workflows for AI agents:
-
-| Prompt | Description | Arguments |
-|--------|-------------|-----------|
-| `analyze-site-performance` | Analyze site's 28-day performance | `siteUrl` |
-| `compare-performance` | Compare this week vs last week | `siteUrl` |
-| `find-declining-pages` | Find pages losing traffic | `siteUrl` |
-| `keyword-opportunities` | Find low-CTR high-impression queries | `siteUrl` |
-| `new-content-impact` | Analyze new content performance | `siteUrl`, `pageUrl` |
-| `mobile-vs-desktop` | Compare device performance | `siteUrl` |
+| Tool | Description |
+|------|-------------|
+| `analytics_query` | Master tool for raw data. Supports `dimensions`, `filters`, `aggregationType` (byPage/byProperty), `dataState` (final/all), and `type` (web/image/news/discover). |
+| `analytics_trends` | Detect trends (rising/falling) for specific queries or pages. |
+| `analytics_anomalies` | Detect statistical anomalies in daily traffic. |
+| `analytics_drop_attribution` | **[NEW]** Attribute traffic drops to mobile/desktop or correlate with known Google Algorithm Updates. |
+| `analytics_time_series` | **[NEW]** Advanced time series with rolling averages, seasonality detection, and forecasting. |
+| `analytics_compare_periods` | Compare two date ranges (e.g., WoW, MoM). |
+| `seo_brand_vs_nonbrand` | **[NEW]** Analyze performance split between Brand vs Non-Brand traffic. |
+
+### SEO Opportunities (Opinionated)
+| Tool | Description |
+|------|-------------|
+| `seo_low_hanging_fruit` | Find keywords ranking in pos 5-20 with high impressions. |
+| `seo_striking_distance` | **[NEW]** Find keywords ranking 8-15 (Quickest ROI wins). |
+| `seo_low_ctr_opportunities` | **[NEW]** Find top ranking queries (pos 1-10) with poor CTR. |
+| `seo_cannibalization` | **[Enhanced]** Detect pages competing for the same query with traffic conflict. |
+| `seo_lost_queries` | **[NEW]** Identify queries that lost all traffic in the last 28 days. |
+
+### SEO Primitives (Atoms for Agents)
+These are low-level tools designed to be used by other AI agents to build complex logic.
+| Tool | Description |
+|------|-------------|
+| `seo_primitive_ranking_bucket` | Categorize a position (e.g. "Top 3", "Page 1", "Unranked"). |
+| `seo_primitive_traffic_delta` | Calculate absolute and % change between two numbers. |
+| `seo_primitive_is_brand` | Check if a query matches a brand regex. |
+| `seo_primitive_is_cannibalized` | Check if two pages are competing for the same query. |
+
+### Sites & Sitemaps
+| Tool | Description |
+|------|-------------|
+| `sites_list` | List all verified sites. |
+| `sites_add` / `sites_delete` | Manage properties. |
+| `sitemaps_list` / `sitemaps_submit` | Manage sitemaps. |
+
+### Inspection & Validation
+| Tool | Description |
+|------|-------------|
+| `inspection_inspect` | Google URL Inspection API (Index status, mobile usability). |
+| `pagespeed_analyze` | Lighthouse scores & Core Web Vitals. |
+| `schema_validate` | Validate Structured Data (JSON-LD). |
 
 ---
 
 ## Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines.
-
-## Roadmap
-
-See [ROADMAP.md](./ROADMAP.md) for planned features.
+We love contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
 
 ## License
 
-MIT - see [LICENSE](./LICENSE)
+MIT

package/dist/docs/algorithm-updates.js

@@ -0,0 +1,20 @@
+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:
+
+| Date | Update Name | Impact Area |
+|------|-------------|-------------|
+| 2025-01-15 | January 2025 Core Update | General Ranking |
+| 2024-11-11 | November 2024 Core Update | General Ranking |
+| 2024-08-15 | August 2024 Core Update | General Ranking |
+| 2024-06-20 | June 2024 Spam Update | Content Quality / Spam |
+| 2024-03-05 | March 2024 Core Update | General Ranking / Quality |
+| 2023-11-02 | November 2023 Core Update | General Ranking |
+| 2023-10-05 | October 2023 Core Update | General Ranking |
+| 2023-09-14 | September 2023 Helpful Content Update | Quality / Value |
+
+## 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.
+`;
+export default algorithmUpdatesDocs;

package/dist/docs/index.js

@@ -5,3 +5,4 @@ export { dimensionsDocs } from './dimensions.js';
 export { filtersDocs } from './filters.js';
 export { searchTypesDocs } from './search-types.js';
 export { patternsDocs } from './patterns.js';
+export { algorithmUpdatesDocs } from './algorithm-updates.js';

package/dist/docs/patterns.js

@@ -26,6 +26,35 @@ Args: {
 }
 \`\`\`
 
+| Tool | Description |
+|------|-------------|
+| \`analytics_drop_attribution\` | Identify if a traffic drop was device-specific or algorithm-linked. |
+| \`analytics_time_series\` | Get rolling averages, seasonality strength, and trend forecasts. |
+
+---
+
+## Advanced Analytics Patterns
+
+### Attribute a Traffic Drop
+Identify if a recent drop was caused by mobile/desktop devices or correlates with a Google Algorithm Update:
+\`\`\`json
+{
+  "siteUrl": "https://example.com",
+  "days": 30
+}
+\`\`\`
+
+### Time Series Forecasting
+Get a 14-day rolling average and forecast the next 14 days of traffic:
+\`\`\`json
+{
+  "siteUrl": "https://example.com",
+  "days": 60,
+  "window": 14,
+  "forecastDays": 14
+}
+\`\`\`
+
 ---
 
 ## Analytics Patterns

package/dist/google-client.js

@@ -1,11 +1,15 @@
 import { google } from 'googleapis';
 const SCOPES = ['https://www.googleapis.com/auth/webmasters'];
+let cachedClient = null;
 /**
  * Get an authenticated Google Search Console API client.
  * Supports both file-based credentials (GOOGLE_APPLICATION_CREDENTIALS)
  * and environment variable credentials (GOOGLE_CLIENT_EMAIL + GOOGLE_PRIVATE_KEY).
  */
 export async function getSearchConsoleClient() {
+    if (cachedClient) {
+        return cachedClient;
+    }
     // Option 1: Environment variables (for serverless/Cloudflare)
     if (!process.env.GOOGLE_APPLICATION_CREDENTIALS && process.env.GOOGLE_CLIENT_EMAIL && process.env.GOOGLE_PRIVATE_KEY) {
         const jwtClient = new google.auth.JWT({
@@ -14,12 +18,14 @@ export async function getSearchConsoleClient() {
             scopes: SCOPES
         });
         await jwtClient.authorize();
-        return google.searchconsole({ version: 'v1', auth: jwtClient });
+        cachedClient = google.searchconsole({ version: 'v1', auth: jwtClient });
+        return cachedClient;
     }
     // Option 2: File-based credentials (default)
     const auth = new google.auth.GoogleAuth({
         scopes: SCOPES,
     });
     const client = await auth.getClient();
-    return google.searchconsole({ version: 'v1', auth: client });
+    cachedClient = google.searchconsole({ version: 'v1', auth: client });
+    return cachedClient;
 }