@awesomate/hosting-mcp 0.34.0 → 0.35.0

package/dist/index.js

@@ -40790,6 +40790,107 @@ async function knowledgeCollections(config3, args) {
     return mapKnowledgeError(err, config3.apiBase);
   }
 }
+var faqEntryBody = (e) => ({
+  question: e.question,
+  answer: e.answer,
+  ...e.altQuestions?.length ? { alt_questions: e.altQuestions } : {},
+  ...e.category ? { category: e.category } : {},
+  ...e.sourceUrl ? { source_url: e.sourceUrl } : {},
+  ...e.externalKey ? { external_key: e.externalKey } : {}
+});
+async function knowledgeFaq(config3, args) {
+  try {
+    if (args.action === "sets") return await hubGet(config3, "/api/knowledge/faq/sets");
+    if (args.action === "create_set") {
+      if (!args.setTitle) return { error: "invalid_request", note: 'create_set needs setTitle, e.g. "Bayside Garden FAQ"' };
+      return await hubPost(config3, "/api/knowledge/faq/sets", {
+        title: args.setTitle,
+        ...args.visibility ? { visibility: args.visibility } : {},
+        ...args.collectionIds?.length ? { collection_ids: args.collectionIds } : {}
+      });
+    }
+    if (args.action === "import") {
+      if (!args.entries?.length) return { error: "invalid_request", note: "import needs entries [{question, answer}], at most 200 per call" };
+      let setId = args.setId;
+      if (!setId) {
+        if (!args.setTitle) return { error: "invalid_request", note: "import needs setId, or setTitle to create or reuse the set by name" };
+        const created = await hubPost(config3, "/api/knowledge/faq/sets", {
+          title: args.setTitle,
+          ...args.visibility ? { visibility: args.visibility } : {},
+          ...args.collectionIds?.length ? { collection_ids: args.collectionIds } : {}
+        });
+        setId = created.set?.set_id;
+        if (!setId) return { error: "unavailable", note: "The FAQ set could not be created; nothing was imported." };
+      }
+      const status = args.status === "published" ? "published" : "draft";
+      const r = await hubPost(config3, `/api/knowledge/faq/sets/${encodeURIComponent(setId)}/entries`, {
+        entries: args.entries.map(faqEntryBody),
+        status,
+        origin: "import",
+        ...args.confirm ? { confirm: args.confirm } : {}
+      });
+      return {
+        ...r,
+        set_id: setId,
+        note: status === "draft" ? "Imported as DRAFTS: nothing is live yet. Show the owner the count and a few samples, then ask ONE question: publish these to their assistant? On yes, call action publish {setId} (a public set also needs confirm: the account slug)." : "Published. The index job makes them searchable within a minute or two; then prove it with awesomate_knowledge_ask using a reworded question."
+      };
+    }
+    if (args.action === "publish") {
+      if (!args.setId) return { error: "invalid_request", note: "publish needs setId (from sets or the import result)" };
+      return await hubPost(config3, `/api/knowledge/faq/sets/${encodeURIComponent(args.setId)}/publish`, {
+        ...args.entryIds?.length ? { entry_ids: args.entryIds } : {},
+        ...args.confirm ? { confirm: args.confirm } : {}
+      });
+    }
+    if (args.action === "list") {
+      if (!args.setId) return { error: "invalid_request", note: "list needs setId (from sets)" };
+      const params = new URLSearchParams();
+      if (args.status) params.set("status", args.status);
+      if (args.q) params.set("q", args.q);
+      if (args.cursor) params.set("cursor", args.cursor);
+      if (args.limit) params.set("limit", String(args.limit));
+      const qs = params.toString();
+      return await hubGet(config3, `/api/knowledge/faq/sets/${encodeURIComponent(args.setId)}/entries${qs ? `?${qs}` : ""}`);
+    }
+    if (!args.entryId) return { error: "invalid_request", note: `${args.action} needs entryId (from list)` };
+    const entryPath = `/api/knowledge/faq/entries/${encodeURIComponent(args.entryId)}`;
+    if (args.action === "delete") {
+      await hubDelete(config3, entryPath);
+      return { deleted: true, entry_id: args.entryId };
+    }
+    const patch = args.action === "archive" ? { status: "archived" } : {
+      ...args.question !== void 0 ? { question: args.question } : {},
+      ...args.answer !== void 0 ? { answer: args.answer } : {},
+      ...args.altQuestions !== void 0 ? { alt_questions: args.altQuestions } : {},
+      ...args.category !== void 0 ? { category: args.category } : {},
+      ...args.sourceUrl !== void 0 ? { source_url: args.sourceUrl } : {},
+      ...args.reviewBy !== void 0 ? { review_by: args.reviewBy } : {},
+      ...args.status !== void 0 ? { status: args.status } : {}
+    };
+    if (!Object.keys(patch).length) return { error: "invalid_request", note: "update needs at least one of question, answer, altQuestions, category, sourceUrl, reviewBy, status" };
+    return await hubPatch(config3, entryPath, { ...patch, ...args.confirm ? { confirm: args.confirm } : {} });
+  } catch (err) {
+    if (err instanceof HubApiError) {
+      const body = bodyOf(err);
+      const code = typeof body?.error === "string" ? body.error : "";
+      const message = typeof body?.message === "string" ? body.message : void 0;
+      if (err.status === 409 && code === "confirm_required") {
+        return {
+          confirm_required: true,
+          confirm_with: body?.confirm_with,
+          note: `${message ?? "This set is public."} Nothing was written. Ask the owner, in plain words, whether to make these answers live on their website assistant; only on a clear yes, repeat the call with confirm set to the account slug.`
+        };
+      }
+      if (err.status === 409 && code === "quota_exceeded") return { error: "quota_exceeded", note: message ?? "This workspace is at its FAQ entry limit." };
+      if (err.status === 503 && code === "faq_unavailable") {
+        return { error: "faq_unavailable", note: "FAQ sets are not live on this account yet. Use the Markdown file method in the awesomate-knowledge skill (references/faqs.md) instead." };
+      }
+      if (err.status === 404 && code === "not_found") return { error: "not_found", note: message ?? "No such FAQ set or entry in this workspace." };
+      if (err.status === 400) return { error: "invalid_request", note: message ?? "The hub refused the request as malformed." };
+    }
+    return mapKnowledgeError(err, config3.apiBase);
+  }
+}
 
 // src/index.ts
 var config2 = null;
