easygsc 0.2.0__py3-none-any.whl

easygsc/__init__.py

@@ -0,0 +1,3 @@
+"""easygsc: minimal, transparent, read-only MCP server for Google Search Console."""
+
+__version__ = "0.2.0"

easygsc/allowlist.py

@@ -0,0 +1,74 @@
+"""Transport-level network allowlist: the single chokepoint for all outbound HTTP.
+
+The guard lives at the ``requests`` transport layer (``Session.send``) because
+several independent sessions exist: our API calls, ``google-auth``'s token
+refresh session, and ``InstalledAppFlow``'s ``OAuth2Session``. Redirects are
+covered: ``requests`` re-calls ``Session.send`` for every hop (its HTTPAdapter
+sends with ``redirect=False``, so urllib3 never follows redirects internally)
+and the final response URL is checked as defense in depth.
+"""
+
+from __future__ import annotations
+
+import types
+from urllib.parse import urlparse
+
+import requests
+from google.auth.transport.requests import AuthorizedSession as _AuthorizedSession
+from google.auth.transport.requests import Request as _GoogleAuthRequest
+
+ALLOWED_HOSTS = frozenset(
+    {
+        "www.googleapis.com",  # webmasters/v3 REST API
+        "searchconsole.googleapis.com",  # urlInspection/index:inspect
+        "oauth2.googleapis.com",  # token refresh and code exchange
+        "accounts.google.com",  # OAuth authorization flow
+    }
+)
+
+
+class DisallowedHostError(Exception):
+    """Raised when an outgoing request targets a host outside ALLOWED_HOSTS."""
+
+
+def check_allowed(url: str) -> str:
+    """Raise DisallowedHostError unless *url*'s host is allowed. Returns the host."""
+    host = (urlparse(url).hostname or "").lower().rstrip(".")
+    if host not in ALLOWED_HOSTS:
+        raise DisallowedHostError(
+            f"Blocked request to non-allowed host {host or '(none)'!r}: {url}. "
+            f"easygsc only talks to: {', '.join(sorted(ALLOWED_HOSTS))}."
+        )
+    return host
+
+
+class GuardedSessionMixin:
+    """Mixin overriding send() to enforce the allowlist, redirects included."""
+
+    def send(self, request, **kwargs):  # type: ignore[override]
+        check_allowed(request.url)
+        # Explicit Session.send: works for real subclasses (MRO) and for
+        # instances guarded via attach_guard (MethodType), where zero-arg
+        # super() cannot resolve. Neither AuthorizedSession nor OAuth2Session
+        # overrides send(), so nothing is bypassed.
+        response = requests.Session.send(self, request, **kwargs)
+        check_allowed(response.url)  # defense in depth against below-send redirects
+        return response
+
+
+class GuardedSession(GuardedSessionMixin, requests.Session):
+    """A requests.Session that may only talk to ALLOWED_HOSTS."""
+
+
+class GuardedAuthorizedSession(GuardedSessionMixin, _AuthorizedSession):
+    """An AuthorizedSession whose own traffic and refresh channel are guarded."""
+
+    def __init__(self, credentials, **kwargs):
+        super().__init__(
+            credentials, auth_request=_GoogleAuthRequest(session=GuardedSession()), **kwargs
+        )
+
+
+def attach_guard(oauth2session) -> None:
+    """Attach the send() guard to an existing OAuth2Session instance."""
+    oauth2session.send = types.MethodType(GuardedSessionMixin.send, oauth2session)

easygsc/api.py

