gsc-mcp-tools 0.4.2__tar.gz

gsc_mcp_tools-0.4.2/.claude/settings.local.json

@@ -0,0 +1,53 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(rtk ls *)",
+      "Bash(rtk read *)",
+      "mcp__gsc-mcp__list_properties",
+      "mcp__gsc-mcp__list_sitemaps",
+      "mcp__gsc-mcp__get_performance_overview",
+      "mcp__gsc-mcp__check_alerts",
+      "mcp__gsc-mcp__batch_url_inspection",
+      "mcp__gsc-mcp__inspect_url",
+      "Bash(rtk pytest *)",
+      "Bash(echo \"---EXIT $?\")",
+      "Bash(rtk proxy *)",
+      "mcp__gsc-mcp__get_search_analytics",
+      "mcp__gsc-mcp__compare_search_periods",
+      "mcp__gsc-mcp__quick_wins",
+      "mcp__gsc-mcp__traffic_drops",
+      "mcp__gsc-mcp__submit_url",
+      "Bash(rtk git *)",
+      "Bash(git add *)",
+      "Bash(git commit -m ' *)",
+      "Bash(rtk pip *)",
+      "Bash(python -c \"from google.analytics.data_v1beta import BetaAnalyticsDataClient; print\\('GA4 lib OK'\\)\")",
+      "Bash(python -c \"from gsc_mcp.server import mcp; print\\('server import OK'\\)\")",
+      "Bash(rtk grep *)",
+      "Bash(python3 *)",
+      "Bash(printenv)",
+      "Bash(git remote *)",
+      "Bash(git config *)",
+      "Bash(hatch build *)",
+      "Bash(/tmp/test-gsc-mcp/bin/pip install *)",
+      "Bash(/tmp/test-gsc-mcp/bin/gsc-mcp --help)",
+      "Bash(/tmp/test-gsc-mcp/bin/python *)",
+      "Bash(rtk gh *)",
+      "Bash(gh repo *)",
+      "Bash(git tag *)",
+      "Bash(gh release *)",
+      "Bash(GSC_SERVICE_ACCOUNT_PATH=/Users/florianbruniaux/bel-etage-analytics-c4db99d1b930.json GSC_SKIP_OAUTH=true /Users/florianbruniaux/Sites/perso/google-search-console-mcp/.venv/bin/python -m gsc_mcp.server)",
+      "Bash(kill %1)",
+      "Bash(wait)",
+      "Bash(/Users/florianbruniaux/Sites/perso/google-search-console-mcp/.venv/bin/pip install *)",
+      "Bash(GSC_SERVICE_ACCOUNT_PATH=/Users/florianbruniaux/bel-etage-analytics-c4db99d1b930.json GSC_SKIP_OAUTH=true /Users/florianbruniaux/Sites/perso/google-search-console-mcp/.venv/bin/python *)",
+      "mcp__gsc-mcp__get_capabilities",
+      "mcp__gsc-mcp__traffic_health_check",
+      "Bash(.venv/bin/pytest tests/test_ga4.py tests/test_cross.py -v)",
+      "Bash(.venv/bin/pytest tests/ -q)",
+      "Bash(git commit *)",
+      "mcp__gsc-mcp__page_analysis",
+      "Bash(rtk find *)"
+    ]
+  }
+}

gsc_mcp_tools-0.4.2/.env.example

@@ -0,0 +1,19 @@
+# Google Search Console MCP — environment variables
+# Copy to .env and fill in your values
+
+# Path to your OAuth2 client credentials JSON (from Google Cloud Console)
+# Required for OAuth flow (default auth method)
+GSC_CREDENTIALS_PATH=/path/to/credentials.json
+
+# Path to a Service Account JSON key file
+# Alternative to OAuth — set this to skip the browser auth flow
+# GSC_SERVICE_ACCOUNT_PATH=/path/to/service-account.json
+
+# Skip OAuth flow entirely (requires GSC_SERVICE_ACCOUNT_PATH)
+# GSC_SKIP_OAUTH=false
+
+# Allow destructive operations (sitemap delete, etc.) — disabled by default
+# GSC_ALLOW_DESTRUCTIVE=false
+
+# Data state for search analytics: "final" or "all" (default: final)
+# GSC_DATA_STATE=final

