Skip to content

Architecture

Release 1.3.0 includes search_change_breakdown (Google-only explicit period comparisons) and link_targets_audit (bounded public destination observations). Release 1.3.1 retains 85 tools and includes the feedback fixes documented below. Read bounded audit workflows for calls, result fields and evidence limits.

gsc-mcp is a FastMCP server exposing 96 source tools over the Model Context Protocol by default. Each tool is a plain Python function returning a JSON string. The CLI derives its full command surface from registry.TOOLS. Since version 1.3.1, the server selects MCP families at startup with GSC_MCP_TOOL_FAMILIES, exposing all by default and retaining core; an import-time assertion keeps that registry aligned with properties._ALL_TOOLS.

src/gsc_mcp/
├── server.py # Entry point. Registers startup-selected functions from registry.TOOLS
├── tool_selection.py # MCP startup family selection since 1.3.1
├── registry.py # Single source of truth for the 96 source MCP and CLI tools
├── cli.py # Flag-only CLI generated from registry function signatures
├── reporting.py # Bounded search report output and snapshot provenance
├── auth.py # Google service helpers, GA4 property resolver, Bing env key reader
├── constants.py # Scopes, quota limits, CTR benchmarks by SERP position
├── meta.py # with_meta(data, tool, params): wraps every tool output
├── retry.py # with_retry() decorator: exponential backoff on retryable HTTP errors
├── quota.py # QuotaTracker: in-memory counter for Indexing API calls
├── providers/
│ ├── base.py # SearchMetricRow/Batch and the common provider protocol
│ ├── google.py # Google Search Console metrics adapter
│ └── bing.py # Redacted Bing JSON/HTTP client and metrics adapter
└── tools/
├── properties.py # 3 capability and GSC property tools
├── analytics.py # 10 GSC analytics tools + shared fetch/date helpers
├── search_breakdown.py # Explicit Google periods and independent dimension views
├── traffic_reference.py # Disjoint same-weekday Google reference
├── crawl_import.py # Caller-supplied bounded SiteOne JSON preview
├── seo.py # 8 SEO analyses; 3 support Bing and 4 refuse unsupported Bing contracts
├── inspection.py # inspect_url, batch_url_inspection, check_indexing_issues
├── indexing.py # submit_url, submit_batch, indexnow_submit
├── sitemaps.py # list_sitemaps, submit_sitemap, sitemaps_get, sitemaps_delete, sitemap_audit
├── ga4.py # 8 GA4 tools + _build_dimension_filter helper
├── cross.py # 4 GSC+GA4 tools + _normalize_url helper
├── crux.py # 3 Chrome UX Report tools via httpx
├── technical.py # 5 schema, AI visibility, GBP and PageSpeed tools
├── drift.py # 3 persisted SEO drift tools
├── content.py # 5 on-page content and technical audits
├── links.py # 2 internal-link tools
├── link_targets.py # Bounded internal destination HTTP observations
├── bing_analytics.py # 6 Bing performance/backlink reads
├── bing_webmaster.py # 9 Bing reads + 4 guarded writes
└── search_compare.py # 1 evidence-bounded Google/Bing comparison

tool_selection.py validates GSC_MCP_TOOL_FAMILIES against the catalogue families before server registration. Unknown or empty selections fail startup. The CLI still reads the full registry. Restart the MCP process after a selection change; discovery selection does not change provider credentials, permissions or confirmation requirements. See installation configuration.

Optional audit APIs and checkout evaluation runners

Section titled “Optional audit APIs and checkout evaluation runners”

audit_runtime.py provides an opt-in read-only acquisition session with exact property scopes, a caller-owned SQLite ledger and session-local immutable observation caching. Provider attempts, tool calls (including cache hits) and native invocations have separate durable counters bound to an immutable run configuration. Reservations happen before the counted dispatch and survive failures/restarts; these are attempt ceilings, not token or monetary limits. Ancillary HTML/CrUX acquisition is outside this allowlist.