@@ -0,0 +1,104 @@
+"""Thin REST wrapper around the four Search Console endpoints.
+
+Nothing more: each function maps one endpoint, URL-encodes the siteUrl, and
+maps errors. All HTTP goes through a guarded AuthorizedSession from auth.
+Responses are returned exactly as Google sent them; formatting lives in
+server.py.
+"""
+
+from __future__ import annotations
+
+import json
+from urllib.parse import quote
+
+import requests
+
+from .auth import make_authorized_session as make_session
+
+SITES_URL = "https://www.googleapis.com/webmasters/v3/sites"
+INSPECT_URL = "https://searchconsole.googleapis.com/v1/urlInspection/index:inspect"
+
+
+class ApiError(RuntimeError):
+    """Google API error with status, Google's message, and a hint (or None)."""
+
+    def __init__(self, status: int, message: str, hint: str | None = None):
+        self.status = status
+        self.message = message
+        self.hint = hint
+        super().__init__(f"Google API error {status}: {message}")
+
+
+def _hint(status: int, reason: str | None) -> str | None:
+    if status == 403:
+        return (
+            "Check the property format: 'sc-domain:example.com' for domain "
+            "properties vs 'https://example.com/' (with trailing slash) for "
+            "URL-prefix properties, and confirm the account has access."
+        )
+    if status == 401 or reason == "invalid_grant":
+        return "The token is expired or revoked; run 'easygsc auth' again."
+    if status == 429 or reason in ("rateLimitExceeded", "quotaExceeded"):
+        return (
+            "Quota exceeded. Search Console enforces per-day/per-property "
+            "quotas; wait or reduce request volume. URL Inspection is limited "
+            "to 2,000 queries/day per property."
+        )
+    return None
+
+
+def _request(session, method: str, url: str, **kwargs) -> dict:
+    try:
+        response = session.request(method, url, timeout=60, **kwargs)
+    except requests.exceptions.RequestException as exc:
+        raise ApiError(0, f"Request failed: {exc}") from exc
+    if response.status_code >= 400:
+        message = response.text
+        reason = None
+        try:
+            err = response.json().get("error", {})
+            message = err.get("message") or message
+            reasons = err.get("errors") or [{}]
+            reason = reasons[0].get("reason")
+        except (ValueError, AttributeError, json.JSONDecodeError):
+            pass
+        raise ApiError(response.status_code, message, _hint(response.status_code, reason))
+    try:
+        return response.json()
+    except ValueError as exc:
+        raise ApiError(response.status_code, f"Non-JSON response: {response.text[:200]}") from exc
+
+
+def _site_url(site_url: str) -> str:
+    return quote(site_url, safe="")
+
+
+def _session():
+    return make_session()
+
+
+def list_sites(session=None) -> dict:
+    """GET /webmasters/v3/sites — properties the account can read."""
+    session = session or _session()
+    return _request(session, "GET", SITES_URL)
+
+
+def search_analytics(site_url: str, body: dict, session=None) -> dict:
+    """POST /sites/{siteUrl}/searchAnalytics/query with the caller-built body."""
+    session = session or _session()
+    url = f"{SITES_URL}/{_site_url(site_url)}/searchAnalytics/query"
+    return _request(session, "POST", url, json=body)
+
+
+def list_sitemaps(site_url: str, session=None) -> dict:
+    """GET /sites/{siteUrl}/sitemaps."""
+    session = session or _session()
+    url = f"{SITES_URL}/{_site_url(site_url)}/sitemaps"
+    return _request(session, "GET", url)
+
+
+def inspect_url(site_url: str, url: str, session=None) -> dict:
+    """POST /v1/urlInspection/index:inspect (index:inspect method)."""
+    session = session or _session()
+    body = {"inspectionUrl": url, "siteUrl": site_url, "languageCode": "en-US"}
+    return _request(session, "POST", INSPECT_URL, json=body)

easygsc/auth.py

