dottide 0.2.0__py3-none-any.whl

dottide/config.py

@@ -0,0 +1,106 @@
+"""Profiles: one TOML file per side, each with its own Google key and its own sites.
+
+Keeping one file per side means a personal profile and a business profile never share a key,
+and an agent can be pointed at a single file when it should only see one side.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from importlib.resources import files
+from pathlib import Path
+
+from dottide import keys
+
+DEFAULT_DIR = Path("~/.config/dottide")
+
+
+@dataclass(frozen=True)
+class Site:
+    name: str
+    profile: str
+    search_console: str | None = None
+    ga4_property: str | None = None
+
+
+@dataclass
+class Profile:
+    name: str
+    keychain: str | None = None
+    key_file: str | None = None
+    sites: list[Site] = field(default_factory=list)
+    stores: dict = field(default_factory=dict)
+
+    @property
+    def key_source(self) -> str:
+        if self.keychain:
+            return f"keychain:{self.keychain}"
+        if self.key_file:
+            return f"file:{self.key_file}"
+        return "none"
+
+    def key_info(self) -> dict:
+        if self.keychain:
+            return keys.read(self.keychain)
+        if self.key_file:
+            return keys.read_file(self.key_file)
+        raise PermissionError(f"profile {self.name!r} has no [key] set")
+
+
+def config_paths() -> list[Path]:
+    """DOTTIDE_CONFIG may name one file or a folder of .toml files."""
+    target = Path(os.environ.get("DOTTIDE_CONFIG", DEFAULT_DIR)).expanduser()
+    if target.is_file():
+        return [target]
+    if target.is_dir():
+        return sorted(p for p in target.glob("*.toml") if not p.name.startswith("_"))
+    return []
+
+
+def load_profile(path: Path) -> Profile:
+    data = tomllib.loads(path.read_text())
+    key = data.get("key", {})
+    profile = Profile(
+        name=path.stem,
+        keychain=key.get("keychain"),
+        key_file=key.get("file"),
+        stores=data.get("stores", {}),
+    )
+    for entry in data.get("sites", []):
+        ga4 = entry.get("ga4_property")
+        profile.sites.append(
+            Site(
+                name=entry["name"],
+                profile=profile.name,
+                search_console=entry.get("search_console"),
+                ga4_property=str(ga4) if ga4 else None,
+            )
+        )
+    return profile
+
+
+def load_profiles() -> list[Profile]:
+    return [load_profile(p) for p in config_paths()]
+
+
+def find_site(profiles: list[Profile], name: str) -> tuple[Profile, Site]:
+    for profile in profiles:
+        for site in profile.sites:
+            if site.name == name:
+                return profile, site
+    known = ", ".join(s.name for p in profiles for s in p.sites) or "none configured"
+    raise ValueError(f"unknown site {name!r}. Configured sites: {known}")
+
+
+def init_profile(name: str = "main") -> Path:
+    """Write a starter profile from the bundled template. Never overwrites a file."""
+    folder = DEFAULT_DIR.expanduser()
+    path = folder / f"{name}.toml"
+    if path.exists():
+        raise FileExistsError(f"{path} already exists; edit it, or pick another --profile name")
+    folder.mkdir(mode=0o700, parents=True, exist_ok=True)
+    path.write_text(files("dottide").joinpath("profile_template.toml").read_text())
+    path.chmod(0o600)
+    return path

dottide/discover.py

@@ -0,0 +1,122 @@
+"""Find every site the key can read and suggest profile entries for the ones not set up yet.
+
+Reading is all it does on Google's side. The only write is `--write`, which appends
+the suggested [[sites]] blocks to a local profile file.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+from dottide import google
+from dottide.config import Profile, config_paths, load_profiles
+
+
+def host(address: str) -> str:
+    """The bare domain behind a Search Console property or a site URL."""
+    if address.startswith("sc-domain:"):
+        address = address.removeprefix("sc-domain:")
+    elif "://" in address:
+        address = urlparse(address).hostname or ""
+    return address.strip("/").lower().removeprefix("www.")
+
+
+def plan(gsc_properties: list[str], streams: list[dict], configured: list[dict]) -> list[dict]:
+    """Suggested sites, one per domain, skipping anything a profile already covers.
+
+    A domain property wins over a URL-prefix property for the same domain, because it
+    covers every subdomain and protocol.
+    """
+    taken = {host(s["name"]) for s in configured}
+    taken |= {host(s["search_console"]) for s in configured if s.get("search_console")}
+    taken_ga4 = {s["ga4_property"] for s in configured if s.get("ga4_property")}
+
+    by_host: dict[str, dict] = {}
+    for prop in gsc_properties:
+        entry = by_host.setdefault(host(prop), {"name": host(prop)})
+        current = entry.get("search_console", "")
+        if not current or (prop.startswith("sc-domain:") and not current.startswith("sc-domain:")):
+            entry["search_console"] = prop
+    for stream in streams:
+        key = host(stream["url"]) if stream["url"] else ""
+        if not key or stream["property"] in taken_ga4:
+            continue
+        entry = by_host.setdefault(key, {"name": key})
+        entry.setdefault("ga4_property", stream["property"])
+        entry.setdefault("measurement_id", stream["measurement_id"])
+    return [by_host[k] for k in sorted(by_host) if k not in taken]
+
+
+def to_toml(sites: list[dict]) -> str:
+    blocks = []
+    for site in sites:
+        lines = ["[[sites]]", f'name = "{site["name"]}"']
+        if site.get("search_console"):
+            lines.append(f'search_console = "{site["search_console"]}"')
+        if site.get("ga4_property"):
+            note = f"   # {site['measurement_id']}" if site.get("measurement_id") else ""
+            lines.append(f'ga4_property = "{site["ga4_property"]}"{note}')
+        blocks.append("\n".join(lines))
+    return "\n\n".join(blocks)
+
+
+def discover(profile_name: str | None = None) -> dict:
+    """Read what the key can see and compare it with every profile."""
+    profiles = load_profiles()
+    keyed = [p for p in profiles if p.keychain or p.key_file]
+    if profile_name:
+        keyed = [p for p in keyed if p.name == profile_name]
+    if not keyed:
+        raise ValueError("no profile with a [key]; add one first (see docs/configuration.md)")
+
+    configured = [
+        {"name": s.name, "search_console": s.search_console, "ga4_property": s.ga4_property}
+        for p in profiles
+        for s in p.sites
+    ]
+    # Several profiles often share one key; read each key once.
+    seen: dict[str, Profile] = {}
+    for p in keyed:
+        seen.setdefault(p.key_source, p)
+
+    gsc, streams, errors = [], [], []
+    for profile in seen.values():
+        gsc += google.gsc_properties(profile)
+        try:
+            streams += google.ga4_web_streams(profile)
+        except Exception as exc:  # noqa: BLE001 - GA4 is optional; Search Console still counts
+            errors.append(f"GA4 ({profile.key_source}): {exc}")
+
+    new = plan(sorted(set(gsc)), streams, configured)
+    result = {
+        "keys": list(seen),
+        "search_console_properties": sorted(set(gsc)),
+        "ga4_web_streams": streams,
+        "already_configured": [s["name"] for s in configured],
+        "new_sites": new,
+        "toml": to_toml(new),
+    }
+    if errors:
+        result["errors"] = errors
+    return result
+
+
+def write(profile_name: str | None, toml: str) -> str:
+    """Append suggested blocks to a profile file and return its path."""
+    paths = config_paths()
+    if profile_name:
+        paths = [p for p in paths if p.stem == profile_name]
+    if len(paths) != 1:
+        names = ", ".join(p.stem for p in config_paths()) or "none"
+        raise ValueError(f"pick one profile with --profile to write to. Profiles: {names}")
+    path = paths[0]
+    text = path.read_text().rstrip()
+    # New sites go before [stores] when it exists, so the file keeps its usual order.
+    marker = "\n[stores]"
+    if marker in text:
+        head, tail = text.split(marker, 1)
+        text = f"{head.rstrip()}\n\n{toml}\n{marker}{tail}"
+    else:
+        text = f"{text}\n\n{toml}"
+    path.write_text(text + "\n")
+    return str(path)

