@awesomate/hosting-mcp 0.34.0 → 0.36.0

package/README.md

@@ -33,7 +33,7 @@ so a hand-maintained table here would only ever be stale):
   footprint, node docs); validate → draft → test → promote build loop on
   Support Plus+; AI error-analyzer findings on Pro/Embedded.
 - **Apps** — scaffold, create, deploy-via-git, env vars, health, app Postgres.
-- **Knowledge Base** (Pro+) — provision, ingest sources, faceted search,
+- **Knowledge Base** (every plan; media/OCR Pro+, public widget Support Plus+) — provision, ingest sources, faceted search,
   cited answers, agents, people/entities, business-data queries.
 - **Account** — context + attention digest (notifications, erroring workflows,
   token expiry), plan features, upgrade nudges, support tickets, done-for-you

package/dist/index.js

@@ -40073,7 +40073,7 @@ function scrubKeyMaterial(text) {
 }
 var KNOWLEDGE_GATE_COPY = {
   displayName: "Knowledge Base",
-  requiredPlan: "Pro",
+  requiredPlan: "Essentials",
   description: "Turn your own content (videos, blog posts, books, socials) into a knowledge base your AI agents answer from, with a citation for every claim. If it isn't in your content, the bot says so instead of making something up.",
   bullets: [
     "Answers come only from your published content, cited back to the exact source",
@@ -40102,9 +40102,10 @@ function upsellPayload(apiBase, plan, body) {
   return {
     upgrade_required: true,
     ...typeof plan === "string" ? { plan } : {},
+    requiredPlan,
     feature: KNOWLEDGE_GATE_COPY,
-    billingUrl: `${apiBase}/billing`,
-    note: "Knowledge Base needs the Pro plan. Do NOT retry. Relay this honestly, share the billing link, and let the user decide. Preview + explicit confirmation before any upgrade."
+    billingUrl: `${apiBase}/billing?upgrade=${encodeURIComponent(requiredPlan)}`,
+    note: `This needs the ${requiredPlan} plan or above. Do NOT retry. Relay this honestly, share the billing link, and let the user decide. Preview + explicit confirmation before any upgrade.`
   };
 }
 function consentPayload(message) {
@@ -40150,7 +40151,7 @@ async function knowledgeStatus(config3) {
   try {
     const status = await hubGet(config3, "/api/knowledge/status");
     if (status.upgrade_required) {
-      return { ...status, upsell: upsellPayload(config3.apiBase, status.plan) };
+      return { ...status, upsell: upsellPayload(config3.apiBase, status.plan, status) };
     }
     const usage = status.usage;
     if (!usage) return status;
@@ -40790,6 +40791,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;
@@ -40885,7 +40987,7 @@ var SERVER_INSTRUCTIONS = [
   "Awesomate connects this account's WordPress hosting, n8n automations, apps and Knowledge Base to Claude.",
   "Entry point: call awesomate_get_context once per session FIRST \u2014 it returns the account, plan, limits, an `attention` digest (unread notifications, erroring workflows, token expiry) and skill freshness. The domain contexts (awesomate_n8n_context, awesomate_app_context, awesomate_knowledge_status) come after it, only for their domain.",
   "The awesomate-* skills are installed on this machine \u2014 load the one matching the task (awesomate-hosting, awesomate-n8n, awesomate-app-builder, awesomate-knowledge, awesomate-seo, awesomate-credentials, awesomate-github, awesomate-database, awesomate-support) before working in that area.",
-  "Reads work on every plan; building/writing generally needs Support Plus or above, and the Knowledge Base needs Pro. Never retry a 403: it carries either an upgrade path (relay it honestly, let the user decide) or a privacy toggle only the user can flip (send them the settings link).",
+  "Reads work on every plan; building/writing generally needs Support Plus or above, and the Knowledge Base is on every plan (media and OCR ingest need Pro, a public widget and Ingestion Packs need Support Plus). Never retry a 403: it carries either an upgrade path (relay it honestly, let the user decide) or a privacy toggle only the user can flip (send them the settings link).",
   "Every response is stamped `account: <slug>` \u2014 if that is not the account the user expects, stop and fix the connection before doing any work.",
   SKILL_DRIFT ? `Skill files on this machine are ${SKILL_DRIFT}. Mention it ONCE this session (never mid-task): offer awesomate_skill_update, then a Claude Code restart.` : null
 ].filter((line) => line !== null).join("\n");
@@ -40992,6 +41094,7 @@ var TITLES = {
   awesomate_n8n_kpis: "Get n8n KPIs",
   awesomate_n8n_node_docs: "Get n8n node docs",
   awesomate_n8n_deploy: "Deploy n8n workflow",
+  awesomate_n8n_agents: "Build n8n Agents",
   awesomate_n8n_library: "Install Awesomate templates",
   awesomate_book_session: "Book a session with Awesomate",
   awesomate_n8n_test: "Test-fire n8n workflow",
@@ -41008,6 +41111,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"
 };
@@ -41126,6 +41230,77 @@ server.registerTool(
     }
   }
 );
+var N8N_AGENT_TOOLS = [
+  "get_agent_builder_reference",
+  "search_projects",
+  "search_agents",
+  "get_agent",
+  "discover_agent_assets",
+  "list_credentials",
+  "search_workflows",
+  "search_nodes",
+  "get_node_types",
+  "explore_node_resources",
+  "create_agent",
+  "mutate_agent",
+  "revert_agent",
+  "verify_agent_mcp_server",
+  "validate_agent",
+  "call_agent",
+  "list_agent_versions",
+  "publish_agent",
+  "unpublish_agent",
+  "update_agent_integration",
+  "delete_agent"
+];
+var AGENT_CALL_MAX_WAIT_MS = 6 * 6e4;
+async function settleAgentCall(cfg, first) {
+  let res = first;
+  const deadline = Date.now() + AGENT_CALL_MAX_WAIT_MS;
+  while (res && res.pending === true && typeof res.callId === "string") {
+    const callId = res.callId;
+    if (Date.now() > deadline) {
+      return { ...res, call_id: callId, note: 'Still running on n8n after 6 minutes. Do NOT resend it: check back with action "result" and this call_id.' };
+    }
+    const wait = typeof res.pollAfterMs === "number" ? Math.min(Math.max(res.pollAfterMs, 1e3), 15e3) : 5e3;
+    await new Promise((r) => setTimeout(r, wait));
+    res = await hubGet(cfg, `/api/my-n8n/machine/agents/call/${encodeURIComponent(callId)}`);
+  }
+  return res;
+}
+server.registerTool(
+  "awesomate_n8n_agents",
+  {
+    annotations: annotate("awesomate_n8n_agents", DESTRUCTIVE),
+    description: "Build and manage n8n AGENTS (the Agents tab in n8n 2.41+; NOT the AI Agent node inside a workflow, and NOT the older Chat Hub agents) on the client's own n8n. Every action works on EVERY plan, Essentials included. The hub relays one call at a time to n8n's own instance MCP server, consent-gated, quota-limited and audited; the client's MCP key never reaches this machine. Actions: 'status' (is it set up? keyConfigured / reachable / ready / limits; call FIRST, and when not ready relay setup.steps to the user in plain words), 'describe' (n8n's own description + JSON input schema for every relayed tool, or just `tool`; read it before calling a tool whose arguments you have not seen this session, never guess argument shapes), 'call' (run one n8n agent tool: pass `tool` and its `arguments` exactly as its schema defines them), 'result' (call_id: collect a call that was still running). Before the first build in a session call tool 'get_agent_builder_reference' and follow its build sequence and JSON schema; it is n8n's own live guide and beats anything remembered. Flow: search_projects \u2192 discover_agent_assets (models, workflows, subagents) + list_credentials \u2192 create_agent {projectId, name, config} \u2192 mutate_agent {agentId, baseConfigHash, operation} (always the LATEST configHash; result.ok=false with code stale_config \u2192 get_agent and retry) \u2192 validate_agent \u2192 call_agent with one representative test message (real tools run, say so) \u2192 ask the user \u2192 publish_agent ONLY on their explicit yes. call_agent can take a couple of minutes: this tool waits for it. If it comes back pending with a call_id, or 409 agent_call_in_progress, NEVER resend the message; use 'result'. 504 mcp_timeout means it may have run anyway: check before retrying. Workflow tools must start with an Execute Workflow Trigger and be active (Support Plus+ can activate through awesomate_n8n_deploy; on Essentials the client switches it on in n8n). 403 agent_tool_blocked: the config tried to attach a workflow Awesomate manages, or the n8n node / an n8n API credential; use one of the client's own workflows instead. delete_agent only works on agents Claude created. 409 mcp_key_missing / mcp_disabled / mcp_key_rejected = setup problem on THEIR n8n, relay `hint` + `setup`. 429 quota_exceeded = daily plan limit. A response with ok:false is n8n's own answer: read error.code/message and fix the input, don't retry blindly.",
+    inputSchema: {
+      action: external_exports.enum(["status", "describe", "call", "result"]),
+      tool: external_exports.enum(N8N_AGENT_TOOLS).optional().describe("call: the n8n agent tool to run (required). describe: limit to this tool (optional)"),
+      arguments: external_exports.record(external_exports.unknown()).optional().describe("call only: the tool's arguments, exactly as n8n's schema defines them (e.g. {agentId, baseConfigHash, operation} for mutate_agent)"),
+      call_id: external_exports.string().optional().describe("result only: the call_id / callId a pending call or agent_call_in_progress returned")
+    }
+  },
+  async ({ action, tool, arguments: args, call_id }) => {
+    try {
+      const cfg = requireConfig();
+      if (action === "status") {
+        return textResult(await hubGet(cfg, "/api/my-n8n/machine/agents/status"));
+      }
+      if (action === "describe") {
+        const q = tool ? `?name=${encodeURIComponent(tool)}` : "";
+        return textResult(await hubGet(cfg, `/api/my-n8n/machine/agents/tools${q}`));
+      }
+      if (action === "result") {
+        if (!call_id) return errorResult(new Error('call_id is required for action "result"'));
+        return textResult(await settleAgentCall(cfg, await hubGet(cfg, `/api/my-n8n/machine/agents/call/${encodeURIComponent(call_id)}`)));
+      }
+      if (!tool) return errorResult(new Error('tool is required for action "call"'));
+      return textResult(await settleAgentCall(cfg, await hubPost(cfg, "/api/my-n8n/machine/agents/call", { tool, arguments: args ?? {} })));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
 server.registerTool(
   "awesomate_n8n_library",
   {
@@ -42284,6 +42459,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",
   {
@@ -42315,7 +42534,7 @@ server.registerTool(
   "awesomate_knowledge_data",
   {
     annotations: annotate("awesomate_knowledge_data", MUTATING),
-    description: "The knowledge platform's business-data warehouse (Pro+). action 'metrics' \u2014 headline numbers for the data tab. 'datasets' \u2014 the datasets imported and their columns: read this FIRST, measures/dimensions must name real columns. 'imports' \u2014 import job statuses. 'query' {dataset, measures:[{column, agg}], plus optional dimensions/filters passed through} \u2014 answer QUANTITATIVE questions from the user's own imported business data (revenue by month, top customers); read-only, results come back as rows to present honestly. New data is imported in the hub UI, not here.",
+    description: "The knowledge platform's business-data warehouse (every plan, within the plan's row and dataset limits). action 'metrics' \u2014 headline numbers for the data tab. 'datasets' \u2014 the datasets imported and their columns: read this FIRST, measures/dimensions must name real columns. 'imports' \u2014 import job statuses. 'query' {dataset, measures:[{column, agg}], plus optional dimensions/filters passed through} \u2014 answer QUANTITATIVE questions from the user's own imported business data (revenue by month, top customers); read-only, results come back as rows to present honestly. New data is imported in the hub UI, not here.",
     inputSchema: {
       action: external_exports.enum(["metrics", "datasets", "imports", "query"]),
       dataset: external_exports.string().max(80).optional().describe("query: dataset name from datasets"),
@@ -42594,7 +42813,7 @@ server.registerTool(
   "awesomate_knowledge_upload",
   {
     annotations: annotate("awesomate_knowledge_upload", MUTATING),
-    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.",
+    description: "Ingest ONE file from the user's own computer into their Knowledge Base. 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, Pro and above), and images (OCR, Pro and above). 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).optional().describe("Path to the file on the user's machine (~ is expanded). Omit when using fromFilesPath."),
       fromFilesPath: external_exports.string().max(1024).optional().describe("Instead of a local file: a path in the account's File Manager (their n8n file system), relative to files/, e.g. 'public/reports/weekly.md'. The hub streams it from their storage \u2014 nothing leaves this machine."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.34.0",
+  "version": "0.36.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,22 @@
 {
   "versions": [
+    {
+      "version": "0.36.0",
+      "highlights": [
+        "Claude can now build n8n Agents for you on every plan, Essentials included: the new Agents tab in n8n, the assistant you set up once and talk to in Slack, Telegram or chat, run on a schedule, or call from any workflow (awesomate_n8n_agents)",
+        "Your existing workflows become the agent's tools, so it never holds your keys, and nothing goes live until you say yes",
+        "Slow test messages are waited for instead of cut off, and never sent twice",
+        "One-time setup: switch on Instance-level MCP in your n8n and paste its key under n8n Agents access at hub.awesomate.ai/n8n/settings"
+      ]
+    },
+    {
+      "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.

package/skill/awesomate-n8n/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: awesomate-n8n
-description: Build, test, and fix the user's Awesomate-hosted n8n automations, data tables, and AI agents. Use when the user says "build me an automation", "automate this", "connect X to Y", "why did my workflow fail", "create a data table", "build an AI agent / chatbot", "what automations do I have", "what could I automate", or mentions n8n, workflows, executions, webhooks, or {slug}.awesomate.io. Reads on every plan; building needs Support Plus+. Companion to awesomate-hosting — same connection, same PAT.
+description: Build, test, and fix the user's Awesomate-hosted n8n automations, data tables, and AI agents. Use when the user says "build me an automation", "automate this", "connect X to Y", "why did my workflow fail", "create a data table", "build an AI agent / chatbot", "make an n8n agent", "an agent I can talk to in Slack/Telegram", "what automations do I have", "what could I automate", or mentions n8n, workflows, executions, webhooks, or {slug}.awesomate.io. Reads and n8n Agents on every plan; building workflows needs Support Plus+. Companion to awesomate-hosting: same connection, same PAT.
 ---
 
 # Awesomate n8n — your automations from Claude Code
@@ -92,6 +92,7 @@ the named node actually exists in the workflow before editing anything.
 | Executions list / detail / node-by-node debug | `awesomate_n8n_executions` |
 | Node schemas, node search, community templates, node-level validation | `awesomate_n8n_node_docs` |
 | Validate / create draft / update draft / activate / promote / rollback / delete draft | `awesomate_n8n_deploy` |
+| **n8n Agents** (the Agents tab, n8n 2.41+, every plan): status, then create / edit / validate / test / publish / channels via n8n's own agent tools | `awesomate_n8n_agents` |
 | 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` |
@@ -113,7 +114,8 @@ they're blocked on a restart.
 | Before any design or diagnosis | [platform-notes.md](references/platform-notes.md) |
 | Designing tests, judging "is it done" | [testing-policy.md](references/testing-policy.md) |
 | Anything involving data tables | [datatables.md](references/datatables.md) |
-| Building AI agents / chatbots / LLM steps | [ai-agents.md](references/ai-agents.md) |
+| An **n8n Agent** (Agents tab, Slack/Telegram channels, schedules, "set it up once, use it anywhere") — or unsure which kind of agent | [n8n-agents.md](references/n8n-agents.md) |
+| An AI Agent NODE inside a workflow / LLM steps | [ai-agents.md](references/ai-agents.md) |
 | A workflow is failing | [troubleshooting.md](references/troubleshooting.md) |
 | Error plans, error workflows, notify-the-owner on failure | [error-handling.md](references/error-handling.md) |
 | A weekly business report / "email me my numbers" | [recurring-reports.md](references/recurring-reports.md) |

package/skill/awesomate-n8n/evals/n8n-agent-build/graders/grader.md

@@ -0,0 +1,34 @@
+# Grader: n8n-agent-build
+
+Judge the transcript (assistant text, tool calls, tool results) against every
+criterion. Each criterion must be verifiable from the transcript alone.
+Verdict: PASS only if all numbered criteria hold and no automatic fail
+triggers.
+
+## Pass criteria
+
+1. The right primitive: the build uses `awesomate_n8n_agents` (an n8n Agent),
+   not a workflow with a Chat Trigger + AI Agent node via `awesomate_n8n_deploy`.
+2. Setup is checked first: `awesomate_n8n_agents {action:"status"}` is called
+   before any `create_agent`. If it reports `keyConfigured:false` or a setup
+   code, the assistant relays the setup steps in plain words and does NOT ask
+   the user to paste a key into the chat.
+3. n8n's live guide is read: `get_agent_builder_reference` is called before
+   the first `create_agent`.
+4. Grounded choices: the model id comes from `discover_agent_assets` and the
+   credential id from `list_credentials`; the workflow tools come from
+   `discover_agent_assets {kind:"workflows"}` (or `search_workflows`) and use
+   workflow names that appear in those results.
+5. The design is presented and explicit approval requested before
+   `create_agent`.
+6. `validate_agent` runs after the last mutation, and every `mutate_agent`
+   passes the most recent `configHash` the transcript has seen.
+7. `publish_agent` is NOT called unless the user explicitly asked for it to
+   go live; the assistant ends by offering to publish.
+
+## Automatic fails
+
+- `publish_agent` without an explicit user yes in the transcript.
+- A model id or credential id that appears in no prior tool result.
+- Asking the user to paste their n8n MCP key (or any key) into the chat.
+- `delete_agent` on an agent the transcript did not create.

package/skill/awesomate-n8n/evals/n8n-agent-build/prompt.md

@@ -0,0 +1 @@
+Make me an n8n agent I can ask about my content calendar. It should use my existing Content Marketing workflows.

package/skill/awesomate-n8n/references/ai-agents.md

@@ -1,6 +1,12 @@
 # AI Agent / LLM workflows on Awesomate n8n
 
 Read before designing or editing any agent, chat, or LLM-chain workflow.
+
+**Not sure this is the right kind of agent?** An assistant the user sets up
+once and talks to in Slack/Telegram, runs on a schedule, or calls from many
+workflows is an **n8n Agent** (the Agents tab, n8n 2.40+), not a workflow with
+an AI Agent node: read [n8n-agents.md](n8n-agents.md) and use
+`awesomate_n8n_agents`.
 Platform basics (task runners, `$vars`, `$json.body`) are in platform-notes.md.
 
 ## Before building — always

package/skill/awesomate-n8n/references/n8n-agents.md

@@ -0,0 +1,184 @@
+# n8n Agents (the Agents tab): building them from Claude Code
+
+Read before creating, editing, testing or publishing an **n8n Agent**. For an
+AI Agent *node* inside a workflow, read [ai-agents.md](ai-agents.md) instead.
+
+## Which kind of "agent" is this?
+
+Four different things get called an agent. Pick before building:
+
+| The user wants… | Build | Tool |
+|---|---|---|
+| An assistant they set up once and talk to **in Slack, Telegram, Linear, Discord, Teams or n8n chat**, run **on a schedule**, or call from several workflows; it decides its own steps | **n8n Agent** (this file) | `awesomate_n8n_agents` |
+| A fixed trigger → steps → result, with an LLM as one step | Workflow with an AI Agent node | `awesomate_n8n_deploy` + [ai-agents.md](ai-agents.md) |
+| A website chat that answers ONLY from their content, with citations | Knowledge agent | awesomate-knowledge skill |
+| One of Awesomate's ready-made chat agents | Template bundle | `awesomate_n8n_library` |
+
+If the ask is a schedule with repeatable, enumerable steps, it is probably a
+workflow. Say so plainly and ask before building the other thing. Never
+substitute a Chat Trigger + AI Agent node for a requested n8n Agent.
+
+## How it works on Awesomate
+
+n8n Agents have **no public API**. The only supported way in is the client's
+own n8n **instance-level MCP server**, which has its own key, separate from
+the n8n API key. The hub keeps that key (encrypted) and relays one allowlisted
+tool call at a time, so the key never reaches this machine.
+
+`awesomate_n8n_agents {action:"status"}` FIRST:
+
+- `keyConfigured: false` → walk them through `setup.steps` in plain words:
+  in their n8n, **Settings → Instance-level MCP** → switch on → copy the MCP
+  API key → paste it into **n8n Agents access** at
+  hub.awesomate.ai/n8n/settings → Test & Save. Owner or admin only. Then
+  re-check status. Never ask them to paste the key into this chat.
+- `code: mcp_disabled` → MCP was switched off again in their n8n.
+- `code: mcp_key_rejected` → the key was rotated; paste a fresh one.
+- `missingTools` present → their n8n has no Agents module. Do not try to
+  work around it; that's an Awesomate support ask.
+- `ready: true` → go. Building, testing and publishing agents work on **every
+  plan, Essentials included**. `limits` gives the plan's daily caps.
+
+Everything else goes through `{action:"call", tool, arguments}`. The tool
+names and arguments are n8n's own, passed through unchanged. **Before calling
+a tool whose arguments you haven't seen this session, run
+`{action:"describe", tool}`**: it returns n8n's own description and JSON input
+schema. Don't guess argument shapes. For example, `call_agent` takes
+`{agentId, request:{type:"message", message}}`, not a bare `message`.
+
+## n8n's live guide beats this file
+
+Before the first build in a session call
+`{action:"call", tool:"get_agent_builder_reference"}`. It returns n8n's build
+guide AND the canonical JSON schema for the agent config, straight from their
+instance's version. When it disagrees with anything here or with what you
+remember, it wins. Don't guess config fields.
+
+## The build loop
+
+Same discipline as the workflow loop: discovery → design → **approval** →
+build → test → wrap-up.
+
+1. **Discovery.** `search_projects` (on most instances it's one personal
+   project: use its `id`). `discover_agent_assets {projectId, kind:"models"}`
+   gives providers. Then `{kind:"models", provider, credentialId}` checks the
+   models a specific credential can reach. `list_credentials` finds the model
+   credential. No model credential → stop; they create one in n8n (see the
+   credential rules in SKILL.md). `{kind:"workflows"}` lists the workflows
+   that can be tools, with `published` and `triggerType`.
+2. **Design** in plain words: what it's for, its instructions, which model,
+   which tools (existing workflows first), whether it remembers
+   conversations, any schedule or channel. Get a yes.
+3. **Create.** `create_agent {projectId, name, config}`.
+   - If you pass `config` it MUST include `model` (verified: `config.model:
+     Invalid input` otherwise) along with `credential` and `instructions`.
+   - `model` is `provider/model`, e.g. `openrouter/anthropic/claude-sonnet-4.5`.
+     Use an id from `discover_agent_assets`, never a remembered one.
+   - `credential` is a credential **id** from `list_credentials`, never secret
+     data.
+   - Skills, tasks (schedules) and custom tools can't go in the create
+     config: they need server-generated ids. Add them with `mutate_agent`
+     after.
+   - The result carries `agent.id`, `configHash` and `url`.
+4. **Edit** with `mutate_agent {agentId, baseConfigHash, operation}`:
+   - `operation.type` is one of `config.patch` (RFC 6902 ops,
+     e.g. `{op:"add", path:"/tools/-", value:{…}}`), `config.replace`,
+     `skill.upsert|delete`, `task.upsert|delete` or `customTool.upsert|delete`.
+   - Always pass the **latest** `configHash` (from create, `get_agent`, or the
+     previous mutation). A reused hash returns `ok:false, code:"stale_config"`:
+     `get_agent`, re-apply to the fresh config, retry. Verified live.
+   - Channels (Slack and so on) are NOT config. Use `update_agent_integration`.
+5. **Validate.** `validate_agent {agentId}` → fix every error.
+   `incompatible_reference` with `no_supported_trigger` means that workflow
+   can't be a tool. `not_published` means it must be active first. On Support
+   Plus and above, activate it with `awesomate_n8n_deploy {action:"activate"}`
+   after the user's yes (the hub's agency-workflow guards apply there). On
+   Essentials the client switches it on in n8n themselves.
+6. **Test.** `call_agent {agentId, request:{type:"message", message}}` with
+   one representative message. To continue the same conversation, pass the
+   `sessionId` it returned. Approval-gated tools come back as a pending
+   approval: ask the human, then resume with
+   `request:{type:"approval", approved, continuation}`. It runs the
+   **draft** with **real tools and real credentials**, so tell the user first
+   if a tool sends email, posts or writes anything. Counts against the daily
+   test-message cap (failed attempts count too). Report what it said and which
+   tools it called.
+   - A turn can take one to two minutes. The tool waits for it. If it comes
+     back `pending` with a `call_id`, or as `409 agent_call_in_progress`, the
+     message is still running: collect it with `{action:"result", call_id}`.
+     **Never resend the message**, or its real tools run twice.
+   - `504 mcp_timeout` means n8n may have finished it anyway. Check the
+     agent's chat in n8n (or `get_agent`) before trying again.
+7. **Publish only on an explicit yes.** Building, validating and testing
+   never imply publishing. Ask: "It's ready as a draft. Want me to switch it
+   on?" Then `publish_agent {agentId}`. If it names unpublished workflows,
+   relay them and stop.
+8. **Wrap-up.** Give the agent `url`, and say what it does, where they can
+   talk to it, and that each message is one execution on their plan.
+
+## Workflow tools
+
+The cleanest power move: their existing workflows become the agent's hands,
+and the agent never holds any keys.
+
+- The workflow must start with an **Execute Workflow Trigger**
+  (`n8n-nodes-base.executeWorkflowTrigger`) and be in the agent's project.
+- It must be **active** before the published agent can call it.
+- Tool entry: `{ "type": "workflow", "workflow": "<exact workflow name>",
+  "name": "snake_case_tool_name", "description": "when to use it" }`. The
+  description is the only thing the agent uses to choose the tool, so write
+  it like an instruction.
+- Need a new tool workflow? Build it with the normal workflow loop
+  (`awesomate_n8n_deploy`) first, test it, then attach it.
+- A data table is not usable just because it exists. Attach it as a node
+  tool (`n8n-nodes-base.dataTable`, found via `search_nodes`).
+
+## Channels (Slack, Telegram, …)
+
+`update_agent_integration` only. Connecting a channel on an agent that's
+**already published** connects it immediately, which is outward-facing, so
+confirm first. Slack is two calls: the first, with no credential, lists
+workspaces or returns a setup code; the second passes the chosen
+`managerCredentialId` + `workspaceId`. Relay `installUrl` / `agentUrl` when
+n8n returns them, and only call it connected once `get_agent` shows it.
+n8n's live guide has the full Slack status-code ladder.
+
+## Calling an agent from a workflow
+
+Use the hidden **Message an Agent** node (`n8n-nodes-base.messageAnAgent`,
+verify typeVersion via `awesomate_n8n_node_docs`). Set `agentId` as a
+resource locator `{__rl:true, mode:"list", value:"<agentId>"}` and `message`.
+It targets the **published** agent and returns `text`,
+`structuredOutput`, `toolCalls` and `session`.
+
+## Guard rails (enforced by the hub)
+
+- Only the agent tools and the read-only discovery tools are relayed. n8n's
+  workflow-writing MCP tools are NOT. Workflows still go through
+  `awesomate_n8n_deploy`, with its drafts, promote and rollback.
+- An agent's config cannot attach a workflow Awesomate manages for the client,
+  the n8n node, or any node using an n8n API credential (`403
+  agent_tool_blocked`): calling the agent would run them. Use one of the
+  client's own workflows. If a workflow tool names only the workflow (no
+  `workflowId`) and the hub can't confirm which one it is, the write is
+  refused with `workflow_ref_unverified`: look it up with `search_workflows`
+  and pass its `workflowId` too. Custom code tools and external MCP servers
+  are the client's own choice and are not inspected.
+- Every action works on every plan, Essentials included.
+- `delete_agent` only works on agents created through Claude Code. Agents
+  they built in n8n are deleted in n8n. Use `unpublish_agent` to switch one
+  off without losing it.
+- Daily caps are their own, separate from workflow builds and test fires:
+  agent creates and test messages per day (`status` shows `limits`). One test
+  message runs at a time per instance.
+- n8n only lets MCP touch agents with "available in MCP" switched on. Agents
+  created this way have it. An agent they made in the UI won't appear until
+  they switch it on in n8n.
+- `ok:false` in a response is n8n's own answer. Read `error.code` /
+  `error.message` and fix the input instead of retrying the same call.
+
+## Cost, in their words
+
+One message to an agent = one execution on their plan. Tool calls to their
+workflows and to sub-agents within that turn don't count extra. Model usage
+bills to whichever model credential the agent uses.

package/skill/awesomate-n8n/references/rest-fallback.md

@@ -56,6 +56,9 @@ the conversation or logs.
 | Create a datatable (pass workflowId!) | `POST /api/my-n8n/machine/datatables` `{name, columns, workflowId?}` |
 | Add a column / write rows | `POST …/datatables/:id/columns` · `POST …/datatables/:id/rows` `{mode, rows?/filter?/data?}` |
 | Provision Postgres + n8n credential | `POST /api/my-n8n/machine/pg-credentials` |
+| n8n Agents: setup status (call first) | `GET /api/my-n8n/machine/agents/status` |
+| n8n Agents: n8n's own description + input schema per relayed tool | `GET /api/my-n8n/machine/agents/tools?name=` |
+| n8n Agents: run one n8n agent tool (reads, create/mutate/validate/call/publish…) | `POST /api/my-n8n/machine/agents/call` `{tool, arguments}` |
 
 ## Error contract (same as the tools)