Automations (n8n)

Call FIRST before any n8n work. Returns the client's n8n instance URL, plan, whether Claude Code n8n access is consented (if consented=false, send the user to settingsUrl and re-check after), template-install capability (Support Plus+) and instance variant. When consented it also returns an instance fingerprint (community packages, workflow/credential/datatable counts). Companion tools once consented: awesomate_n8n_workflows (world picture), awesomate_n8n_inspect (nodes/datatables/possibilities/credentials/variables), awesomate_n8n_executions, awesomate_n8n_node_docs (live node schemas + community templates, every plan).

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 → discover_agent_assets (models, workflows, subagents) + list_credentials → create_agent {projectId, name, config} → mutate_agent {agentId, baseConfigHash, operation} (always the LATEST configHash; result.ok=false with code stale_config → get_agent and retry) → validate_agent → call_agent with one representative test message (real tools run, say so) → ask the user → 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 (the client switches it on in n8n, or through their own connection to the instance's MCP server). 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.

The Awesomate template library for THIS account: ready-made n8n automations and AI agents that Awesomate curates, including bundles linked to the account's referrer (e.g. Business Blueprint members see Dale Beaumont's bundles). Actions: 'list' (every bundle the account may see, each with installed, plan_ok and credentials_missing; every plan), 'detail' (slug: the templates in the bundle, what each does, the credential types it needs and whether the account already has each; every plan), 'install_plan' (slug: runs the pre-install checks WITHOUT writing and returns ready | paused | blocked; paused carries a help card per missing credential with where to get it, the exact page on their n8n to create it and our help article; Support Plus+), 'install' (slug: installs; refused unless the plan is ready, or every missing OPTIONAL credential is named in proceed_without and every ambiguous one has a choice in credential_choices; Support Plus+), 'redeem' (token: installs what a redeem token unlocks; Support Plus+). Then: 'installs' (what is on the instance, grouped by bundle), 'activate' (slug; switches the bundle's workflows on behind the same credential gate the hub uses: a workflow with an empty or missing credential answers setup_incomplete with the exact list; pass active:false to switch off; this includes workflows Awesomate installed, marked built_by_us), 'test' (slug; runs each template's test recipe and returns passed | failed | untested with the execution id; real side effects DO run, warn the client), 'rollback' (slug; removes what YOUR most recent install of this bundle created, never anything reused). Workflows land INACTIVE on install; activate is a separate, confirmed step. A 403 whose missingScopes contains n8n:deploy means the plan is Essentials: show the catalog, say installing needs Support Plus, and stop. Never create a credential for the client; send them to create_url and re-run install_plan afterwards.

The client's workflows. No id → EVERY workflow as a node-level summary in one call (nodeCount, nodeTypes, triggers, usesAi, communityNodes, dates; ?active filter + pagination), use this for the session's world picture instead of fetching workflows one by one. With id → that workflow's JSON: detail 'full' (default, nodes with parameters, connections, settings) or 'structure' (nodes WITHOUT parameters + connections, cheap shape check for big workflows). 403 consent_required → send the user to settingsUrl and re-check.

Instance inventory reads, one tool: 'nodes' (distinct node types in use, counts, versions, community/AI flags), 'datatables' (tables + columns + row counts), 'datatable_rows' (pass datatableId; limit ≤ 100), 'possibilities' (facts for "what could I automate": connected services with live-usage cross-check, unused connections, top nodes, AI tools [null = unknown, not none], community packages, counts: YOU turn these into suggestions, grounded only in what's actually there), 'credentials' (names/types/inferred service: never secrets; a leading 'warning' means the list may be out of date: say so to the user), 'variables' ($vars keys), 'credential_schema' (pass credentialType, e.g. openRouterApi: the fields that credential type takes, which are required, and their allowed values, read from their own n8n; never a value). All consent-gated server-side; 403 consent_required → settingsUrl.

Execution reads. workflowId → recent executions of that workflow. executionId → detail with errorSummary, trust errorSummary.failingNode only when confident:true (structural decode; also carries errorType/code/lastNodeExecuted); when confident:false it came from a heuristic and may name a node that does not exist, verify against the workflow before editing anything. executionId + debug:true → node-by-node decode (statuses, timings, errors, 2 example items per node), the best failure-diagnosis view; needs the 'error content analysis' privacy toggle (403 consent_required → settingsUrl), and responses with tooLarge:true mean the payload exceeded 15MB, fall back to the non-debug detail. For 'what is failing across ALL my workflows', use awesomate_n8n_errors instead.

Live n8n documentation, 500+ nodes + 2,500+ community templates, ALWAYS prefer this over memory for node schemas and typeVersions. tools: search_nodes {query}, get_node {nodeType, full form like 'n8n-nodes-base.gmail' works, add detail:'full' for everything}, search_templates {query} / get_template {templateId} (real importable community workflows, great starting points), validate_node {nodeType, config}, tools_documentation {}. Works on every plan, no consent needed. 503 node_catalog_unavailable → use the skill's references/vendor/ files instead; 422 catalog_tool_error → YOUR args were wrong (message says why), the catalog is fine.

Wire an app to call the user's own n8n as a backend. Give it the app + the production webhook URL of a workflow on their n8n (read it with awesomate_n8n_workflows; a workflow Claude built through the instance's own MCP server works too). It stores N8N_WEBHOOK_URL + a generated N8N_WEBHOOK_SECRET on the app (encrypted + injected) and RETURNS the secret so you can add a matching X-Awesomate-Webhook-Secret header check to the n8n workflow (so the webhook isn't world-callable). The app then calls it via src/lib/n8n.ts callWorkflow(). Node apps only. Only reach for this when the job needs an external app/credential or AI the user already has in n8n, not for pure in-app logic.

Automation KPIs from the hub's monitoring: executions, error rate, avg + p95 duration, time saved, 7-day-vs-prior deltas. No workflowId → the whole instance (the headline numbers for any report). With workflowId → that workflow, plus last_error_at and clean_days. Needs the 'aggregate monitoring' privacy toggle (on by default). Pair with awesomate_n8n_errors for what is failing and awesomate_site_uptime for the hosting side.

What is broken across the WHOLE instance, error events grouped by fingerprint (category, workflow, node, occurrences, first/last seen), newest first. THE first call when the user says 'something is failing' or at the start of an n8n session (a quick 7-day sweep; stay silent when it's clean). Counts and categories only, drill into a specific failure with awesomate_n8n_executions. days defaults to 30 (max 90).

What the n8n instance's data actually weighs: execution-table bytes, whole-database size, a per-table breakdown, and the last-24h per-workflow write offenders. Use it when executions feel slow, before suggesting cleanup, and as an OPPORTUNITY signal, heavy binary/media data is a cue to suggest a purpose-built app (awesomate-app-builder) for browsing it. Integers only; content never leaves the instance.

Findings from Awesomate's automated error analyzer for THIS account (Pro/Embedded + the 'Enable AI Error Diagnosis' privacy toggle (n8n → Settings → Privacy)): severity, workflow, occurrences, a plain-language clientSummary, needsClientAction (something only the user can fix, expired logins, third-party quotas), and fixReady (a reviewed fix is prepared, raise it with awesomate_support to have it applied). Read-only. An empty list on a healthy instance is the good state, not an error.