dottide/google.py

@@ -0,0 +1,126 @@
+"""Search Console and GA4 reads through a service account. Read-only scopes only."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+import httpx
+from google.auth.transport.requests import Request
+from google.oauth2 import service_account
+
+from dottide.config import Profile
+
+SCOPES = [
+    "https://www.googleapis.com/auth/webmasters.readonly",
+    "https://www.googleapis.com/auth/analytics.readonly",
+]
+GSC = "https://searchconsole.googleapis.com/webmasters/v3"
+GA4_DATA = "https://analyticsdata.googleapis.com/v1beta"
+GA4_ADMIN = "https://analyticsadmin.googleapis.com/v1beta"
+
+_credentials: dict[str, service_account.Credentials] = {}
+
+
+def client_email(profile: Profile) -> str:
+    return profile.key_info()["client_email"]
+
+
+def _token(profile: Profile) -> str:
+    creds = _credentials.get(profile.name)
+    if creds is None:
+        creds = service_account.Credentials.from_service_account_info(
+            profile.key_info(), scopes=SCOPES
+        )
+        _credentials[profile.name] = creds
+    if not creds.valid:
+        creds.refresh(Request())
+    return creds.token
+
+
+def _call(profile: Profile, method: str, url: str, **kwargs) -> dict:
+    headers = {"Authorization": f"Bearer {_token(profile)}"}
+    response = httpx.request(method, url, headers=headers, timeout=30, **kwargs)
+    if response.status_code >= 400:
+        try:
+            message = response.json()["error"]["message"]
+        except (ValueError, KeyError, TypeError):
+            message = response.text[:200]
+        raise RuntimeError(f"Google API {response.status_code}: {message}")
+    return response.json()
+
+
+def gsc_properties(profile: Profile) -> list[str]:
+    entries = _call(profile, "GET", f"{GSC}/sites").get("siteEntry", [])
+    return [e["siteUrl"] for e in entries if e.get("permissionLevel") != "siteUnverifiedUser"]
+
+
+def gsc_query(
+    profile: Profile, prop: str, start: str, end: str, dimension: str | None, limit: int = 25
+) -> dict[str, dict]:
+    """Rows keyed by query or page. With no dimension, one row keyed "total"."""
+    body: dict = {"startDate": start, "endDate": end, "rowLimit": limit}
+    if dimension:
+        body["dimensions"] = [dimension]
+    url = f"{GSC}/sites/{quote(prop, safe='')}/searchAnalytics/query"
+    rows = _call(profile, "POST", url, json=body).get("rows", [])
+    return {
+        (row["keys"][0] if dimension else "total"): {
+            "clicks": row["clicks"],
+            "impressions": row["impressions"],
+            "ctr": round(row["ctr"] * 100, 2),
+            "position": round(row["position"], 1),
+        }
+        for row in rows
+    }
+
+
+def ga4_sources(profile: Profile, prop: str, start: str, end: str) -> list[dict]:
+    """Sessions by source and medium, biggest first."""
+    body = {
+        "dateRanges": [{"startDate": start, "endDate": end}],
+        "dimensions": [{"name": "sessionSource"}, {"name": "sessionMedium"}],
+        "metrics": [{"name": "sessions"}, {"name": "engagedSessions"}, {"name": "totalUsers"}],
+        "orderBys": [{"metric": {"metricName": "sessions"}, "desc": True}],
+        "limit": 1000,
+    }
+    data = _call(profile, "POST", f"{GA4_DATA}/properties/{prop}:runReport", json=body)
+    rows = []
+    for row in data.get("rows", []):
+        source, medium = (d["value"] for d in row["dimensionValues"])
+        sessions, engaged, users = (int(m["value"]) for m in row["metricValues"])
+        rows.append(
+            {
+                "source": source,
+                "medium": medium,
+                "sessions": sessions,
+                "engaged_sessions": engaged,
+                "users": users,
+            }
+        )
+    return rows
+
+
+def ga4_web_streams(profile: Profile) -> list[dict]:
+    """Every GA4 web stream the key can read, with the site address it tracks."""
+    streams, page = [], None
+    while True:
+        params = {"pageSize": 200, **({"pageToken": page} if page else {})}
+        data = _call(profile, "GET", f"{GA4_ADMIN}/accountSummaries", params=params)
+        for account in data.get("accountSummaries", []):
+            for prop in account.get("propertySummaries", []):
+                pid = prop["property"].split("/")[1]
+                url = f"{GA4_ADMIN}/properties/{pid}/dataStreams"
+                for stream in _call(profile, "GET", url).get("dataStreams", []):
+                    web = stream.get("webStreamData")
+                    if web:
+                        streams.append(
+                            {
+                                "property": pid,
+                                "name": prop.get("displayName"),
+                                "measurement_id": web.get("measurementId"),
+                                "url": web.get("defaultUri", ""),
+                            }
+                        )
+        page = data.get("nextPageToken")
+        if not page:
+            return streams

dottide/keys.py

@@ -0,0 +1,53 @@
+"""Service account keys, read from the macOS keychain or a file outside any repo.
+
+Keychain values are stored base64-encoded: `security find-generic-password -w` prints values
+that contain newlines as hex, and base64 also lets us pass the key on stdin instead of argv,
+so it never shows up in the process list.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import subprocess
+from pathlib import Path
+
+SECURITY = "/usr/bin/security"
+ACCOUNT = "dottide"
+
+
+def _validate(info: dict, where: str) -> dict:
+    if info.get("type") != "service_account" or "client_email" not in info:
+        raise ValueError(f"{where} is not a Google service account key")
+    return info
+
+
+def read(service: str) -> dict:
+    out = subprocess.run(
+        [SECURITY, "find-generic-password", "-s", service, "-a", ACCOUNT, "-w"],
+        capture_output=True,
+        text=True,
+    )
+    if out.returncode != 0:
+        raise PermissionError(
+            f"no keychain item {service!r}; run: dottide import-key {service} <key.json>"
+        )
+    return _validate(json.loads(base64.b64decode(out.stdout.strip())), f"keychain item {service!r}")
+
+
+def read_file(path: str) -> dict:
+    return _validate(json.loads(Path(path).expanduser().read_text()), path)
+
+
+def store(service: str, path: str) -> str:
+    """Copy a key file into the keychain. Returns the service account email."""
+    info = read_file(path)
+    blob = base64.b64encode(json.dumps(info, separators=(",", ":")).encode()).decode()
+    label = f"'dotTide {service}'"
+    command = f"add-generic-password -U -s {service} -a {ACCOUNT} -l {label} -w {blob}\n"
+    out = subprocess.run([SECURITY, "-i"], input=command, capture_output=True, text=True)
+    if out.returncode != 0 or out.stderr.strip():
+        raise RuntimeError(f"keychain write failed: {out.stderr.strip() or out.returncode}")
+    if read(service)["client_email"] != info["client_email"]:
+        raise RuntimeError("keychain read-back did not match the key file")
+    return info["client_email"]

