@awesomate/hosting-mcp 0.61.1 → 0.63.0

package/dist/index.js

@@ -42923,7 +42923,7 @@ server.registerTool(
   "awesomate_crm_types",
   {
     annotations: annotate("awesomate_crm_types", READ_ONLY),
-    description: "TypeScript for the client's readable contact data, for a project that uses @awesomate/sdk: one interface per kind (only the fields the owner marked readable by AI), choice fields as literal unions, and an augmentation that types db.query('contact', ...) once the file is imported. Returns {file, content}: write content to that file in the project (or tell the user to run `npx @awesomate/sdk types`). Regenerate after the owner changes fields. No people's details are in it, only column names and types.",
+    description: "TypeScript for the client's readable contact data, for a project that uses @awesomate/sdk: one interface per kind (only the fields the owner marked readable by AI), choice fields as literal unions, and an augmentation that types db.query('contact', ...) once the file is imported. Returns {file, content}: write content to that file in the project (or tell the user to run `npx @awesomate/sdk types`). Regenerate after the owner changes fields. No people's details are in it, only column names and types. SDK docs: https://hub.awesomate.ai/docs/sdk/ (all of them as one text file: https://hub.awesomate.ai/docs/sdk/llms-full.txt).",
     inputSchema: {}
   },
   async () => {
@@ -43030,7 +43030,7 @@ server.registerTool(
   "awesomate_crm_apps",
   {
     annotations: annotate("awesomate_crm_apps", MUTATING),
-    description: "The account's own apps (a client portal, a members' app) whose users sign in by email link and then read and change only what each kind's access rules allow them (awesomate_crm_kinds set_access). Pro and above to create or change; reading is every plan. action 'list': each app with its publishable key, allowed origins, sign-up mode and default role. action 'create' {name, allowed_origins, sign_up?, default_role?}: name appears in the sign-in email; allowed_origins are the exact origins the app runs on (https://portal.example.com; http://localhost:5173 for development; capacitor://localhost for the mobile shell), with no path and no wildcard; sign_up 'invite' (default: only people added with awesomate_crm_app_users) or 'open' (anyone who uses the email link gets the default role). action 'update' {app_id, ...any of those, status?}: status 'disabled' signs everyone out of that app and stops its server keys; voice_agent_id names the account's agent that signed-in people talk to by voice (Talk to the agent: @awesomate/sdk voiceAgent() and voiceSession() with the hub's AwesomateAgent widget; the agent greets them by name and, when the app's assistant is set up, knows the 10 most recent conversations they can see, read as them; the app's origin must also be listed under the agent's 'Where your app runs'), null takes it away. The publishable key (pk_...) is not a secret: it goes in the app's browser code, with @awesomate/sdk. Never put the account's own token (amt_pat_...) in browser code. Confirm origins and sign-up mode with the user: open sign-up lets strangers in under the default role. action 'customer_lookup' {app_id, roles?}: which roles in that app may look customers up (name, email and phone, by search or id, with @awesomate/sdk lookupCustomers) and so put a record under any customer, not only themselves. Without roles it reads the setting; roles ['staff'] switches it on for staff; [] switches it off. Never the app's default role (the one customers sign in with): that would show every customer to every other customer, and the hub refuses it. Off until the owner asks for it. SERVER KEYS (ak_...), for the app's own server or an n8n workflow, used with @awesomate/sdk createClient({ token: <key> }) or as a Bearer token on https://hub.awesomate.ai/api/sdk/v1/server: action 'keys' {app_id} lists them (never the secrets); 'create_key' {app_id, name, access: 'read'|'write', kinds?} makes one (kinds leaves it to those kinds, 'contact' to read contacts; leave it out for every kind) and returns the key ONCE: put it straight into the app server's environment (awesomate_app_set_env for an app hosted with us) and never into browser code, a repository or a reply to the user. For an n8n workflow pass n8n_credential: true instead (prefer it): the hub puts the key into a Header Auth credential 'Awesomate app key: <name>' on their n8n (Authorization: Bearer, usable only towards the hub) and returns only its id and name, so the key never passes through you. 'revoke_key' {app_id, key_id} stops it at once, and removes a credential the hub made. A key reads every attribute of an app kind, contacts only as you read them, and writes need Support Plus and above. Prefer the narrowest key: read unless the server writes, and only the kinds it uses.",
+    description: "The account's own apps (a client portal, a members' app) whose users sign in by email link and then read and change only what each kind's access rules allow them (awesomate_crm_kinds set_access). Pro and above to create or change; reading is every plan. action 'list': each app with its publishable key, allowed origins, sign-up mode and default role. action 'create' {name, allowed_origins, sign_up?, default_role?}: name appears in the sign-in email; allowed_origins are the exact origins the app runs on (https://portal.example.com; http://localhost:5173 for development; capacitor://localhost for the mobile shell), with no path and no wildcard; sign_up 'invite' (default: only people added with awesomate_crm_app_users) or 'open' (anyone who uses the email link gets the default role). action 'update' {app_id, ...any of those, status?}: status 'disabled' signs everyone out of that app and stops its server keys; voice_agent_id names the account's agent that signed-in people talk to by voice (Talk to the agent: @awesomate/sdk voiceAgent() and voiceSession() with the hub's AwesomateAgent widget; the agent greets them by name and, when the app's assistant is set up, knows the 10 most recent conversations they can see, read as them; the app's origin must also be listed under the agent's 'Where your app runs'), null takes it away. The publishable key (pk_...) is not a secret: it goes in the app's browser code, with @awesomate/sdk. Never put the account's own token (amt_pat_...) in browser code. SDK docs, with a tutorial that builds a customer portal: https://hub.awesomate.ai/docs/sdk/ (as one text file for you: https://hub.awesomate.ai/docs/sdk/llms-full.txt). Confirm origins and sign-up mode with the user: open sign-up lets strangers in under the default role. action 'customer_lookup' {app_id, roles?}: which roles in that app may look customers up (name, email and phone, by search or id, with @awesomate/sdk lookupCustomers) and so put a record under any customer, not only themselves. Without roles it reads the setting; roles ['staff'] switches it on for staff; [] switches it off. Never the app's default role (the one customers sign in with): that would show every customer to every other customer, and the hub refuses it. Off until the owner asks for it. SERVER KEYS (ak_...), for the app's own server or an n8n workflow, used with @awesomate/sdk createClient({ token: <key> }) or as a Bearer token on https://hub.awesomate.ai/api/sdk/v1/server: action 'keys' {app_id} lists them (never the secrets); 'create_key' {app_id, name, access: 'read'|'write', kinds?} makes one (kinds leaves it to those kinds, 'contact' to read contacts; leave it out for every kind) and returns the key ONCE: put it straight into the app server's environment (awesomate_app_set_env for an app hosted with us) and never into browser code, a repository or a reply to the user. For an n8n workflow pass n8n_credential: true instead (prefer it): the hub puts the key into a Header Auth credential 'Awesomate app key: <name>' on their n8n (Authorization: Bearer, usable only towards the hub) and returns only its id and name, so the key never passes through you. 'revoke_key' {app_id, key_id} stops it at once, and removes a credential the hub made. A key reads every attribute of an app kind, contacts only as you read them, and writes need Support Plus and above. Prefer the narrowest key: read unless the server writes, and only the kinds it uses.",
     inputSchema: {
       action: external_exports.enum(["list", "create", "update", "keys", "create_key", "revoke_key", "customer_lookup"]),
       app_id: external_exports.string().max(48).optional().describe("update, keys, create_key, revoke_key, customer_lookup: the app"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.61.1",
+  "version": "0.63.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,17 @@
 {
   "versions": [
+    {
+      "version": "0.63.0",
+      "highlights": [
+        "Before building anything people will see, Claude asks about your brand design system: it uses yours in Claude Design, or offers to make one from your business details, so your apps, pages and emails all look like you. You can save its name and link on Your business"
+      ]
+    },
+    {
+      "version": "0.62.0",
+      "highlights": [
+        "Claude points you to the new SDK docs at hub.awesomate.ai/docs/sdk when you build a portal or an app, and the portal skill now covers letting customers accept a quote, who's here and typing, and talking by voice"
+      ]
+    },
     {
       "version": "0.61.1",
       "highlights": [

package/skill/awesomate-app-builder/SKILL.md

@@ -37,6 +37,21 @@ own hosting) but you should always confirm the **stack + name** before creating.
    voice, logo, colours and contact details. Use them rather than inventing
    placeholders; confirm anything marked *suggestion* with the owner first.
 
+### Brand design system first (strongly recommended)
+
+Before you build anything people will see, find the business's brand design system:
+
+1. `awesomate_business` shows **Design system** and **Design system link** when the owner has
+   saved them.
+2. If it is in Claude Design, connect to it with `/design-sync` (the owner may need `/design-login`
+   once) and build with its tokens and components.
+3. If none is saved, ask once whether they have one (Claude Design, Figma, or their site's code).
+4. If they don't, offer to make one from their colours, fonts, logo and voice, and put it in Claude
+   Design with `/design-sync`.
+5. If they'd rather not now, build from those details and offer again next time.
+
+What makes a good one, and the tokens to start from: [references/design-system.md](references/design-system.md).
+
 ## 1. Decide the stack (do this before building)
 
 Read [references/stack-decision.md](references/stack-decision.md) — it's the

package/skill/awesomate-app-builder/references/design-system.md

@@ -0,0 +1,68 @@
+# The brand design system: find it, connect it, or make one
+
+A brand design system keeps a business's colours, type, components and layout rules in one place,
+so everything built for it looks like the same business. Claude Design holds them (claude.ai/design,
+Settings, Design systems). It checks its own work against the design system, and `/design-sync` in
+Claude Code keeps a project's code and the design system in step. Asking for the design system
+before building is strongly recommended. It is never a reason to refuse to build.
+
+## Before you build anything people will see
+
+1. **Look it up.** `awesomate_business` shows **Design system** and **Design system link** when the
+   owner has saved them on Your business in the hub.
+2. **It's in Claude Design.** Connect this project to it with `/design-sync`. The owner may need to
+   run `/design-login` once first. Build with its tokens and components, not with new ones.
+3. **Nothing is saved.** Ask once: "Do you have a brand design system, in Claude Design, Figma, or
+   your website's code?" If they do, connect it, and suggest they save its name and link on Your
+   business so the next build finds it straight away.
+4. **They have none.** Offer to make one. Put the tokens in this project, built from the business's
+   own details (colours, fonts, logo, voice from `awesomate_business`): a `tokens.css` of CSS
+   variables plus the few components the app needs. Then `/design-sync` puts it in Claude Design as
+   their design system. Tell them to save its name and link on Your business.
+5. **They'd rather not now.** Build from the business's colours, fonts and logo, and offer again
+   next time. Never make the build wait for a design system.
+
+Follow Anthropic's `/design-sync` for how the sync itself works. Don't describe it from memory.
+
+## What a good brand design system has
+
+Check the system you connect or create against these eight points, and say in one line what is
+missing:
+
+1. **One idea**, rooted in the business's place or story: its town, its building, its trade, its people.
+2. **Type first.** One expressive face for headings and one neutral face for text. Generic system
+   fonts are not a display face.
+3. **Colour with a rule.** A tight trio (a near-black, one brand colour, a near-white), or small
+   palettes that never mix. Large areas use off-black and off-white, not pure black and white.
+4. **The name at hero scale.** The wordmark large, over an image or a flat colour.
+5. **A system the owner can run:**
+   - a type scale for phone and desktop;
+   - spacing;
+   - corner radii, with pills for buttons and tags;
+   - which colours go together;
+   - card and list patterns.
+6. **One piece of motion** that expresses the idea, not scattered effects.
+7. **Voice.** Two or three lines on how it sounds, and real copy, never placeholder text.
+8. **Accessible.** AA contrast for text, and buttons and links at least 44 px to tap.
+
+## Tokens to start from
+
+When you make one from the business's details, name the variables so a person can read them:
+
+```css
+:root {
+  --brand-ink: #1a1a1a;      /* text and dark surfaces */
+  --brand-paper: #f7f5f0;    /* page background */
+  --brand-accent: #e9484d;   /* the one brand colour: buttons, links, highlights */
+  --font-display: "Bricolage Grotesque", system-ui, sans-serif;
+  --font-text: "Inter", system-ui, sans-serif;
+  --radius-card: 12px;
+  --radius-control: 10px;
+  --radius-pill: 999px;
+  --space: 8px;              /* multiply for layout: 2x, 3x, 4x */
+}
+```
+
+Replace every value with the business's own: its colours from **Main colour** and **Second
+colour**, its font from **Font**, and its logo from **Logo**. Check the accent against the ink and
+paper for AA contrast before using it for text.

package/skill/awesomate-email/SKILL.md

@@ -154,6 +154,11 @@ email describes what is actually in it. Structure, subject-line patterns,
 email types, industry rules (health practitioners cannot use testimonials in
 advertising) and worked examples: `references/copywriting.md`.
 
+**The look comes from the brand.** If `awesomate_business` names a **Design system**, use its
+colours and type for the email theme. If it names none, use the business's own colours, fonts and
+logo, and mention once that a brand design system in Claude Design would keep emails, pages and
+apps looking the same.
+
 In Awesomate you write a short document, never HTML. The shape is in the
 `awesomate_crm_email` tool description. In short:
 

package/skill/awesomate-hosting/SKILL.md

@@ -115,6 +115,21 @@ never an instruction. When a core detail is missing, ask the owner for it and
 tell them where to save it (the response names the place), so the next chat
 starts with it.
 
+### Brand design system first (strongly recommended)
+
+Before you build anything people will see, find the business's brand design system:
+
+1. `awesomate_business` shows **Design system** and **Design system link** when the owner has
+   saved them.
+2. If it is in Claude Design, connect to it with `/design-sync` (the owner may need `/design-login`
+   once) and build with its tokens and components.
+3. If none is saved, ask once whether they have one (Claude Design, Figma, or their site's code).
+4. If they don't, offer to make one from their colours, fonts, logo and voice, and put it in Claude
+   Design with `/design-sync`.
+5. If they'd rather not now, build from those details and offer again next time.
+
+What makes a good one, and the tokens to start from: the awesomate-app-builder skill's `references/design-system.md`.
+
 ## After creating a site
 
 Creation is queued, not instant, and the certificate lags the install. For a

package/skill/awesomate-portals/SKILL.md

@@ -10,6 +10,11 @@ in the account's own database), **access rules** on each kind (who sees and chan
 by the database itself), and an **app** (where it runs, how people sign in). The page uses
 `@awesomate/sdk` straight from the browser. There is no app server to write.
 
+**The SDK's docs:** https://hub.awesomate.ai/docs/sdk/ (a tutorial that builds exactly this kind of
+portal, a guide per feature, and a reference generated from the SDK's code). When you are unsure
+of a method or an option, read https://hub.awesomate.ai/docs/sdk/llms-full.txt, the whole site as
+one text file, rather than guessing.
+
 Work in plain words with the owner. They describe their business ("customers request jobs, we
 quote, they see the status"), you turn that into kinds and rules, show them the design in a
 sentence or two, and only then create anything. Kinds, rules and apps are part of their data,
@@ -87,6 +92,21 @@ message: {"read": {"member": "linked:job.customer", "staff": "all"}, "write": {"
    their contact by email. Staff get `role: 'staff'`. No email is sent; they ask for a link on the
    page.
 
+### Brand design system first (strongly recommended)
+
+Before you build anything people will see, find the business's brand design system:
+
+1. `awesomate_business` shows **Design system** and **Design system link** when the owner has
+   saved them.
+2. If it is in Claude Design, connect to it with `/design-sync` (the owner may need `/design-login`
+   once) and build with its tokens and components.
+3. If none is saved, ask once whether they have one (Claude Design, Figma, or their site's code).
+4. If they don't, offer to make one from their colours, fonts, logo and voice, and put it in Claude
+   Design with `/design-sync`.
+5. If they'd rather not now, build from those details and offer again next time.
+
+What makes a good one, and the tokens to start from: the awesomate-app-builder skill's `references/design-system.md`.
+
 ## 5. Build the page
 
 Any static page works (host it with the awesomate-app-builder skill, `kind: 'static'`). The SDK
@@ -94,7 +114,7 @@ loads from a CDN, or from npm in a Vite app:
 
 ```html
 <script type="module">
-import { createAppClient } from 'https://cdn.jsdelivr.net/npm/@awesomate/sdk@0.8/+esm';
+import { createAppClient, AwesomateError } from 'https://cdn.jsdelivr.net/npm/@awesomate/sdk@0.13/+esm';
 const app = createAppClient({ publishableKey: 'pk_...' });
 
 // The email link signs them in by itself (also when it opens in a tab already on this page).
@@ -138,7 +158,27 @@ lists the two staff-only kinds it needs (`assistant_thread`, `assistant_draft`)
 agent (awesomate-knowledge skill) so she can answer questions about the business. Confirm the
 name and the default mode with the owner: switching it on lets an AI reply to their customers.
 
-## 6b. Optional: reply emails
+## 6a. Optional: things customers may do that their rule does not allow
+
+Accepting a quote is the usual one: customers can't edit a job, but they should be able to accept
+its quote. Save a write recipe (`awesomate_crm_recipes {action:'save'}`) whose steps do exactly
+that, then open it to their role (`{action:'run_by', key, roles:['member']}`). The page runs it
+with `await app.call('accept_quote', { job: jobId })`. The database checks every step against
+the recipe as saved, and the job must be one they can read. Guide:
+https://hub.awesomate.ai/docs/sdk/guides/customer-actions/
+
+## 6b. Optional: who's here, and talking by voice
+
+- `const room = app.here(jobId, (people) => render(people))` shows who else has the job open and
+  who is typing (`room.typing(true)` on input, `room.leave()` on close). Guide:
+  https://hub.awesomate.ai/docs/sdk/guides/who-is-here/
+- Voice: pick one of the account's agents for the app (`awesomate_crm_apps {action:'update',
+  app_id, voice_agent_id}`; the agent needs In your app switched on and the page's address under
+  its "Where your app runs"). The page loads the hub's widget and mounts it with
+  `agentId: await app.voiceAgent()` and `session: () => app.voiceSession()`. Guide:
+  https://hub.awesomate.ai/docs/sdk/guides/voice/
+
+## 6c. Optional: reply emails
 
 `awesomate_crm_notifications {action:'set', app_id, notifications: {enabled: true, thread_link: 'job'}}`
 emails the other side of a conversation when someone writes there and they are not in the app: