> For the complete documentation index, see [llms.txt](https://docs.buzzy.buzz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buzzy.buzz/getting-started-with-buzzy/tutorial-carer-app-from-a-template.md). # Getting started with Buzzy Builder MCP This is a complete, follow-along walkthrough. By the end you will have your **own working app** — a marketplace for booking disability-support carers — adapted from Buzzy's **ShortStay** rental template by chatting with an AI agent. No code. We adapt **ShortStay → CareConnect**. The same steps work for any "browse a provider, book them, message them" idea (tutors, cleaners, trades, and more). {% hint style="info" %} **Why start from a template instead of a blank prompt?** Blank prompts are great for exploring; templates are faster when the business pattern already exists. Most apps are variations on the same shapes — booking, search, provider profiles, availability, pricing, admin review, and role-based access. ShortStay already has those, so you adapt the *meaning* rather than rebuild the *shape*: **the workflow stays familiar; what it means changes.** {% endhint %} {% hint style="info" %} This is the guided, hands-on version of [From a Template](/the-building-blocks/mcp/buzzy-builder-mcp/from-a-template.md). Use that page for the underlying rules and gotchas; use this page to actually build something. {% endhint %}
Short Stay to Care Connect: adapt a proven template, deliver a new purpose

You'll adapt the ShortStay template into CareConnect using the Buzzy Builder MCP — one maintained Buzzy engine, a new app-specific definition.

**You act as the product owner. The agent acts as the builder.** Your job is mostly to describe what you want and approve each stage. **Time:** \~30–45 minutes.
Builder MCP workflow: MCP client, local workspace, Builder MCP, Buzzy runtime

How it works: your agent edits the app's semantic definition locally and pushes governed updates to Buzzy, which runs the app — prompt-to-structure, not prompt-to-code sprawl.

*** ## Before you start You need: * a Buzzy workspace with **MCP access** enabled * an **MCP-capable agent** (Claude Code, Claude Desktop, Codex, …) * the **ShortStay template** editor URL (or any short-stay template from the [Buzzy Templates](/working-with-buzzy/buzzy-app-examples/buzzy-templates.md) gallery) {% hint style="warning" %} Keep your MCP token and any secrets out of the repo, and out of prompts and screenshots. {% endhint %} If your agent isn't connected to Buzzy yet, do that first: {% content-ref url="/pages/gOBi8D5yPTX9ofnQJTfT" %} [Getting started with Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp/getting-started.md) {% endcontent-ref %} *** ## Step 1 — Set the agent up With your agent connected to Buzzy, start its setup. 🗣 **Say:** ``` Use the Buzzy MCP and bootstrap the setup for this session. ``` 👀 **What happens:** the agent reads Buzzy's builder guides and prepares its workspace, then confirms it's ready. Nothing for you to do here. {% hint style="success" %} **Checkpoint:** the agent reports that bootstrap is complete. {% endhint %} *** ## Step 2 — Point it at ShortStay and describe your app Now tell the agent what to build and which template to copy. Be specific about what makes your app **different** — especially the data and privacy needs. 🗣 **Say (swap in your template URL):** ``` I want to create an application for booking carers for clients (people with disabilities). Use this ShortStay app as the starting template: https://app.buzzy.buzz/editor/edit/ It's very similar to short-stay booking. Note that client profiles need to share some private/sensitive data, so adapt the template to handle those requirements. Do NOT edit or change the original template. ``` 👀 **What happens:** the agent copies the template into a private, read-only reference, summarizes its structure (roles, data, screens), and proposes a **concept map** for the new domain — mapping each ShortStay concept to its carer-domain equivalent, and adding one entirely new piece: a private **Client Care Data** record for sensitive details.
Template Adaptation Map: ShortStay concepts mapped to CareConnect concepts (property listing to carer profile, host to carer, daily booking to hourly booking, and more)

The concept map, visualized: the workflow pattern stays; the domain semantics change.

These aren't just word swaps. A night-based booking and an hour-based care visit behave differently, and a home address and a client's care record carry very different privacy expectations — which is why you adapt the **data model and access rules**, not only the labels. **The visible before & after.** Same home-page shape — search plus featured listings — re-targeted to care: | Before — ShortStay | After — CareConnect | | ------------------------------------------------------------------- | ----------------------------------------------------------------------- | | ![ShortStay rental template home page](/files/hLFKjVNZSuPcYZtSXGBx) | ![CareConnect carer marketplace home page](/files/aYqOmJrEDdI1L7OXNfIh) | {% hint style="warning" %} Always include "**do not change the original template**." Your new app is a separate copy; the template stays untouched. {% endhint %} {% hint style="success" %} **Checkpoint:** a new empty target app exists, and the agent has shown its concept map and plan. {% endhint %} *** ## Step 3 — Answer a few setup questions Because a carer app handles sensitive data, the agent asks a small number of **high-impact questions** before building. In this build it asked three: 1. **Who manages a client's profile and bookings?** — *the client themselves, or also a guardian/coordinator?* 2. **When can a carer see a client's private details?** — *only after a booking is confirmed, or ongoing?* 3. **How sensitive is the data?** — *basic care needs only, or full health/medical details?* For this tutorial we chose: **client self-manages**, carer sees private data **only after a booking is confirmed**, and **include health/medical detail**. {% hint style="info" %} These decisions are the whole point of adapting a template thoughtfully — they determine what's captured and who can see it. Answer them deliberately. {% endhint %} *** ## Step 4 — Review and approve each stage The agent now builds in a fixed order and **pauses for your approval** at each milestone, showing a readable summary. Reply **`approve`**, or ask for a change. ### 4a. Brief The product definition: what the app is, the roles (Client / Carer / Admin), the features, and the data — including the key privacy idea that sensitive details live in a separate **Client Care Data** record shared only on a confirmed booking. This is a great moment to make a domain change. In this build we adjusted the booking model here: 🗣 **Say:** ``` Change the booking so clients choose a visit length from 1 hour up to a full day, and price care services by the hour. ``` Then approve: ``` Approve. ``` ### 4b. Flows The user journeys: discover a carer → request a visit → carer confirms/declines → message in the confirmed booking. Check they match how your users behave, then approve. ### 4c. Data model Tables and fields, with privacy settings. The sensitive **Client Care Data** record holds support needs, mobility/access notes, emergency contact, and health/medication/allergy details — the health fields marked **sensitive** and viewer-restricted. ### 4d. Look & feel (theme) Colours, fonts, and style. Approve if it suits your audience (you can completely restyle later — see Step 6). ### 4e. Blueprint The full list of screens and how they're navigated (public discovery, client area, carer workspace, admin console, plus auth and support screens). Confirm the screens you need are there, then approve. {% hint style="info" %} **Why the gates matter:** these stages shape everything downstream. A change to the brief or data model is quick now; the same change after every screen is built is much more work. Take your time here. {% endhint %} {% hint style="success" %} **Checkpoint:** you've approved the brief, flows, data model, theme, and blueprint. {% endhint %} *** ## Step 5 — See your app come to life After you approve the blueprint, the agent creates all the screens, adds **realistic sample data** (carers, services, bookings), and builds the layouts. Then it gives you a **live link**. 🗣 **Say (anytime):** ``` Show me the live link. ``` Open it and try the core journey: **search → open a carer profile → request a booking.**
A live CareConnect carer profile detail page

Your live carer profile: photo, hourly pricing, a care-visit request, and a general service area.

The CareConnect care-visit booking request panel

Requesting a care visit — choose a service, date, start time, and how long you need.

{% hint style="success" %} **Checkpoint:** you can complete the search → profile → booking journey in the live app. {% endhint %} *** ## Step 6 — Refine by asking (the fun part) Now you polish the app in plain English. Below are the exact refinements made while building CareConnect — each is a small, focused request. Do as many as you like. The detail page is the clearest comparison — the same gallery, booking panel, and detail layout, re-targeted to care: | Before — ShortStay property detail | After — CareConnect carer profile | | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | ![ShortStay property detail with gallery, booking panel, and details](/files/urtLWz0wqUQBOoy7Ypqw) | ![CareConnect carer profile detail with photo, hourly pricing, booking, and general area](/files/fRZ5svTjPxacq5RAnQVW) | ### Make the carer photo a simple image The template used a gallery slideshow on the detail screen. A single bound image is cleaner. 🗣 **Say:** ``` For the carer's photo on the detail screen, just use a simple image field, not the gallery/slideshow widget. ``` ### Keep the carer's location private A carer's exact address shouldn't be public. Show only a general area. 🗣 **Say:** ``` The carer's location should show only a general suburb/area on public screens, not the precise street address — it's private. ``` {% hint style="warning" %} **Treat sensitive data as a data-layer problem, not just UI hiding.** Hiding a value on one screen isn't the same as protecting it. For anything sensitive, ask the agent to set field-level privacy in the data model (who can view it, and when) so it's protected everywhere — runtime, other screens, and the API — not only where you happened to look. {% endhint %}
Governed app delivery: privacy controls, security review, automated testing, and release promotion around the semantic app definition

For sensitive apps, privacy, testing, and review belong in the app's definition — not bolted on at the end.

### Show a general area on the map (not a pin) 🗣 **Say:** ``` On the carer detail, don't show a precise pin — show a general area (about 1 km) instead. ``` ### Add a richer home search 🗣 **Say:** ``` Replace the home search with one where you can search by location, date, and type of support. ``` ### Give it a fresh look 🗣 **Say:** ``` Give it a UI makeover — keep it suitable for a care site but make it look clearly different. Use a fresh, natural look. And square off the corners (no rounded edges). ``` {% hint style="info" %} **Show, don't just tell.** If something looks wrong — a misaligned button, a broken image — paste a **screenshot** into the chat and say what you want. It's the fastest way to a precise fix. {% endhint %} *** ## A quick checklist for adapting any template Keep these in mind whenever you adapt a template — not just for carers: * **Start from the closest working template**, not the most generic prompt. * **Map the domain entities first** (the concept table) before asking the agent to change anything. * **Separate copy/visual changes from semantic changes** — data, roles, booking logic, and access rules are the ones that really matter. * **Test the key paths early:** home, search, profile, booking, admin, and permissions. * **Treat sensitive data as a data-layer privacy problem**, not only UI hiding. ## Tips for working with your agent * **Approve or redirect at each gate.** A specific request (`make X do Y`) beats "I don't like it." * **Be specific about anything unusual**, especially privacy and who can see what — otherwise sensible defaults are assumed. * **One change at a time** for visual tweaks. * **Use screenshots** for anything visual. * **Ask for a summary** anytime: `Where are we up to, and what's left?` * **You can always go back.** `Actually, add a guardian role to the data model` is fine even later. ## If something doesn't look right * **A screen looks empty or odd?** Ask the agent to check and re-build it; sample data for a record may be missing. * **An image is wrong or broken?** Ask it to generate a new, on-topic image for that spot. * **A change didn't appear?** Refresh the live link (hard-refresh if needed). If it's still off, paste a screenshot. * **Want exact details?** Ask: `Show me the live link` or `Open the editor for this app.` ## What you end up with A complete, working Buzzy app — your own copy, separate from the ShortStay template — with a tailored data model and privacy rules, a full set of navigable screens with realistic content, your chosen look and feel, and an easy way to keep refining it: just keep asking. ## Going further * Add a guardian/coordinator role, or a care team per client. * Tighten privacy further and verify what public, signed-in, and denied users can each see. * Publish your app and invite users. For the underlying rules, review gates, and technical gotchas behind this workflow: {% content-ref url="/pages/1t1hGsfoVEqERpYTsk06" %} [From a template](/the-building-blocks/mcp/buzzy-builder-mcp/from-a-template.md) {% endcontent-ref %} Want the story behind this tutorial — and why adapting a semantic app definition beats generating another standalone codebase? Read [How we turned a short-stay rental app into a care booking app](https://www.buzzy.buzz/post/short-stay-to-care-connect-buzzy-builder-mcp/) on the Buzzy blog. *** ## Key Buzzy MCP tools at a glance You never call these yourself — your agent does. But it helps to recognise them, so when the agent says "pushing the data model" or "ensuring screens", you know what's happening behind the scenes. | Stage | Tools the agent uses | What they do | | --------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | **Orientation** | `get_guide`, `get_builder_overview`, `get_schema` | Load Buzzy's build guides and artifact schemas so the agent follows the correct process. | | **Bootstrap** | `get_repo_bootstrap_manifest`, `get_shell_client_bundle`, `get_agent_instructions` | One-time setup: pull the workspace scaffolding, shell tools, and Buzzy's agent instructions. | | **Get the template** | `list_apps` / `list_user_apps`, `export_app_bundle` | Find the source template and copy its full definition into a local, read-only reference. | | **Create your app** | `create_app`, `update_app` | Make the new, empty app and wire up its home, sign-in, and public screens. | | **Adapt the app** | `get_*` / `update_*` for `brief`, `flows`, `data_model`, `theme`, `blueprint` | Read and re-target each part of the app definition, one reviewed stage at a time. | | **Validate** | `validate_data_model`, `validate_blueprint_draft`, `validate_screen_draft` | Sanity-check a draft for broken references or missing pieces before it's saved. | | **Build screens** | `ensure_screens_from_blueprint`, `read_screen`, `apply_layout_updates` | Create real screens from the approved blueprint and refine their layouts. | | **Data & images** | `generate_sample_data`, `generate_image`, `search_images` | Add realistic sample records and on-topic imagery so the app isn't empty. | | **Inspect & preview** | `get_app_status`, `get_app_preview_url`, `get_editor_url`, `get_screenshot` | Check progress, get the live link, open the editor, or grab a screenshot. | {% hint style="info" %} You don't need to memorise these. The point of the workflow is that you describe outcomes in plain language and review the result — the agent chooses the right tools. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.buzzy.buzz/getting-started-with-buzzy/tutorial-carer-app-from-a-template.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.