homaroma/apps/mcp-server

DBK Platform MCP Server

HomAroma is the reference tenant. This server exposes shared MCP capabilities; a tool call must use the active tenant's data and configuration.

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 เท่านั้น
• get_footer_brand / update_footer_brand อ่านและแก้ Footer Brand block โดยตรง (brand name, logo, คำอธิบายแยกภาษา, social links) พร้อม dryRun และ expectedVersion

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_media, 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

Category media uses semantic roles: thumbnail, hero_desktop, hero_mobile, card_portrait, and social_share. update_category_media replaces the complete media set, so omitted roles are removed. update_category_image remains available only as a legacy thumbnail compatibility tool.

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