@awesomate/hosting-mcp 0.23.0 → 0.24.0

package/dist/index.js

@@ -41251,17 +41251,32 @@ server.registerTool(
   "awesomate_support",
   {
     annotations: annotate("awesomate_support", MUTATING),
-    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.",
+    description: "Help the user with the service itself \u2014 questions, being stuck, or reaching a human. **action 'ask' {q} is the FIRST thing to try for any question about Awesomate** \u2014 it answers from Awesomate's own Knowledge Base with numbered citations, works on every plan, and composes across articles rather than matching titles; relay its answer and cite the source URLs. If it returns no_answer:true the grounding gate declined, so offer a ticket instead of guessing; if degraded:true the Knowledge Base was unavailable and you are looking at keyword matches, so do not present them as a verified answer. 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, category} 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. **`category` is REQUIRED and must name what the ticket is actually about \u2014 'Other' is refused.** Ticket access splits by SUBJECT, not by plan: reporting a problem with AWESOMATE ITSELF ('Infrastructure fault' \u2014 site down, instance unreachable, provisioning or SSL failure; 'Claude/MCP connectivity' \u2014 pairing fails, token rejected, tools erroring) and 'Account/billing' work on EVERY plan. Asking for help USING the products ('Workflow not running', 'Workflow error', 'New automation request', 'How-to question') needs Support Plus or above and returns 403 upgrade_required below it \u2014 when that happens, answer from 'faq'/'help_docs' instead and relay the upgrade honestly; do NOT relabel the ticket as a fault to get through. 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", "help_docs", "create_ticket", "list_tickets"]),
-      q: external_exports.string().optional().describe("faq and help_docs: the question or topic"),
+      action: external_exports.enum(["ask", "faq", "help_docs", "create_ticket", "list_tickets"]),
+      q: external_exports.string().optional().describe("ask, 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")
+      message: external_exports.string().optional().describe("create_ticket only: the body, in the user's words"),
+      category: external_exports.enum([
+        "Infrastructure fault",
+        "Claude/MCP connectivity",
+        "Workflow not running",
+        "Workflow error",
+        "New automation request",
+        "Account/billing",
+        "How-to question"
+      ]).optional().describe(
+        "create_ticket: REQUIRED. What the ticket is about. The first two and Account/billing work on every plan; the rest need Support Plus or above."
+      )
     }
   },