scripts/run_bounded_audit.py acquires an explicit plan, then optionally uses native_audit.py and the nine native_roles.py source-review profiles. Selected specialists receive copies of original observations without adding acquisition requests; their references retain original source indices. Specialist concurrency is bounded within the pipeline; synthesis and a fresh reviewer invocation remain sequential. Structural reference validation cannot establish semantic support. These profiles do not execute the interactive .claude/agents/ playbooks or the former JavaScript Workflow host.

flowchart LR
P[Explicit scoped request plan] --> T[Reserve tool call in SQLite]
T --> C{Session cache hit?}
C -->|Yes| O[Immutable observations]
C -->|No| D[Execute allowed read-only tool]
D -->|Local result| O
D -->|Counted physical provider dispatch| B[Reserve before each physical attempt]
B --> O
O --> N[Reserve native attempt before each invocation]
N --> S[Selected source-only specialists]
S --> A[Reserve and run sequential author and fresh reviewer]
N --> A
A --> R[Draft, review and unavailable reasons]

native_process.py launches each native invocation in a separate process group on Linux/macOS. It counts stdout/stderr live, caps each stream at 2,000,000 bytes, retains bounded stdout and discards stderr. An isolated pre-exec launcher installs RLIMIT_FSIZE at no more than that size while preserving lower inherited soft/hard limits. This bounds every regular file written by the host, including host state, and may make it unavailable. Completion, timeout and overflow stop ordinary group descendants and reap the direct child; deliberately detached groups are outside that guarantee. This is not an aggregate disk quota, host memory limit or hostile-code sandbox.

scripts/eval_classifier.py, scripts/eval_audit_reports.py and scripts/eval_content_extraction.py are separate offline interfaces outside the public registry. Query/pair metadata rejects self-review identifiers but cannot authenticate humans. Report evaluation classifies supplied claims and leaves release gating unavailable. Extraction compares hash-checked local HTML against labeled snippets; whole-content precision/recall and downstream warning effects remain unmeasured. Synthetic success approves none of these tasks or a paid model backend.

Version 1.6.0 packages the experimental audit/native/query Python modules. The runner and evaluation scripts and workspace skills require a checkout; the wheel does not install them as console commands. Both native hosts’ recorded offline cases and controlled output/extraction checks establish separate evidence scopes. The authenticated GSC pilot separately records actual Google acquisition, partial coverage and native source reviews. The C1 follow-up records eight retained controlled client cases passing their frozen missing-count criteria. Complete error/retry scenarios, implicit interactive routing and expert human quality remain open. See the native runner guide, extraction guide, human intake and remaining action plan.

Google clients, Bing transport and IndexNow

Section titled “Google clients, Bing transport and IndexNow”

The server has three independent API clients, each with its own scope and token file:

  • GSC analytics and inspection: https://www.googleapis.com/auth/webmasters (client: searchconsole/v1)
  • Indexing API: https://www.googleapis.com/auth/indexing
  • GA4 (Analytics Data API): https://www.googleapis.com/auth/analytics.readonly

auth.py exposes three independent functions (get_searchconsole_service(), get_indexing_service(), get_ga4_service()) that each resolve credentials for their respective scope, either from a Service Account file or from a cached OAuth token stored per-scope in the OS user data directory.

The same Service Account JSON can serve all three APIs: add the SA email (client_email field) as a Viewer in GSC and in GA4 Property Access Management. No separate key file needed.

Bing uses a separate BING_WEBMASTER_API_KEY read from the process environment. This is a user-level key: one value can access every verified site visible to that Bing account, while each tool receives its target site. The key is added only inside BingWebmasterClient; it is never accepted as a tool argument or returned in metadata or errors.

BingWebmasterClient calls the Bing JSON/HTTP endpoint with method allowlists, no redirects, a 15-second operation deadline and bounded retry for 429/5xx. Remote errors are reduced to status, method and a sanitized code. The client does not serialize response bodies or request parameters into exceptions.

IndexNow is not Bing Webmaster auth. indexnow_submit receives a separate key as an argument, and that key must be verifiable on each target host or subdomain. The repository does not consume an INDEXNOW_KEY environment variable.

providers/base.py defines the minimal cross-engine row: date, query, page, clicks, impressions, CTR, position and provider_metrics. Google and Bing adapters retain their own position semantics. Bing stores avg_click_position and avg_impression_position in provider_metrics; date rows expose no position.

The Bing adapter supports one dimension at a time: query, page or date. It filters returned rows to the requested local bounds but sets window_exact=False because the API does not accept arbitrary date bounds. Country, device and bulk page-query dimensions are explicitly unsupported. Cross-engine click and impression deltas are emitted only when both providers expose equal exact observed windows. Positions remain side by side.

The redacted live canary verified 15 of 17 Bing read methods. GetKeywordStats and GetRelatedKeywords returned HTTP 400 and have no registered tools. The public Bing API also does not expose the full URL Inspection or AI Performance interface.

Since version 1.3.1, bing_query_stats aggregates query rows before ranking and limiting; daily=True returns the source daily rows. CTR is a ratio of summed counts and positions use their corresponding available click/impression weights. Anomalous source CTR remains unavailable with diagnostics even when aggregation would hide the anomaly. Bing query, page and date adapters preserve those diagnostics for comparisons as well. See Bing aggregation examples.

Since version 1.3.1, ai_visibility_audit checks ClaudeBot (training), Claude-User (user-directed retrieval) and Claude-SearchBot (search), alongside the other configured bots. These names and purposes follow Anthropic’s crawler documentation. Robots permissions are local observations, not proof of crawler activity or AI citations.

Unlike the GSC client (which uses googleapiclient.discovery and plain Python dicts), the GA4 client (BetaAnalyticsDataClient from google-analytics-data) uses protobuf request objects. Requests are constructed with typed classes from google.analytics.data_v1beta.types:

from google.analytics.data_v1beta.types import RunReportRequest, Dimension, Metric, DateRange
response = client.run_report(RunReportRequest(
property="properties/123456789",
dimensions=[Dimension(name="pagePath")],
metrics=[Metric(name="sessions")],
date_ranges=[DateRange(start_date="28daysAgo", end_date="today")],
))

Row values are accessed as row.dimension_values[i].value and row.metric_values[j].value (always strings). The helpers _f() and _i() in ga4.py coerce them to float/int with a safe fallback to 0.

For ga4_user_behavior, a single BatchRunReportsRequest wraps three sub-requests. The property field goes on the wrapper, not on each sub-request. The response exposes response.reports[0|1|2].

The GA4_PROPERTY_ID environment variable accepts either a bare numeric ID (123456789) or the full resource name (properties/123456789). get_ga4_property_id(override=None) normalises it and raises RuntimeError if absent and no override is passed, validated lazily (first tool call, never at startup).

All 8 GA4 tools and the 4 GSC+GA4 cross tools accept an optional property_id: str = None parameter. When provided, it is forwarded to get_ga4_property_id(override=property_id) and takes precedence over the env var. This allows querying multiple GA4 properties from a single MCP instance without config changes.

Token files are JSON, not pickle. google.oauth2.credentials.Credentials provides .to_json() and .from_authorized_user_info() for round-tripping safely.

The key technical improvement over Suganthan-Mohanadasan/Suganthans-GSC-MCP is in tools/indexing.py.

Suganthan’s implementation sends one HTTP request per URL in a for loop. For 100 URLs that is 100 separate HTTPS round trips.

submit_batch here uses service.new_batch_http_request(), which bundles up to 100 individual requests into a single multipart/mixed HTTP request sent to indexing.googleapis.com/batch. The response is a single multipart body that the client library demultiplexes, calling a per-request callback for each result.

def _make_callback(results: list, url: str):
def callback(request_id, response, exception):
if exception:
results.append({"url": url, "status": "error", "error": str(exception)})
else:
results.append({"url": url, "status": "submitted"})
return callback

