@awesomate/hosting-mcp 0.20.0 → 0.20.2

package/dist/index.js

@@ -39891,7 +39891,11 @@ async function hubRequest(config3, method, path, jsonBody, opts = {}) {
     body = text;
   }
   if (!res.ok) {
-    const serverMsg = body && typeof body === "object" && "error" in body && typeof body.error === "string" ? body.error : `Request failed (${res.status})`;
+    const asObj = body && typeof body === "object" ? body : null;
+    const errField = typeof asObj?.error === "string" ? asObj.error : null;
+    const msgField = typeof asObj?.message === "string" && asObj.message.trim() ? asObj.message.trim() : null;
+    const looksLikeCode = errField !== null && /^[a-z0-9_]+$/.test(errField);
+    const serverMsg = msgField ? looksLikeCode ? `${msgField} (${errField})` : msgField : errField ?? `Request failed (${res.status})`;
     const code = body && typeof body === "object" && "code" in body && typeof body.code === "string" ? body.code : null;
     let hint = "";
     if (res.status === 401) {
@@ -41584,7 +41588,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'. 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.`,
+    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 BOTH status and grounded. grounded:true \u2192 present the answer with its numbered sources. grounded:false (status ok but ZERO sources) \u2192 the agent answered from MODEL MEMORY, not their content: say their content does not cover it, never present it as an answer from their knowledge base, never build on it. The default workspace agent is not strict-grounded, so this is common \u2014 anything customer-facing should use a purpose-built agent (awesomate_knowledge_agents) with strict grounding. 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"),
@@ -41935,10 +41939,11 @@ var KB_UPLOAD_TYPES = {
   ".webp": "image/webp"
 };
 var KB_MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
+var KB_UNPARSEABLE = /* @__PURE__ */ new Set([".doc", ".docx", ".ppt", ".pptx", ".rtf", ".epub", ".html", ".htm"]);
 server.registerTool(
   "awesomate_knowledge_upload",
   {
-    description: "Ingest ONE file from the user's own computer into their Knowledge Base (Pro+). Pass a LOCAL PATH \u2014 this server runs on their machine and streams the file to the hub itself, so the file contents never pass through the conversation. Handles documents (pdf, docx, pptx, xlsx, csv, txt, md, epub), audio and video (transcribed), and images. Max 100 MB per file; bigger media goes through the hub's Knowledge \u2192 Sources page. INGESTING COSTS MONEY and counts against the monthly allowance, so ALWAYS get explicit approval for the specific file(s) first and say what it will consume. For several files, call once per file and report progress \u2014 do not loop silently. Returns a job; poll awesomate_knowledge_sources {action:'jobs'} until it succeeds, then probe the content with awesomate_knowledge_ask before building anything on it. A pack_required response means the allowance is exhausted: nothing was ingested and nothing was purchased.",
+    description: "Ingest ONE file from the user's own computer into their Knowledge Base (Pro+). Pass a LOCAL PATH \u2014 this server runs on their machine and streams the file to the hub itself, so the file contents never pass through the conversation. Handles documents (pdf, md, txt), business data (csv, tsv, xls, xlsx, json), audio and video (transcribed), and images. Word/PowerPoint/RTF/EPUB files are NOT parseable yet \u2014 the tool refuses them with the workaround (export to PDF, or save as .md/.txt). Max 100 MB per file; bigger media goes through the hub's Knowledge \u2192 Sources page. INGESTING COSTS MONEY and counts against the monthly allowance, so ALWAYS get explicit approval for the specific file(s) first and say what it will consume. For several files, call once per file and report progress \u2014 do not loop silently. Returns a job; poll awesomate_knowledge_sources {action:'jobs'} until it succeeds, then probe the content with awesomate_knowledge_ask before building anything on it. A pack_required response means the allowance is exhausted: nothing was ingested and nothing was purchased.",
     inputSchema: {
       path: external_exports.string().min(1).max(4096).describe("Path to the file on the user's machine (~ is expanded)"),
       title: external_exports.string().max(300).optional().describe("Display title; defaults to the filename")
@@ -41975,6 +41980,13 @@ server.registerTool(
         );
       }
       const ext = extname(abs).toLowerCase();
+      if (KB_UNPARSEABLE.has(ext)) {
+        return errorResult(
+          new Error(
+            `${basename(abs)} is a format the Knowledge Base cannot parse yet (${ext}). Export it to PDF, or save the text as .md or .txt, and upload that instead. For a web page, add its public URL with awesomate_knowledge_sources {action:'add'} rather than uploading the HTML file.`
+          )
+        );
+      }
       const contentType = KB_UPLOAD_TYPES[ext] ?? "application/octet-stream";
       const filename = title?.trim() ? `${title.trim()}${ext}` : basename(abs);
       const result = await hubUploadFile(requireConfig(), "/api/knowledge/sources", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.20.0",
+  "version": "0.20.2",
   "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,19 @@
 {
   "versions": [
+    {
+      "version": "0.20.2",
+      "highlights": [
+        "Plain-text (.txt) and Markdown files now ingest into your Knowledge Base - a bug stopped both from working",
+        "Unsupported file types (Word, PowerPoint, EPUB) are refused up front with the fix - export to PDF - instead of failing later"
+      ]
+    },
+    {
+      "version": "0.20.1",
+      "highlights": [
+        "Claude now tells you clearly when an answer did NOT come from your content, instead of showing it like a verified one",
+        "Clearer error messages when something is not supported, instead of a generic failure"
+      ]
+    },
     {
       "version": "0.20.0",
       "highlights": [
@@ -34,13 +48,13 @@
       "highlights": [
         "Search your knowledge base with filters and ask questions within a slice of your content",
         "People & entities: your knowledge base now recognises who appears in your content, and you can name and merge them",
-        "Build AI agents from your own content — drafted, tested privately, and published only when you approve"
+        "Build AI agents from your own content \u2014 drafted, tested privately, and published only when you approve"
       ]
     },
     {
       "version": "0.14.0",
       "highlights": [
-        "Tools built for business owners, not developers — plain-language answers about your account, plan and limits",
+        "Tools built for business owners, not developers \u2014 plain-language answers about your account, plan and limits",
         "New support skill: get help, understand credits, or request a done-for-you build without leaving Claude",
         "New database skill: Claude picks the right place to keep your data and sets it up for you"
       ]

package/skill/awesomate-knowledge/SKILL.md

@@ -124,13 +124,16 @@ enough to route through explicit REST calls the user has just approved.
 
 | Action | Endpoint |
 |---|---|
-| Status / provision / sources / jobs / agent / ask | `GET\|POST /api/knowledge/{status,provision,sources,jobs,agent,chat}` (tool equivalents) |
+| Status / provision / sources / jobs / agent | `GET\|POST /api/knowledge/{status,provision,sources,jobs,agent}` (tool equivalents) |
+| Ask the knowledge base | `POST /api/knowledge/chat` `{question, session?}` — **returns SSE (`text/event-stream`), NOT JSON.** `JSON.parse` of the body yields `null` and reading `.status` off it throws. Concatenate `event: answer` data lines; the single `event: meta` line carries the verdict `{status, sources, score}`. |
+| Whole-library counts | `GET /api/knowledge/sources/summary` — a PATH. **`?action=summary` is NOT a thing:** it returns 200 with a plain source list, so `.total` is `undefined` and any count derived from it silently becomes 0 or NaN. |
 | Faceted search (what `awesomate_knowledge_search` calls) | `GET /api/knowledge/explore?q=…` + the same facet params. **Add `&include=media` to get `url`/`poster_url` on image/video hits** — without it you get titles with nothing to display. |
 | Business-data warehouse (what `awesomate_knowledge_data` calls) | `GET /api/knowledge/data/{metrics,datasets,datasets/:id,imports,imports/:id}` · `PATCH /api/knowledge/data/datasets/:id` · `POST /api/knowledge/data/imports/:id/:action` · `POST /api/knowledge/data/query` (read-only SQL) |
 | Agent builder (what `awesomate_knowledge_agents` calls) | `GET\|POST /api/knowledge/agents` · `GET\|PATCH\|DELETE /api/knowledge/agents/:agent_id` · `POST /api/knowledge/agents/:agent_id/{publish,suspend,resume}` |
 | **Test a DRAFT agent** (`action:'test'`) | `POST /api/knowledge/agents/:agent_id/chat` `{message, session_id?}`. There is **no** `/test` endpoint — guessing one returns 404. |
 | Entity layer probe (`available` false = not enabled yet, stop) | `GET /api/knowledge/entities` |
-| People list / detail | `GET /api/knowledge/people?status=named\|unknown\|hidden\|all` · `GET /api/knowledge/people/:id` |
+| People list / detail | `GET /api/knowledge/people?status=named\|unknown\|hidden\|all` · `GET /api/knowledge/people/:id` — returns `{people, next_cursor}` and **no `counts` key**. |
+| Entity COUNTS + availability | `GET /api/knowledge/entities` → `{available, counts: {...}}` — counts are nested under `counts`. Reading `people.counts?.x ?? 0` prints a confident row of zeros next to data that plainly exists. |
 | Name or hide/unhide a person (after approval) | `PATCH /api/knowledge/people/:id` `{display_name}` or `{status: "hidden"\|"unknown"}` |
 | Merge two people (after approval; source is hidden) | `POST /api/knowledge/people/:id/merge` `{into_person_id}` |
 | Alias suggestions / decision (identity = kind + alias_norm) | `GET /api/knowledge/entities/aliases?status=pending` · `POST /api/knowledge/entities/aliases/decision` `{kind, alias_norm, decision, entity_id? \| create_person?}` |
@@ -151,7 +154,10 @@ Learning one shape and applying it to the other is a guaranteed `400`:
 | `POST /api/knowledge/agents/:id/chat` — test a draft agent | `{message, session_id?, filters?}` |
 
 `question` vs `message`, `session` vs `session_id`. Both are strict objects, so
-sending both spellings to be safe fails too. Measured on a real first-time
+sending both spellings to be safe fails too — as does **camelCase**: `{message,
+sessionId}` is a 400, and so is an extra `{draft: true}`. Going direct, use
+snake_case and send nothing the schema does not name. (The MCP tool parameters
+are camelCase — `sessionId`, `agentId` — because the tool translates for you.) Measured on a real first-time
 session (2026-09-01): fourteen `400`s and one `404` were spent rediscovering
 exactly this.
 

package/skill/awesomate-knowledge/references/from-your-files.md

@@ -37,6 +37,9 @@ contents never pass through the conversation and a 100 MB PDF costs no context.
 - A folder path is rejected on purpose — list it, agree the files, then upload.
 - Public URLs and whole sitemaps stay on `awesomate_knowledge_sources`
   `{action:'add'}`. Use that for their website; use upload for their disk.
+- **What parses:** pdf, md, txt (documents); csv, tsv, xls, xlsx, json (business data);
+  audio, video, images. Word/PowerPoint/RTF/EPUB/HTML files are refused with a
+  workaround — export to PDF or save as .md/.txt; a web page goes in by URL.
 
 ## 3. Wait for ingestion, and check it actually succeeded
 
@@ -52,17 +55,19 @@ processing never creates a source row, so `{action:'summary'}` still reports
 a failed ingest looks exactly like one that was never attempted.
 
 So: read the job's `status` AND its `error`, and relay the error text to the
-user. Two real ones seen in the wild, both platform-side configuration rather
-than anything wrong with their file:
+user. Real ones seen in the wild, all platform-side rather than anything wrong
+with their file:
 
-- `new row violates row-level security policy for table "documents"` —
-  document/markdown ingestion is not currently permitted for that tenant.
+- `new row violates row-level security policy for table "documents"` — a
+  platform bug in markdown/text ingestion, fixed 2026-09-02. A failed job wrote
+  nothing, so once support confirms the fix is deployed the same file can
+  simply be re-uploaded.
 - `transcription_not_configured: DEEPGRAM_API_KEY is not set` — audio/video
   cannot be transcribed on that deployment yet.
 
-Neither is fixable by the user or by retrying. Say plainly that the upload
-reached Awesomate and failed on our side, and raise it with support
-(awesomate-support skill) rather than re-uploading and spending allowance again.
+None of these are fixable by the user. Say plainly that the upload reached
+Awesomate and failed on our side, and raise it with support (awesomate-support
+skill) rather than blindly re-uploading and spending allowance again.
 
 Then `{action:'summary'}` for the whole-library counts once the job has
 actually succeeded.