dottide/profile_template.toml

@@ -0,0 +1,25 @@
+# dotTide profile, written by `dottide init`. The file name is the profile name.
+# Never commit a filled-in copy. Every field is explained in docs/configuration.md.
+
+[key]
+# Where the Google service account key lives. Pick one.
+keychain = "dottide-main"             # set with: dottide import-key dottide-main key.json
+# file = "~/.config/dottide/keys/main.json"
+
+# One block per site. `dottide discover --write` adds them for you once the key can read your sites.
+#
+# search_console: the property exactly as Search Console shows it:
+#   "sc-domain:example.com" for a domain property, "https://example.com/" for a URL prefix.
+# ga4_property: the numeric property ID (Admin > Property details), not the G- measurement ID.
+#   Leave it out for sites without GA4.
+#
+# [[sites]]
+# name = "example.com"
+# search_console = "sc-domain:example.com"
+# ga4_property = "123456789"
+
+[stores]
+# Public numbers, no key needed.
+wordpress_org = []      # plugin slugs
+firefox = []            # Firefox Add-ons slugs
+github_owners = []      # users or orgs; only public repos are counted

dottide/report.py

@@ -0,0 +1,197 @@
+"""The four reports, shared by the MCP server, the CLI, and the weekly snapshot."""
+
+from __future__ import annotations
+
+from datetime import date, timedelta
+
+from dottide import google, stores
+from dottide.config import Profile, find_site, load_profiles
+
+# Search Console data settles about three days after the fact.
+GSC_LAG_DAYS = 3
+
+AI_SOURCES = {
+    "chatgpt.com": "ChatGPT",
+    "chat.openai.com": "ChatGPT",
+    "perplexity.ai": "Perplexity",
+    "copilot.microsoft.com": "Copilot",
+    "copilot.com": "Copilot",
+    "gemini.google.com": "Gemini",
+    "bard.google.com": "Gemini",
+    "claude.ai": "Claude",
+    "chat.mistral.ai": "Mistral",
+    "chat.deepseek.com": "DeepSeek",
+    "grok.com": "Grok",
+    "meta.ai": "Meta AI",
+    "you.com": "You.com",
+    "phind.com": "Phind",
+}
+
+
+def ai_assistant(source: str) -> str | None:
+    host = source.lower().strip().removeprefix("www.")
+    for domain, name in AI_SOURCES.items():
+        if host == domain or host.endswith("." + domain):
+            return name
+    return None
+
+
+def period(start: str | None, end: str | None, days: int) -> tuple[date, date]:
+    last = date.fromisoformat(end) if end else date.today() - timedelta(days=GSC_LAG_DAYS)
+    first = date.fromisoformat(start) if start else last - timedelta(days=days - 1)
+    if first > last:
+        raise ValueError(f"start {first} is after end {last}")
+    return first, last
+
+
+def previous(first: date, last: date) -> tuple[date, date]:
+    length = (last - first).days + 1
+    prev_last = first - timedelta(days=1)
+    return prev_last - timedelta(days=length - 1), prev_last
+
+
+def _delta(now: dict, before: dict | None, fields: tuple[str, ...]) -> dict:
+    out = dict(now)
+    for f in fields:
+        old = (before or {}).get(f)
+        out[f"previous_{f}"] = old
+        out[f"change_{f}"] = None if old is None else round(now[f] - old, 2)
+    return out
+
+
+def sites() -> dict:
+    """Every configured site, the key that covers it, and whether access works when you ask."""
+    report = []
+    for profile in load_profiles():
+        entry: dict = {"profile": profile.name, "key": profile.key_source, "sites": []}
+        try:
+            entry["service_account"] = google.client_email(profile)
+            visible = google.gsc_properties(profile)
+            entry["search_console_visible"] = visible
+        except Exception as exc:  # noqa: BLE001 - report every failure, never stop the list
+            entry["key_error"] = str(exc)
+            visible = None
+        for site in profile.sites:
+            status: dict = {"site": site.name}
+            if site.search_console:
+                if visible is None:
+                    status["search_console"] = "no key access"
+                elif site.search_console in visible:
+                    status["search_console"] = "ok"
+                else:
+                    near = [v for v in visible if site.name in v]
+                    status["search_console"] = "not shared with this key" + (
+                        f"; visible instead: {', '.join(near)}" if near else ""
+                    )
+            if site.ga4_property:
+                status["ga4"] = _ga4_check(profile, site.ga4_property)
+            else:
+                status["ga4"] = "not used"
+            entry["sites"].append(status)
+        report.append(entry)
+    return {"profiles": report}
+
+
+def _ga4_check(profile: Profile, prop: str) -> str:
+    day = (date.today() - timedelta(days=1)).isoformat()
+    try:
+        google.ga4_sources(profile, prop, day, day)
+        return "ok"
+    except Exception as exc:  # noqa: BLE001
+        return str(exc)
+
+
+def search_queries(
+    site: str,
+    by: str = "query",
+    start: str | None = None,
+    end: str | None = None,
+    days: int = 28,
+    compare: bool = False,
+    limit: int = 25,
+) -> dict:
+    if by not in ("query", "page"):
+        raise ValueError("by must be 'query' or 'page'")
+    profile, s = find_site(load_profiles(), site)
+    if not s.search_console:
+        raise ValueError(f"{site} has no search_console property in its profile")
+    first, last = period(start, end, days)
+    fields = ("clicks", "impressions", "ctr", "position")
+    rows = google.gsc_query(profile, s.search_console, str(first), str(last), by, limit)
+    totals = google.gsc_query(profile, s.search_console, str(first), str(last), None).get(
+        "total", dict.fromkeys(fields, 0)
+    )
+    result: dict = {
+        "site": site,
+        "property": s.search_console,
+        "start": str(first),
+        "end": str(last),
+        "by": by,
+    }
+    if compare:
+        p_first, p_last = previous(first, last)
+        p_args = (profile, s.search_console, str(p_first), str(p_last))
+        before = google.gsc_query(*p_args, by, 5000)
+        p_totals = google.gsc_query(*p_args, None).get("total")
+        result["previous_start"], result["previous_end"] = str(p_first), str(p_last)
+        result["totals"] = _delta(totals, p_totals, fields)
+        result["rows"] = [{by: k, **_delta(v, before.get(k), fields)} for k, v in rows.items()]
+    else:
+        result["totals"] = totals
+        result["rows"] = [{by: k, **v} for k, v in rows.items()]
+    return result
+
+
+def _traffic_summary(rows: list[dict], limit: int) -> dict:
+    ai: dict[str, dict] = {}
+    for row in rows:
+        if name := ai_assistant(row["source"]):
+            bucket = ai.setdefault(name, {"assistant": name, "sessions": 0, "engaged_sessions": 0})
+            bucket["sessions"] += row["sessions"]
+            bucket["engaged_sessions"] += row["engaged_sessions"]
+    return {
+        "sessions": sum(r["sessions"] for r in rows),
+        "ai_sessions": sum(a["sessions"] for a in ai.values()),
+        "ai_referrals": sorted(ai.values(), key=lambda a: -a["sessions"]),
+        "sources": rows[:limit],
+    }
+
+
+def traffic(
+    site: str,
+    start: str | None = None,
+    end: str | None = None,
+    days: int = 28,
+    compare: bool = False,
+    limit: int = 25,
+) -> dict:
+    profile, s = find_site(load_profiles(), site)
+    if not s.ga4_property:
+        raise ValueError(f"{site} has no GA4 property; traffic only covers sites with GA4")
+    first, last = period(start, end, days)
+    rows = google.ga4_sources(profile, s.ga4_property, str(first), str(last))
+    result = {"site": site, "property": s.ga4_property, "start": str(first), "end": str(last)}
+    result |= _traffic_summary(rows, limit)
+    if compare:
+        p_first, p_last = previous(first, last)
+        p_rows = google.ga4_sources(profile, s.ga4_property, str(p_first), str(p_last))
+        before = _traffic_summary(p_rows, limit)
+        result["previous"] = {
+            "start": str(p_first),
+            "end": str(p_last),
+            "sessions": before["sessions"],
+            "ai_sessions": before["ai_sessions"],
+            "ai_referrals": before["ai_referrals"],
+        }
+    return result
+
+
+def store_stats(profile: str | None = None) -> dict:
+    merged: dict[str, list] = {}
+    for p in load_profiles():
+        if profile and p.name != profile:
+            continue
+        for store, items in p.stores.items():
+            merged.setdefault(store, [])
+            merged[store] += [i for i in items if i not in merged[store]]
+    return stores.collect(merged)