The _make_callback(url) factory is intentional. A naive closure inside a loop would capture url by reference, so all callbacks would record the last URL in the loop. The factory captures it by value at construction time.

For more than 100 URLs, _submit_batch_impl loops over 100-item chunks, creating one batch request per chunk.

Every tool returns json.dumps(with_meta(data, tool=..., params=...)). The _meta block gives Claude the name of the tool that produced the data and the call parameters, which helps it reason about what it has already fetched and avoid redundant calls.

{
"count": 3,
"properties": [...],
"_meta": {
"tool": "list_properties",
"params": {}
}
}

quick_wins, seo_striking_distance and prune_candidates accept engine="bing" and consume normalized Bing rows. A missing Bing position excludes a row only from analyses that require position. prune_candidates can still classify a page from measured clicks and impressions, but it never treats missing impressions as proof that the page is not indexed.

Four analyses return structured refusals without a provider call: traffic_drops and seo_lost_queries require exact adjacent periods; check_alerts and seo_cannibalization require the bulk page-query dimension. No N+1 fallback synthesizes those missing contracts.

The Bing family has 15 reads and 4 writes. Every write validates a public target URL and requires the target to share the site’s origin. bing_url_submit and bing_feed_submit can report an accepted request, with indexed=false and indexed_semantics="not_verified". bing_urls_submit_batch currently refuses before SubmitUrlBatch because DailyQuota and MonthlyQuota are observed integers whose total-versus-remaining semantics remain UNKNOWN. bing_feed_remove requires confirm=true, a feed-shaped URL and a pre-existing matching feed.

Live-runtime evidence remains bounded. Data freshness is unknown; a non-empty GetCrawlIssues item shape has not been observed; nested backlink item schemas and RemoveFeed remain UNVERIFIED_RUNTIME. No Bing write was executed against a production site during validation. HTTP 200, an accepted submission or a last crawl date does not prove current indexation or an SEO effect.

retry.py provides a with_retry(max_retries=3, base_delay=1.0) decorator. It catches two families of transient errors and retries with exponential backoff (base_delay * 2^attempt):

  • googleapiclient.errors.HttpError on status codes {429, 500, 502, 503, 504}: GSC and Indexing API errors
  • google.api_core.exceptions subtypes ServiceUnavailable, ResourceExhausted, InternalServerError, BadGateway, RetryError: GA4 gRPC errors

It does not retry on 4xx errors other than 429 (those are client errors, not transient).

The decorator is applied at the function level rather than the tool level. _fetch_rows in analytics.py is the main call site: since all analytics and SEO tools use it as their data layer, a single @with_retry() there covers those tools entirely. GA4 tools each carry their own @with_retry() since they call client.run_report() / client.batch_run_reports() directly. Properties, inspection, and sitemap tools are also individually decorated.

QuotaTracker is a simple in-memory counter with a configurable limit and warn threshold. The Indexing API has a default quota of 200 requests per day. submit_batch calls quota.check(n) before sending (raises RuntimeError if the batch would exceed the limit) and quota.consume(n) after a successful batch. When quota.should_warn() returns true, the tool adds "quota_warning": true to the JSON response.

The tracker resets on server restart. For persistent quota tracking across sessions, a file-backed counter would be needed.

The Google API Python client (google-api-python-client) is the canonical, officially maintained client for these APIs. It exposes service.new_batch_http_request() natively, which is what makes true HTTP batching possible without implementing the multipart/mixed wire format by hand. The Go client library (google.golang.org/api) and the Rust ecosystem for Google APIs rely on unofficial or generated clients that do not provide this abstraction.

FastMCP also has first-class Python support with a decorator-based API that keeps tool registration minimal. The only real trade-off vs a compiled language is startup time (a few hundred milliseconds), which does not matter for a locally-run MCP server called interactively.

Three algorithmic patterns introduced in Phase 1 reuse _fetch_rows and _date_range from analytics.py without adding dependencies.