-  async ({ action, q, subject, message }) => {
+  async ({ action, q, subject, message, category }) => {
     try {
       const cfg = requireConfig();
+      if (action === "ask") {
+        if (!q) return errorResult(new Error("ask needs q"));
+        return textResult(await hubGet(cfg, `/api/help/ask?q=${encodeURIComponent(q)}`));
+      }
       if (action === "faq") {
         return textResult(await hubGet(cfg, `/api/help/faq${q ? `?q=${encodeURIComponent(q)}` : ""}`));
       }
@@ -41273,7 +41288,14 @@ server.registerTool(
         return textResult(await hubGet(cfg, "/api/support/tickets"));
       }
       if (!subject || !message) return errorResult(new Error("create_ticket needs subject and message"));
-      return textResult(await hubPost(cfg, "/api/support/tickets", { subject, body_text: message }));
+      if (!category) {
+        return errorResult(
+          new Error(
+            'create_ticket needs a category naming what the ticket is about. Use "Infrastructure fault" or "Claude/MCP connectivity" when the problem is with Awesomate itself, "Account/billing" for money, and the workflow/how-to categories (Support Plus and above) for help using the products.'
+          )
+        );
+      }
+      return textResult(await hubPost(cfg, "/api/support/tickets", { subject, body_text: message, category }));
     } catch (err) {
       return errorResult(err);
     }
@@ -41303,7 +41325,7 @@ server.registerTool(
   "awesomate_site_create",
   {
     annotations: annotate("awesomate_site_create", MUTATING),
-    description: "Create a WordPress site on the user's hosting. Plan limits are enforced server-side (429/403 with an upgrade hint if they're at their cap \u2014 relay it; 409 means WordPress already exists at that domain). Ask 'live or dev?' first per the awesomate-hosting skill. Omit `domain` and the next free siteN.{primary} subdomain is chosen for you. ASYNC and returns only {success:true} \u2014 no domain, no admin details: poll awesomate_list_sites to learn the name, and expect HTTPS to refuse connections for a minute or two while AutoSSL issues even though the site is already serving over http. See 'After creating a site' in the skill.",
+    description: "Create a WordPress site on the user's hosting. **Needs Support Plus or above from Claude** \u2014 on Essentials this returns 403 `upgrade_required` ALWAYS, not only at a cap, because building hosting from a machine token is a Support Plus capability; the Essentials site itself is real and is created by the user in the hub at hub.awesomate.ai/sites, so offer that path first rather than leading with the upgrade. Plan COUNT limits are enforced separately (403 with an upgrade hint at the cap; 409 means WordPress already exists at that domain). Ask 'live or dev?' first per the awesomate-hosting skill. Omit `domain` and the next free siteN.{primary} subdomain is chosen for you. ASYNC and returns only {success:true} \u2014 no domain, no admin details: poll awesomate_list_sites to learn the name, and expect HTTPS to refuse connections for a minute or two while AutoSSL issues even though the site is already serving over http. See 'After creating a site' in the skill.",
     inputSchema: {
       domain: external_exports.string().optional().describe("Custom domain if they have one; omit for a default *.awesomate.site subdomain"),
       siteTitle: external_exports.string().optional(),
@@ -41322,7 +41344,7 @@ server.registerTool(
   "awesomate_domain_add",
   {
     annotations: annotate("awesomate_domain_add", MUTATING),
-    description: "Add a custom domain to the user's hosting account. Returns the DNS steps they need to complete at their registrar. Plan-gated (some plans allow zero custom domains \u2014 relay the upgrade hint on 403).",
+    description: "Add a custom domain to the user's hosting account. Returns the DNS steps they need to complete at their registrar. **Needs Support Plus or above from Claude** \u2014 Essentials gets 403 `upgrade_required` even though its plan DOES include one custom domain, because adding it from a machine token is Support Plus; tell them it takes two clicks at hub.awesomate.ai/sites/domains instead. Plan COUNT limits are enforced separately on top.",
     inputSchema: { domain: external_exports.string().describe("The domain to add, e.g. example.com") }
   },
   async ({ domain }) => {
@@ -41337,7 +41359,7 @@ server.registerTool(
   "awesomate_run_wp_cli",
   {
     annotations: annotate("awesomate_run_wp_cli", DESTRUCTIVE),
-    description: "Run an allowlisted WP-CLI command on one of the user's WordPress sites (plugin/theme list+activate+update, cache flush, option get/update, post/media/menu/comment/user list). ARGUMENTS CANNOT CONTAIN SPACES (letters, digits and -_./=:@+, only) \u2014 so a site title, tagline or any multi-word value is impossible here: use awesomate_wp_settings for those, and awesomate_wp_post for post/page content. Installs accept wp.org SLUGS only \u2014 never URLs. args is the command as an array, e.g. ['plugin','list'] or ['plugin','install','wordpress-seo','--activate']. A 400 wp_cli_not_allowed means that command isn't permitted; a 502 wp_cli_unavailable is a temporary server-side issue, not your command.",
+    description: "Run an allowlisted WP-CLI command on one of the user's WordPress sites (plugin/theme list+activate+update, cache flush, option get/update, post/media/menu/comment/user list). **Needs Support Plus or above** \u2014 the whole route is behind the write gate, so even the READS (option get, plugin list) return 403 `upgrade_required` on Essentials. ARGUMENTS CANNOT CONTAIN SPACES (letters, digits and -_./=:@+, only) \u2014 so a site title, tagline or any multi-word value is impossible here: use awesomate_wp_settings for those, and awesomate_wp_post for post/page content. Installs accept wp.org SLUGS only \u2014 never URLs. args is the command as an array, e.g. ['plugin','list'] or ['plugin','install','wordpress-seo','--activate']. A 400 wp_cli_not_allowed means that command isn't permitted; a 502 wp_cli_unavailable is a temporary server-side issue, not your command.",
     inputSchema: {
       domain: external_exports.string().describe("The site domain"),
       args: external_exports.array(external_exports.string()).describe("WP-CLI args, e.g. ['plugin','list']")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "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/awesomate-support/SKILL.md

@@ -28,36 +28,61 @@ what's actually spendable once credits promised to builds in flight are
 set aside — rather than the raw balance.) Never quote a plan, price, or
 balance from memory.
 
-## 1. FAQ first, then help docs
+## 1. Ask the Knowledge Base first
 
 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 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. (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.)
+1. Call `awesomate_support {action:'ask', q:'<their question>'}`. This is
+   Awesomate's own Knowledge Base answering from Awesomate's own content,
+   with numbered citations. It works on every plan.
+2. Read the response's `source` and `degraded` fields before you answer —
+   they are the difference between three very different situations:
+
+   - `source:'knowledge_base'`, `no_answer:false` → a grounded answer.
+     Relay it in your own plain words and give the citation URLs.
+   - `source:'knowledge_base'`, `no_answer:true` → the grounding gate
+     declined, because the answer is not in our content. **Do not fill the
+     gap yourself.** Offer a ticket (§2).
+   - `degraded:true` → the Knowledge Base was unavailable or is not
+     switched on, and you are looking at keyword matches from `faq` and
+     `docs` instead. Useful, but **never present them as a verified
+     answer**, and say the search was limited if it matters.
+
+3. Only if `ask` came back thin do you need `faq` or `help_docs` directly.
+   Both remain available and behave as before, and `help_centre_url` in
+   any response is always safe to offer for browsing.
+4. Cite nothing the tools didn't say. No invented policy, no guessed
+   pricing, no remembered plan limits.
 
 ## 2. Ticket flow — talking to a human
 
 When the user wants a human, or §1 came up empty:
 
+**First, what is this ticket about?** Access splits by SUBJECT, not by
+plan, and you must pass a `category` naming it. `Other` is refused.
+
+| The problem is | category | Who can raise it |
+|---|---|---|
+| Our platform is broken: site down, n8n unreachable, provisioning or SSL failed, the hub is erroring | `Infrastructure fault` | **every plan** |
+| They cannot connect or use Claude: pairing fails, the token is rejected, tools error | `Claude/MCP connectivity` | **every plan** |
+| Money: invoices, plans, credits, refunds | `Account/billing` | **every plan** |
+| Help USING n8n, their website, or the Knowledge Base | `Workflow not running`, `Workflow error`, `New automation request`, `How-to question` | **Support Plus and above** |
+
+Choose the category that is actually true. If a product-help ticket comes
+back `403 upgrade_required`, answer from §1 instead and relay the upgrade
+honestly — **never relabel a workflow question as an outage to get it
+through.** That is lying to your own support team about the state of the
+platform, and it puts a false fault report in front of an engineer.
+
 1. Draft the ticket in the USER'S words — their description of the problem,
    what they were trying to do, what happened. Add context you observed
    (which site/app, what you already tried) in one short paragraph. No
    stack traces, no jargon dumps.
 2. Show the full draft (subject + message) and ask plainly: "Send this to
    the Awesomate team?" NEVER call `create_ticket` without an explicit yes.
-3. On yes: `awesomate_support {action:'create_ticket', subject, message}`.
-   Confirm: "Sent. The team replies by email, usually within a business
-   day."
+3. On yes: `awesomate_support {action:'create_ticket', subject, message,
+   category}`. Confirm: "Sent. The team replies by email, usually within a
+   business day."
 4. Later, "any update on my ticket?" →
    `awesomate_support {action:'list_tickets'}` and report each ticket's
    status in one line.