@getmcpads/google-search-console-mcp-server 1.0.2 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+## 2.0.0 - 2026-09-20
+
+- Bound automatic pagination to four pages, 100,000 rows and a 30-second total deadline.
+- Expose pagination and truncation diagnostics while preserving hourly data and native metadata.
+- Remove provider error bodies from logs and errors; bound search-type comparison fan-out.
+- Require Node.js 22.12 or newer and check Node 22/24 in CI.
+- Update vulnerable dependencies and regenerate the MCP catalog.
+- No hosted creative UI or MCP Apps integrations.
+
+
+## 1.1.0
+
+- Synchronize applicable platform features with GetMCPAds commit b1471be while retaining local read-only exploration tools and credential configuration.
+- Expose 20 read tools.
+- Add MCP annotations, parameter descriptions, structured results, server identity and an offline-generated discovery card.
+- Preserve preview/confirmation boundaries; test provider request construction and errors with mocked APIs.
+- Refuse credential-bearing redirects and document provider-specific limitations.
+
+No live advertiser mutation is performed by the release tests.

package/README.md

@@ -1,28 +1,60 @@
-# google-search-console-mcp-server
+<div align="center">
 
+# Google Search Console MCP server
+
+### Bring your search performance into the conversation.
+
+Investigate queries, pages, indexing and sitemaps through a read-only MCP server.
+
+[![Release](https://img.shields.io/github/v/release/getmcpads-com/google-search-console-mcp-server?color=2448e5)](https://github.com/getmcpads-com/google-search-console-mcp-server/releases/latest)
 [![CI](https://github.com/getmcpads-com/google-search-console-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/getmcpads-com/google-search-console-mcp-server/actions/workflows/ci.yml)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
-[![Node](https://img.shields.io/badge/node-%E2%89%A518-brightgreen.svg)](package.json)
+[![Node](https://img.shields.io/badge/node-%E2%89%A522.12-brightgreen.svg)](package.json)
+
+[Watch the demo](https://www.getmcpads.com/home/film/get-mcp-ads-film-1080p.mp4) · [What's new](#whats-new) · [Install](#install-this-release) · [Tool reference](#tools) · [Try hosted getmcpads](https://www.getmcpads.com/tools/search-console?utm_source=github&utm_medium=readme&utm_campaign=google-search-console)
+
+[![Watch the getmcpads product demo: campaign review in Claude](https://www.getmcpads.com/home/film/poster-rich.webp)](https://www.getmcpads.com/home/film/get-mcp-ads-film-1080p.mp4)
+
+**[Play the 27-second product film](https://www.getmcpads.com/home/film/get-mcp-ads-film-1080p.mp4)**
+
+</div>
+
+The film demonstrates hosted getmcpads with staged data. Its creative galleries and MCP Apps interface belong to the hosted product. This repository provides the standalone native API tools.
+
+**20 read tools** · Read-only by design.
+
+Run locally with your own platform credentials and a client that supports stdio MCP, such as Claude Desktop, Claude Code or Cursor. Your requests go directly to the platform. For managed connections, including supported ChatGPT setups, use the hosted option.
 
-An open-source [Model Context Protocol](https://modelcontextprotocol.io) server for
-**Google Search Console**. It lets Claude, ChatGPT, Cursor or any MCP client query your
-search performance, inspect indexing, and analyse sitemaps.
+## What's new
 
-**Read-only, with no way to turn that off.** You run it, and your credentials stay on your
-machine.
+**[v2.0.0: Native tools and security update](https://github.com/getmcpads-com/google-search-console-mcp-server/releases/tag/v2.0.0) · September 20, 2026**
+
+- Bound automatic pagination to four pages, 100,000 rows and a 30-second total deadline.
+- Expose pagination and truncation diagnostics while preserving hourly data and native metadata.
+- Remove provider error bodies from logs and errors; bound search-type comparison fan-out.
+- Require Node.js 22.12 or newer and check Node 22/24 in CI.
+- Update vulnerable dependencies and regenerate the MCP catalog.
+
+[Full changelog](CHANGELOG.md) · [Source synchronization details](SOURCE_SYNC.md) · [All releases](https://github.com/getmcpads-com/google-search-console-mcp-server/releases)
+
+### Upgrade notes
+
+Requires **Node.js 22.12 or newer**. CI covers Node 22 and 24. Version 2.0.0 drops Node 18 and 20 support. Hosted creative integrations and MCP Apps UI are outside this release.
+
+## Install this release
+
+This is a GitHub source release. npm and MCP Registry versions are published separately. The commands below select this exact version; unpinned `npx` examples later in this document select the version currently available on npm.
 
 ```bash
-npx -y @getmcpads/google-search-console-mcp-server
+git clone --branch v2.0.0 --depth 1 https://github.com/getmcpads-com/google-search-console-mcp-server.git
+cd google-search-console-mcp-server
+npm ci
+npm run build
 ```
 
-Also listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as **`com.getmcpads/google-search-console`**, so clients that read the registry can install it by name.
+Configure your MCP client to run `node` with the absolute path to `dist/cli.js` and the platform credentials documented below.
 
-> **Prefer not to run it yourself?** [getmcpads.com](https://www.getmcpads.com) is the hosted
-> version of this server, with Search Console alongside Meta Ads, Google Ads, TikTok Ads,
-> Pinterest Ads and Google Analytics behind a single endpoint, hosted OAuth, and
-> cross-platform reporting. Same tools, same safety model, no setup.
-
----
+> **Prefer a managed connection?** [Use Google Search Console with hosted getmcpads](https://www.getmcpads.com/tools/search-console?utm_source=github&utm_medium=readme&utm_campaign=google-search-console). Connect your account, select the data your assistant may access and use the hosted MCP connection. See the site for current features and plans.
 
 ## What you get
 
@@ -203,46 +235,33 @@ npm run doctor
 
 ## Tools
 
+Every tool is listed below. See [server-card.json](server-card.json) for complete parameter and output schemas.
+
 <details>
 <summary><b>20 read tools</b></summary>
 
-### Discovery and health
 | Tool | Purpose |
-|---|---|
-| `gsc_health_check` | Validates credentials and reachable properties |
-| `gsc_list_sites` / `gsc_get_site` | Properties you can reach, and their permission level |
-| `gsc_get_data_freshness` | How settled the most recent data is |
-
-### Search Analytics
-| Tool | Purpose |
-|---|---|
-| `gsc_query_search_analytics` | The main reporting tool. Dimensions, filters, date ranges |
-| `gsc_validate_query` | Check a combination *before* running it |
-| `gsc_compare_search_types` | Web, image, video, news and discover side by side |
-| `gsc_analyze_search_appearance_trends` | How rich results evolve over time |
-
-### SEO analysis
-| Tool | Purpose |
-|---|---|
-| `gsc_detect_cannibalization` | Pages competing for the same query |
-| `gsc_find_losses_gains` | Queries and pages won or lost between two periods |
-| `gsc_cluster_queries` | Group queries by shared intent |
-
-### Indexing
-| Tool | Purpose |
-|---|---|
-| `gsc_inspect_url` | Crawl and index status for one URL |
-| `gsc_bulk_inspect_urls` | Up to 10 URLs per call, to protect your quota |
-| `gsc_indexation_watchlist` | Track URLs whose verdict changed |
-| `gsc_monitor_indexation_freshness` | Freshness and indexation drift together |
-| `gsc_plan_large_site_sampling` | Build an inspection sample when you cannot inspect everything |
-
-### Sitemaps
-| Tool | Purpose |
-|---|---|
-| `gsc_list_sitemaps` / `gsc_get_sitemap` | Submitted sitemaps and their status |
-| `gsc_get_sitemap_health` | Errors, warnings and pending states |
-| `gsc_track_sitemap_deltas` | What changed against a baseline you supply |
+| --- | --- |
+| `gsc_list_sites` | List all Google Search Console properties accessible with the current credentials. |
+| `gsc_get_site` | Get one Search Console property and its exact permission level (read-only sites.get). |
+| `gsc_health_check` | Verify Google Search Console read-only authentication, visible properties, configured default site, and permission levels without exposing tokens. |
+| `gsc_query_search_analytics` | Query Google Search Console Search Analytics. |
+| `gsc_inspect_url` | Inspect a URL for Google indexing status, crawl info, mobile usability, AMP, and rich results. |
+| `gsc_bulk_inspect_urls` | Inspect multiple URLs with a conservative sequential limit and normalized URL Inspection results. |
+| `gsc_list_sitemaps` | List sitemaps submitted for a Search Console property, including processing status and submitted/indexed counts. |
+| `gsc_get_sitemap` | Get one submitted sitemap by full feed path, including type, fetch state, warnings/errors, and submitted/indexed content totals. |
+| `gsc_get_sitemap_health` | Return an enriched read-only sitemap health summary with status totals, submitted/indexed content counts, warnings, and errors. |
+| `gsc_compare_search_types` | Compare performance across Search Console search types: web, image, video, news, discover, and Google News. |
+| `gsc_get_data_freshness` | Detect the most recent date with Search Analytics data by querying recent daily rows. |
+| `gsc_monitor_indexation_freshness` | Read-only monitoring snapshot for Search Analytics freshness, sitemap indexation totals, and an optional small URL Inspection sample. |
+| `gsc_track_sitemap_deltas` | Read-only sitemap delta tracker. |
+| `gsc_analyze_search_appearance_trends` | Analyze structured data and rich-result trend signals via the Search Analytics searchAppearance dimension when GSC exposes it. |
+| `gsc_plan_large_site_sampling` | Build a read-only URL Inspection sampling plan for large sites from sitemap risk signals and Search Analytics page performance. |
+| `gsc_indexation_watchlist` | Read-only URL Inspection watchlist for critical URLs. |
+| `gsc_find_losses_gains` | Compare two periods for query or page performance and return click/impression/CTR/position deltas. |
+| `gsc_cluster_queries` | Cluster Search Console queries by simple tokens and intent signals: brand/non-brand, question, category, and topic tokens. |
+| `gsc_detect_cannibalization` | Detect queries where multiple pages compete for clicks/impressions in Search Analytics query-page rows. |
+| `gsc_validate_query` | Validate a Search Console metric/dimension/search type combination before executing it. |
 
 </details>
 
@@ -281,14 +300,20 @@ Full policy: [SECURITY.md](SECURITY.md).
 
 ## Looking for a managed, multi-platform version?
 
-This server does one platform, on your machine, with your credentials. That is on purpose.
+[Try hosted Search Console](https://www.getmcpads.com/tools/search-console?utm_source=github&utm_medium=readme&utm_campaign=search_console_hosted) if you want to use this source without operating a local server.
+getmcpads also connects advertising, Search Console and GA4 through one MCP URL.
+Source availability and plan limits are listed on the site; connecting an account is still required.
 
-If you'd rather not run it yourself, or you need Search Console **alongside Meta Ads, Google
-Ads, TikTok Ads, Pinterest Ads and Google Analytics** behind one endpoint, with hosted OAuth
-and cross-platform reporting, that's what we build at **[getmcpads.com](https://www.getmcpads.com)**.
+1. Follow the [Search Console connection guide](https://www.getmcpads.com/guides/sources/search-console).
+2. Select the account or property your assistant may read.
+3. Connect [Claude](https://www.getmcpads.com/guides/setup/claude),
+   [ChatGPT](https://www.getmcpads.com/guides/setup/chatgpt) or
+   [Codex](https://www.getmcpads.com/guides/setup/codex).
+4. Try a read-only review: “Find which pages and queries account for a change in organic clicks. State missing data and do not change anything.”
 
-Same philosophy, less plumbing. This project stays open source and independently useful
-either way.
+See the [current hosted tool catalogue](https://www.getmcpads.com/tools/search-console)
+and [pricing](https://www.getmcpads.com/pricing) before choosing a paid plan.
+This Apache 2.0 adapter remains independently useful with your own credentials.
 
 ---
 
@@ -304,3 +329,15 @@ Please read [SECURITY.md](SECURITY.md) before reporting anything security-relate
 Google and Google Search Console are trademarks of Google LLC.
 **This project is not affiliated with, endorsed by, or sponsored by Google LLC.**
 It is an independent client of a public API.
+
+## MCP contracts and desktop bundle
+
+Every tool declares read/write annotations, parameter descriptions and a structured output schema. Successful calls expose the payload as `structuredContent.result`; errors retain `isError: true`. The generated [server card](server-card.json) contains definitions only.
+
+Run `npm run bundle -- /path/to/output` to build a `.mcpb` desktop bundle from the current catalog. Credentials are entered locally during installation. This server remains read-only.
+
+## More from getmcpads
+
+[Meta Ads](https://github.com/getmcpads-com/meta-ads-mcp-server) · [Google Ads](https://github.com/getmcpads-com/google-ads-mcp-server) · [Google Analytics 4](https://github.com/getmcpads-com/google-analytics-mcp-server) · [TikTok Ads](https://github.com/getmcpads-com/tiktok-ads-mcp-server) · [Pinterest Ads](https://github.com/getmcpads-com/pinterest-ads-mcp-server) · [X Ads](https://github.com/getmcpads-com/x-ads-mcp-server)
+
+Maintained by **Emmanuel** at [getmcpads](https://www.getmcpads.com). Questions: [hello@getmcpads.com](mailto:hello@getmcpads.com).