homaroma/apps/mcp-server/README.md

HomAroma MCP Server

MCP server สำหรับเชื่อม AI tools เข้ากับ backend ของ HomAroma ผ่าน stdio transport

Run

bun install
bun run --cwd apps/mcp-server dev

หรือรันตรงจาก package:

cd apps/mcp-server
bun run dev

Environment

รองรับตัวแปรต่อไปนี้:

• MCP_BACKEND_URL สำหรับกำหนด backend target ตรง ๆ
• MCP_BACKEND_URL_LOCAL ค่าเริ่มต้นสำหรับ local
• MCP_BACKEND_URL_PRODUCTION ค่าเริ่มต้นสำหรับ production
• MCP_ADMIN_USERNAME
• MCP_ADMIN_PASSWORD

ถ้าไม่ตั้งค่า MCP_BACKEND_URL server จะเริ่มที่ local backend และสลับเป็น production ได้ด้วย tool set_target_environment

Available tools

• update_brand_name เปลี่ยนชื่อแบรนด์กลางที่ใช้ใน header/footer ของ apps/spa และ apps/website
• update_store_settings_translation อัปเดตข้อความแปลของ store settings
• update_footer_content อัปเดตคำอธิบายแบรนด์และ social links เท่านั้น

Footer Menu LLM Workflow

Footer Explore and Footer Support are flat item menus, not Mega Menu payload trees. Supported menu names are:

footer-explore
footer-support

Use this workflow for every Footer menu edit:

1. Call get_footer_menu with the target language.
2. Keep the returned version.
3. Call one item-level write tool with dryRun: true and expectedVersion.
4. Review the compact preview.
5. Apply the same operation with dryRun: false and the same version.
6. Call get_footer_menu again to verify and obtain the next version.

If an allowed Footer menu does not exist yet, get_footer_menu returns exists: false, version: null, and an empty item list. Previewing the first add returns willCreateMenu: true; applying that add creates the menu as active and inserts the first item atomically.

Available item-level tools:

• add_footer_menu_item
• update_footer_menu_item
• delete_footer_menu_item
• reorder_footer_menu_items
• update_footer_menu_item_translation

Every reorder request must include every current item ID exactly once. A MENU_VERSION_CONFLICT response means Admin or another agent changed the menu after it was read; fetch it again before retrying.

Do not pass exploreLinks, collectionLinks, or supportLinks to legacy update_footer_content. Full menu-array replacement is rejected because it can delete item IDs and translations. Website Collections are populated from Categories rather than a footer-collections menu.

Mega Menu LLM Workflow

Header Mega Menu uses the main menu payload tree. The website renders this structure:

Root -> Column -> Link -> Child Link

Supported localized text keys are:

th, en, ja, zh, vi, ko, lo, it

LLM agents should use this workflow for every menu edit:

1. capture_menu_snapshot for main
2. get_mega_menu_tree
3. validate_mega_menu_tree
4. Plan operations from diagnostics and current nodeId values
5. bulk_menu_operations with dryRun: true
6. Review preview.diff, preview.before, preview.after, issues, and warnings
7. Apply only after approval
8. Run validate_mega_menu_tree again
9. Use restore_menu_snapshot if the applied result is wrong

Do not add a Link directly under root. Add a Column under Root first, then add Links under that Column.

Dry-run responses are expected to include path-based diffs such as:

{
  "path": "payload[0].columns[0].links[0].label.it",
  "before": null,
  "after": "Candele"
}

validate_mega_menu_tree reports:

• missing locale keys, especially lo and it
• unsupported translation keys
• duplicate or missing nodeId
• invalid URL shape
• placeholder text
• empty columns
• featured card issues
• desktop render limits such as hidden columns or links

Category Management LLM Workflow

Product categories are managed by backend /categories APIs through MCP. Supported localized text keys are:

th, en, ja, zh, vi, ko, lo, it

LLM agents should use this workflow for category edits:

1. list_categories with lang: "all" to discover category IDs and current translations
2. create_category, update_category, update_category_translations, or delete_category with dryRun: true
3. Review the preview and product counts
4. Apply only after the intended change is clear
5. Run list_categories again to verify

Backend category support currently covers:

• base name
• imageUrl
• localized names
• product-count guarded soft delete (deletedAt)

Backend category support does not currently cover:

• slug
• nested parent/child hierarchy
• sort order
• active/inactive state
• restore/undelete workflow

Scripts

• bun run dev
• bun run start
• bun run check