@@ -0,0 +1,168 @@
+"""Credential resolution, the OAuth flow, and token storage.
+
+Resolution order (documented in README, printed by ``easygsc doctor``):
+1. service account file (``EASYGSC_SERVICE_ACCOUNT_FILE``)
+2. refresh token from the environment (``EASYGSC_REFRESH_TOKEN`` plus the
+   OAuth client from env vars or ``client_secret.json``), for stateless setups
+3. saved OAuth token (``~/.config/easygsc/token.json``)
+4. otherwise run ``easygsc auth``
+
+Nothing here logs or returns secrets; the refresh token is printed exactly
+once, by ``run_oauth_flow``, because the user asked for it.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from google.auth.transport.requests import Request as GoogleAuthRequest
+from google.oauth2 import credentials as oauth2_credentials
+from google.oauth2 import service_account
+from google_auth_oauthlib.flow import InstalledAppFlow
+
+from .allowlist import GuardedSession, attach_guard
+
+SCOPES = ["https://www.googleapis.com/auth/webmasters.readonly"]
+
+# Same location on every OS, per the project spec.
+CONFIG_DIR = Path.home() / ".config" / "easygsc"
+TOKEN_PATH = CONFIG_DIR / "token.json"
+CLIENT_SECRET_PATH = CONFIG_DIR / "client_secret.json"
+
+GOOGLE_AUTH_URI = "https://accounts.google.com/o/oauth2/auth"
+GOOGLE_TOKEN_URI = "https://oauth2.googleapis.com/token"
+
+
+class AuthError(RuntimeError):
+    """Raised when no usable credentials can be resolved."""
+
+
+def client_config() -> dict:
+    """Build the 'installed' client config from env vars or client_secret.json."""
+    client_id = os.environ.get("EASYGSC_CLIENT_ID")
+    client_secret = os.environ.get("EASYGSC_CLIENT_SECRET")
+    if client_id and client_secret:
+        return {
+            "installed": {
+                "client_id": client_id,
+                "client_secret": client_secret,
+                "auth_uri": GOOGLE_AUTH_URI,
+                "token_uri": GOOGLE_TOKEN_URI,
+                "redirect_uris": ["http://localhost"],
+            }
+        }
+    if CLIENT_SECRET_PATH.is_file():
+        with open(CLIENT_SECRET_PATH, encoding="utf-8") as f:
+            return json.load(f)
+    raise AuthError(
+        "No OAuth client configured. Provide EASYGSC_CLIENT_ID and "
+        "EASYGSC_CLIENT_SECRET, or place a Desktop-app client_secret.json at "
+        f"{CLIENT_SECRET_PATH}, then run 'easygsc auth'."
+    )
+
+
+def resolve_credentials():
+    """Resolve credentials in the documented order. Raises AuthError if none."""
+    sa_file = os.environ.get("EASYGSC_SERVICE_ACCOUNT_FILE")
+    if sa_file:
+        creds = service_account.Credentials.from_service_account_file(sa_file, scopes=SCOPES)
+        return creds
+    refresh_token = os.environ.get("EASYGSC_REFRESH_TOKEN")
+    if refresh_token:
+        client = next(iter(client_config().values()))
+        return oauth2_credentials.Credentials(
+            token=None,
+            refresh_token=refresh_token,
+            token_uri=client.get("token_uri", GOOGLE_TOKEN_URI),
+            client_id=client["client_id"],
+            client_secret=client["client_secret"],
+            scopes=SCOPES,
+        )
+    if TOKEN_PATH.is_file():
+        return oauth2_credentials.Credentials.from_authorized_user_file(
+            str(TOKEN_PATH), scopes=SCOPES
+        )
+    raise AuthError(
+        "No credentials found. Run 'easygsc auth' first, or set "
+        "EASYGSC_SERVICE_ACCOUNT_FILE for service-account setups. "
+        f"Expected token at {TOKEN_PATH}."
+    )
+
+
+def token_info() -> dict:
+    """Safe description of the stored token for doctor: no secrets."""
+    if not TOKEN_PATH.is_file():
+        return {"present": False}
+    try:
+        data = json.loads(TOKEN_PATH.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {"present": True, "readable": False}
+    return {
+        "present": True,
+        "readable": True,
+        "expiry": data.get("expiry"),
+        "has_refresh_token": bool(data.get("refresh_token")),
+        "scopes": data.get("scopes"),
+        "account": data.get("account"),
+    }
+
+
+def save_token(credentials) -> Path:
+    """Write the credentials JSON atomically with 0600 (best effort on Windows)."""
+    payload = credentials.to_json()
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(dir=CONFIG_DIR, prefix=".token-", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(payload)
+            f.flush()
+            os.fsync(f.fileno())
+        try:
+            os.chmod(tmp_name, 0o600)
+        except OSError:
+            pass  # best effort on platforms without POSIX permissions
+        os.replace(tmp_name, TOKEN_PATH)
+    except BaseException:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+    return TOKEN_PATH
+
+
+def run_oauth_flow(no_browser: bool = False, *, print_refresh_token: bool = True):
+    """Run the installed-app OAuth flow and persist the token.
+
+    ``--no-browser`` still uses the loopback redirect flow; it only skips
+    opening the browser window automatically (the URL is printed instead).
+    ``print_refresh_token=False`` keeps the token out of stdout for callers
+    such as ``easygsc setup``; ``easygsc auth`` keeps the default.
+    """
+    flow = InstalledAppFlow.from_client_config(client_config(), scopes=SCOPES)
+    # The code exchange goes through the flow's own OAuth2Session: guard it.
+    attach_guard(flow.oauth2session)
+    credentials = flow.run_local_server(port=0, open_browser=not no_browser)
+    save_token(credentials)
+    # The user explicitly asked for the refresh token (stateless setups);
+    # this is the only place it is ever printed.
+    if print_refresh_token:
+        print(f"EASYGSC_REFRESH_TOKEN={credentials.refresh_token}")
+    return credentials
+
+
+def make_authorized_session():
+    """AuthorizedSession with guarded own traffic and guarded refresh channel."""
+    from .allowlist import GuardedAuthorizedSession
+
+    return GuardedAuthorizedSession(resolve_credentials())
+
+
+def refresh_credentials_if_expired(credentials) -> None:
+    """Refresh credentials through the guarded session if needed."""
+
+    if not credentials.valid:
+        credentials.refresh(GoogleAuthRequest(session=GuardedSession()))

easygsc/cli.py

@@ -0,0 +1,144 @@
+"""CLI: ``easygsc``/``easygsc serve`` runs MCP over stdio; ``auth`` runs the
+OAuth flow; ``doctor`` reports auth state and exits 1 when auth fails; ``setup``
+runs the guided wizard; ``connect`` adds easygsc to the user's AI apps. Logs go to
+stderr (WARNING by default); secrets are never printed; doctor output goes to stdout.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from . import __version__, api, auth, connect, server
+
+
+def _setup_logging() -> None:
+    logging.basicConfig(
+        stream=sys.stderr,
+        level=logging.WARNING,
+        format="%(name)s %(levelname)s: %(message)s",
+        force=True,  # a fresh CLI process has no handlers; also rebinds in tests
+    )
+
+
+def _auth_mode() -> str:
+    import os
+
+    if os.environ.get("EASYGSC_SERVICE_ACCOUNT_FILE"):
+        return "service-account"
+    if os.environ.get("EASYGSC_REFRESH_TOKEN"):
+        return "oauth-env"
+    if auth.TOKEN_PATH.is_file():
+        return "oauth-token"
+    return "none"
+
+
+def _doctor() -> int:
+    mode = _auth_mode()
+    lines = [
+        f"easygsc version: {__version__}",
+        f"auth mode: {mode}",
+        f"config dir: {auth.CONFIG_DIR}",
+        f"token file: {auth.TOKEN_PATH}",
+        f"client secret file: {auth.CLIENT_SECRET_PATH}",
+    ]
+    if mode == "oauth-token":
+        info = auth.token_info()
+        lines.append(f"token expiry: {info.get('expiry', 'unknown')}")
+        lines.append(f"token has refresh_token: {info.get('has_refresh_token', False)}")
+    elif mode == "oauth-env":
+        lines.append("token expiry: n/a (refresh token from EASYGSC_REFRESH_TOKEN)")
+    elif mode == "service-account":
+        lines.append("token expiry: n/a (service account keys do not expire)")
+    else:
+        lines.append("token expiry: n/a (not authenticated)")
+
+    if mode == "none":
+        lines += [
+            "readable properties: unknown (not authenticated)",
+            "auth check: FAILED - run 'easygsc auth' or set EASYGSC_SERVICE_ACCOUNT_FILE",
+        ]
+        print("\n".join(lines))
+        return 1
+
+    try:
+        count = len(api.list_sites().get("siteEntry", []))
+        lines += [f"readable properties: {count}", "auth check: OK"]
+        print("\n".join(lines))
+        return 0
+    except api.ApiError as err:
+        lines += ["readable properties: unknown (API error)", f"auth check: FAILED - {err}"]
+        print("\n".join(lines))
+        return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    _setup_logging()
+    parser = argparse.ArgumentParser(
+        prog="easygsc",
+        description=(
+            "Minimal, transparent, read-only MCP server for Google Search "
+            "Console. With no arguments, serves MCP over stdio."
+        ),
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    auth_parser = sub.add_parser("auth", help="run the OAuth flow and store the token")
+    auth_parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="do not open a browser window; print the URL to open instead",
+    )
+
+    sub.add_parser("doctor", help="show auth mode, token expiry, config paths, version")
+    sub.add_parser("serve", help="run the MCP server over stdio (default)")
+
+    setup_parser = sub.add_parser(
+        "setup", help="guided setup: Google Cloud steps, login, connect your AI apps"
+    )
+    setup_parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="print URLs instead of opening a browser window",
+    )
+
+    sub.add_parser(
+        "connect", help="add easygsc to your AI apps (Claude, Cursor, VS Code, and more)"
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command == "connect":
+        if _auth_mode() == "none":
+            print("Note: you are not logged in yet. Run 'easygsc setup' first.")
+        try:
+            return connect.run()
+        except KeyboardInterrupt:
+            print("\nconnect interrupted: run 'easygsc connect' again.", file=sys.stderr)
+            return 130
+
+    if args.command == "setup":
+        from . import setup  # lazy: setup imports _doctor from this module
+
+        try:
+            return setup.run(no_browser=args.no_browser)
+        except KeyboardInterrupt:
+            print("\nsetup interrupted: run 'easygsc setup' again when ready.", file=sys.stderr)
+            return 130
+    if args.command == "auth":
+        try:
+            auth.run_oauth_flow(no_browser=args.no_browser)
+            return 0
+        except auth.AuthError as exc:
+            print(f"auth failed: {exc}", file=sys.stderr)
+            return 1
+    if args.command == "doctor":
+        return _doctor()
+    # No args or explicit serve: MCP over stdio.
+    server.run()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())