x

LLM_MCP_GUIDE.md

@@ -0,0 +1,140 @@
+# HomAroma MCP Guide for LLMs
+
+This guide explains how to use the HomAroma MCP tools safely and consistently.
+
+## Core Rules
+
+- Prefer the dedicated block tools over the generic `add_page_section` / `update_page_section` tools when available.
+- Use `update_page_translations` when you need to set several languages for a page title in one call.
+- Treat localized fields and plain strings differently.
+- Read back the page after edits when you need confirmation.
+
+## Finding a Page
+
+- Use `get_dynamic_page_detail` with the page slug when you already know the slug.
+- Use `list_dynamic_pages_metadata` when you need to search all pages quickly.
+- The dynamic page detail response includes the page `id`, which is the `pageId` you use for section tools.
+
+## Create Page Response Contract
+
+`create_dynamic_page` now returns a structured response that is easy for LLMs to parse:
+
+- `success`
+- `operation`
+- `pageId`
+- `slug`
+- `title`
+- `isPublished`
+- `diagnostic`
+- `page`
+
+Use `diagnostic` as the human-readable explanation, not as the only signal of success.
+
+## Section Tool Mapping
+
+- `update_hero_article`
+- `update_rich_text`
+- `update_scent_notes_breakdown`
+- `update_quote_callout`
+- `update_product_carousel`
+- `update_accordion`
+- `update_contact_info`
+- `update_contact_form`
+
+These tools return a normalized response with:
+
+- `success`
+- `tool`
+- `sectionType`
+- `sectionId`
+- `updatedFields`
+- `appliedPayload`
+- `notes`
+- `section`
+
+## Payload Shape Cheat Sheet
+
+### Localized string
+
+Use this when a field can be translated:
+
+```json
+{ "th": "ข้อความภาษาไทย", "en": "English text" }
+```
+
+### Plain string
+
+Use one string only for URLs, slugs, IDs, and booleans/numbers as appropriate.
+
+## Block-Specific Rules
+
+### `HERO_ARTICLE`
+
+- Localized: `title`, `subtitle`, `author`, `category`
+- Plain string: `publishDate`, `date`, `imageUrl`, `backgroundImageUrl`, `overlayColor`
+- The image is passed as a URL string in `imageUrl`
+
+### `RICH_TEXT`
+
+- `title` is optional and localized
+- `content` is required and localized
+- HTML is allowed in `content`
+
+### `SCENT_NOTES_BREAKDOWN`
+
+- `title` and `description` are localized
+- Each note item may be a plain string or a localized string object
+- `heartNotes` and `middleNotes` are mirrored by the backend
+
+### `QUOTE_CALLOUT`
+
+- `quote` is required and localized
+- `author` and `role` are optional localized fields
+
+### `PRODUCT_CAROUSEL`
+
+- `title` and `description` are localized
+- `collectionId`, `limit`, `showPrice`, `showAddToCart`, and `products` are plain values
+- If `products` is omitted, the backend can auto-populate products on read-back
+
+### `ACCORDION`
+
+- `title` is optional and localized
+- `categories` is required
+- Each category needs:
+  - localized `name`
+  - optional `icon`
+  - at least one question
+- Each question needs localized `q` and `a`
+
+### `CONTACT_INFO`
+
+- `title` is optional and localized
+- `address` and `hours` are localized
+- `email` and `line` are plain strings
+
+### `CONTACT_FORM`
+
+- `title` and `subtitle` are localized
+- There are no extra fields
+
+## Recommended Flow
+
+1. Find the page id from slug or metadata.
+2. Create or update the page title translations.
+3. Add sections using the dedicated block tool when possible.
+4. Read back the page with `get_dynamic_page_detail`.
+5. If a section has auto-populated fields, trust the read-back result over the raw update payload.
+
+## What to Expect
+
+- `PRODUCT_CAROUSEL` may return products even when you did not send them.
+- `SCENT_NOTES_BREAKDOWN` may show mirrored note groups in the response.
+- `create_dynamic_page` should now return a clear success/error contract.
+
+## Safe Usage Tips
+
+- Do not guess the field shape from the UI alone.
+- If a field is a URL, send a URL string.
+- If a field is translated, send a localized object.
+- If you are unsure, inspect an existing page with `get_dynamic_page_detail` first.