Two-period comparison. Both tools compare adjacent windows of days length. Since version 1.3.1, traffic_drops ends its current window three days before date.today() to allow for GSC reporting lag; seo_lost_queries retains its current window ending today. traffic_drops returns metric-based diagnosis_candidates, their diagnosis_status and previous/current metrics. Ranking and CTR candidates require impressions in both periods; demand decline requires observed impression decline. These rules do not prove causes. Missing current query rows appear in unavailable_queries with metrics_current=null; absence does not establish zero traffic. CTR and position are null when impressions are zero. The lost-query tool’s separate previous-period iteration and prev_clicks >= 5 guard are unchanged.

HHI conflict score. seo_cannibalization queries with dimensions=["query","page"] so each row carries both keys. Rows are grouped by query; for each group with more than one page, the Herfindahl-Hirschman Index measures concentration: hhi = sum((clicks_i / total_clicks)^2) and conflict_score = 1 - hhi. A score near 0 means one page dominates (no real conflict); near 1 means clicks are split evenly. When total_clicks == 0 the function falls back to hhi = 1/n (uniform share), avoiding division by zero while still surfacing impression-heavy splits. Only groups with conflict_score > 0.1 are returned.

Since version 1.3.1, seo_cannibalization excludes queries containing site:, intitle:, inurl: or filetype: search operators by default. excluded_search_operator_queries counts distinct excluded query strings. include_search_operators=True retains them and records the opt-in in metadata. Operator queries can intentionally return several pages, so a split alone does not establish an SEO conflict.

Z-score anomaly detection. analytics_anomalies queries with dimensions=["date"] to get a daily click series, then uses statistics.pstdev (population standard deviation, not sample) because the series is a complete known dataset rather than a sample from a larger population. The guard if std == 0: return [] handles flat series and all-zero traffic, both common on low-traffic sites, without raising ZeroDivisionError.

In release 1.3.0, traffic_health_check resolves concrete GSC dates and passes them to GA4. Each source reports availability, requested/reported windows, filters and coverage. The ratio requires compatible covered inputs; empty responses remain null and explicit-zero rows stay zero. Calendar boundaries and property mapping remain unverified. Other combined reports still use independent windows.

ga4_ai_referrals checks property-specific dimension/metric compatibility and reads at most 10,000 source/medium/landing-page rows with sessions, engaged sessions and keyEvents. Confirmed source rules are dated; candidate sources are excluded from confirmed totals. All-source shares require complete unrestricted coverage. The output measures attributed visits, not citations. See the evidence contract.

with_meta adds concrete per-field JSON Pointer evidence descriptors from a tool/path inventory. No whole-output basis is inferred for mixed reports, and no numeric confidence is fabricated. Existing metrics and source identities retain their meanings. The shared HTML trust observer does not execute or rewrite fetched instructions; a narrow challenge detector protects schema and editorial assessment.

cross.py does not call the Google APIs directly. It calls the high-level tool functions from analytics.py and ga4.py, parses their JSON string output with json.loads, and then joins the results.

