141 lines
3.8 KiB
Markdown
141 lines
3.8 KiB
Markdown
# 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.
|