@awesomate/hosting-mcp 0.20.7 → 0.21.0

package/dist/index.js

@@ -40196,6 +40196,49 @@ async function knowledgeSources(config3, args) {
       const page = await hubGet(config3, `/api/knowledge/sources${qs ? `?${qs}` : ""}`);
       return describeSourcePage(page);
     }
+    if (args.action === "search") {
+      const q = new URLSearchParams();
+      if (args.q) q.set("q", args.q);
+      if (args.kind) q.set("kind", args.kind);
+      if (args.visibility) q.set("visibility", args.visibility);
+      for (const t of args.tags ?? []) q.append("tag", t);
+      for (const c of args.collectionIds ?? []) q.append("collection", c);
+      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/library${qs ? `?${qs}` : ""}`);
+      return { ...describeSourcePage(page), note_visibility: "Each source carries visibility (private|internal|public \u2014 who may retrieve it; enforced) and collections. Nothing marked public = a public chatbot answers nothing." };
+    }
+    if (args.action === "tag") {
+      if (!args.sourceId || !Array.isArray(args.tags)) return { error: "invalid_request", note: "tag needs sourceId and tags (the full replacement list of free-form tags; collections are unaffected)" };
+      return await hubPatch(config3, `/api/knowledge/sources/${encodeURIComponent(args.sourceId)}`, { tags: args.tags });
+    }
+    if (args.action === "set_visibility") {
+      const ids = args.sourceIds?.length ? args.sourceIds : args.sourceId ? [args.sourceId] : [];
+      if (!ids.length || !args.visibility) return { error: "invalid_request", note: "set_visibility needs sourceId (or sourceIds) and visibility" };
+      if (args.visibility === "public" && !args.confirm) {
+        return {
+          error: "confirmation_required",
+          note: `Making ${ids.length} source(s) PUBLIC means anyone with a public key or a public chatbot can retrieve them, and once fetched or crawled that cannot be taken back. Explain this to the user, then call again with confirm set to their account slug (awesomate_whoami \u2192 account) only after they have agreed in so many words.`
+        };
+      }
+      return await hubPost(config3, "/api/knowledge/sources/batch", {
+        source_ids: ids,
+        visibility: args.visibility,
+        ...args.confirm ? { confirm: args.confirm } : {}
+      });
+    }
+    if (args.action === "move") {
+      const ids = args.sourceIds?.length ? args.sourceIds : args.sourceId ? [args.sourceId] : [];
+      if (!ids.length || !args.collectionIds?.length && !args.removeCollectionIds?.length) {
+        return { error: "invalid_request", note: "move needs sourceId (or sourceIds) and collectionIds (add to) and/or removeCollectionIds" };
+      }
+      return await hubPost(config3, "/api/knowledge/sources/batch", {
+        source_ids: ids,
+        ...args.collectionIds?.length ? { add_collection_ids: args.collectionIds } : {},
+        ...args.removeCollectionIds?.length ? { remove_collection_ids: args.removeCollectionIds } : {}
+      });
+    }
     if (args.action === "summary") {
       try {
         const s = await hubGet(config3, "/api/knowledge/sources/summary");
@@ -40232,7 +40275,12 @@ async function knowledgeSources(config3, args) {
         note: "add needs url or sitemap. For a local FILE on this machine, use awesomate_knowledge_upload \u2014 it reads the file off disk and streams it, so the bytes never pass through the conversation."
       };
     }
-    const body = args.url ? { url: args.url } : { sitemap: args.sitemap, ...args.since ? { since: args.since } : {} };
+    const body = {
+      ...args.url ? { url: args.url } : { sitemap: args.sitemap, ...args.since ? { since: args.since } : {} },
+      ...args.visibility ? { visibility: args.visibility } : {},
+      ...args.tags?.length ? { tags: args.tags } : {},
+      ...args.collectionIds?.length ? { collection_ids: args.collectionIds } : {}
+    };
     return await hubPost(config3, "/api/knowledge/sources", body);
   } catch (err) {
     return mapKnowledgeError(err, config3.apiBase);
@@ -40572,11 +40620,12 @@ async function knowledgeAgents(config3, args) {
       if (args.goal) {
         const draft = await hubPost(config3, "/api/knowledge/agents/draft", { goal: args.goal });
         if (!draft.proposal) return { error: "draft_failed", detail: draft };
-        const created = await hubPost(config3, "/api/knowledge/agents", draft.proposal);
-        return { ...created, test_questions: draft.test_questions ?? [], status_note: "Created as a private DRAFT: test it, then publish when the user approves." };
+        const body = { ...draft.proposal, ...args.audience ? { audience: args.audience } : {} };
+        const created = await hubPost(config3, "/api/knowledge/agents", body);
+        return { ...created, test_questions: draft.test_questions ?? [], status_note: `Created as a private DRAFT serving audience '${args.audience ?? "private"}': test it, then publish when the user approves.` };
       }
       if (!args.name) return { error: "name (or goal) is required for create" };
-      return await hubPost(config3, "/api/knowledge/agents", { name: args.name });
+      return await hubPost(config3, "/api/knowledge/agents", { name: args.name, ...args.audience ? { audience: args.audience } : {} });
     }
     if (args.action === "publish") {
       if (!args.agentId) return { error: "agentId is required for publish" };
@@ -40592,6 +40641,48 @@ async function knowledgeAgents(config3, args) {
     return mapAgentsError(err, config3.apiBase);
   }
 }
+async function knowledgeCollections(config3, args) {
+  try {
+    if (args.action === "list") {
+      const r = await hubGet(config3, "/api/knowledge/collections");
+      return { ...r, note: 'A collection is a named set of sources; scope an agent to one with scope.tags ["collection:<collection_id>"]. default_visibility only pre-fills new sources \u2014 each source keeps its own visibility.' };
+    }
+    if (args.action === "create") {
+      if (!args.slug || !args.name) return { error: "invalid_request", note: "create needs slug (lower-case, hyphens) and name" };
+      return await hubPost(config3, "/api/knowledge/collections", {
+        slug: args.slug,
+        name: args.name,
+        ...args.description ? { description: args.description } : {},
+        ...args.defaultVisibility ? { default_visibility: args.defaultVisibility } : {}
+      });
+    }
+    if (!args.collectionId) return { error: "invalid_request", note: `${args.action} needs collectionId (from list)` };
+    if (args.action === "get") {
+      const r = await hubGet(config3, "/api/knowledge/collections");
+      const c = r.collections?.find((x) => x.collection_id === args.collectionId);
+      return c ? { collection: c } : { error: "not_found", note: "No collection with that id in this workspace" };
+    }
+    if (args.action === "update") {
+      const body = {
+        ...args.slug ? { slug: args.slug } : {},
+        ...args.name ? { name: args.name } : {},
+        ...args.description !== void 0 ? { description: args.description } : {},
+        ...args.defaultVisibility ? { default_visibility: args.defaultVisibility } : {}
+      };
+      if (!Object.keys(body).length) return { error: "invalid_request", note: "update needs at least one of slug, name, description, defaultVisibility" };
+      return await hubPatch(config3, `/api/knowledge/collections/${encodeURIComponent(args.collectionId)}`, body);
+    }
+    if (args.action === "delete") {
+      return await hubDelete(config3, `/api/knowledge/collections/${encodeURIComponent(args.collectionId)}`);
+    }
+    if (!args.sourceIds?.length) return { error: "invalid_request", note: `${args.action} needs sourceIds` };
+    return await hubPost(config3, `/api/knowledge/collections/${encodeURIComponent(args.collectionId)}/sources`, {
+      [args.action]: args.sourceIds
+    });
+  } catch (err) {
+    return mapKnowledgeError(err, config3.apiBase);
+  }
+}
 
 // src/index.ts
 var config2 = null;
@@ -41545,9 +41636,17 @@ server.registerTool(
 server.registerTool(
   "awesomate_knowledge_sources",
   {
-    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. 'summary' \u2014 exact whole-library counts {total, by_kind, chunks, indexed_chunks, failed_sources, failed_jobs_7d}: use THIS to say what the knowledge base contains, and if failed_jobs_7d > 0 say so \u2014 those ingests are missing from every other count. '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), for a local FILE on the user's machine use awesomate_knowledge_upload instead (it streams the file from disk; this tool takes URLs only). 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 \u2014 the LIBRARY. action 'search' {q?, kind?, visibility?, tags?, collectionIds?, cursor?, limit?} \u2014 find sources by title/tag substring and metadata filters (instant, free; for CONTENT search use awesomate_knowledge_search); each row carries visibility (private|internal|public \u2014 who may retrieve it, ENFORCED), tags and collections. 'tag' {sourceId, tags} \u2014 REPLACE a source's free-form tags. 'set_visibility' {sourceId|sourceIds, visibility, confirm?} \u2014 change who may retrieve the source(s); 'public' is irreversible once fetched, so it needs the user's explicit agreement and their account slug as confirm. 'move' {sourceId|sourceIds, collectionIds?, removeCollectionIds?} \u2014 add to / remove from collections. '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. 'summary' \u2014 exact whole-library counts {total, by_kind, chunks, indexed_chunks, failed_sources, failed_jobs_7d}: use THIS to say what the knowledge base contains, and if failed_jobs_7d > 0 say so \u2014 those ingests are missing from every other count. '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?}, optionally with visibility (default private), tags and collectionIds; ALWAYS get explicit approval first (ingest costs money and counts against quota), for a local FILE on the user's machine use awesomate_knowledge_upload instead (it streams the file from disk; this tool takes URLs only). 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", "summary", "add", "remove", "jobs"]),
+      action: external_exports.enum(["list", "summary", "add", "remove", "jobs", "search", "tag", "set_visibility", "move"]),
+      q: external_exports.string().max(100).optional().describe("search: title/tag substring"),
+      kind: external_exports.string().max(32).optional().describe("search: source kind filter (web, document, video, audio, image, book, dataset)"),
+      visibility: external_exports.enum(["private", "internal", "public"]).optional().describe("add: the audience the new source is cleared for (default private); set_visibility: the level to apply; search: filter"),
+      tags: external_exports.array(external_exports.string().max(64)).max(64).optional().describe("add: free-form tags; tag: the REPLACEMENT list; search: filter (AND)"),
+      collectionIds: external_exports.array(external_exports.string().max(64)).max(16).optional().describe("add: put the source in these collections; move: add to; search: filter"),
+      removeCollectionIds: external_exports.array(external_exports.string().max(64)).max(16).optional().describe("move: remove from these collections"),
+      sourceIds: external_exports.array(external_exports.string().max(300)).max(200).optional().describe("set_visibility/move: several sources at once"),
+      confirm: external_exports.string().max(64).optional().describe("set_visibility to 'public' only: the account slug, after the user agreed in so many words"),
       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"),
@@ -41557,10 +41656,10 @@ server.registerTool(
       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, cursor, limit }) => {
+  async ({ action, url, sitemap, since, sourceId, status, cursor, limit, q, kind, visibility, tags, collectionIds, removeCollectionIds, sourceIds, confirm }) => {
     try {
       return knowledgeResult(
-        await knowledgeSources(requireConfig(), { action, url, sitemap, since, sourceId, status, cursor, limit })
+        await knowledgeSources(requireConfig(), { action, url, sitemap, since, sourceId, status, cursor, limit, q, kind, visibility, tags, collectionIds, removeCollectionIds, sourceIds, confirm })
       );
     } catch (err) {
       return knowledgeError(err);
@@ -41658,6 +41757,7 @@ server.registerTool(
       agentId: external_exports.string().max(64).optional().describe("get/publish/test: agent_id from list"),
       name: external_exports.string().max(80).optional().describe("create: blank draft with this name"),
       goal: external_exports.string().max(2e3).optional().describe("create: describe the agent and AI drafts it from the account content"),
+      audience: external_exports.enum(["private", "internal", "public"]).optional().describe("create: who the agent serves \u2014 'public' for anything customers or a website will talk to (it then answers from sources marked public ONLY), 'internal' for the team, 'private' (default) for the owner's own tools. Widening later is a publish, so choose now."),
       message: external_exports.string().max(4e3).optional().describe("test: the question to ask the draft"),
       sessionId: external_exports.string().max(128).optional().describe("test: keep follow-ups in one thread")
     }
@@ -41670,6 +41770,28 @@ server.registerTool(
     }
   }
 );
+server.registerTool(
+  "awesomate_knowledge_collections",
+  {
+    description: "Collections: named sets of knowledge sources with a default audience \u2014 the unit a chatbot is scoped to (agent scope.tags ['collection:<collection_id>']). action 'list' \u2014 every collection with source counts by visibility. 'create' {slug, name, description?, defaultVisibility?} \u2014 defaultVisibility only pre-fills NEW sources' visibility; each source keeps its own. 'get' {collectionId}. 'update' {collectionId, slug?|name?|description?|defaultVisibility?}. 'delete' {collectionId} \u2014 removes the collection; the sources survive (explicit approval first). 'add'/'remove' {collectionId, sourceIds} \u2014 membership. A source may be in several collections. A PUBLIC chatbot over a collection whose sources are all private answers nothing \u2014 check visibility (awesomate_knowledge_sources search) before building on one.",
+    inputSchema: {
+      action: external_exports.enum(["list", "create", "get", "update", "delete", "add", "remove"]),
+      collectionId: external_exports.string().max(64).optional().describe("get/update/delete/add/remove: collection_id from list"),
+      slug: external_exports.string().max(64).optional().describe("create/update: lower-case letters, digits, hyphens"),
+      name: external_exports.string().max(120).optional().describe("create/update"),
+      description: external_exports.string().max(2e3).optional().describe("create/update"),
+      defaultVisibility: external_exports.enum(["private", "internal", "public"]).optional().describe("create/update: pre-fills new sources only"),
+      sourceIds: external_exports.array(external_exports.string().max(300)).max(200).optional().describe("add/remove")
+    }
+  },
+  async (args) => {
+    try {
+      return knowledgeResult(await knowledgeCollections(requireConfig(), args));
+    } catch (err) {
+      return knowledgeError(err);
+    }
+  }
+);
 server.registerTool(
   "awesomate_knowledge_people",
   {
@@ -41976,10 +42098,13 @@ server.registerTool(
     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 with its live status; poll awesomate_knowledge_sources {action:'jobs'} until it succeeds (a duplicate upload replays the earlier job \u2014 a response already reading succeeded needs no polling), 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")
+      title: external_exports.string().max(300).optional().describe("Display title; defaults to the filename"),
+      visibility: external_exports.enum(["private", "internal", "public"]).optional().describe("Who may retrieve this source (default private). public = customers and public chatbots; irreversible once fetched \u2014 ask first."),
+      tags: external_exports.array(external_exports.string().max(64)).max(64).optional().describe("Free-form tags for the new source"),
+      collectionIds: external_exports.array(external_exports.string().max(64)).max(16).optional().describe("Put the new source in these collections (awesomate_knowledge_collections list)")
     }
   },
-  async ({ path: rawPath, title }) => {
+  async ({ path: rawPath, title, visibility, tags, collectionIds }) => {
     try {
       const { statSync, existsSync: existsSync3 } = await import("node:fs");
       const { resolve: resolve2, basename, extname } = await import("node:path");
@@ -42019,7 +42144,12 @@ server.registerTool(
       }
       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", {
+      const uploadQuery = new URLSearchParams();
+      if (visibility) uploadQuery.set("visibility", visibility);
+      for (const t of tags ?? []) uploadQuery.append("tags", t);
+      for (const c of collectionIds ?? []) uploadQuery.append("collection_ids", c);
+      const uploadQs = uploadQuery.toString();
+      const result = await hubUploadFile(requireConfig(), `/api/knowledge/sources${uploadQs ? `?${uploadQs}` : ""}`, {
         localPath: abs,
         filename,
         contentType

package/package.json

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

@@ -58,11 +58,12 @@ platform's answer beats anything you remember.
 |---|---|
 | Tenant state, plan gate, consent, quota, packs (CALL FIRST) | `awesomate_knowledge_status` |
 | Enable the knowledge base (idempotent; 202 = keep polling status) | `awesomate_knowledge_provision` |
-| Sources list / add url·sitemap / remove / ingest jobs | `awesomate_knowledge_sources` |
+| 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` |
 | 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` |
 | Agent persona / fallback message / model tier — get & set (the single workspace default) | `awesomate_knowledge_agent` |
-| Agent BUILDER: list / get / create (AI-drafted from their content, saved as a private draft) / test the draft / publish (explicit approval first) | `awesomate_knowledge_agents` |
+| Agent BUILDER: list / get / create (AI-drafted from their content, saved as a private draft; pass `audience:'public'` for anything customers will talk to — it then answers from sources marked public ONLY) / test the draft / publish (explicit approval first) | `awesomate_knowledge_agents` |
 | People, places, topics: list / name / hide / merge / alias suggestions / re-run resolution | `awesomate_knowledge_people` |
 | 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` |

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

@@ -83,10 +83,20 @@ before a customer sees it. Show the citations.
 
 ## 5. Draft the agent
 
-`awesomate_knowledge_agents {action:'create', goal}` — describe what the agent
-is for and the platform drafts instructions, scope, tone and test questions
-from the account's own content. It saves as a **private draft**; nothing is
-live and nothing is lost.
+`awesomate_knowledge_agents {action:'create', goal, audience}` — describe what
+the agent is for and the platform drafts instructions, scope, tone and test
+questions from the account's own content. It saves as a **private draft**;
+nothing is live and nothing is lost.
+
+**`audience` is the retrieval ceiling, and it is enforced.** `public` for
+anything customers or a website will talk to: the agent then answers from
+sources marked public ONLY, whatever key runs it. `internal` for the team
+(internal + public sources). `private` (the default) for the owner's own
+tools. A source's own visibility is set at upload (`visibility` on
+`awesomate_knowledge_upload` / `sources add`) or in the hub Library; a public
+agent over a library with nothing marked public answers nothing — say so
+before building, and get the owner to mark the customer-facing sources public
+first. Widening an agent later is a publish, so choose now.
 
 Then `{action:'test', agentId, message}` — free and unmetered, and the right
 way to check behaviour. Test the awkward cases: something out of scope, a