The join key is _normalize_url(url), a small helper that strips scheme, host, query string and trailing slash so that a GSC absolute URL (https://example.com/blog/) and a GA4 landing page path (/blog?ref=home) resolve to the same key (/blog).

ga4_organic_landing_pages does not expose engagement_rate directly (it exposes engaged_sessions and sessions). The cross module derives it as engaged_sessions / sessions, which is the GA4 native formula. This avoids modifying the Phase 2 tool surface.

opportunity_score weights three signals: impressions (log-scaled, 10x), engagement rate (100x, linear), and conversions (log-scaled, 20x). The log scaling compresses high-impression pages while still surfacing low-traffic pages with strong engagement. None fields fall back to 0 via (value or 0), so GSC-only and GA4-only pages score on the signals they have.

Tests for cross tools patch gsc_mcp.tools.cross.get_search_analytics and gsc_mcp.tools.cross.ga4_organic_landing_pages to return JSON strings, matching what the actual functions return. The GA4 protobuf fixtures from conftest.py are not needed.

crux.py calls the Chrome UX Report API via httpx (not the Google API Python client, which does not cover this API). Two endpoints: :queryRecord for the latest snapshot, :queryHistoryRecord for 25 weeks of weekly p75 series. Both require a plain Google API key (CRUX_API_KEY), not a service account or OAuth token. The key is read from env by _crux_api_key(), which raises RuntimeError if absent.

A 404 response means the URL has insufficient field data; crux_page_vitals returns verdict="not_enough_data" without raising. The form_factor parameter (default "ALL_FORM_FACTORS") adds a formFactor key to the POST body only when not the default, matching the CrUX API contract.

CWV thresholds used for rating:

MetricGoodPoor
LCP<= 2500ms> 4000ms
INP<= 200ms> 500ms
CLS<= 0.1> 0.25
FCP<= 1800ms> 3000ms
TTFB<= 800ms> 1800ms

sitemap_audit in sitemaps.py fetches XML via httpx and parses with defusedxml.ElementTree (not stdlib xml.etree.ElementTree). The stdlib parsers are vulnerable to XXE (external entity injection) and billion-laughs attacks when processing untrusted external XML. defusedxml is a drop-in replacement that disables those features.

For sitemap index files, child sitemap URLs are validated against the origin of the parent sitemap before fetching. This prevents SSRF: a poisoned sitemap index could otherwise point <loc> entries at http://169.254.169.254/ (AWS metadata) or internal services. follow_redirects=False on the httpx client prevents redirect-based SSRF pivots.

The cross-reference uses get_search_analytics with dimensions=["page"] and row_limit=5000 over 90 days. URLs are normalised with .rstrip("/").lower() before set intersection. Missing sample is capped at 20 items to keep the response payload bounded.

technical.py uses html.parser (Python stdlib HTMLParser) to extract JSON-LD blocks, avoiding an external dependency. The _JsonLdExtractor subclass tracks when it’s inside a <script type="application/ld+json"> tag and accumulates text chunks, then calls json.loads on the joined string at the closing tag. JSON-LD blocks that contain a top-level array are expanded so each item is validated individually.

The tool makes no Google API calls and requires no auth. httpx is used for the page fetch with follow_redirects=True (legitimate redirects are expected on public URLs).

editorial_audit uses a packaged versioned FR/EN house-style profile and the existing bounded same-site safe fetcher. It returns rule warnings over eligible parsed passages, source locations, coverage limits and rewriting guidance. The profile is independent of content_quality, indexing and ranking scores. It never calls a classifier or writes content. See editorial audit and rewrite profile.

Release 1.4.0 contains 89 tools, adding seo_change_impact, rewrite_fidelity_check, search_weekday_reference and crawl_import_preview to the 85-tool release 1.3.1 surface. Releases 1.3.0 and 1.3.1 each contain 85 tools. change_impact.py retains caller events and reuses search_change_breakdown coverage without persisting events or attributing causality. IANA zones use system data or the packaged tzdata fallback.

editorial_drafts.py adapts bounded caller text/Markdown into the existing editorial rule core; it performs no fetch, execution or file read. rewrite.py compares protected literals and qualifiers with local lexical anchors; semantic dimensions remain unassessed.

reporting.py attaches a deterministic snapshot fingerprint to search_change_breakdown without storing a report. Its optional byte budget covers the complete UTF-8 JSON envelope and metadata; the CLI preserves returned budget JSON; a ceiling too small for the minimum envelope fails explicitly without JSON. One requested dimension is valid.

traffic_reference.py shifts equal windows by a whole number of weeks to keep matching weekdays and no overlap, with a final-data request ending no later than Pacific today minus three days. It does not establish annual or causal effects. crawl_import.py previews caller-provided SiteOne JSON in memory under fixed bounds, without crawling, files, network access, credentials or a GSC join. See bounded audit workflows and editorial workflows for signatures and limits.