dottide/server.py

@@ -0,0 +1,172 @@
+"""dotTide MCP server and command line.
+
+dottide                      run the MCP server on stdio (what MCP clients call)
+dottide sites                print any report as JSON; also search_queries, traffic, store_stats
+dottide init                 write a starter profile to ~/.config/dottide/main.toml
+dottide discover [--write]   suggest profile entries for sites the key can read
+dottide snapshot [--out DIR] write the weekly snapshot, one file per profile
+dottide import-key NAME FILE copy a service account key into the macOS keychain
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+
+from mcp.server.mcpserver import MCPServer
+from mcp.types import ToolAnnotations
+
+from dottide import discover as finder
+from dottide import keys, report, snapshot
+from dottide.config import init_profile
+
+READ_ONLY = ToolAnnotations(read_only_hint=True, open_world_hint=True)
+
+server = MCPServer(
+    name="dottide",
+    instructions=(
+        "Read-only numbers for every configured site and product. Call `sites` first to see "
+        "which sites exist and whether their access works. Search Console data lags about "
+        "three days, so default ranges end three days ago."
+    ),
+)
+
+
+@server.tool(annotations=READ_ONLY)
+def sites() -> dict:
+    """Every configured site, which key covers it, and whether Search Console and GA4 access
+    works at the moment of the call."""
+    return report.sites()
+
+
+@server.tool(annotations=READ_ONLY)
+def search_queries(
+    site: str,
+    by: str = "query",
+    start: str | None = None,
+    end: str | None = None,
+    days: int = 28,
+    compare: bool = False,
+    limit: int = 25,
+) -> dict:
+    """Search Console clicks, impressions, CTR (percent) and average position, by "query" or
+    "page". Dates are YYYY-MM-DD; without them the range is the last `days` days ending three
+    days ago. compare=true adds the previous period of the same length and the change."""
+    return report.search_queries(site, by, start, end, days, compare, limit)
+
+
+@server.tool(annotations=READ_ONLY)
+def traffic(
+    site: str,
+    start: str | None = None,
+    end: str | None = None,
+    days: int = 28,
+    compare: bool = False,
+    limit: int = 25,
+) -> dict:
+    """GA4 sessions by source and medium, plus AI assistant referrals (ChatGPT, Perplexity,
+    Copilot, Gemini, Claude and others) totalled separately. Only for sites with GA4."""
+    return report.traffic(site, start, end, days, compare, limit)
+
+
+@server.tool(annotations=READ_ONLY)
+def store_stats(profile: str | None = None) -> dict:
+    """Live public store numbers that need no keys: WordPress.org plugins (installs, rating,
+    downloads last 7 days), Firefox Add-ons (daily users, ratings), GitHub stars."""
+    return report.store_stats(profile)
+
+
+@server.tool(annotations=READ_ONLY)
+def discover(profile: str | None = None) -> dict:
+    """Every Search Console property and GA4 web stream the key can read, matched by domain,
+    with ready-to-paste [[sites]] blocks for any site not in a profile yet. Reads only; the
+    user adds the blocks with `dottide discover --write`."""
+    return finder.discover(profile)
+
+
+def main() -> None:
+    # httpx logs every request URL at INFO; keep stderr for real problems.
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    if len(sys.argv) == 1:
+        server.run("stdio")
+        return
+    parser = argparse.ArgumentParser(prog="dottide")
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("sites")
+    q = sub.add_parser("search_queries")
+    q.add_argument("site")
+    q.add_argument("--by", default="query", choices=["query", "page"])
+    t = sub.add_parser("traffic")
+    t.add_argument("site")
+    for p in (q, t):
+        p.add_argument("--start")
+        p.add_argument("--end")
+        p.add_argument("--days", type=int, default=28)
+        p.add_argument("--compare", action="store_true")
+        p.add_argument("--limit", type=int, default=25)
+    s = sub.add_parser("store_stats")
+    s.add_argument("--profile")
+    i = sub.add_parser("init")
+    i.add_argument("--profile", default="main", help="profile name, which is also the file name")
+    d = sub.add_parser("discover")
+    d.add_argument("--profile", help="only use this profile's key, and write to it")
+    d.add_argument("--write", action="store_true", help="append the new sites to the profile")
+    snap = sub.add_parser("snapshot")
+    snap.add_argument("--out", help="folder for <profile>-<year>-W<week>.json; stdout if absent")
+    k = sub.add_parser("import-key")
+    k.add_argument("name", help="keychain item name, for example dottide-main")
+    k.add_argument("file", help="path to the downloaded service account JSON key")
+    args = parser.parse_args()
+    try:
+        _run(args)
+    except (OSError, ValueError, RuntimeError) as exc:
+        # Expected problems (missing key, unknown site, existing file) get one clear line.
+        sys.exit(f"dottide: {exc}")
+
+
+def _run(args: argparse.Namespace) -> None:
+    if args.command == "import-key":
+        print(f"stored {keys.store(args.name, args.file)} in keychain item {args.name}")
+        return
+    if args.command == "init":
+        path = init_profile(args.profile)
+        print(f"wrote {path}")
+        print("next: dottide import-key dottide-main <key.json>, then dottide discover --write")
+        return
+    if args.command == "discover":
+        found = finder.discover(args.profile)
+        if args.write and found["new_sites"]:
+            path = finder.write(args.profile, found["toml"])
+            print(f"added {len(found['new_sites'])} sites to {path}")
+        elif found["new_sites"]:
+            print(found["toml"])
+            print(
+                f"\n# {len(found['new_sites'])} new sites. Add them with --write.", file=sys.stderr
+            )
+        else:
+            print("Every site the key can read is already in a profile.")
+        for error in found.get("errors", []):
+            print(f"note: {error}", file=sys.stderr)
+        return
+    if args.command == "snapshot":
+        snapshot.run(args.out)
+        return
+    if args.command == "sites":
+        result = report.sites()
+    elif args.command == "search_queries":
+        result = report.search_queries(
+            args.site, args.by, args.start, args.end, args.days, args.compare, args.limit
+        )
+    elif args.command == "traffic":
+        result = report.traffic(
+            args.site, args.start, args.end, args.days, args.compare, args.limit
+        )
+    else:
+        result = report.store_stats(args.profile)
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

dottide/snapshot.py

@@ -0,0 +1,65 @@
+"""Weekly snapshot: last full week against the week before, one JSON file per profile.
+
+One file per profile keeps each side's numbers apart, the same way the keys are.
+A failing site records its error and the snapshot carries on, so one revoked
+permission never costs the whole week's numbers.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, date, datetime, timedelta
+from pathlib import Path
+
+from dottide import report
+from dottide.config import load_profiles
+
+SCHEMA = 1
+
+
+def _safe(fn, *args, **kwargs) -> dict:
+    try:
+        return fn(*args, **kwargs)
+    except Exception as exc:  # noqa: BLE001 - the error is the data point
+        return {"error": str(exc)}
+
+
+def build(profile_name: str) -> dict:
+    profile = next(p for p in load_profiles() if p.name == profile_name)
+    last = date.today() - timedelta(days=report.GSC_LAG_DAYS)
+    first = last - timedelta(days=6)
+    week = {"start": str(first), "end": str(last), "days": 7, "compare": True}
+    sites = []
+    for site in profile.sites:
+        entry: dict = {"site": site.name}
+        if site.search_console:
+            entry["queries"] = _safe(report.search_queries, site.name, "query", **week, limit=10)
+            entry["pages"] = _safe(report.search_queries, site.name, "page", **week, limit=10)
+        if site.ga4_property:
+            entry["traffic"] = _safe(report.traffic, site.name, **week, limit=10)
+        sites.append(entry)
+    return {
+        "schema": SCHEMA,
+        "profile": profile.name,
+        "generated_at": datetime.now(UTC).isoformat(timespec="seconds"),
+        "week": {"start": str(first), "end": str(last)},
+        "sites": sites,
+        "stores": _safe(report.store_stats, profile.name),
+    }
+
+
+def run(out: str | None) -> list[Path]:
+    written = []
+    year, week, _ = date.today().isocalendar()
+    for profile in load_profiles():
+        data = build(profile.name)
+        if out is None:
+            print(json.dumps(data, indent=2))
+            continue
+        folder = Path(out).expanduser()
+        folder.mkdir(parents=True, exist_ok=True)
+        path = folder / f"{profile.name}-{year}-W{week:02d}.json"
+        path.write_text(json.dumps(data, indent=2) + "\n")
+        written.append(path)
+        print(path)
+    return written