@@ -41008,6 +41109,7 @@ var TITLES = {
   awesomate_knowledge_agent: "Configure knowledge agent",
   awesomate_knowledge_agents: "Manage knowledge agents",
   awesomate_knowledge_collections: "Manage knowledge collections",
+  awesomate_knowledge_faq: "Manage FAQs",
   awesomate_knowledge_people: "Manage knowledge entities",
   awesomate_knowledge_data: "Query knowledge data warehouse"
 };
@@ -42284,6 +42386,50 @@ server.registerTool(
     }
   }
 );
+server.registerTool(
+  "awesomate_knowledge_faq",
+  {
+    annotations: annotate("awesomate_knowledge_faq", MUTATING),
+    description: "The business's FAQs as a first-class part of its Knowledge Base: every entry is one question and its answer, edited one at a time, cited as 'FAQ: <question>'. Use for 'import the FAQs from my website', 'add this to our FAQ', 'fix that answer'. The owner makes ONE decision per import: whether to publish. action 'sets': every FAQ set with draft/published/archived counts. 'create_set' {setTitle, visibility?, collectionIds?}: idempotent by title; creating a public set asks nothing, since a new set holds nothing live. 'import' {setId | setTitle, entries[{question, answer, altQuestions?, category?, sourceUrl?, externalKey?}] (max 200 per call; call again for more), status?}: upserts on the question itself, so re-running an import UPDATES in place and never duplicates. Default status draft: nothing goes live. Copy answers WORD FOR WORD from the source; never rewrite, shorten or merge them. 'publish' {setId, entryIds?}: every draft (or the listed ones) goes live. 'list' {setId, status?, q?, cursor?, limit?}. 'update' {entryId, question?|answer?|altQuestions?|category?|sourceUrl?|reviewBy?|status?}. 'archive' {entryId}: takes it out of every answer. 'delete' {entryId}. PUBLIC sets: anything that would make an answer live to customers (publish, import as published, editing a published answer) answers confirm_required until you pass confirm: the account slug. Ask the owner in plain words first; never pass the slug on your own initiative. After publishing, answers are searchable within a minute or two; prove it with awesomate_knowledge_ask using a reworded question. faq_unavailable means this account does not have FAQ sets yet: fall back to the Markdown method in the awesomate-knowledge skill.",
+    inputSchema: {
+      action: external_exports.enum(["sets", "create_set", "list", "import", "publish", "update", "archive", "delete"]),
+      setId: external_exports.string().max(200).optional().describe("the set_id from sets or an import result"),
+      setTitle: external_exports.string().min(1).max(200).optional().describe("create_set, or import without a setId: the set is created or reused by this name"),
+      visibility: external_exports.enum(["private", "internal", "public"]).optional().describe("create_set / import-with-setTitle, NEW sets only: 'public' for a website assistant"),
+      collectionIds: external_exports.array(external_exports.string().max(64)).max(16).optional().describe("create_set: put the set in these collections"),
+      entries: external_exports.array(
+        external_exports.object({
+          question: external_exports.string().min(1).max(500),
+          answer: external_exports.string().min(1).max(4e3),
+          altQuestions: external_exports.array(external_exports.string().max(500)).max(20).optional().describe("other ways customers ask it"),
+          category: external_exports.string().max(80).optional(),
+          sourceUrl: external_exports.string().max(2048).optional().describe("the page the pair was copied from"),
+          externalKey: external_exports.string().max(128).optional().describe("only when the source has its own stable id; the question is the default key")
+        })
+      ).max(200).optional().describe("import: the pairs, word for word"),
+      status: external_exports.enum(["draft", "published", "archived"]).optional().describe("import: draft (default) or published; list: filter; update: set it"),
+      q: external_exports.string().max(200).optional().describe("list: substring over question, answer and alternates"),
+      cursor: external_exports.string().max(20).optional().describe("list: next_cursor from the previous page"),
+      limit: external_exports.number().int().min(1).max(500).optional().describe("list: page size (default 100)"),
+      entryId: external_exports.string().max(64).optional().describe("update/archive/delete: entry_id from list"),
+      entryIds: external_exports.array(external_exports.string().max(64)).max(1e4).optional().describe("publish: only these drafts"),
+      question: external_exports.string().min(1).max(500).optional().describe("update"),
+      answer: external_exports.string().min(1).max(4e3).optional().describe("update"),
+      altQuestions: external_exports.array(external_exports.string().max(500)).max(20).optional().describe("update: REPLACES the list"),
+      category: external_exports.string().max(80).optional().describe("update"),
+      sourceUrl: external_exports.string().max(2048).optional().describe("update"),
+      reviewBy: external_exports.string().max(10).optional().describe("update: YYYY-MM-DD, a date to check this answer is still right"),
+      confirm: external_exports.string().max(64).optional().describe("the account slug, ONLY after the owner said yes to making answers live on a public set")
+    }
+  },
+  async (args) => {
+    try {
+      return knowledgeResult(await knowledgeFaq(requireConfig(), args));
+    } catch (err) {
+      return knowledgeError(err);
+    }
+  }
+);
 server.registerTool(
   "awesomate_knowledge_people",
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.34.0",
+  "version": "0.35.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,13 @@
 {
   "versions": [
+    {
+      "version": "0.35.0",
+      "highlights": [
+        "Your FAQs now live as real FAQ entries: Claude imports them as drafts, asks you one question (publish?), and later fixes a single answer without re-uploading anything (awesomate_knowledge_faq)",
+        "Every answer your website assistant gives from an FAQ cites the exact question it came from",
+        "Nothing goes live on a public assistant without your yes: publishing or editing a live public answer always asks first"
+      ]
+    },
     {
       "version": "0.34.0",
       "highlights": [

package/skill/awesomate-knowledge/SKILL.md

@@ -60,6 +60,7 @@ platform's answer beats anything you remember.
 | Enable the knowledge base (idempotent; 202 = keep polling status) | `awesomate_knowledge_provision` |
 | The LIBRARY: search by title/tag/collection/visibility, list, add url·sitemap (with visibility, tags, collections), tag, set visibility (public needs the slug typed), move between collections, remove, ingest jobs | `awesomate_knowledge_sources` |
 | Collections — named sets of sources a chatbot is scoped to: list / create / update / delete / add / remove members | `awesomate_knowledge_collections` |
+| FAQs: sets of question-and-answer entries, imported as drafts, published with ONE owner yes, edited one answer at a time ([faqs.md](references/faqs.md)) | `awesomate_knowledge_faq` |
 | Keep a File Manager folder (their n8n file system) synced into the knowledge base: `sync_rules` / `sync_rule_create` / `sync_rule_delete` / `sync_run` / `sync_state` on the sources tool; one file at a time via `awesomate_knowledge_upload {fromFilesPath}` | `awesomate_knowledge_sources`, `awesomate_knowledge_upload` |
 | Instant search with facet counts (find WHAT is in there: moments, pages, datasets; free) | `awesomate_knowledge_search` |
 | Ask a question → verified answer + numbered sources (accepts the same facet `filters` to ask within a slice) | `awesomate_knowledge_ask` |

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

@@ -97,9 +97,29 @@ one citable section per question, and needs nobody to pick the right option.
 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.
+## With the FAQ tool (use this first)
+
+`awesomate_knowledge_faq` stores every question and answer as its own entry, so an owner can
+fix one answer without re-uploading a file, and every citation names the exact entry. Use it
+whenever it is in your tools. The Markdown method above is the fallback, for when the tool
+answers `faq_unavailable`.
+
+1. Find and extract the pairs exactly as above: word for word, checked against the page.
+2. `import {setTitle: "<Business> FAQ", visibility: "public", entries: [...]}` in batches of
+   200. Entries land as **drafts**, so nothing is live yet. Re-running it later updates the
+   same entries rather than duplicating them.
+3. Show the count, a few samples and anything you dropped, then ask the one question:
+   *"Publish these 42 answers to your website assistant?"*
+4. On yes, `publish {setId}`. A public set answers `confirm_required` the first time; repeat
+   it with `confirm` set to the account slug, which is only allowed because the owner just
+   said yes. Never pass the slug on your own initiative.
+   On no, first `awesomate_knowledge_sources {action:'set_visibility', sourceId: setId,
+   visibility:'internal'}` (lowering visibility needs no confirm), then `publish {setId}`:
+   the team's assistants and the owner's own use the answers, the website assistant does
+   not. Leaving them as drafts would hide them from everyone.
+5. Prove it: ask `awesomate_knowledge_ask` two of the questions reworded, and one thing the
+   FAQ does not cover.
+
+Fixing one answer later is `list {setId, q: "<words from the question>"}` to find it, then
+`update {entryId, answer}` (a live public answer needs the owner's yes again). `archive` takes
+an entry out of every answer without deleting it.