gsc_mcp_tools-0.4.2/.gitignore

@@ -0,0 +1,13 @@
+.env
+*.pyc
+__pycache__/
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/
+token.pickle
+token_*.json
+*client_secret*.json
+*credentials*.json
+*service_account*.json
+.claudedocs/

gsc_mcp_tools-0.4.2/.idea/.gitignore

@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

gsc_mcp_tools-0.4.2/.idea/google-search-console-mcp.iml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

gsc_mcp_tools-0.4.2/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/google-search-console-mcp.iml" filepath="$PROJECT_DIR$/.idea/google-search-console-mcp.iml" />
+    </modules>
+  </component>
+</project>

gsc_mcp_tools-0.4.2/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

gsc_mcp_tools-0.4.2/.idea/workspace.xml

@@ -0,0 +1,97 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="AutoImportSettings">
+    <option name="autoReloadType" value="SELECTIVE" />
+  </component>
+  <component name="ChangeListManager">
+    <list default="true" id="463c5a88-8b49-4583-a93b-5bde7abb04de" name="Changes" comment="">
+      <change beforePath="$PROJECT_DIR$/.gitignore" beforeDir="false" afterPath="$PROJECT_DIR$/.gitignore" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/docs/architecture.md" beforeDir="false" afterPath="$PROJECT_DIR$/docs/architecture.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/gsc_mcp/auth.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/gsc_mcp/auth.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/gsc_mcp/retry.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/gsc_mcp/retry.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/gsc_mcp/tools/analytics.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/gsc_mcp/tools/analytics.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/gsc_mcp/tools/ga4.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/gsc_mcp/tools/ga4.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/gsc_mcp/tools/indexing.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/gsc_mcp/tools/indexing.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/gsc_mcp/tools/inspection.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/gsc_mcp/tools/inspection.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/gsc_mcp/tools/properties.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/gsc_mcp/tools/properties.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/gsc_mcp/tools/seo.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/gsc_mcp/tools/seo.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/gsc_mcp/tools/sitemaps.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/gsc_mcp/tools/sitemaps.py" afterDir="false" />
+    </list>
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="CopilotPersistence">
+    <persistenceIdMap>
+      <entry key="_/Users/florianbruniaux/Sites/perso/google-search-console-mcp" value="3FP6uMgTYPCWF1rcWtp89wMwXqi" />
+    </persistenceIdMap>
+  </component>
+  <component name="EmbeddingIndexingInfo">
+    <option name="cachedIndexableFilesCount" value="3722" />
+    <option name="fileBasedEmbeddingIndicesEnabled" value="true" />
+  </component>
+  <component name="Git.Settings">
+    <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
+  </component>
+  <component name="McpProjectServerCommands">
+    <commands />
+    <urls />
+  </component>
+  <component name="ProjectColorInfo">{
+  &quot;associatedIndex&quot;: 7,
+  &quot;fromUser&quot;: false
+}</component>
+  <component name="ProjectId" id="3FP6uMgTYPCWF1rcWtp89wMwXqi" />
+  <component name="ProjectViewState">
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent">{
+  &quot;keyToString&quot;: {
+    &quot;ModuleVcsDetector.initialDetectionPerformed&quot;: &quot;true&quot;,
+    &quot;RunOnceActivity.MCP Project settings loaded&quot;: &quot;true&quot;,
+    &quot;RunOnceActivity.ShowReadmeOnStart&quot;: &quot;true&quot;,
+    &quot;RunOnceActivity.TerminalTabsStorage.copyFrom.TerminalArrangementManager.252&quot;: &quot;true&quot;,
+    &quot;RunOnceActivity.git.unshallow&quot;: &quot;true&quot;,
+    &quot;RunOnceActivity.typescript.service.memoryLimit.init&quot;: &quot;true&quot;,
+    &quot;codeWithMe.voiceChat.enabledByDefault&quot;: &quot;false&quot;,
+    &quot;com.intellij.ml.llm.matterhorn.ej.ui.settings.DefaultModelSelectionForGA.v1&quot;: &quot;true&quot;,
+    &quot;git-widget-placeholder&quot;: &quot;main&quot;,
+    &quot;javascript.preferred.runtime.type.id&quot;: &quot;node&quot;,
+    &quot;junie.onboarding.icon.badge.shown&quot;: &quot;true&quot;,
+    &quot;last_opened_file_path&quot;: &quot;/Users/florianbruniaux/Sites/perso/google-search-console-mcp&quot;,
+    &quot;node.js.detected.package.eslint&quot;: &quot;true&quot;,
+    &quot;node.js.detected.package.tslint&quot;: &quot;true&quot;,
+    &quot;node.js.selected.package.eslint&quot;: &quot;(autodetect)&quot;,
+    &quot;node.js.selected.package.tslint&quot;: &quot;(autodetect)&quot;,
+    &quot;nodejs_package_manager_path&quot;: &quot;npm&quot;,
+    &quot;to.speed.mode.migration.done&quot;: &quot;true&quot;,
+    &quot;vue.rearranger.settings.migration&quot;: &quot;true&quot;
+  }
+}</component>
+  <component name="SharedIndexes">
+    <attachedChunks>
+      <set>
+        <option value="bundled-js-predefined-d6986cc7102b-31caf2ab9e3c-JavaScript-WS-261.25134.101" />
+      </set>
+    </attachedChunks>
+  </component>
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <changelist id="463c5a88-8b49-4583-a93b-5bde7abb04de" name="Changes" comment="" />
+      <created>1781964578952</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1781964578952</updated>
+      <workItem from="1781964579955" duration="2110000" />
+      <workItem from="1782057449022" duration="7333000" />
+      <workItem from="1782214079804" duration="3000" />
+    </task>
+    <servers />
+  </component>
+  <component name="TypeScriptGeneratedFilesManager">
+    <option name="version" value="3" />
+  </component>
+</project>

