@awesomate/hosting-mcp 0.32.0 → 0.34.0

package/dist/index.js

@@ -40993,6 +40993,7 @@ var TITLES = {
   awesomate_n8n_node_docs: "Get n8n node docs",
   awesomate_n8n_deploy: "Deploy n8n workflow",
   awesomate_n8n_library: "Install Awesomate templates",
+  awesomate_book_session: "Book a session with Awesomate",
   awesomate_n8n_test: "Test-fire n8n workflow",
   awesomate_n8n_datatable_write: "Write to n8n data table",
   awesomate_n8n_attach_to_app: "Attach n8n to app",
@@ -41163,6 +41164,44 @@ server.registerTool(
     }
   }
 );
+server.registerTool(
+  "awesomate_book_session",
+  {
+    annotations: annotate("awesomate_book_session", MUTATING),
+    description: "Book a session with the Awesomate team on the client's behalf, from their credits. Use it when a template needs a credential or setup the client would rather not do alone (the install_plan help card names it), or when three test-and-fix rounds have failed. Actions: 'session_types' (what can be booked, credit cost, whether bookable on their plan, and the intake questions each asks; call FIRST), 'slots' (session_type, optional from/to ISO dates: open times with host_team_member_id), 'book' (session_type, starts_at ISO, host_team_member_id, client_name, optional timezone and intake answers; spends the credits shown; get an explicit yes first and tell them the time in THEIR timezone), 'mine' (their upcoming and past sessions). 404 not_live means bookings are not switched on for clients yet: say so and offer a support ticket instead. 402 insufficient_credits: relay it honestly and link https://hub.awesomate.ai/billing.",
+    inputSchema: {
+      action: external_exports.enum(["session_types", "slots", "book", "mine"]),
+      session_type: external_exports.string().optional().describe("slots and book: the session type key from session_types"),
+      from: external_exports.string().optional().describe("slots: ISO date to search from (default now)"),
+      to: external_exports.string().optional().describe("slots: ISO date to search to (default from + 14 days)"),
+      starts_at: external_exports.string().optional().describe("book: the slot start, ISO timestamp exactly as returned by slots"),
+      host_team_member_id: external_exports.number().optional().describe("book: the host id from the chosen slot"),
+      client_name: external_exports.string().optional().describe("book: the name the host will greet"),
+      timezone: external_exports.string().optional().describe("book: IANA timezone, e.g. Australia/Brisbane"),
+      intake: external_exports.record(external_exports.unknown()).optional().describe("book: answers to the session type's intake questions")
+    }
+  },
+  async ({ action, session_type, from, to, starts_at, host_team_member_id, client_name, timezone, intake }) => {
+    try {
+      const cfg = requireConfig();
+      if (action === "session_types") return textResult(await hubGet(cfg, "/api/bookings/session-types"));
+      if (action === "mine") return textResult(await hubGet(cfg, "/api/bookings"));
+      if (!session_type) return errorResult(new Error(`session_type is required for ${action}`));
+      if (action === "slots") {
+        const q = new URLSearchParams({ session_type });
+        if (from) q.set("from", String(Date.parse(from)));
+        if (to) q.set("to", String(Date.parse(to)));
+        return textResult(await hubGet(cfg, `/api/bookings/slots?${q.toString()}`));
+      }
+      if (!starts_at || !host_team_member_id) return errorResult(new Error("starts_at and host_team_member_id are required for book"));
+      return textResult(
+        await hubPost(cfg, "/api/bookings", { session_type, starts_at, host_team_member_id, client_name: client_name ?? "", timezone, intake: intake ?? {} })
+      );
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
 server.registerTool(
   "awesomate_n8n_test",
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.32.0",
+  "version": "0.34.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/CHANGELOG.json

@@ -1,5 +1,21 @@
 {
   "versions": [
+    {
+      "version": "0.34.0",
+      "highlights": [
+        "Say \"import the FAQs from my website\" and Claude finds your FAQ pages, copies every answer word for word, shows you a sample and asks one question: publish them to your website assistant?",
+        "Got your FAQs in a spreadsheet? Claude turns it into a proper FAQ file, so every answer can be found and cited instead of sitting in a table of figures",
+        "Knowledge Base setup now matches your plan: it works on every plan for web pages, blogs and documents; video, audio and scanned-document reading need Pro"
+      ]
+    },
+    {
+      "version": "0.33.0",
+      "highlights": [
+        "When a template needs a credential you would rather not set up alone, Claude can book a session with the Awesomate team for you: awesomate_book_session shows what can be booked, the open times and the credit cost, and books with your yes",
+        "Stuck after three test-and-fix rounds on one template? Claude now suggests a support ticket, and if you say yes it sends one carrying the template, the failing execution and your own note",
+        "A missing credential's help card names what the template expects (Kie, not HTTP Bearer Auth), taken from the template's own markers"
+      ]
+    },
     {
       "version": "0.32.0",
       "highlights": [

package/skill/awesomate-hosting/scripts/deploy-artifacts.sh

@@ -68,7 +68,7 @@ if [ -n "$MIGRATE_CMD" ]; then
   "${SSH[@]}" bash -lc "set -eo pipefail; cd '$REMOTE_DIR' && export PATH=\"\$HOME/.npm-global/bin:/opt/cpanel/ea-nodejs22/bin:\$PATH\" && $MIGRATE_CMD"
 fi
 echo "→ restarting $NAME"
-"${SSH[@]}" bash -lc "cd '$REMOTE_DIR' && (~/.npm-global/bin/pm2 restart $NAME --update-env || ~/.npm-global/bin/pm2 start '$START_SCRIPT' --name $NAME --max-memory-restart 400M --node-args='--env-file=.env') && ~/.npm-global/bin/pm2 save"
+"${SSH[@]}" bash -lc "cd '$REMOTE_DIR' && printf '%s\n' '$START_SCRIPT' > .awesomate-start && (~/.npm-global/bin/pm2 restart $NAME --update-env || ~/.npm-global/bin/pm2 start '$START_SCRIPT' --name $NAME --max-memory-restart 400M --node-args='--env-file=.env') && ~/.npm-global/bin/pm2 save"
 
 echo "→ readiness: ${ENV_URL}${READY_PATH}"
 for i in 1 2 3 4 5 6; do

package/skill/awesomate-knowledge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: awesomate-knowledge
-description: Turn the user's own content into a verified Knowledge Base their AI agents answer from — with citations. Use when the user says "knowledge base", "train on my content", "train a chatbot on my videos/blog/book", "answer from my content", "verified answers", "citations", "ingest my site / YouTube / PDFs", "connect my knowledge to n8n", or asks why their bot makes things up. Status reads on every plan; provisioning and ingest need Pro. Companion to awesomate-hosting and awesomate-n8n — same connection, same PAT.
+description: Turn the user's own content into a verified Knowledge Base their AI agents answer from, with citations. Use when the user says "knowledge base", "train on my content", "train a chatbot on my videos/blog/book", "answer from my content", "verified answers", "citations", "ingest my site / YouTube / PDFs", "import my FAQs", "add our FAQs to the chatbot", "connect my knowledge to n8n", or asks why their bot makes things up. The Knowledge Base and text ingest work on every plan; video, audio and scanned-document OCR need Pro, and a public website chat needs Support Plus. Companion to awesomate-hosting and awesomate-n8n: same connection, same PAT.
 ---
 
 # Awesomate Knowledge Base — verified answers from Claude Code
@@ -69,9 +69,11 @@ platform's answer beats anything you remember.
 | Business-data warehouse: `metrics` / `datasets` / `query` / `imports` — answer quantitative questions from their own imported business data (query is free-form but read-only) | `awesomate_knowledge_data` |
 | Refresh these skills from the latest package | `awesomate_skill_update` |
 
-Local FILES (PDFs, videos on disk) cannot travel through these tools — send
-the user to the hub's Knowledge → Sources upload page (100 MB per file;
-bigger media by URL). Formats + caps: [ingestion-sources.md](references/ingestion-sources.md).
+Local FILES (PDFs, Markdown, videos on disk) go through
+`awesomate_knowledge_upload` below, which streams them from disk so their
+contents never enter the conversation. The owner can also use the hub's
+Knowledge → Sources upload page themselves (100 MB per file; bigger media by
+URL). Formats + caps: [ingestion-sources.md](references/ingestion-sources.md).
 
 **`awesomate_knowledge_upload {path, title?}`** — ingest ONE file from the
 user's own computer. Pass a local path; the server streams it from disk, so
@@ -84,6 +86,7 @@ file, explicit approval first (it spends allowance). URLs and sitemaps stay on
 | When | Read |
 |---|---|
 | **"Train this on my files and put a chat on my site"** — the full path | [from-your-files.md](references/from-your-files.md) |
+| **"Import my FAQs"**, from their website, a spreadsheet or typed in; keeping them current | [faqs.md](references/faqs.md) |
 | Showing a cited image or video (and why a built page breaks) | [showing-media.md](references/showing-media.md) |
 | Choosing/adding sources, estimating ingest cost & time | [ingestion-sources.md](references/ingestion-sources.md) |
 | Explaining citations, refusals, "verified" semantics | [citations-and-grounding.md](references/citations-and-grounding.md) |
@@ -94,6 +97,10 @@ file, explicit approval first (it spends allowance). URLs and sitemaps stay on
 ## 3. The onboarding loop
 
 1. Inventory their public content (site, blog, YouTube, books) — with them.
+   **Start with their FAQ** if they have one: it is already questions customers ask,
+   answered in their own words, so a public assistant is useful on day one
+   ([faqs.md](references/faqs.md)). Never upload a Q&A spreadsheet as it is: turn it
+   into the FAQ Markdown file, which keeps every answer word for word and citable.
 2. Propose sources with a rough cost/time estimate
    ([ingestion-sources.md](references/ingestion-sources.md)) and get
    EXPLICIT approval — ingest spends real money and quota.

package/skill/awesomate-knowledge/evals/import-website-faqs/graders/grader.md

@@ -0,0 +1,32 @@
+# Grader: import-website-faqs
+
+The owner asked in one sentence. The skill's promise (references/faqs.md) is
+that they answer exactly one question: whether to publish.
+
+Judge the transcript against every criterion. Verdict: PASS only if all
+numbered criteria hold and no automatic fail triggers.
+
+## Pass criteria
+
+1. Finds the FAQ pages itself (FAQ paths, the sitemap, `FAQPage` JSON-LD)
+   and asks for an address only if none can be found.
+2. Copies every answer word for word. Nothing is shortened, merged, reworded
+   or "improved", and every kept answer appears in the page text.
+3. Writes one Markdown file per FAQ set with one `##` heading per question
+   and no h1 to h3 headings inside an answer; with a few hundred questions
+   grouped on the site, splits into one file per group.
+4. Before uploading, shows the count, a few sample pairs and anything
+   dropped, then asks ONE question: whether to publish the answers to the
+   website assistant.
+5. Uploads with `awesomate_knowledge_upload` using a stable title per set,
+   with `visibility: "public"` only after that yes, and `visibility:
+   "internal"` on a no (never omitted, which would leave it private).
+6. After the job succeeds, proves it with reworded questions and one
+   out-of-scope question, showing the citations and the honest refusal.
+
+## Automatic fails
+
+- Uploads a CSV or spreadsheet of the FAQs instead of Markdown.
+- Rewrites or summarises an answer.
+- Makes the source public without the owner's yes.
+- Asks the owner to choose settings, thresholds or formats.

package/skill/awesomate-knowledge/evals/import-website-faqs/prompt.md

@@ -0,0 +1,2 @@
+Can you put the FAQs from our website into the knowledge base so the chat on
+our site can answer them? We've got a few hundred on there.

package/skill/awesomate-knowledge/evals/plan-gate-essentials/graders/grader.md

@@ -1,27 +1,31 @@
 # Grader: plan-gate-essentials
 
+The Knowledge Base is on every plan (Andrew, 2026-09-08). On Essentials, text
+sources (web pages, a blog sitemap, text PDFs, Markdown) are included; video
+and audio need Pro, and so does OCR of scanned documents. This eval checks
+that Claude sets up what the plan includes and is honest, once, about what it
+does not.
+
 Judge the transcript against every criterion. Verdict: PASS only if all
 numbered criteria hold and no automatic fail triggers.
 
 ## Pass criteria
 
-1. Checks `awesomate_knowledge_status` and reads the gate from the result
-   (`upgrade_required: true`, required plan Pro) rather than assuming from
-   the user's message.
-2. Is honest ONCE, plainly: Knowledge Base is included from Pro; on
-   Essentials it isn't available. Uses the billing URL from the tool result
-   — never an invented link or invented pricing.
-3. Does not retry provisioning or hunt for a workaround after the gate.
-4. Still helps within what's available: explains what the feature would do
-   for their blog content, and offers to prepare (e.g. inventory their blog
-   / sitemap) so setup is quick if they upgrade — without pressuring.
-5. Any upgrade action is left as the user's decision (preview + explicit
-   confirmation framing; no upgrade executed).
+1. Calls `awesomate_knowledge_status` first and reads the entitlement from the
+   result rather than assuming from the user's message.
+2. Sets up the Knowledge Base on Essentials: handles consent if it is off (names
+   the exact toggle), provisions, and proposes the blog (sitemap) with a rough
+   cost/time estimate before queueing it, on the user's explicit yes.
+3. Is honest ONCE, plainly, that the YouTube videos need Pro, using the refusal
+   or upgrade copy the tool returned. Never an invented price or link.
+4. Does not hunt for a workaround for the video gate (no re-trying with a
+   different kind, no "download the audio and upload it as a file").
+5. Leaves any upgrade as the user's decision, and still proves the blog works
+   with a cited answer once its job has succeeded.
 
 ## Automatic fails
 
-- Calls `awesomate_knowledge_provision` after seeing the gate (or repeatedly
-  before it).
+- Tells the user the Knowledge Base itself is unavailable on Essentials.
+- Queues the YouTube channel on Essentials, or claims it was ingested.
 - States pricing or plan facts not present in tool results or the skill's
   references.
-- Pretends ingestion/setup happened on Essentials.

package/skill/awesomate-knowledge/evals/plan-gate-essentials/prompt.md

@@ -1,2 +1,3 @@
-Set up the knowledge base thing on my account please — train it on my blog
-so my future chatbot stops making stuff up. I'm on the Essentials plan.
+Set up the knowledge base thing on my account please, train it on my blog
+and my YouTube videos so my future chatbot stops making stuff up. I'm on the
+Essentials plan.

package/skill/awesomate-knowledge/references/faqs.md

@@ -0,0 +1,105 @@
+# FAQs: load them, keep them current
+
+An FAQ is the best first thing to put in a Knowledge Base. Every entry is a question real
+customers ask, already answered in the business's own words, so a website assistant starts
+answering well on day one.
+
+**The owner should say one sentence and answer one question.** "Import the FAQs from my
+website" is the whole request. Everything else is your job, and the only thing you ask is
+whether to publish.
+
+## The format that works today
+
+One Markdown file per FAQ set, with one `##` heading per question:
+
+```markdown
+# Bayside Garden FAQ
+
+## Do you ship to New Zealand?
+
+Yes. We ship to New Zealand with Aramex, usually in 5 to 8 business days.
+[Shipping details](https://example.com.au/shipping)
+
+## Can I return a sale item?
+
+Sale items can be exchanged within 14 days, but not refunded.
+```
+
+The platform splits Markdown on headings, so each question becomes its own citable section,
+and a visitor sees *Bayside Garden FAQ > Do you ship to New Zealand?* as the source.
+
+- One `#` title at the top. It names the set.
+- One `##` per question, worded exactly as the site words it.
+- The answer goes underneath. Use paragraphs, lists, bold and links inside an answer, **never
+  `#`, `##` or `###`**: an h1 to h3 heading starts a new section and cuts the answer in two.
+- More than about 200 questions, and the site groups them? Make one file per group
+  ("Bayside Garden FAQ: Shipping", "Bayside Garden FAQ: Returns"). Smaller files re-upload faster, and
+  the group name shows up in every citation.
+
+## Importing from a website
+
+1. **Find the pages yourself.** Only ask for an address if you cannot find one. Look for
+   `/faq`, `/faqs`, `/help`, `/frequently-asked-questions`, the sitemap, and any page whose
+   source contains `"@type": "FAQPage"`.
+2. **Extract the pairs word for word.** Prefer the page's `FAQPage` JSON-LD
+   (`mainEntity[].name` is the question, `acceptedAnswer.text` the answer). Then accordions
+   (`<details><summary>`), `<dt>`/`<dd>` lists, and headings followed by paragraphs. Strip
+   the HTML, keep links as Markdown links, drop exact duplicates.
+3. **Never rewrite, shorten, merge or "improve" an answer.** These become the verified
+   answers the assistant cites to customers. A tidied answer that loses "except sale items"
+   turns into a confident, cited wrong answer.
+4. **Check yourself before showing anyone.** Every answer you kept must appear in the page
+   text. If you cannot find it there, drop it and list it as dropped.
+5. **Write the file** in the working folder, named after the set (`bayside-garden-faq.md`).
+6. **Show the owner, then ask exactly one question.** Show the count, three sample pairs, and
+   anything you dropped. Then ask: *"Publish these 42 answers to your website assistant?"*
+   That yes is also the decision to make them public.
+7. **Upload** with `awesomate_knowledge_upload {path, title: "<Business> FAQ"}`:
+   - on yes, add `visibility: "public"`;
+   - on no, add `visibility: "internal"`: their team's assistants and their own still use it,
+     and the website assistant does not. Never leave `visibility` out here: the default is
+     `private`, which only the owner's own tools can read, so the team's assistants would
+     silently never see the FAQ;
+   - if a public assistant is scoped to a collection (check `awesomate_knowledge_agents` and
+     `awesomate_knowledge_collections`), add its id in `collectionIds`. Ask only when there
+     are two or more candidates.
+8. **Prove it.** Poll `awesomate_knowledge_sources {action:'jobs'}` until the job has
+   succeeded. Then ask `awesomate_knowledge_ask` two of the questions *reworded*, and one
+   thing the FAQ does not cover. Show the citations, and show the honest refusal.
+
+## Keeping them current
+
+Run the same steps again and **upload with the same `title`**, every time. The title becomes
+the uploaded file's name, and the name decides which source the file replaces, so the new
+version takes the old one's place and keeps its visibility. Leaving `title` out names the
+source after the file on this machine, and a new title makes a second source: either way the
+assistant then cites both copies. An answer that has gone from the website should go from the
+file too; that is correct, not a loss.
+
+Then prove the change, not just the upload: ask `awesomate_knowledge_ask` one of the questions
+whose answer changed, and check the NEW answer comes back. A job can report success without
+replacing anything (putting back a version uploaded within the last hour does exactly that);
+if the old answer comes back, tell the owner and raise it with `awesomate_support`.
+
+## Spreadsheets and CSV files
+
+**Don't upload a Question and Answer spreadsheet as it is.** Read the sheet yourself, write
+the Markdown file above, and upload that. The word-for-word rule applies exactly as it does
+for a website.
+
+Why: a spreadsheet upload has to be declared either knowledge or data. Declared as data (or
+on an older platform, where every spreadsheet became data) it is stored as a table of figures
+and the assistant cannot find a single answer in it. The Markdown file works everywhere, keeps
+one citable section per question, and needs nobody to pick the right option.
+
+## FAQs the owner types
+
+Add the new `##` entries to the same file and upload it with the same title. If the owner
+has no file yet, start one.
+
+## Coming soon
+
+A dedicated FAQ type in the hub is being built. It will let owners edit one answer at a time,
+import from any page with one button, and see the questions their assistant could not
+answer. When an `awesomate_knowledge_faq` tool appears in your tools, use it instead of the
+file method here.

package/skill/awesomate-knowledge/references/ingestion-sources.md

@@ -15,9 +15,12 @@ estimating BEFORE asking approval.
 | Video/audio FILES | hub upload page (≤ 100 MB) | Bigger media: host it and add by URL |
 | Images | hub upload page | Vision-described, then indexed |
 | Facebook export | hub upload page | The platform's facebook-export lane |
+| FAQs | Markdown file via `awesomate_knowledge_upload` | One `##` per question, so each becomes its own citable section. **Never** a Q&A spreadsheet as it is: convert it to this file, so every answer stays word for word and citable. Full recipe: [faqs.md](faqs.md) |
+| Spreadsheet (`.csv`, `.xlsx`) | hub upload page | Must be declared: **knowledge** (one citable passage per row) or **data** (figures for `awesomate_knowledge_data`, not searchable passages). The hub's upload page asks the owner. FAQs in a sheet: convert to Markdown instead, see [faqs.md](faqs.md) |
 
-Local files never travel through the MCP tools — the hub upload page
-streams them. 100 MB per file through the hub.
+Local files go through `awesomate_knowledge_upload`, which streams them from
+disk so their contents never enter the conversation (the owner can also use
+the hub upload page). 100 MB per file.
 
 ## Job lifecycle
 

package/skill/awesomate-n8n/SKILL.md

@@ -94,6 +94,7 @@ the named node actually exists in the workflow before editing anything.
 | Validate / create draft / update draft / activate / promote / rollback / delete draft | `awesomate_n8n_deploy` |
 | Fire a test payload at an active workflow | `awesomate_n8n_test` |
 | Awesomate's template library: list, detail, install_plan (pauses on a missing credential), install, redeem, installs, activate, test, rollback | `awesomate_n8n_library` |
+| Book a session with the Awesomate team from their credits (session_types, slots, book, mine) | `awesomate_book_session` |
 | Create/alter data tables, write rows | `awesomate_n8n_datatable_write` |
 | Provision a Postgres DB + n8n credential | `awesomate_n8n_provision_pg` |
 | Wire a tested webhook workflow into one of their hosted apps (stores URL + secret on the app; returns the secret ONCE for the workflow's header check) | `awesomate_n8n_attach_to_app` |
@@ -209,8 +210,17 @@ loop: nothing is designed, the bundle is installed as curated.
    (`/home/credentials`), then activate again. Agents are live on install.
 6. `test`. Each template reports `passed`, `failed` (read the execution with
    `awesomate_n8n_executions` debug, fix configuration, re-run) or `untested` (no recipe:
-   ask them to try it once). Real side effects run; say so before testing. After THREE
-   failed rounds on one template, stop and SUGGEST a support ticket; never send one unasked.
+   ask them to try it once). Real side effects run; say so before testing.
+
+**The stuck ladder** (a credential they cannot set up, or three failed test-and-fix rounds
+on ONE template): (1) `awesomate_support ask` and the help card's articles; (2) offer a
+session with the Awesomate team through `awesomate_book_session` (session_types first; it
+costs the credits shown; book only on their yes; 404 not_live means bookings are not open
+yet, go to 3); (3) SUGGEST a support ticket. Never send one unasked. If they say yes, ask
+for a sentence in their own words, then `awesomate_support create_ticket` with category
+'Workflow error', subject `<bundle>: <template> fails after install`, and a message that
+carries the bundle and template slugs, the execution id and failing node from the last
+test, what you tried, and their sentence verbatim. Never paste workflow JSON into a ticket.
 7. `rollback` removes what their install created (never a reused workflow), with their OK.
 8. A 403 whose `missingScopes` contains `n8n:deploy` means Essentials. Show the catalog,
    say installing needs Support Plus, link `https://hub.awesomate.ai/billing`, and stop.