@awesomate/hosting-mcp 0.16.2 → 0.16.4

package/dist/index.js

@@ -39855,12 +39855,13 @@ var HubApiError = class extends Error {
   }
 };
 var REQUEST_TIMEOUT_MS = 15e3;
-async function hubRequest(config3, method, path, jsonBody) {
+async function hubRequest(config3, method, path, jsonBody, opts = {}) {
   const timeoutMs = method === "GET" ? REQUEST_TIMEOUT_MS : 24e4;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   const headers = { Authorization: `Bearer ${config3.pat}` };
   if (jsonBody !== void 0) headers["Content-Type"] = "application/json";
+  if (opts.accept) headers.Accept = opts.accept;
   let res;
   try {
     res = await (0, import_undici.fetch)(`${config3.apiBase}${path}`, {
@@ -39907,8 +39908,8 @@ async function hubRequest(config3, method, path, jsonBody) {
 function hubGet(config3, path) {
   return hubRequest(config3, "GET", path);
 }
-function hubPost(config3, path, jsonBody = {}) {
-  return hubRequest(config3, "POST", path, jsonBody);
+function hubPost(config3, path, jsonBody = {}, opts = {}) {
+  return hubRequest(config3, "POST", path, jsonBody, opts);
 }
 function hubPatch(config3, path, jsonBody = {}) {
   return hubRequest(config3, "PATCH", path, jsonBody);
@@ -40012,6 +40013,13 @@ async function knowledgeStatus(config3) {
     if (status.upgrade_required) {
       return { ...status, upsell: upsellPayload(config3.apiBase, status.plan) };
     }
+    const usage = status.usage;
+    if (usage && usage.sources_total_truncated === true) {
+      return {
+        ...status,
+        note: `usage.sources_total is a floor: the live count stopped at ${String(usage.sources_total)} sources (paged-count cap). The library holds at least that many \u2014 never quote it as the exact total.`
+      };
+    }
     return status;
   } catch (err) {
     return mapKnowledgeError(err, config3.apiBase);
@@ -40031,10 +40039,31 @@ async function knowledgeProvision(config3) {
     return mapKnowledgeError(err, config3.apiBase);
   }
 }
+function describeSourcePage(page) {
+  if (!Array.isArray(page.sources)) return page;
+  const kinds = {};
+  for (const s of page.sources) {
+    const k = typeof s.kind === "string" ? s.kind : "unknown";
+    kinds[k] = (kinds[k] ?? 0) + 1;
+  }
+  const hasMore = typeof page.next_cursor === "string" && page.next_cursor.length > 0;
+  return {
+    ...page,
+    page: { returned: page.sources.length, kinds_on_this_page: kinds, has_more: hasMore },
+    ...hasMore ? {
+      note: 'This is ONE page of the most recently ingested sources, not the whole library \u2014 do not summarise the knowledge base from it. Pass cursor=next_cursor to continue (limit up to 200). For the total, use awesomate_knowledge_status \u2192 usage.sources_total (sources_total_truncated:true means "at least that many").'
+    } : {}
+  };
+}
 async function knowledgeSources(config3, args) {
   try {
     if (args.action === "list") {
-      return await hubGet(config3, "/api/knowledge/sources");
+      const q = new URLSearchParams();
+      if (args.cursor) q.set("cursor", args.cursor);
+      if (args.limit !== void 0) q.set("limit", String(args.limit));
+      const qs = q.toString();
+      const page = await hubGet(config3, `/api/knowledge/sources${qs ? `?${qs}` : ""}`);
+      return describeSourcePage(page);
     }
     if (args.action === "jobs") {
       const q = args.status ? `?status=${encodeURIComponent(args.status)}` : "";
@@ -40072,15 +40101,29 @@ function parseSse(text) {
   }
   return events;
 }
-function renderAnswer(meta, streamedAnswer) {
-  const status = typeof meta.status === "string" ? meta.status : streamedAnswer ? "ok" : "error";
+function renderAnswer(meta, streamedAnswer, streamError = null) {
+  const status = typeof meta.status === "string" ? meta.status : streamError ? "error" : streamedAnswer ? "ok" : "error";
+  const session = typeof meta.session === "string" && meta.session ? { session: meta.session } : {};
+  const fallback = typeof meta.answer_plain === "string" && meta.answer_plain || typeof meta.no_answer_message === "string" && meta.no_answer_message || null;
+  if (status === "error") {
+    return {
+      status: "error",
+      answer: null,
+      platform_error: true,
+      not_in_verified_content: false,
+      detail: streamError ?? (streamedAnswer || null),
+      configured_fallback: fallback,
+      ...session,
+      note: "The knowledge platform failed to answer \u2014 a service problem, NOT a content gap. Do not tell the user their content lacks this. Say the service hit a problem, retry once, and if it persists raise it via awesomate_support. configured_fallback is only what an end customer would have seen meanwhile."
+    };
+  }
   if (status !== "ok") {
-    const fallback = typeof meta.answer_plain === "string" && meta.answer_plain || typeof meta.no_answer_message === "string" && meta.no_answer_message || null;
     return {
       status,
       answer: null,
       not_in_verified_content: true,
       configured_fallback: fallback,
+      ...session,
       note: "The knowledge base has no verified answer for this \u2014 relay that honestly (use the configured fallback wording if present). Never fill the gap from memory."
     };
   }
@@ -40097,20 +40140,25 @@ function renderAnswer(meta, streamedAnswer) {
     answer: typeof meta.answer_plain === "string" && meta.answer_plain ? meta.answer_plain : streamedAnswer,
     sources,
     ...typeof meta.score === "number" ? { score: meta.score } : {},
+    ...session,
     note: "Present the answer with its numbered sources \u2014 the citations are the product."
   };
 }
 async function knowledgeAsk(config3, args) {
   try {
-    const raw = await hubPost(config3, "/api/knowledge/chat", {
-      question: args.question,
-      ...args.session ? { session: args.session } : {}
-    });
+    const raw = await hubPost(
+      config3,
+      "/api/knowledge/chat",
+      { question: args.question, ...args.session ? { session: args.session } : {} },
+      { accept: "application/json" }
+    );
     if (raw && typeof raw === "object") {
-      return renderAnswer(raw, "");
+      const envelope = raw;
+      return renderAnswer(envelope, typeof envelope.answer === "string" ? envelope.answer : "");
     }
     const events = parseSse(String(raw ?? ""));
     let streamedAnswer = "";
+    let streamError = null;
     let meta = {};
     for (const ev of events) {
       if (ev.event === "answer") streamedAnswer += ev.data;
@@ -40119,9 +40167,16 @@ async function knowledgeAsk(config3, args) {
           meta = { ...meta, ...JSON.parse(ev.data) };
         } catch {
         }
+      } else if (ev.event === "error" && ev.data) {
+        try {
+          const parsed = JSON.parse(ev.data);
+          streamError = typeof parsed.message === "string" ? parsed.message : ev.data;
+        } catch {
+          streamError = ev.data;
+        }
       }
     }
-    return renderAnswer(meta, streamedAnswer);
+    return renderAnswer(meta, streamedAnswer, streamError);
   } catch (err) {
     return mapKnowledgeError(err, config3.apiBase);
   }
@@ -40980,20 +41035,22 @@ server.registerTool(
 server.registerTool(
   "awesomate_knowledge_sources",
   {
-    description: "The knowledge base's content sources. action 'list' \u2014 current sources (live metadata). 'jobs' \u2014 ingest job statuses (optional status filter: queued|running|succeeded|failed). 'add' \u2014 ingest a public page {url} or a whole site {sitemap, since?}; ALWAYS get explicit approval first (ingest costs money and counts against quota), and for local FILES send the user to the hub's Knowledge \u2192 Sources upload page \u2014 this tool cannot carry file bytes. A pack_required response means the allowance is exhausted: NOTHING was purchased \u2014 present the pack price (1 credit = $100) and let the user buy from the hub if they want it. 'remove' {sourceId} \u2014 deletes the source AND its indexed content; explicit approval required.",
+    description: "The knowledge base's content sources. action 'list' \u2014 ONE page of sources, most recently ingested first (default 50, max 200 via limit): read `page.has_more`/`next_cursor` and pass cursor to continue \u2014 a page is never the whole library, and the total lives in awesomate_knowledge_status \u2192 usage.sources_total. 'jobs' \u2014 ingest job statuses (optional status filter: queued|running|succeeded|failed). 'add' \u2014 ingest a public page {url} or a whole site {sitemap, since?}; ALWAYS get explicit approval first (ingest costs money and counts against quota), and for local FILES send the user to the hub's Knowledge \u2192 Sources upload page \u2014 this tool cannot carry file bytes. A pack_required response means the allowance is exhausted: NOTHING was purchased \u2014 present the pack price (1 credit = $100) and let the user buy from the hub if they want it. 'remove' {sourceId} \u2014 deletes the source AND its indexed content; explicit approval required.",
     inputSchema: {
       action: external_exports.enum(["list", "add", "remove", "jobs"]),
       url: external_exports.string().url().optional().describe("add: one public page / blog post / YouTube link"),
       sitemap: external_exports.string().url().optional().describe("add: sitemap.xml URL \u2014 ingests every listed page"),
       since: external_exports.string().optional().describe("add+sitemap only: skip entries with lastmod older than this ISO date"),
       sourceId: external_exports.string().optional().describe("remove only"),
-      status: external_exports.string().optional().describe("jobs only: queued|running|succeeded|failed")
+      status: external_exports.string().optional().describe("jobs only: queued|running|succeeded|failed"),
+      cursor: external_exports.string().max(512).optional().describe("list only: next_cursor from the previous page"),
+      limit: external_exports.number().int().min(1).max(200).optional().describe("list only: page size (default 50, max 200)")
     }
   },
-  async ({ action, url, sitemap, since, sourceId, status }) => {
+  async ({ action, url, sitemap, since, sourceId, status, cursor, limit }) => {
     try {
       return knowledgeResult(
-        await knowledgeSources(requireConfig(), { action, url, sitemap, since, sourceId, status })
+        await knowledgeSources(requireConfig(), { action, url, sitemap, since, sourceId, status, cursor, limit })
       );
     } catch (err) {
       return knowledgeError(err);
@@ -41003,7 +41060,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_knowledge_ask",
   {
-    description: `Ask the account's knowledge base a question and get the VERIFIED answer with numbered sources (title, locator, url) \u2014 the test surface for 'is my content in there and answering well'. status other than ok means the verified content has no answer: relay that honestly (use the configured fallback wording), never fill the gap from memory \u2014 an honest "it doesn't know" is the feature working. Counts against the monthly answers quota.`,
+    description: `Ask the account's knowledge base a question and get the VERIFIED answer with numbered sources (title, locator, url) \u2014 the test surface for 'is my content in there and answering well'. Read status: ok \u2192 present answer + sources. no_results / failed_validation (not_in_verified_content:true) \u2192 the verified content has no answer: relay that honestly (use configured_fallback), never fill the gap from memory \u2014 an honest "it doesn't know" is the feature working. error (platform_error:true) \u2192 the platform itself failed (model/API/infra): NOT a content gap \u2014 never tell the user their content lacks the answer; retry once, then awesomate_support. Counts against the monthly answers quota.`,
     inputSchema: {
       question: external_exports.string().min(1).max(2e3),
       session: external_exports.string().max(128).optional().describe("Stable id to keep follow-up questions in one conversation thread")

package/package.json

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

@@ -36,9 +36,13 @@ platform's answer beats anything you remember.
      content is indexed in Sydney, deletable any time), wait, re-check.
    - `tenant: null` or `status: 'provisioning'` → not enabled yet /
      still building; `usage` → month-to-date vs `usage.included` quota.
-3. Only then design: what content exists, what's already ingested
-   (`awesomate_knowledge_sources {action:'list'}`), what the user wants the
-   bot to answer.
+3. Only then design: what content exists, what's already ingested, what the
+   user wants the bot to answer. For "what's ingested" use
+   `status.usage.sources_total` (with `sources_total_truncated:true` it is a
+   floor). `awesomate_knowledge_sources {action:'list'}` returns ONE page —
+   the most recently ingested first (default 50, `limit` up to 200) — read
+   `page.kinds_on_this_page` / `page.has_more` and follow `next_cursor`;
+   never describe the library from a single page.
 
 ## 1. Tools
 

package/skill/awesomate-knowledge/references/citations-and-grounding.md

@@ -17,8 +17,12 @@ and widgets never see a partial or unvalidated answer.
 - `status: 'failed_validation'` — the model drafted something that didn't
   survive the citation gate. The user never sees the draft; treat exactly
   like no_results.
-- `status: 'error'` — infrastructure problem; suggest trying again, and
-  `awesomate_support` if it persists.
+- `status: 'error'` (`platform_error: true`, `not_in_verified_content:
+  false`) — the platform could not answer at all (model/API/infra outage).
+  This says NOTHING about the content: never relay it as "your content
+  doesn't cover this". `detail` carries the platform's message when it sent
+  one; `configured_fallback` is only what an end customer would have seen
+  meanwhile. Retry once; if it persists, `awesomate_support`.
 
 ## Rendering citations for humans