gsc_mcp_tools-0.4.2/.python-version

@@ -0,0 +1 @@
+3.13.0

gsc_mcp_tools-0.4.2/.superpowers/sdd/progress.md

@@ -0,0 +1,17 @@
+# gsc-mcp v0.5.0 SDD Progress
+
+Branch: main
+Started: 2026-06-23
+MERGE_BASE: 587c08cee (to be confirmed at start of each review)
+
+## Tasks
+
+- [ ] Task 1: Phase 1 - GA4 hostname + country filters
+- [ ] Task 2: Phase 2 - CrUX tools (crux_page_vitals, crux_history)
+- [ ] Task 3: Phase 3 - sitemap_audit tool
+- [ ] Task 4: Phase 4 - schema_validate tool
+- [ ] Task 5: Phase 5 - version bump + capabilities + docs
+
+## Log
+
+(entries appended as tasks complete)

gsc_mcp_tools-0.4.2/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+## [0.4.2] - 2026-06-22
+
+### Added
+
+- Tous les tools GA4 (`ga4_organic_landing_pages`, `ga4_traffic_sources`, `ga4_page_performance`, `ga4_realtime`, `ga4_user_behavior`, `ga4_conversion_funnel`) et les tools cross (`traffic_health_check`, `page_analysis`) acceptent un paramètre optionnel `property_id: str = None`. Quand fourni, il override `GA4_PROPERTY_ID` sans modifier la config. Permet de requêter plusieurs properties GA4 depuis une seule instance MCP.
+- `get_ga4_property_id(override=None)` dans `auth.py` : accepte un override direct, court-circuite la lecture de l'env var. Sans override, comportement identique à avant.
+- 4 nouveaux tests : `test_get_ga4_property_id_override_takes_precedence`, `test_get_ga4_property_id_override_no_env_needed`, `test_thc_property_id_propagated`, `test_pa_property_id_propagated`
+
+## [0.4.1] - 2026-06-22
+
+Corrections de cohérence et consolidation interne : pas de nouveaux tools.
+
+### Fixed
+
+- `get_capabilities` retournait 18 tools sur les 32 réellement disponibles. Les 14 manquants (`analytics_anomalies`, `seo_striking_distance`, `seo_cannibalization`, `seo_lost_queries`, `sitemaps_delete`, `sitemaps_get`, 6 tools GA4, `traffic_health_check`, `page_analysis`) sont maintenant listés
+- `inspect_url`, `batch_url_inspection`, `check_indexing_issues` appelaient `webmasters/v3`, qui n'expose pas `urlInspection`. Ces trois tools levaient une `AttributeError` au runtime sur chaque appel. Corrigé en passant sur `searchconsole/v1` (API qui expose la ressource `urlInspection`)
+- `traffic_health_check` et `page_analysis` incluent maintenant un champ `note` dans leur réponse JSON pour avertir que GSC a un décalage de 3 jours vs GA4, les ratios sont donc approximatifs
+- `ga4_organic_landing_pages` ajoute un champ `note` quand le nombre de résultats atteint la limite, signalant une troncature potentielle
+
+### Changed
+
+- Tous les tools GSC (analytics, SEO, sitemaps, properties) consolidés sur `searchconsole/v1`. Le client `webmasters/v3` (`get_gsc_service`) est supprimé de `auth.py`. `searchconsole/v1` expose les mêmes ressources `sites`, `searchanalytics`, `sitemaps` en plus de `urlInspection`
+
+### Tests
+
+- Couverture `quick_wins` améliorée : 4 nouveaux cas couvrant les pages à CTR zéro avec impressions suffisantes, l'exclusion sous le seuil d'impressions et l'exclusion des pages déjà au benchmark de CTR
+
+## [0.4.0] - 2026-06-22
+
+Phase 3: 2 tools cross-platform GSC+GA4, nouveau module `cross.py`.
+
+### Added
+
+- `traffic_health_check(site, days)`: compare les clics GSC agrégés avec les sessions organiques GA4 pour détecter les écarts de tracking. Retourne un statut parmi `no_gsc_data`, `tracking_gap` (ratio < 0.6), `filter_issue` (ratio > 1.3) ou `healthy`. GA4 interrogé avec `limit=10000` pour éviter les sous-comptages sur les gros sites
+- `page_analysis(site, days, limit)`: jointure page par page entre GSC (dimensions=["page"]) et GA4 (landing pages organiques). Les pages présentes dans une seule source sont incluses avec les champs manquants à `None`. Chaque page reçoit un `opportunity_score = log10(impressions+1)*10 + engagement_rate*100 + log10(conversions+1)*20`, trié décroissant, tronqué à `limit`
+- `_normalize_url(url)` helper interne: ramène URLs absolues (GSC) et paths GA4 au même chemin nu, sans scheme, host, query ni slash final, pour fiabiliser la jointure
+- `engagement_rate` dérivé dans `cross.py` comme `engaged_sessions/sessions` (formule GA4 native), sans modifier la sortie de `ga4_organic_landing_pages`
+- 24 nouveaux tests dans `tests/test_cross.py`, dont les boundaries 0.6 et 1.3 du ratio, les cas GSC-only, GA4-only, trailing slash et query string
+
+### Changed
+
+- Tool count: 30 vers 32
+
+## [0.3.0] - 2026-06-22
+
+Phase 2: 6 new GA4 tools, new dependency, new environment variable.
+
+### Added
+
+- `ga4_organic_landing_pages(start_date, end_date, limit)`: sessions, engaged sessions, bounce rate, average session duration, conversions and revenue for organic landing pages. Uses the `sessionMedium=organic` filter on `landingPagePlusQueryString`
+- `ga4_traffic_sources(start_date, end_date)`: sessions and conversions broken down by channel group, source and medium
+- `ga4_page_performance(start_date, end_date, page_path)`: 7 metrics per page path (page views, active users, average session duration, engagement rate, bounce rate, conversions, revenue). Optional `page_path` parameter adds a CONTAINS filter
+- `ga4_realtime()`: active users right now, by screen name, country and device. No date range, uses `run_realtime_report` directly
+- `ga4_user_behavior(start_date, end_date)`: single `batch_run_reports` call returning three breakdowns (by device, by country top 20, by user type new/returning)
+- `ga4_conversion_funnel(start_date, end_date, event_name)`: two sequential `run_report` calls. First lists pages with conversions > 0; second lists events, optionally filtered by exact event name
+- New dependency: `google-analytics-data>=0.18.0` (Google Analytics Data API v1beta, protobuf-based client)
+- New environment variable: `GA4_PROPERTY_ID` (numeric property ID, e.g. `123456789`). Validated lazily on first GA4 tool call, never at startup. GSC-only users are not affected
+- `get_ga4_service()` and `get_ga4_property_id()` in `auth.py`, reusing the same `_resolve_creds` path as GSC and Indexing clients
+
+### Changed
+
+- Tool count: 24 → 30
+
+## [0.2.0] - 2026-06-22
+
+Phase 1: 6 new tools, no new dependencies.
+
+### Added
+
+- `seo_striking_distance(site, days, min_impressions)`: queries in positions 8-15 sorted by impressions desc. Separate band from `quick_wins` (4-15), intended for queries one push away from page 1
+- `seo_cannibalization(site, days, min_impressions)`: detects queries split across multiple pages using an HHI conflict score (`1 - sum(share²)`). Zero-click groups use uniform `1/n` fallback to avoid division by zero. Filters on per-query total impressions, not per-page
+- `seo_lost_queries(site, days)`: flags queries with a click drop ≥ 80% vs the previous period, requiring at least 5 previous clicks. Iterates over the previous period to catch fully-vanished queries. Same two-window no-lag pattern as `traffic_drops`
+- `analytics_anomalies(site, days, threshold)`: Z-score anomaly detection on daily clicks via `statistics.pstdev`. Returns `anomalies = []` when std is zero (constant or all-zero series) to handle low-traffic sites safely
+- `sitemaps_delete(site, sitemap_url)`: deletes a sitemap with a safety check before any API call (URL must end with `.xml` or contain `/sitemap`, raises `ValueError` otherwise)
+- `sitemaps_get(site, sitemap_url)`: fetches a single sitemap resource and normalises it to the same flat shape as `list_sitemaps` (warnings and errors coerced to int)
+- 62 new tests (35 SEO, 15 sitemaps, 9 analytics anomalies): all mocked, no API calls
+
+### Changed
+
+- Tool count: 18 → 24
+
+## [0.1.0] - 2026-06-20
+
+Initial release.
+
+### Added
+
+- 18 MCP tools across 6 categories: meta, properties, analytics, SEO, inspection, indexing, sitemaps
+- `submit_batch` using true HTTP multipart batch via `new_batch_http_request()`, chunked at 100 URLs per request. Avoids the late-binding closure bug with a `_make_callback(url)` factory pattern
+- Dual OAuth scope architecture: separate clients for GSC (`auth/webmasters`) and Indexing API (`auth/indexing`), because the Indexing API rejects webmasters tokens
+- OAuth flow with token stored as JSON (`google.oauth2.credentials.Credentials.to_json()`) instead of pickle
+- Service Account support as an alternative to OAuth (set `GSC_SERVICE_ACCOUNT_PATH`)
+- Exponential backoff retry on HTTP 429/500/502/503/504 via `with_retry()` decorator, no retry on 404
+- In-memory quota tracker (`QuotaTracker`) with configurable limit and warn threshold (warns at 180/200 by default)
+- `with_meta()` wrapper on all tool outputs: every response includes a `_meta` block with tool name and call parameters, so Claude has full context on what was fetched
+- `quick_wins` tool scoring CTR opportunity vs benchmark by SERP position
+- `check_indexing_issues` categorizing URLs into `not_indexed`, `robots_blocked`, `fetch_error`, `canonical_issue`, `indexed`
+- `traffic_drops` diagnosing drops as `ranking_loss`, `ctr_collapse`, or `demand_decline`
+- Full test suite: 52 tests, fully mocked, no Google API calls required