dottide/stores.py

@@ -0,0 +1,94 @@
+"""Public store numbers that need no login: WordPress.org, Firefox Add-ons, GitHub."""
+
+from __future__ import annotations
+
+import html
+import os
+from datetime import UTC, datetime
+
+import httpx
+
+TIMEOUT = 20
+
+
+def _get(url: str, **kwargs) -> httpx.Response:
+    return httpx.get(url, timeout=TIMEOUT, follow_redirects=True, **kwargs)
+
+
+def wordpress_org(slug: str) -> dict:
+    info = _get(
+        "https://api.wordpress.org/plugins/info/1.2/",
+        params={"action": "plugin_information", "request[slug]": slug},
+    ).json()
+    if "error" in info:
+        return {"slug": slug, "error": info["error"]}
+    daily = _get(
+        "https://api.wordpress.org/stats/plugin/1.0/downloads.php",
+        params={"slug": slug, "limit": 8},
+    ).json()
+    # The endpoint returns full days only; keep the newest seven.
+    week = dict(sorted(daily.items())[-7:])
+    return {
+        "slug": slug,
+        "name": html.unescape(info.get("name") or ""),
+        "version": info.get("version"),
+        "active_installs": info.get("active_installs"),
+        "rating": info.get("rating"),
+        "num_ratings": info.get("num_ratings"),
+        "support_threads": info.get("support_threads"),
+        "support_threads_resolved": info.get("support_threads_resolved"),
+        "last_updated": info.get("last_updated"),
+        "downloads_last_7_days": sum(int(v) for v in week.values()),
+        "downloads_by_day": {day: int(v) for day, v in week.items()},
+    }
+
+
+def firefox(slug: str) -> dict:
+    response = _get(f"https://addons.mozilla.org/api/v5/addons/addon/{slug}/")
+    if response.status_code != 200:
+        return {"slug": slug, "error": f"AMO {response.status_code}"}
+    data = response.json()
+    return {
+        "slug": slug,
+        "version": (data.get("current_version") or {}).get("version"),
+        "average_daily_users": data.get("average_daily_users"),
+        "weekly_downloads": data.get("weekly_downloads"),
+        "rating": data.get("ratings", {}).get("average"),
+        "num_ratings": data.get("ratings", {}).get("count"),
+    }
+
+
+def github(owner: str) -> dict:
+    """Stars and forks for an owner's public repos. Anonymous unless DOTTIDE_GITHUB_TOKEN is set."""
+    headers = {"Accept": "application/vnd.github+json"}
+    if token := os.environ.get("DOTTIDE_GITHUB_TOKEN"):
+        headers["Authorization"] = f"Bearer {token}"
+    response = _get(
+        f"https://api.github.com/users/{owner}/repos",
+        params={"type": "owner", "per_page": 100},
+        headers=headers,
+    )
+    if response.status_code == 403 and response.headers.get("x-ratelimit-remaining") == "0":
+        reset = datetime.fromtimestamp(int(response.headers["x-ratelimit-reset"]), UTC)
+        return {"owner": owner, "error": f"GitHub rate limit, resets {reset:%Y-%m-%d %H:%M} UTC"}
+    if response.status_code != 200:
+        return {"owner": owner, "error": f"GitHub {response.status_code}"}
+    repos = [
+        {"repo": r["name"], "stars": r["stargazers_count"], "forks": r["forks_count"]}
+        for r in response.json()
+        if not r.get("fork") and not r.get("private")
+    ]
+    return {
+        "owner": owner,
+        "total_stars": sum(r["stars"] for r in repos),
+        "repos": sorted(repos, key=lambda r: -r["stars"]),
+    }
+
+
+def collect(stores: dict) -> dict:
+    """stores is the merged [stores] table: lists of slugs or owners per store."""
+    return {
+        "wordpress_org": [wordpress_org(s) for s in stores.get("wordpress_org", [])],
+        "firefox": [firefox(s) for s in stores.get("firefox", [])],
+        "github": [github(o) for o in stores.get("github_owners", [])],
+    }

