> 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/the-building-blocks/mcp/buzzy-builder-mcp/for-new-apps.md). # For new apps This tutorial shows a complete MCP-driven build workflow using a simple recipe review app as the example. It starts after the shared Builder MCP setup and covers app creation, staged artifact review, initial screen generation, sample data, Playwright inspection, and several realistic refinement rounds. The goal is to show a practical, repeatable way to work with Buzzy MCP well. {% hint style="info" %} This guide assumes you want to work in a normal git repo with an AI coding agent such as Codex or Claude, and let the agent collaborate with the Buzzy MCP server to build and refine the app. {% endhint %} ## What You'll Build In this walkthrough, the app is a small recipe review product called **Tasteful Reviews**. It includes: * public recipe browsing * a recipe detail screen * sample data * community reviews * a custom code-widget search/filter bar * iterative refinements to the home, discovery, and detail screens By the end, you should understand the standard staged flow: `brief -> flows -> data model -> theme -> blueprint -> screens -> refinements` ## Before You Start You will need: * an empty git repo * a connected and bootstrapped Buzzy Builder MCP agent * access to Playwright or another browser-inspection path if you want screenshots If you have not connected and bootstrapped your agent yet, start with [Getting Started with Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp/getting-started.md). ## 1. Kick Off the App Build Create the app with a focused product prompt. In this walkthrough, the prompt was: > Create a recipe review app that allows users to read recipes and leave reviews on the recipes. Recipes should have a photo, title, three rich text fields for description, ingredients and instructions, as well as fields for difficulty, serving size, total preparation time as a number, and a set of reviews. Reviews should have a rating and a comment and record the submitter and submitted time of the review. ``` Create a recipe review app that allows users to read recipes and leave reviews on the recipes. Recipes should have a photo, title, three rich text fields for description, ingredients and instructions, as well a fields for difficulty, serving size, total preparation time as a number, and a set of reviews. Reviews should have a rating and a comment and record the submitter and submitted time of the review. ``` At this point, Buzzy should stop at the **brief** stage so you can review it before continuing. ## 2. Review the Brief At the brief stage, the most useful live link is the workspace or editor URL, so you can inspect what Buzzy has created and review the brief in context. Typical asks: * `Can I get the workspace URL for this app` * `Can I get the editor URL too` When reviewing the brief, check: * are the core entities right * is the auth posture right * are the relationships valid in Buzzy terms * is the naming good enough to keep * did Buzzy invent any extra ownership pattern you do not want This is also the right stage to give feedback on the **data requirements section of the brief** if the structure is not quite right yet. In this build, one of the first brief-stage corrections was: > Get rid of the User Reviews table, we can work out who owns a review from who created it. That was really a correction to the way the brief described the data requirements. Catching that early is valuable, because it keeps the flows, data model, and later screens from building on top of the wrong shape. You can still make structural corrections later if you need to, but the earlier you catch them, the cheaper they are to fix. {% hint style="info" %} Be specific in your feedback. One clear structural correction is usually better than rewriting the whole brief. {% endhint %} ## 3. Move Through Flows and Data Model After the brief is accepted, move to flows and then the data model. At the flows stage, check: * public vs signed-in journeys * whether the review flow makes sense * whether onboarding and profile flows are proportionate At the data-model stage, check: * entities and fields * parent/child relationships * access posture * whether the `User` table is carrying the right kind of information In this example, one useful refinement was: > User table - I dont think the name, image and bio need to be private data That led to a better public-profile posture for: * `displayName` * `profileImage` * `bio` ## 4. Theme, Blueprint, and Screen Shells Once the data model is accepted, you can move through theme and blueprint. If the theme is directionally fine, you may move through it quickly. The blueprint is more important to inspect carefully, because it is the last cheap place to fix: * screen inventory * public/private posture * navigation * shell decisions * major screen purposes When the blueprint looks good, ensure the screens from blueprint and wire the app's screen settings before generating detailed screens. ## 5. Generate a Small First Screen Batch Do not generate every screen at once. A better pattern is to generate a small first batch such as: * `Landing Page` * `Discover Recipes` * `Recipe Detail` * `Add Review` * `My Reviews` Then verify that first batch in the live app. If the agent does not give you a preview URL automatically once screens exist, you can ask for one directly, for example: * `Can I have a preview URL for the app` ![First generated screen batch](/files/gsoRmjlYosTWf1GFtb9v) This keeps the review loop tight and gives you something concrete to react to before the app gets too broad. ## 6. Generate Sample Data Early Once the data model is accepted, generate sample data early. Screens are much easier to evaluate when they have real rows to bind against. One thing to expect: sample data can take a little while to appear in the live app. In this build, the correct pattern was: 1. generate sample data 2. wait a little 3. re-open the app 4. confirm the sample rows are visible 5. capture the screen state you want to review ![Landing page with sample data](/files/kLorDVNDjJxHVcTxSc8b) ## 7. Use Playwright to Inspect the Live App Once screens and sample data exist, use Playwright as a live inspection tool. The goal is not just to collect screenshots. The goal is to have the agent look at the running app, exercise the important paths, and report concrete issues before changing anything. Useful prompts at this point are specific: > Open the app with Playwright and inspect the first generated screens. Look for obvious layout issues, empty states, broken navigation, or interactions that do not behave as expected. Summarize what you find before making changes. > Open the recipe discovery screen, try a search term, and confirm whether the results update correctly. > Open a recipe detail screen and check whether the image, metadata, recipe content, review summary, and reviews are readable. This gives you a better review loop: 1. generate screens 2. inspect the live app 3. identify specific product issues 4. ask for a plan if the changes span multiple screens 5. implement and capture screenshots of the result {% hint style="info" %} Use screenshots as evidence during the product review. They are most useful when they show the specific state you just inspected or fixed. {% endhint %} ## 8. Plan the Screen Refinement Pass Once the first generated pass is visible, the next step is often not "change this now" but "make a plan first". That is especially helpful when feedback spans several screens. In this walkthrough, the planned refinement pass covered: * a more curated home screen * a clearer discovery screen * a tighter recipe detail screen A useful prompt shape is: > I have reviewed the first generated screens. Please make a plan before implementing changes. The home screen should feel more curated and include latest recipes. The recipes screen should be a simple search/filter experience with responsive results. The recipe detail screen should be more compact, with an image-led hero and a concise rating summary. That gives the agent room to inspect the current state, propose an order of work, and then implement the changes as one coherent screen refinement pass. ## 9. Round One: Tidy the Home Screen The first screen refinement round was small but important. It focused on tightening the home screen so it felt more curated and moving latest recipes into the home experience rather than scattering them across screens. This kind of round is a good fit for a short plan plus one implementation pass. You are not redesigning the whole app yet. You are cleaning up the most obvious product mismatch in the main entry screen. ![Home screen after fixes](/files/s121WVtJLhmoLYJbt4Rr) ## 10. Round Two: Rebuild Discovery Around Search For the discovery page, the final direction was: * single-column layout * code-widget search/filter bar at the top * results grid below * no extra featured/latest sections at the bottom ![Discovery screen with responsive results grid](/files/UoxblBmqbhvXwqaC3Gwe) That gave the app a much clearer browsing flow. Instead of trying to do too many things at once, the screen now has one job: help the user search, filter, and browse published recipes efficiently. This is the kind of refinement request that works well in product language: > Use a single-column setup with a search widget at the top that lets you search by name and filter by metadata, and then a results view that shows the published recipes that fit those criteria. ## 11. Use a Code Widget for Advanced Search/Filtering One of the most useful implementation patterns in this walkthrough is the search/filter widget on the recipe discovery screen. The important product decision was: > the search/filter bar is a code widget, and that drives the view component via a filterContext This is a strong pattern when: * the standard filter component is too limited * you want a better search UX * you still want the normal Buzzy view component to own the result rendering So the division of labor becomes: * **widget**: collect richer search/filter input * **filterContext**: shared handoff layer * **view component**: render the filtered rows You can then verify that the widget is actually driving the results, for example by testing a specific search term: ![Discovery screen filtered by search](/files/FWSkZrnFsvQ238SM3AlN) ## 12. Round Three: Polish the Recipe Detail Screen Important screens often take more than one refinement round. The recipe detail screen did here. The broad progression was: 1. tighten the top of the page into a compact image-led hero 2. move the key metadata into that hero 3. replace the larger ratings block with a small summary widget 4. keep the lower content focused on the recipe itself and the review stream After the hero and summary refinements: ![Detail screen after hero refinement](/files/SFzf74sM8gantTFbrNPb) This was a good example of precise iterative feedback: > I still dont like the recipe detail - can you change the top into more of a hero style section with the recipe image as the background and the main metadata on top. It's all just too large right now. > > Also get rid of the section called "ratings snapshot". Instead of that I just want one small code widget under the main hero that calculates an average rating, total number of ratings, that kind of thing. That is exactly the kind of feedback an MCP-driven build responds well to. ## 13. Verify Signed-In Behavior Where It Matters For review-driven features, it is worth verifying the signed-in experience directly, especially once you are working with user-owned or user-submitted data. The useful habit here is simple: * inspect the public view * inspect the signed-in view when reviews or profile data are involved * capture the screenshot that reflects the real user experience you want to document For the final verification in this build, the signed-in session was the important one: ![Logged-in detail screen with reviews](/files/eRu14i8eRktDMYks7Ic7) {% hint style="warning" %} If you need to verify runtime data that may be permission-sensitive, test both anonymous and signed-in views explicitly. {% endhint %} ## 14. A Good Build Chat Pattern This tutorial follows a repeatable build pattern: 1. ask the agent to do one stage 2. review the output 3. give targeted feedback 4. ask for a plan if the change is broad 5. inspect the running app when screens exist 6. continue You do not need to script every sentence. But it helps to be deliberate about the prompts you give. Useful examples: * `Move on to the flows stage, then stop for review.` * `Move on to the data model and call out anything I should check carefully.` * `Generate sample data so the screens can be reviewed with realistic content.` * `Inspect the live app with Playwright and summarize any obvious layout or interaction issues.` * `Please make a plan before changing these screens.` * `Use a code widget for this search/filter interaction.` The more concrete your feedback, the better the result. ## 15. Useful Prompt Shapes These prompt shapes came up repeatedly in this build, and they generalize well to other Buzzy MCP projects. * `Create an app for [problem domain]. It should support [core user actions], and the main records should include [key fields and relationships].` * `Move on to the brief review summary and stop there.` * `Move on to flows and then the data model. Stop after each one if there is anything I should review.` * `Can I get the workspace URL for this app?` * `Can I get the editor URL too?` * `Can I have a preview URL for the app?` * `Please make a plan for the next set of changes before implementing them.` * `Here is what I do not like about this screen: [short product feedback].` * `Use a code widget for this interaction, and have it drive the result through a filterContext.` * `Use Playwright to inspect [screen or workflow], test [specific interaction], and summarize what you find.` * `Capture a screenshot after the change so I can review the result.` * `Apply this small change directly: [single focused correction].` ## 16. What This Example Demonstrates This walkthrough shows a practical Buzzy MCP workflow that is worth reusing: * bootstrap the repo first * build in stages * stop at review gates * use sample data early * use Playwright for verification * ask for plans before broad changes * use code widgets where Buzzy's standard components are not enough It also shows that the best MCP builds come from **collaborative iteration with clear review checkpoints**. ## Next Step The best way to get comfortable with this workflow is to keep going inside the same app: * add another public browse or detail screen * introduce a small new feature such as saved recipes or review moderation * tighten one screen at a time and verify each change with screenshots That is usually the fastest way to build confidence with the Buzzy MCP loop. --- # 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, and the optional `goal` query parameter: ``` GET https://docs.buzzy.buzz/the-building-blocks/mcp/buzzy-builder-mcp/for-new-apps.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.