gsc_mcp_tools-0.4.2/CLAUDE.md

@@ -0,0 +1,62 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Requires Python 3.11+
+python3 --version  # must be 3.11 or higher
+
+# Install (dev mode with test deps)
+pip install -e ".[dev]"
+
+# Run the MCP server
+gsc-mcp
+# or
+python -m gsc_mcp.server
+
+# Run all tests
+pytest tests/ -v
+
+# Run a single test file
+pytest tests/test_analytics.py -v
+
+# Run a specific test by name
+pytest tests/ -k "test_submit_batch" -v
+```
+
+## Architecture
+
+**Entry point**: `src/gsc_mcp/server.py` creates a `FastMCP("gsc-mcp")` instance and registers all 32 tools via `mcp.tool()()`. No dynamic discovery; every tool is explicitly imported and registered here. Adding a new tool means: implement it in the relevant `tools/` module, import it in `server.py`, and register it.
+
+**Auth layer** (`auth.py`): Three separate credential pairs: GSC API (`searchconsole/v1`), Indexing API (`indexing/v3`), and GA4 (`analytics.readonly`). Resolution order: if `GSC_SERVICE_ACCOUNT_PATH` is set, use service account credentials. Otherwise, fall through to OAuth with token cached as JSON (not pickle) at the OS user data dir (`~/Library/Application Support/gsc-mcp/` on macOS). Token files: `token_gsc.json`, `token_indexing.json`, `token_ga4.json`. `get_ga4_property_id(override=None)` accepts an optional override string that bypasses `GA4_PROPERTY_ID`, enabling per-call multi-property support.
+
+**Tools** (`src/gsc_mcp/tools/`): Eight modules, each owns a logical domain (analytics, cross, ga4, indexing, inspection, properties, seo, sitemaps). Every tool function is a plain Python function (no class, no decorator) registered by `server.py`. All return JSON strings via `json.dumps(with_meta(...))`.
+
+**Cross-platform pattern** (`cross.py`): `traffic_health_check` and `page_analysis` compose the high-level functions from `analytics.py` and `ga4.py`. They call those functions, parse their JSON strings with `json.loads`, then join on `_normalize_url` (strips scheme/host/query/trailing-slash so GSC absolute URLs and GA4 paths match). `engagement_rate` is derived as `engaged_sessions/sessions` because `ga4_organic_landing_pages` does not expose it directly.
+
+**Output contract** (`meta.py`): Every tool wraps its response dict with `with_meta(data, tool=..., params=...)`, which appends a `_meta` block (`{"tool": "<name>", "params": {...}}`). Any new tool must follow this pattern.
+
+**Retry** (`retry.py`): `@with_retry(max_retries=3, base_delay=1.0)` wraps Google API calls. Retries on 429/500/502/503/504 with exponential backoff (`base_delay * 2^attempt`). Other HTTP errors propagate immediately.
+
+**Quota tracking** (`quota.py` + `indexing.py`): `QuotaTracker` is a module-level singleton in `indexing.py` that tracks Indexing API usage within a single process lifetime (200 req/day limit, warns at 180). It does not persist across restarts; restarting the server resets the counter.
+
+**Batching** (`indexing.py`): `submit_batch` uses `svc.new_batch_http_request()` chunked at 100 URLs per HTTP request. This is a true multipart batch, not a sequential loop. Callbacks collect per-URL results.
+
+## Test conventions
+
+All tests are fully mocked (no real Google API calls). `tests/conftest.py` defines two shared fixtures:
+- `mock_gsc_service`: MagicMock wired for `sites`, `searchanalytics`, `sitemaps`, `urlInspection`
+- `mock_indexing_service`: MagicMock with a working `new_batch_http_request()` implementation that fires callbacks synchronously
+
+Tests patch `get_searchconsole_service` / `get_indexing_service` / `get_ga4_service` at the call site (e.g., `gsc_mcp.tools.analytics.get_searchconsole_service`) and inject the fixture as the return value. GA4 tests also use an `autouse` fixture to set `GA4_PROPERTY_ID`, since `get_ga4_property_id()` raises `RuntimeError` if the env var is absent and no `override` is passed.
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `GSC_SERVICE_ACCOUNT_PATH` | Path to service account JSON (preferred for automation) |
+| `GSC_CREDENTIALS_PATH` | Path to OAuth Desktop client JSON (interactive OAuth flow) |
+| `GSC_SKIP_OAUTH` | Set to `true` to disable OAuth fallback (requires SA path) |
+| `GA4_PROPERTY_ID` | Numeric GA4 property ID (e.g. `123456789`). Required for GA4 tools only, validated lazily |

gsc_mcp_tools-0.4.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Florian Bruniaux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.