homaroma/LLM_MCP_GUIDE.md

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:

{ "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.