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

Use create_page_with_section only when the slug does not exist. It atomically creates a new page and its first section; it does not update an existing page. If it returns PAGE_SLUG_EXISTS, use the returned pageId with add_page_section.

To add another block to an existing page:

1. Call get_dynamic_page_detail with the slug.
2. Call get_page_block_schema for the desired block type.
3. Call add_page_section with the returned page id.
4. Call reorder_page_sections if the new block must move relative to existing blocks.
5. Read the page back with get_dynamic_page_detail.

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

ARTICLE_MEDIA

• body is required, localized plain text; do not send HTML
• heading, imageAlt, and imageCaption are localized
• imageUrl is a plain URL or website-relative media path
• imageAlt is required whenever imageUrl is present
• imagePosition accepts left, right, or top
• width accepts narrow, standard, or wide
• background accepts default or muted

Article composition blocks

• ARTICLE_HEADER: article title, subtitle, category, author, date, and optional cover image
• ARTICLE_GALLERY: 2–8 images with required localized alt text; layouts are grid or featured
• ARTICLE_FACTS: 1–8 concise facts or key takeaways
• ARTICLE_VIDEO: HTTPS YouTube, Vimeo, or direct video URL; embed HTML is not accepted
• ARTICLE_REFERENCES: 1–20 references with optional verified HTTPS URLs and notes
• Reuse QUOTE_CALLOUT, ACCORDION, and PRODUCT_CAROUSEL instead of creating duplicate article-only variants

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. Determine whether the page already exists.
2. For a new page, use create_page_with_section for the page and first block.
3. For an existing page, get its id and use add_page_section.
4. Create or update the page title translations.
5. Update existing sections using the dedicated block tool when possible.
6. Read back the page with get_dynamic_page_detail.
7. 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.