@awesomate/hosting-mcp 0.20.5 → 0.20.6

package/dist/index.js

@@ -41877,6 +41877,26 @@ server.registerTool(
     }
   }
 );
+server.registerTool(
+  "awesomate_site_audit",
+  {
+    description: "Run the SEO + AEO build gates against ONE live page the user owns, fetched AS GPTBot. Returns pass/fail per gate with specific fixes: is the content in the raw HTML at all (a React/Vue site is invisible to ChatGPT, Claude and Perplexity \u2014 only Gemini and Applebot run JavaScript), can the four retrieval bots reach it, is there an accidental noindex/nosnippet, does the canonical point at THIS domain (a leftover pointing at a Replit/Vercel/staging host silently de-indexes the real site), is the structured data valid AND mirrored in visible text, is the content structured so a single section survives being quoted, robots.txt + sitemap, and time-to-first-byte. Run it after building or changing any public page, and before telling the user their site is discoverable \u2014 reads on every plan. Two gates are reported as `skipped` because they need a headless browser or a full crawl; treat skipped as unknown, never as passing.",
+    inputSchema: {
+      domain: external_exports.string().min(3).max(253).describe("a domain on the user's own hosting account"),
+      path: external_exports.string().max(400).optional().describe("page path to audit, default /")
+    },
+    annotations: READ_ONLY
+  },
+  async ({ domain, path }) => {
+    try {
+      const dom = encodeURIComponent(domain.toLowerCase());
+      const q = path && path !== "/" ? `?path=${encodeURIComponent(path)}` : "";
+      return textResult(await hubGet(requireConfig(), `/api/client-hosting/sites/${dom}/audit${q}`));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
 server.registerTool(
   "awesomate_wp_media_import",
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.20.5",
+  "version": "0.20.6",
   "description": "Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases",
   "license": "UNLICENSED",
   "type": "module",

package/skill/CHANGELOG.json

@@ -1,5 +1,12 @@
 {
   "versions": [
+    {
+      "version": "0.20.6",
+      "highlights": [
+        "Ask Claude to check any page and it now runs a full findability audit - whether AI assistants can actually read and quote it, not just whether Google can find it",
+        "Catches the faults that silently make a site invisible to ChatGPT and Perplexity, like content that only appears once the browser runs it"
+      ]
+    },
     {
       "version": "0.20.5",
       "highlights": [

package/skill/awesomate-hosting/SKILL.md

@@ -105,6 +105,7 @@ proxy failures, resuming a connect, support report) ·
 | `awesomate_domain_add` | Attach a custom domain to a site |
 | `awesomate_dns_check` | Live answer to "where does this domain actually point" — before and after any DNS change |
 | `awesomate_site_uptime` | 30-day availability, incidents, downtime per domain (cached, free) |
+| `awesomate_site_audit` | SEO + AEO build gates for one page, fetched as GPTBot — content present without JS, retrieval bots reachable, canonical, schema, structure, speed. Not plan-gated. Run it after any public-page change, and see the awesomate-seo skill for the fixes |
 | `awesomate_snapshot_site` | Before ANY change to a live site — files + DB restore point |
 | `awesomate_list_snapshots` | What restore points a site has |
 | `awesomate_rollback_site` | Restore a snapshot after something went wrong (confirm first) |

package/skill/awesomate-seo/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: awesomate-seo
-description: Make the user's site findable — by Google AND by AI assistants. Adds title/meta/Open Graph tags, sitemap.xml, robots.txt, canonical tags, JSON-LD structured data, and a general llms.txt. Works for static sites, Node apps, and WordPress. Use when the user says "SEO", "get found on Google", "rank higher", "make my site discoverable", "sitemap", "meta tags", "schema", or after building/changing a public site. Companion to awesomate-app-builder.
+description: Make the user's site findable by Google AND quotable by AI assistants (SEO + AEO). Runs the build gates with awesomate_site_audit, then fixes what fails: title/meta/Open Graph, sitemap.xml, robots.txt, canonical tags, JSON-LD, answer-shaped content structure, and llms.txt. Works for static sites, Node apps, and WordPress. Use when the user says "SEO", "AEO", "GEO", "answer engine optimisation", "get found on Google", "get cited by ChatGPT", "rank higher", "make my site discoverable", "sitemap", "meta tags", "schema", or after building/changing any public page. Companion to awesomate-app-builder.
 ---
 
 # Awesomate SEO — get found on Google and AI
@@ -43,11 +43,13 @@ branch honestly.
 `plugin list`) — the whole route is behind the write gate, so "just reading
 the options" is not a way round it. The account-level reads do work
 (`awesomate_get_context`, `awesomate_list_sites`, `awesomate_list_domains`,
-`awesomate_dns_check`, `awesomate_site_uptime`).
+`awesomate_dns_check`, `awesomate_site_uptime`, and **`awesomate_site_audit`** —
+the full gate sweep works on every plan, because it reads the public page).
 
 **What Essentials CAN do — which is most of the value:** audit and advise
-from the outside. `curl` the pages, the sitemap, robots.txt and the rendered
-HTML; combine that with what they tell you; then produce the exact changes —
+from the outside. Start with `awesomate_site_audit` — it runs the whole sweep
+in one call and is NOT plan-gated, so an Essentials user gets exactly the same
+findings as anyone else. Then produce the exact changes —
 the titles and descriptions to paste, the JSON-LD block, the llms.txt
 content, which plugin to install and where its settings live. They apply
 them in wp-admin; you verify by fetching the live page again. Say that up
@@ -67,12 +69,18 @@ formats + length limits. In short, per site:
 3. **`sitemap.xml`** at the root — list every real URL with `<loc>` (+ `<lastmod>`).
 4. **JSON-LD** (`<script type="application/ld+json">`) — the right schema.org
    type (`Organization` / `WebSite` / `Product` / `Article` / `LocalBusiness`).
-5. **`llms.txt`** at the root — a short, plain-markdown summary of what the
-   site/business is and its key pages, so AI assistants can understand and cite
-   it. (This is the general, non-shop counterpart to the Woo `llms.txt`.)
-   Be honest about what it does: Google ignores it — it serves the *other*
-   assistants. For Google's AI features, normal SEO is the whole strategy.
-   Details + crawler/rendering gotchas: [references/ai-discoverability.md](references/ai-discoverability.md).
+5. **Answer-shaped content** — the part that decides whether the page is
+   actually *quoted* rather than merely found: answer-first sections of 120–180
+   words, no section opening with "it"/"this"/"also", comparisons in a real
+   `<table>`, specific numbers and dates inline, and every schema fact also
+   present in the visible copy.
+   Full discipline: [references/answer-structure.md](references/answer-structure.md).
+   This is the highest-leverage item on the list and the one most often skipped.
+6. **`llms.txt`** at the root — cheap, so write it, but keep it in proportion:
+   Google ignores it entirely and one study of 137,210 domains found 97% of
+   published files got zero requests. Generate it, never present it as a pillar,
+   never bill for it. Crawler/rendering gotchas:
+   [references/ai-discoverability.md](references/ai-discoverability.md).
 
 Then commit + deploy (awesomate-github). On content changes, update the
 affected `<head>` tags, `sitemap.xml` `<lastmod>`, and `llms.txt`.
@@ -142,7 +150,24 @@ On WordPress those three come from:
 the robots rules, the JSON-LD block, and tell them precisely where each goes
 — that is the useful half, and it works on every plan.
 
-## 3. Verify
+## 3. Verify — run the gates, don't eyeball it
+
+**`awesomate_site_audit { domain, path }`** runs the mechanical gates against
+the live page, fetched *as GPTBot*, and returns pass/fail with specific fixes:
+content present without JavaScript, all four retrieval bots reachable, no
+accidental `noindex`/`nosnippet`, canonical pointing at this domain, valid
+structured data whose facts also appear in the copy, section structure,
+robots.txt + sitemap, and time-to-first-byte.
+
+Run it after building or changing any public page, and **before telling the user
+their site is discoverable**. Checking in a browser is not equivalent — the
+browser runs the JavaScript that hides the biggest failure.
+
+Two gates come back `skipped` because they need a headless browser (content
+revealed only on click) or a full crawl (internal 404s). **Skipped means
+unknown, not passing** — say so rather than reporting a clean sweep.
+
+Then confirm by hand what the tool can't judge:
 - `robots.txt` and `sitemap.xml` (or the WP sitemap) return 200 at the root.
 - Each key page has a unique title + description and valid JSON-LD (no syntax
   errors — a broken `application/ld+json` block is worse than none).

package/skill/awesomate-seo/references/ai-discoverability.md

@@ -23,7 +23,7 @@ it, but present it as that, never as a Google requirement.
 
 | Kind | Bots | Blocking means |
 |---|---|---|
-| Search-indexing | OAI-SearchBot, Claude-SearchBot, PerplexityBot | The site can't be cited in that assistant's answers. **Allow these.** |
+| Search-indexing | OAI-SearchBot, Claude-SearchBot, PerplexityBot, **Bingbot** | The site can't be cited in that assistant's answers. **Allow these.** Bingbot belongs here because Copilot and several assistants ground on Bing's index. |
 | Training | GPTBot, ClaudeBot, Google-Extended, CCBot, Applebot-Extended, Meta-ExternalAgent | Owner's policy choice about model training; doesn't remove the site from answers |
 | User-triggered retrieval | ChatGPT-User, Perplexity-User, Claude-User | Fetches when a live user asks; may not fully respect robots.txt |
 
@@ -75,14 +75,34 @@ the edge. Where to fix it:
 - **Awesomate-managed domain** (`*.awesomate.site` etc.): the zone is managed
   by Awesomate — the user can't change it. Raise it via `awesomate_support`
   so the zone's AI Crawl Control settings get reviewed.
-- **Custom domain on the user's own Cloudflare account**: they fix it
-  themselves in the Cloudflare dashboard → Security → Bots → AI Crawlers.
+- **Custom domain on the user's own Cloudflare account**: fix it with a WAF
+  custom rule, action **Skip**, expression:
 
-## AI crawlers do not run JavaScript
+  ```
+  cf.verified_bot_category in {"AI Crawler" "Search Engine Crawler"}
+  ```
 
-Only Googlebot renders JS. GPTBot, ClaudeBot, PerplexityBot, and the other AI
-crawlers read the **raw HTML response**. A client-rendered app (React/Vue SPA)
-is invisible to every AI assistant regardless of its meta tags and llms.txt.
+  Match on the **verified category, never on user-agent strings** — a UA
+  allowlist is trivially spoofed and silently rots as bots are renamed.
+  Cloudflare's own AI-bot toggle does not separate citation bots from training
+  bots, which is why the toggle alone is the wrong instrument.
+
+Verified 2026-09-02 across awesomate.ai, hub.awesomate.ai and eight live client
+sites: all four retrieval bots got **200**, so this is not currently biting the
+fleet. Re-check per site rather than assuming either way — it is a per-zone
+setting and new zones are steered into blocking at signup.
+
+## Most AI crawlers do not run JavaScript
+
+**Googlebot, Gemini and Applebot render JS. GPTBot, ClaudeBot, PerplexityBot,
+OAI-SearchBot and Claude-SearchBot do not** — they read the **raw HTML
+response**. So a client-rendered app (React/Vue/Next SPA without SSR) is
+invisible to ChatGPT, Claude and Perplexity regardless of its meta tags,
+schema or llms.txt.
+
+`awesomate_site_audit` checks this automatically (gate G1) — run it rather
+than eyeballing the page in a browser, which renders the JS and hides the
+problem.
 
 Red flags — check the raw response, not the browser:
 
@@ -100,6 +120,29 @@ app projects, static marketing/landing pages in front of the app is usually
 enough. Don't rebuild a working app over this, but never claim AI
 discoverability for client-rendered content.
 
+## The accidental opt-out — check before blaming anything else
+
+A page can be perfectly built, reachable and fast, and still be barred from
+every AI answer by one directive. Sweep for these before investigating
+anything subtler:
+
+- `<meta name="robots" content="noindex">` — out of search AND AI answers
+- `nosnippet` or `max-snippet:0` — nothing may be quoted, which is the same as
+  being uncitable even though the page still ranks
+- an `X-Robots-Tag` response **header** carrying any of the above (easy to miss:
+  it is not in the HTML, so viewing source shows nothing)
+- a staging `robots.txt` that shipped to production with `Disallow: /`
+- in Search Console, the Search generative AI control left off
+
+The usual causes are an SEO plugin default, a staging file promoted by mistake,
+or a "private launch" setting nobody turned back off. `awesomate_site_audit`
+covers the meta and header cases (gate G3); the Search Console control has to be
+checked by the owner in their own account.
+
+Note that blocking `Google-Extended` does **not** remove a site from AI
+Overviews or AI Mode — that control is about training, not answers. Don't
+"fix" it expecting a visibility change.
+
 ## llms.txt rules
 
 - Optional inventory for non-Google assistants — Google ignores it.

package/skill/awesomate-seo/references/answer-structure.md

@@ -0,0 +1,128 @@
+# Writing to be quoted — structure for AI answers
+
+SEO gets a page found. This gets a page **cited**. Answer engines retrieve
+**passages, not pages**: they lift a section, attribute it, and drop the rest.
+So the section — not the page — is the unit of competition, and a section that
+cannot stand alone cannot be quoted.
+
+Run `awesomate_site_audit` to catch the mechanical faults (gate G8). It cannot
+judge whether an answer is any good; that part is a human read.
+
+## The one rule that matters most
+
+**Answer first.** Under every heading, the first 40–60 words must be a
+complete, standalone statement that names the subject.
+
+Roughly **55% of AI Overview citations come from the first 30% of the page**, so
+an answer buried under three paragraphs of preamble is an answer nobody quotes.
+
+```
+Bad:   ## Our pricing
+       It depends on a few things. Every job is different, and we always…
+
+Good:  ## Our pricing
+       Robs Plumbing charges $180 for a standard callout in metropolitan Perth,
+       including the first 30 minutes on site. Emergency after-hours callouts
+       are $290. Quotes for larger jobs are free and fixed.
+```
+
+The second one survives being lifted out of the page. The first one is useless
+the moment it loses its heading.
+
+## Never open a section with a back-reference
+
+"It", "this", "that", "these", "they", "also", "however", "as above", "as
+mentioned". Once a section is extracted, there is no "above" — the subject has
+vanished. Name it again, every time, even when it reads slightly repetitively on
+the page. Repetition is the cost of being quotable, and it is a small cost.
+
+## Section length: 120–180 words
+
+Long enough to answer, short enough to be one clean retrieval unit. A 900-word
+section under one heading competes with itself: the engine has to choose which
+part to lift, and often lifts none of it. Split it and give each part a heading.
+
+## Say the specific thing
+
+Vague copy loses to specific copy, measurably. Adding **quotations from credible
+sources raised a source's share of an AI answer by roughly 41%, statistics by
+about 31%, and citations by about 28%**.
+
+So: real numbers, real dates, named sources, units and currency **inline in the
+sentence** rather than implied by a table header or an image.
+
+```
+Bad:   We serve the whole metro area and have done for years.
+Good:  We service Perth from Joondalup to Rockingham, and have since 2009.
+```
+
+## Comparisons go in a real `<table>`
+
+`<table>` with `<th>`, never styled divs and never an image of a table. A
+comparison rendered as divs is a wall of unlabelled fragments to a parser; an
+image of a price list is invisible to everything. This is the single most
+common way a genuinely useful pricing page fails to get cited.
+
+## Headings: descriptive, with the question phrasing in the first line
+
+The evidence here is genuinely mixed, so hold it loosely:
+
+- **FAQ *schema* shows a small negative correlation** with citations (one
+  analysis: 3.6 citations with it against 4.2 without). The effect is modest and
+  probably confounded — FAQ blocks tend to sit on thin support pages that would
+  earn fewer citations anyway. Google also retired FAQ rich results in May 2026.
+- **Question-shaped *content*, on the other hand, is the extraction unit
+  everyone describes**: a question followed by a 40–80 word answer.
+
+The safe position that satisfies both readings: **plain descriptive headings,
+with the question phrasing carried in the first body line.** You keep the
+question language on the page where models read it, without betting the page on
+FAQ markup.
+
+Keep real FAQs because users want them. Just don't expect the schema to be the
+lever.
+
+## Every schema fact must also be visible
+
+The hard rule, and the one most often broken: **no fact may exist only in
+JSON-LD.** Models read the rendered text; structured data helps machines agree
+on entities, but a phone number, address or price that appears *only* in the
+markup is invisible to the thing you are optimising for.
+
+`awesomate_site_audit` cross-checks this automatically (gate G7b) and lists any
+schema value missing from the page copy. The fix is always **add it to the
+page** — never delete it from the schema.
+
+## Freshness
+
+A visible "Last updated" date, matching `dateModified` in the JSON-LD. Bump it
+only on substantive change; a date that moves nightly while the words stay the
+same is a stale-content signal, not a freshness one.
+
+Sensible cadence: pricing quarterly, comparisons six-monthly, evergreen guides
+annually.
+
+## What not to bother with
+
+- **llms.txt as a priority.** Generate it if it's free — it is one small file —
+  but one study of 137,210 domains found 97% of published files received zero
+  requests, and Google ignores it outright. Never present it as a pillar, and
+  never bill for it.
+- **Speakable schema.** No engine confirms using it.
+- **Hidden text or instructions aimed at crawlers.** Zero measured effect, and
+  classed as spam by both Google and Microsoft.
+- **Mass AI-written listicles.** Hit hard by the August 2026 spam update, and an
+  organic penalty propagates into AI visibility.
+
+## Local businesses: the profile usually outranks the site
+
+For anything with a location or a service area, **Google Business Profile
+supplies about 67% of local citations in AI Overviews** — more than the website
+does. So a correct primary category, the full services list, real hours and
+real photos are higher-leverage than another page of copy.
+
+Keep the name, address and phone **identical** across the site, the profile and
+the main directories for the vertical. Contradictions are what stop an engine
+treating the business as one confident entity. For AU service businesses that
+means ProductReview.com.au plus the relevant trade directories — not a blast to
+hundreds of listing sites, which does nothing.