seo-netmedia — MCP server

gsc_clicks(clients: list, start_date: str | None = None, end_date: str | None = None)

Total Search Console clicks per client for a date range.

`clients` (required) is a list of GSC property strings, e.g. `["sc-domain:example.com", "https://foo.com/"]`. Each is queried independently; a property that errors is reported with `clicks: null` and an `error` message rather than failing the whole call. Dates are ISO `YYYY-MM-DD`; omit them to default to the last 28 days. Returns JSON {range, clients, total_clicks}.

gsc_index_status(url: str, site: str | None = None)

Is a URL already indexed by Google? Returns Google's URL Inspection result.

Inspects one page within a verified Search Console property and returns Google's response **unmodified** (the raw `inspectionResult` envelope). Read `inspectionResult.indexStatusResult.verdict` (`PASS` = on Google) and `.coverageState` for the human detail (e.g. "Submitted and indexed" vs "URL is unknown to Google"). The service account must be a verified user of the property (else 403); a bad URL/site or auth error surfaces as an error, not a captured field.

gsc_indexing(urls: list | str)

Notify Google to (re)crawl one or more URLs via the Indexing API.

`urls` (required) is a single absolute URL or a list of them; bare hosts like `example.com` are accepted and normalized to `https://example.com`. Each usable URL is submitted independently — one that errors gets `ok: false` plus an error message instead of failing the whole call. A blank or malformed entry never reaches the API and is reported under `skipped`. The service account must be an Owner of the property in Search Console (else a 403). Returns JSON {type, submitted, succeeded, retries, results, skipped} where `results` is one {url, ok, ...} per submitted URL and `skipped` is one {url, reason} per unusable input.

gsc_verify_index(urls: list | str)

Check whether one or more URLs are indexed by Google (URL Inspection API).

`urls` (required) is a single absolute URL or a list of them. Each is inspected and its verdict returned: `INDEXED`, `NOT_INDEXED`, or `FORBIDDEN` (the service account isn't a verified user of the URL's Search Console property). URLs are grouped by the `sc-domain:` property derived from their host; a URL whose host can't be mapped to a property is reported under `skipped` as `CONFIG_ERROR`. The Inspection API allows ~2000 calls/day per property, so the run **stops as soon as Google returns a quota/rate-limit (429)** — `stopped` is `"quota"` in that case, else `null`. Returns JSON {inspected, indexed, succeeded, forbidden, config_errors, stopped, rows, skipped} where `rows` is one {url, status, indexed} per inspected URL.

notion_table_read(db_id: str | None = None, max_rows: int | None = None, filter: dict | None = None, sorts: list | None = None)

Read the rows of a Notion database (the table you see in Notion).

Each row is flattened to plain values keyed by column name, with the Notion page id and link added as `_id` and `_url`. Pagination is followed to the end unless `max_rows` caps it.

runner_job_status(job_id: str)

Full status of one job: state, progress, result/error, and logs (JSON).

runner_jobs(random_string: str | None = None)

List all jobs this process knows about (JSON, no per-job logs).

runner_start(task: str = 'sample_api_query', count: int = 5, delay: float = 1.0, params: dict | None = None, webhook_url: str | None = None)

Start a background job and return its record (JSON, incl. `id`).

`task` picks what to run: `sample_api_query` (recursive — recurses one level per "page", sleeping `delay` seconds to replicate an API round-trip) or `sample_job` (a flat loop) — both driven by `count` (pages/steps) — or `verify_and_index`, the real per-row crawl: for each due page it inspects the URL and, only if it's not already indexed, submits it to the Indexing API, writing each verdict back to Notion. Pass `params={"max_rows": N}` to cap the crawl; omit for the whole due table. If `webhook_url` is set, the runner POSTs the final job state there when it finishes. Poll `runner_job_status` for live `stats`. `verify_and_index` is a singleton: starting it while one is already running returns an `already_running` error with the running job's id.

runner_status(random_string: str | None = None)

Is the runner busy? Returns JSON {state: IDLE|RUNNING, jobs, counts}.

runner_stop(job_id: str)

Request a stop (cooperative); the job moves to STOPPED at its next check.

runner_stop_all(random_string: str | None = None)

Request a stop for every running/pending job (cooperative); each moves to STOPPED at its next check. Returns JSON {stopped, ids}.

seo_client_add(domain: str, name: str | None = None, ga4_property_id: str | None = None)

Register a client by domain and start Search Console verification.

Stores the client (domain, name, GA4 property id), then requests a domain verification token. Because DNS verification can't complete until the record is live, this returns the exact DNS TXT record to add; once deployed, call seo_client_verify. Returns JSON {client, verification}.

seo_client_list(random_string: str | None = None)

List all registered clients and their verification status (JSON).

seo_client_verify(domain: str)

Finalize Search Console verification for a registered client.

Call after the DNS TXT record from seo_client_add has propagated. On success the client is marked verified. Returns JSON {verified, detail}.

seo_service_account_email(random_string: str | None = None)

Show the Google service-account email that needs access to client data.

Grant THIS email Search Console **Owner** and GA4 **Viewer** on each client's property, otherwise the data tools return nothing. Returns JSON {client_email, note}.