dottide-0.2.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: dottide
+Version: 0.2.0
+Summary: Read-only numbers for every site and product you run, across Google accounts, for people and AI agents.
+Project-URL: Homepage, https://github.com/dotbrainhq/dottide
+Project-URL: Documentation, https://github.com/dotbrainhq/dottide/tree/main/docs
+Project-URL: Issues, https://github.com/dotbrainhq/dottide/issues
+Project-URL: Changelog, https://github.com/dotbrainhq/dottide/blob/main/CHANGELOG.md
+Author-email: Dotbrain LLC <hello@dotbrainhq.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,analytics,claude,cli,ga4,google-analytics,google-search-console,mcp,mcp-server,seo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Requires-Python: >=3.12
+Requires-Dist: google-auth[requests]>=2.40
+Requires-Dist: httpx>=0.28
+Requires-Dist: mcp>=2.3
+Description-Content-Type: text/markdown
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/dotbrainhq/dottide/main/.github/assets/cover-dark.png">
+  <img src="https://raw.githubusercontent.com/dotbrainhq/dottide/main/.github/assets/cover-light.png" alt="dotTide: every site's numbers, one place. Search Console, GA4 and store stats across Google accounts, for you and your AI agents. Local and read-only. Next to the text, the dotTide icon: a wave running across a green tile, with one dot under the surface.">
+</picture>
+
+# dotTide
+
+dotTide is a read-only MCP server and command-line tool that gives Claude, Cursor, Codex and other AI agents the numbers for every site you run. It reads Google Search Console and Google Analytics 4 (GA4) across multiple Google accounts, plus WordPress.org, Firefox Add-ons and GitHub stats, and writes a weekly snapshot for scripts and agents.
+
+Nothing gets added to your sites. dotTide only reads numbers you already have, and your keys stay on your Mac.
+
+## Why
+
+If your sites sit under different Google accounts, checking them means logging in and out of each one. The weekly check slips to monthly, and any AI agent you ask works from stale numbers. Store numbers for plugins, extensions and repos live in yet more places.
+
+dotTide reads all of it with one read-only key, and answers the same way in Claude, on the command line, and in a weekly JSON file.
+
+## What it does
+
+- **`sites`:** every configured site, which key covers it, and whether Search Console and GA4 access works when you ask.
+- **`search_queries`:** clicks, impressions, CTR and average position by query or page, for any date range, with an optional comparison to the previous period.
+- **`traffic`:** GA4 sessions by source and medium, with AI assistant referrals (ChatGPT, Perplexity, Copilot, Gemini, Claude and others) counted separately. Only for sites that have GA4.
+- **`store_stats`:** live public numbers that need no key: WordPress.org plugins, Firefox Add-ons, GitHub stars.
+- **`discover`:** finds every Search Console property and GA4 property the key can read, and writes the profile entries for you.
+- **Weekly snapshot:** last full week against the week before, one JSON file per profile, for scripts and agents that read files.
+
+## How access works
+
+No site moves to a new Google account. You create one Google service account, and whichever Google account owns a site invites that service account's email:
+
+- **Search Console:** as a Restricted user.
+- **GA4:** as a Viewer.
+
+The service account can only read, and you can remove it from any site in one click. Its key lives in the macOS keychain.
+
+## Quick start
+
+You need macOS and [uv](https://docs.astral.sh/uv/). There is nothing to clone: `uvx` downloads dotTide the first time you run it.
+
+1. Write a starter profile, then add a plugin slug, an add-on slug or a GitHub user under `[stores]` in it:
+
+```
+uvx dottide init
+```
+
+2. Check that it runs. Store numbers need no Google setup at all:
+
+```
+uvx dottide store_stats
+```
+
+3. Set up Google access by following [Google setup](https://github.com/dotbrainhq/dottide/blob/main/docs/google-setup.md). It takes about ten minutes, plus a minute per site.
+
+4. Store the key, let dotTide find your sites, and check access:
+
+```
+uvx dottide import-key dottide-main ~/Downloads/<downloaded-key>.json
+uvx dottide discover --write
+uvx dottide sites
+```
+
+5. Connect it to Claude Code:
+
+```
+claude mcp add --scope user dottide -- uvx dottide
+```
+
+To update later, run `uvx dottide@latest sites` once; after that `uvx dottide` uses the new version.
+
+## Documentation
+
+- [Google setup](https://github.com/dotbrainhq/dottide/blob/main/docs/google-setup.md): the service account, click by click, and sharing each site.
+- [Configuration](https://github.com/dotbrainhq/dottide/blob/main/docs/configuration.md): profiles, every field, keys and environment variables.
+- [Using dotTide](https://github.com/dotbrainhq/dottide/blob/main/docs/usage.md): each tool and its options, MCP clients, the weekly snapshot and its format, and fixes for common errors.
+- [Asking an AI agent for your numbers](https://github.com/dotbrainhq/dottide/blob/main/docs/examples.md): example prompts for weekly checks, content to refresh, AI referrals and store numbers, plus a saved Claude Code command.
+- [Connecting AI clients](https://github.com/dotbrainhq/dottide/blob/main/docs/clients.md): Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex, Gemini CLI, Grok, and agents without MCP.
+
+## Good to know
+
+- Search Console data settles about three days after the fact, so default ranges end three days ago.
+- Every Google scope dotTide asks for is read-only, and no tool can change anything.
+- GitHub allows 60 anonymous requests an hour per IP. Set `DOTTIDE_GITHUB_TOKEN` to a read-only token if you hit the limit.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/dotbrainhq/dottide/blob/main/CONTRIBUTING.md). Security reports go through [SECURITY.md](https://github.com/dotbrainhq/dottide/blob/main/SECURITY.md).
+
+## License
+
+The code is released under the [MIT License](https://github.com/dotbrainhq/dottide/blob/main/LICENSE). The dotTide name and icon are not covered by the license, so please use your own name and icon if you ship a copy.

dottide-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+dottide/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dottide/config.py,sha256=oIFWuaGRT4xY3R1rtJUM9nqEwZHmnxBtFWhJ4D9tLLE,3276
+dottide/discover.py,sha256=pGFQ_4zAsYI0ra12oW8f9U1DBHEAFrFNJwuDNh_hE-U,4832
+dottide/google.py,sha256=Vp_gs1KwQs37xdjpOC2mdisHIGoEZIMlPK52F0y70FQ,4872
+dottide/keys.py,sha256=iqBMPMy7hOPs2x3YnOGBc3BWkTQ3E8cGyAQF7GtzqoM,2021
+dottide/profile_template.toml,sha256=6mDlSKeT0Tnz0460gSYoY_3nk7WVEUb2IZJA5dLwP3w,1071
+dottide/report.py,sha256=ZVGatjCopiswHKoYXVQ5zpCWrB93yeU6xPGdRJ3Q_Zo,7240
+dottide/server.py,sha256=Gu0xnoWY_ulW4OY_shQ6kVbJH2fBJyZw4q2vmiTWMzU,6664
+dottide/snapshot.py,sha256=z_rlheJkkSMMUNksRH4VJwAbnh8nx_caGsiL-4vyIcc,2288
+dottide/stores.py,sha256=LoO_3Zu3KVjIQB0RxNauyDQoouD04FcIS6L_vlk_kjE,3622
+dottide-0.2.0.dist-info/METADATA,sha256=aHKcJ956xx72Lk4_GXlcCxktcqm8li9l8jWWMaYzuXk,6409
+dottide-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+dottide-0.2.0.dist-info/entry_points.txt,sha256=W7izUDENGBxbvryFkU_tm1woqJRZkfQ6Yhc9qMpQLZo,48
+dottide-0.2.0.dist-info/licenses/LICENSE,sha256=9872o4dDkt3afhExxcLHMsWCbMY8ad2QlbR_AMw45UU,1069
+dottide-0.2.0.dist-info/RECORD,,

dottide-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dottide-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dottide = dottide.server:main

dottide-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dotbrain LLC
+
+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.