@awesomate/hosting-mcp 0.15.0 → 0.16.1

package/dist/index.js

@@ -40031,7 +40031,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_get_context",
   {
-    description: "Call this FIRST each session. Returns the connected Awesomate account: plan, capabilities (shell access), plan limits, scopes this token can exercise, token expiry (warn the user if within 7 days), cPanel routing when provisioned, and skill.updateAvailable \u2014 if true, the local awesomate-hosting skill files are older than this server; tell the user to re-run Connect Claude Code from hub.awesomate.ai/sites to refresh them (this also renews the token).",
+    description: "Call this FIRST each session. Returns the connected Awesomate account: plan, capabilities (shell access), plan limits, scopes this token can exercise, token expiry (warn the user if within 7 days), cPanel routing when provisioned, and skill.updateAvailable \u2014 if true, the local Awesomate skill files are older than this server; run awesomate_skill_update to refresh them in place (new content loads next session \u2014 mention once, finish the current task first). If the token is also near expiry, re-running Connect Claude Code from hub.awesomate.ai/sites refreshes skills AND renews the token in one go.",
     inputSchema: {}
   },
   async () => {
@@ -40285,10 +40285,10 @@ server.registerTool(
 server.registerTool(
   "awesomate_support",
   {
-    description: "Help the user with the service itself \u2014 questions, being stuck, or reaching a human. action 'faq' {q} searches the published help library (answer FROM the results; never invent policy or pricing). action 'create_ticket' {subject, message} opens a support ticket \u2014 draft it in the user's words, SHOW it, and get an explicit yes before sending; it emails the Awesomate team and returns a portal URL. action 'list_tickets' shows their tickets and status. Use the awesomate-support skill for the full flow. Not for building \u2014 route n8n work to awesomate-n8n and hosting to awesomate-hosting.",
+    description: "Help the user with the service itself \u2014 questions, being stuck, or reaching a human. action 'faq' {q} searches the published help library (answer FROM the results; never invent policy or pricing). action 'help_docs' {q} searches the full Help Centre articles live \u2014 use when the FAQ has no good answer, and cite the returned article URLs. action 'create_ticket' {subject, message} opens a support ticket \u2014 draft it in the user's words, SHOW it, and get an explicit yes before sending; it emails the Awesomate team and returns a portal URL. action 'list_tickets' shows their tickets and status. Use the awesomate-support skill for the full flow. Not for building \u2014 route n8n work to awesomate-n8n and hosting to awesomate-hosting.",
     inputSchema: {
-      action: external_exports.enum(["faq", "create_ticket", "list_tickets"]),
-      q: external_exports.string().optional().describe("faq only: the question"),
+      action: external_exports.enum(["faq", "help_docs", "create_ticket", "list_tickets"]),
+      q: external_exports.string().optional().describe("faq and help_docs: the question or topic"),
       subject: external_exports.string().optional().describe("create_ticket only"),
       message: external_exports.string().optional().describe("create_ticket only: the body, in the user's words")
     }
@@ -40299,6 +40299,10 @@ server.registerTool(
       if (action === "faq") {
         return textResult(await hubGet(cfg, `/api/help/faq${q ? `?q=${encodeURIComponent(q)}` : ""}`));
       }
+      if (action === "help_docs") {
+        if (!q) return errorResult(new Error("help_docs needs q"));
+        return textResult(await hubGet(cfg, `/api/help/docs?q=${encodeURIComponent(q)}`));
+      }
       if (action === "list_tickets") {
         return textResult(await hubGet(cfg, "/api/support/tickets"));
       }

package/package.json

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

package/skill/awesomate-hosting/SKILL.md

@@ -37,8 +37,9 @@ once (plus `awesomate_get_limits` before any create/change) and cache:
 - **`patExpiresAt`** — within ~7 days, or any 401: re-run the setup prompt at
   **hub.awesomate.ai/sites → Connect Claude Code** to refresh the token.
 - **`skill.updateAvailable`** — this skill's local files are older than the MCP
-  server. Mention once (don't nag); the same Connect re-run refreshes the skill
-  and renews the token in one go. Not urgent — finish the user's request first.
+  server. Mention once (don't nag); run `awesomate_skill_update` to refresh in
+  place (new content loads next session). If the token is also near expiry, the
+  Connect re-run above does both. Not urgent — finish the user's request first.
 - **`cpanel`** routing (host/user), present once hosting is provisioned.
 
 If `awesomate_get_context` fails with a connectivity error, it's the user's

package/skill/awesomate-seo/SKILL.md

@@ -40,6 +40,9 @@ formats + length limits. In short, per site:
 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).
 
 Then commit + deploy (awesomate-github). On content changes, update the
 affected `<head>` tags, `sitemap.xml` `<lastmod>`, and `llms.txt`.
@@ -61,6 +64,13 @@ Through the awesomate-hosting skill's `wp` passthrough:
 - 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).
 - `llms.txt` exists and is accurate.
+- **Content is in the raw HTML** — `curl -s https://DOMAIN/page` shows the
+  actual content, not an empty `<div id="root">`. AI crawlers don't run
+  JavaScript; a client-rendered page is invisible to them.
+- **AI crawlers aren't blocked at the edge** — a `curl` with a GPTBot /
+  ClaudeBot user-agent returns 200, not a 403/Cloudflare challenge (Cloudflare
+  blocks many AI bots by default; robots.txt can't fix that). Commands + where
+  to fix each case: [references/ai-discoverability.md](references/ai-discoverability.md).
 Tell the user the next step is submitting the sitemap in Google Search Console
 (you can't do that for them) — offer a one-paragraph how-to if they want it.
 

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

@@ -0,0 +1,109 @@
+# AI discoverability — crawlers, rendering, llms.txt
+
+How AI assistants (ChatGPT, Claude, Perplexity, Gemini, Copilot) find and cite
+a site — and the two silent failure modes that make a "perfectly SEO'd" site
+invisible to them anyway. Crawler/rendering tables adapted from
+[claude-blog](https://github.com/AgriciDaniel/claude-blog) (MIT © AgriciDaniel).
+
+## Google needs nothing special — say so when asked
+
+Google's official guidance
+(https://developers.google.com/search/docs/fundamentals/ai-optimization-guide):
+AI Overviews and AI Mode run on Google's normal Search ranking systems. No
+special markup, no AI schema, no llms.txt — **Google Search ignores llms.txt
+entirely**. Normal SEO (the main checklist) *is* the Google-AI strategy. If
+the user asks about "GEO"/"AEO" tactics or paid AI-optimization services,
+this is the honest answer: for Google it's just SEO; for other assistants
+the extras below help.
+
+llms.txt still earns its place for **non-Google** assistants — keep writing
+it, but present it as that, never as a Google requirement.
+
+## Three kinds of AI bot — three different decisions
+
+| Kind | Bots | Blocking means |
+|---|---|---|
+| Search-indexing | OAI-SearchBot, Claude-SearchBot, PerplexityBot | The site can't be cited in that assistant's answers. **Allow these.** |
+| 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 |
+
+The default `User-agent: * / Allow: /` robots.txt already allows all of them —
+no explicit allowlist needed. Explicit stanzas only matter when the owner
+wants to opt out of **training** while staying visible in answers:
+
+```
+# Stay citable, opt out of model training
+User-agent: GPTBot
+Disallow: /
+
+User-agent: Google-Extended
+Disallow: /
+
+User-agent: CCBot
+Disallow: /
+
+User-agent: *
+Allow: /
+Sitemap: https://DOMAIN/sitemap.xml
+```
+
+Never block the search-indexing bots "for safety" — that silently removes the
+site from ChatGPT/Claude/Perplexity answers.
+
+Note for Awesomate-managed domains: the CDN prepends a managed section to the
+site's robots.txt (a Content Signals preamble plus disallows for the
+*training*-bot family). Search-indexing bots stay allowed, so the site remains
+citable — but the served robots.txt is the site file *plus* that preamble.
+Always check the live `https://DOMAIN/robots.txt`, not just the file you wrote.
+
+## robots.txt allows it — but the CDN can still 403 it
+
+Cloudflare **blocks many AI crawlers by default on new zones** (GPTBot,
+ClaudeBot, PerplexityBot, CCBot, Google-Extended). The crawler gets a 403 or a
+challenge page before it ever reads robots.txt, so a perfect robots.txt proves
+nothing. Always verify from the outside:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}\n" -A "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; GPTBot/1.0; +https://openai.com/gptbot)" https://DOMAIN/
+curl -s -o /dev/null -w "%{http_code}\n" -A "Mozilla/5.0 (compatible; ClaudeBot/1.0)" https://DOMAIN/
+curl -s -o /dev/null -w "%{http_code}\n" -A "Mozilla/5.0 (compatible; PerplexityBot/1.0)" https://DOMAIN/
+```
+
+200 = reachable. 403, 503, or an HTML page mentioning Cloudflare = blocked at
+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.
+
+## AI crawlers do not run JavaScript
+
+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.
+
+Red flags — check the raw response, not the browser:
+
+```bash
+curl -s https://DOMAIN/page | head -100
+```
+
+- Body is essentially an empty `<div id="root">` / `<div id="app">` /
+  `<div id="__next">`
+- Full HTML under ~5KB for a content page
+- The content exists only inside `<script>` tags as JSON
+
+Fix: keep public, indexable content in static or server-rendered HTML — for
+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.
+
+## llms.txt rules
+
+- Optional inventory for non-Google assistants — Google ignores it.
+- Under 10KB (assistants may truncate or skip larger files).
+- Markdown links: `[Title](URL): one-line description`. Only real,
+  high-value pages; only true facts.
+- Supplements sitemap.xml, never replaces it. Update both when content changes.

package/skill/awesomate-seo/references/seo-checklist.md

@@ -47,10 +47,32 @@ Pick the type that fits; validate before shipping.
 ```
 Common types: `WebSite` (+ `SearchAction`), `Organization` / `LocalBusiness`
 (add `address`, `telephone`, `openingHours`), `Product` (`offers`, `brand`,
-`gtin`), `Article` (`headline`, `datePublished`, `author`), `FAQPage`.
+`gtin`), `Article` (`headline`, `datePublished`, `author`).
+
+**Don't add `FAQPage` or `HowTo` expecting search features** — Google retired
+FAQ rich results for all sites on 2026-05-07 and HowTo earlier. Both remain
+valid schema.org markup, but they earn nothing; only add them if the visible
+FAQ itself is useful.
+
+Multiple entities on one page: combine them in ONE script tag using `@graph`,
+with stable `@id` fragments cross-referencing instead of duplicating:
+```json
+{
+  "@context": "https://schema.org",
+  "@graph": [
+    { "@type": "Organization", "@id": "https://DOMAIN/#organization", "name": "Brand", "url": "https://DOMAIN/", "logo": "https://DOMAIN/logo.png" },
+    { "@type": "Article", "@id": "https://DOMAIN/PATH#article", "headline": "…", "datePublished": "YYYY-MM-DD", "publisher": { "@id": "https://DOMAIN/#organization" } }
+  ]
+}
+```
+Keep `@id` values stable across rebuilds (URL + `#fragment`, never random).
+Validate at https://validator.schema.org (schema validity); use Google's Rich
+Results Test only for types Google actually supports as rich results.
 
 ## `llms.txt` (site root — AI discoverability)
-Plain markdown so assistants can read + cite the site. Keep it current.
+Plain markdown so assistants can read + cite the site. Keep it current and
+under 10KB. Honest framing: **Google ignores llms.txt** — it serves the other
+AI assistants (see [ai-discoverability.md](ai-discoverability.md)).
 ```
 # Brand — what we do
 

package/skill/awesomate-support/SKILL.md

@@ -20,18 +20,22 @@ also carries the plan). Describe what a plan or upgrade INCLUDES from
 balance without spending anything. Never quote a plan, price, or balance
 from memory.
 
-## 1. FAQ first
+## 1. FAQ first, then help docs
 
 For any "how do I", "why does", "what is" question about the service:
 
 1. Call `awesomate_support {action:'faq', q:'<their question>'}`.
 2. Answer FROM the returned entries, in your own plain words. Cite nothing
    the FAQ and tools didn't say — no invented policy, no guessed pricing.
-3. If the FAQ answers it, you're done. If it partially answers, give what
-   you have and say which part is unconfirmed.
-4. If it doesn't answer it: "I don't have a confirmed answer for that. Want
+3. If the FAQ misses or only partially answers, call
+   `awesomate_support {action:'help_docs', q:'<topic>'}` — a live search of
+   the full Help Centre articles. Answer from the excerpts and give the
+   article's URL so the user can read the full steps.
+4. If neither answers it: "I don't have a confirmed answer for that. Want
    me to ask the Awesomate team? I'll draft a support ticket for you to
-   approve first." Then go to §2 if they say yes.
+   approve first." Then go to §2 if they say yes. (An empty help_docs
+   result can also mean the search is temporarily down — the response's
+   help_centre_url is always safe to offer for browsing.)
 
 ## 2. Ticket flow — talking to a human