geoseo-mcp

Report which engines are configured and reachable. Always safe to call. Returns a dict keyed by engine name with `configured: bool` and a short message. Use this as the first call in a session to know what's available.

Ask Grok (with live web search) a question; return answer + cited URLs. Uses the xAI Responses API with the ``web_search`` tool. ``citations`` are the URLs Grok actually cites inline; ``sources_considered`` lists everything it looked at. Set ``x_search=True`` to also search X posts. Default model: ``GEOSEO_GROK_MODEL`` (``grok-4.3``).

Get index status for a specific URL via the URL Inspection API. Returns coverage state, last crawl time, mobile usability, indexed verdict, and indexing rich-result data. Slow (~1s/call); rate-limited by Google.

List all Search Console properties the authenticated user can access. Returns a list of site entries with ``siteUrl`` and ``permissionLevel``. Use ``siteUrl`` from this list as input to other ``gsc_*`` tools.

Query GSC search analytics. Args: site_url: The property as it appears in GSC (e.g. ``sc-domain:example.com`` or ``https://example.com/``). start_date: ISO date (YYYY-MM-DD). Defaults to 28 days ago. end_date: ISO date. Defaults to 2 days ago (GSC has ~2-day latency). dimensions: One or more of ``query``, ``page``, ``country``, ``device``, ``date``, ``searchAppearance``. Defaults to ``["query"]``. row_limit: Max rows (capped at 25,000). search_type: ``web``, ``image``, ``video``, ``news``, or ``discover``. country: ISO 3166-1 alpha-3 country filter …

Submit (or resubmit) a sitemap URL to GSC. ``feedpath`` is the absolute URL of the sitemap, e.g. ``https://example.com/sitemap.xml``.

Notify Bing, Yandex, Naver, Seznam, and Yep that a single URL was published or updated. Requires ``GEOSEO_INDEXNOW_KEY`` env var (a 32-char hex string you also host at ``https://yourdomain.com/<key>.txt``).

Batch-notify search engines about up to 10,000 URLs (must share one host). Best for sitemap-wide rebuilds or large content updates.

Audit a folder of HTML pages as a directed internal-link graph. Returns counts of files/edges, the orphans (no inbound links), dead-ends (no outbound links), top hub pages, and a list of dangling internal hrefs that don't resolve to any file. Pass ``site_host`` (e.g. ``"example.com"``) if pages link to themselves with absolute URLs — those will then count as internal edges. Files are also matched by URL slug, so ``/blog/foo`` resolves to ``foo.html`` even when paths don't match exactly.

Validate a page's JSON-LD against Google's structured-data requirements. ``source`` is a local HTML file or an http(s) URL. Every ``application/ld+json`` block is parsed (``@graph`` included) and each typed entity is checked against Google's documented required and recommended properties for Article, Product (with nested Offer / AggregateRating / Review), Recipe, LocalBusiness, BreadcrumbList, Event, VideoObject, SoftwareApplication, JobPosting, QAPage, Review and Organization. FAQPage and HowTo are checked against schema.org since Google no longer shows those rich results. Returns per-entit…

Run ``lint_schema_page`` over every HTML file in a folder. Returns files with errors, files that have no JSON-LD at all, a count of schema types found, the most common missing required properties, and per-file problems.

Return the LLM engines currently configured (have an API key).

How often each configured LLM cites (or mentions) ``target_domain``. The headline GEO/AEO tool. Feed it your top 20-50 buyer questions and get a per-engine breakdown for ChatGPT/Claude/Gemini/Perplexity/Grok/Brave: - ``citation_rate`` (+ 95% interval): share of answers linking to your domain or any subdomain of it. - ``mention_rate`` / ``unlinked_mention_rate``: answers that name your brand, with or without a link. Pass ``brand_aliases`` (e.g. ``["Acme", "Acme CRM"]``) if your brand isn't obvious from the domain. - ``top_competing_domains`` and per-question results. LLM answers vary r…

Ask the same question to all (or selected) configured LLM engines in parallel. ``engines``: optional subset of ``["perplexity","openai","anthropic","gemini","grok","brave"]``. Default: every engine with credentials configured (see ``geoseo_status``). Engines that error are reported per-engine and don't block the others.

Ask ChatGPT (with web search) a question; return answer + cited URLs. Uses the OpenAI Responses API with the ``web_search`` tool. Default model: ``GEOSEO_OPENAI_MODEL`` (``gpt-5-mini``).

Citation share for ``target_domain`` across a Perplexity question batch.

Ask Perplexity (Agent API + web search); return answer + cited URLs/domains. Defaults to the ``fast`` effort preset. Pass ``model`` to pin one (e.g. ``openai/gpt-5-mini``); legacy names like ``sonar`` still work.

Run a GSC performance query and persist the rows as a snapshot. Run this on a schedule (cron, n8n, ``launchd`` — anything that can invoke an MCP tool) to build a local time-series of search performance. Default dimensions: ``["query"]``.

Run multi-LLM citation check and persist the per-question results. Builds the dataset behind ``trend_llm_citations``. ``engines`` defaults to every configured LLM (see ``geoseo_status``). With ``samples > 1`` a question is stored as cited when most samples cite you.

Run AIO citation check via SerpAPI and persist as ``serpapi_aio`` engine rows.

Suggest top-K internal links to add to each page in a folder. By default uses TF-IDF cosine similarity over ``<title>``, headings, meta description and body text (offline, free). Set ``mode`` to ``"openai"`` (text-embedding-3-small), ``"gemini"`` (gemini-embedding-001) or ``"local"`` (sentence-transformers) for embedding similarity; ``model`` overrides the default model. Vectors are cached in SQLite by content hash, so re-runs are cheap. Excludes links the source already has, plus the page itself. Returns suggestions for ``page`` only if provided, otherwise for every page. Each suggestion in…

Time-series of clicks/impressions/position from stored GSC snapshots. Aggregates by ``captured_at``. Filter by ``query`` and/or ``page`` to drill in. Returns up to ``limit`` most recent snapshots in chronological order.

Create the local SQLite snapshot DB if it doesn't exist; return its path.

Per-snapshot citation share for ``target_domain`` over time. ``engine`` filters to one of ``perplexity|openai|anthropic|gemini|serpapi_aio``. Returns rows of ``{captured_at, engine, questions, cited, citation_share}``.

Inventory of what's stored: row counts, sites/domains, oldest/newest snapshots.

Validate an ``llms.txt`` file (local path or URL) against the spec. Returns parsed structure plus an ``issues`` list with line numbers for any violations (missing H1, broken link syntax, non-http(s) URLs, etc).

Active Yandex site diagnostics (by severity) plus sample broken internal links.

List sites in the token owner's Yandex Webmaster account.

Top Yandex search queries: shows, clicks, average show/click position. ``order_by``: ``TOTAL_SHOWS`` or ``TOTAL_CLICKS``. ``device``: ``ALL``, ``DESKTOP``, ``MOBILE_AND_TABLET``, ``MOBILE``, ``TABLET``. Dates are ``YYYY-MM-DD``; defaults to the last week.

Site quality index (SQI), pages in search, excluded pages, problem counts. ``site`` can be a URL (``https://example.com/``) or a Yandex host id (``https:example.com:443``).

Queue a URL for Yandex recrawl. Daily quota applies.

Indexing + search status for a URL in Yandex "Monitoring important pages".