homaroma/mcp_update.md

DBK Platform MCP Update: mega-showcase

Historical implementation context: This update was produced against the HomAroma reference tenant. The MCP contracts described here are platform capabilities unless explicitly marked tenant-specific.

เอกสารนี้สรุปผลการใช้งาน homaroma_mcp กับหน้า CMS mega-showcase เพื่อส่งต่อให้ทีม Dev ของ MCP Tool และ Backend ใช้พัฒนาต่อ

เป้าหมายงาน

• ต้องการให้หน้า CMS mega-showcase แปลภาษาให้ครบทุก section
• ต้องทำผ่าน MCP Tool เท่านั้น
• ห้ามใช้ workaround ด้วยการแก้โค้ด, แก้ DB, หรือ patch ข้อมูลนอก MCP
• ถ้า MCP ไม่รองรับบางส่วน ต้องระบุข้อจำกัดให้ชัดเจน

สิ่งที่ตรวจสอบแล้วก่อนลงมือ

• ตรวจสอบหน้า dynamic page ด้วย get_dynamic_page_detail(slug: "mega-showcase")
• ตรวจสอบ schema section ที่เกี่ยวข้องใน:
  • packages/types/index.ts
  • apps/backend/src/routes/pages.ts
  • apps/mcp-server/index.ts
• ยืนยันแล้วว่า LocalizedStringSchema รองรับทั้ง string และ object map ของภาษา
• ยืนยันแล้วว่า section types บางตัวรองรับ localized payload โดยตรง

สรุปผลที่ทำสำเร็จผ่าน MCP

1) Page translation

อัปเดต translation ของหน้า mega-showcase สำเร็จครบ 6 ภาษา

• th: หน้าเมก้าโชว์เคส
• en: Mega Showcase Page
• ja: メガショーケースページ
• zh: 超级展示页面
• vi: Trang Mega Showcase
• ko: 메가 쇼케이스 페이지

2) Product translation

สินค้า id: 16 ซึ่งอยู่ใน PRODUCTS section ถูกแปลครบ 6 ภาษาแล้ว

• name
• description
• details

Translation records ถูกบันทึกจริงในระบบและยืนยันได้จาก get_product_detail(id: 16, lang: "all")

3) Sections ที่อัปเดตสำเร็จ

Section 87 - HERO

อัปเดตได้สำเร็จ:

• title
• tagline
• description
• buttonText

คงค่าเดิมไว้:

• imageUrl
• buttonLink

Section 88 - CATEGORIES

อัปเดตได้สำเร็จ:

• title
• subtitle

คงค่าเดิมไว้:

• categoryIds

Section 89 - PRODUCTS

อัปเดตได้สำเร็จ:

• title

คงค่าเดิมไว้:

• type
• limit
• products

รายการสินค้าใน block นี้ประกอบด้วย 1, 6, 11, 16 และสินค้า 16 ถูกแปลครบแล้วในระดับ product translation

Section 90 - BANNER

อัปเดตได้สำเร็จ:

• title

คงค่าเดิมไว้:

• imageUrl

Section 91 - TEXT

อัปเดตได้สำเร็จ:

• content

คงค่าเดิมไว้:

• textAlign

Section 92 - ANNOUNCEMENT_BAR

อัปเดตได้สำเร็จ:

• slides[0]
• slides[1]

Section 93 - NEWSLETTER

อัปเดตได้สำเร็จ:

• title
• description
• buttonText

คงค่าเดิมไว้:

• showPrivacyCheckbox

Section 94 - EDITORIAL_TILE

อัปเดตได้สำเร็จ:

• title
• description

คงค่าเดิมไว้:

• imageUrl
• imagePosition

Section 95 - EDITORIAL_CAROUSEL

อัปเดตได้สำเร็จ:

• title
• slides[0].category
• slides[0].title
• slides[0].description

คงค่าเดิมไว้:

• imageUrl

สถานะหลังอัปเดต

ยืนยันจาก MCP ว่าบันทึกสำเร็จ

• get_product_detail(id: 16, lang: "all") แสดง translation records ครบจริง
• get_dynamic_page_detail(slug: "mega-showcase") แสดง payload ของ section ที่อัปเดตแล้วเป็น multilingual object จริง

ตัวอย่างข้อมูลที่ยืนยันได้

• Hero payload เก็บเป็น object แยกภาษาแล้ว
• Categories payload เก็บเป็น object แยกภาษาแล้ว
• Announcement bar slides เก็บเป็น object แยกภาษาแล้ว
• Newsletter / Editorial / Banner / Text เก็บเป็น object แยกภาษาแล้ว

Sections ที่ปิด gap แล้ว

หลังจากขยาย backend validation และเพิ่ม UI/renderer ให้รองรับ payload แบบ localized แล้ว section ต่อไปนี้ใช้งาน multilingual ได้ครบในทางปฏิบัติ:

• 96 - HERO_ARTICLE
• 97 - RICH_TEXT
• 98 - SCENT_NOTES_BREAKDOWN
• 99 - QUOTE_CALLOUT
• 100 - PRODUCT_CAROUSEL
• 101 - ACCORDION
• 102 - CONTACT_INFO
• 103 - CONTACT_FORM

สิ่งที่ปิด gap ให้ครบ

• apps/backend/src/routes/pages.ts รับ payload ของ section เหล่านี้ได้แล้วผ่าน validation แบบ localized-friendly
• apps/admin มี form สำหรับสร้าง/แก้ block เหล่านี้แล้ว
• apps/spa แสดงผล block เหล่านี้ตามภาษา active ได้แล้ว

จุดที่ยังควรยกระดับสำหรับ LLM

แม้ section gap จะปิดแล้ว แต่ถ้าเป้าหมายคือทำให้ LLM ใช้งาน MCP ได้ดีที่สุด ยังมีงานที่ควรทำต่อ:

1) เพิ่ม tool แบบเฉพาะ block

ตอนนี้มี tool เฉพาะ block เพิ่มแล้ว โดยยังคง add_page_section และ update_page_section เป็น fallback:

• update_hero_article
• update_rich_text
• update_scent_notes_breakdown
• update_quote_callout
• update_product_carousel
• update_accordion
• update_contact_info
• update_contact_form
• update_page_translations

ถ้าจะเพิ่มฝั่ง create แบบเฉพาะ block ต่อไป ค่อยขยายเป็นคู่ add_* เพิ่มจากชุดนี้ได้อีกชั้น

จุดที่ช่วยให้ LLM อ่านง่ายขึ้น: tool แต่ละตัวมี description พร้อมบอกชัดว่า field ไหนเป็น localized object, field ไหนเป็น plain string และมีตัวอย่าง payload ให้ดูทันที ฝั่ง SCENT_NOTES_BREAKDOWN จะ mirror heartNotes กับ middleNotes ให้ตรงกันอัตโนมัติ และผลลัพธ์จะบอก note นี้กลับมาใน response ด้วย PRODUCT_CAROUSEL ตอนนี้ backend จะพยายามเติม products ให้อัตโนมัติเมื่อ payload ยังไม่มีรายการสินค้า และ response จะบอกไว้ชัดว่าเกิด auto-populate หรือไม่

2) ทำ structured read-back

ตอนนี้ update tools คืนข้อมูลแบบ normalize แล้วใน JSON response

ถ้าจะยกระดับต่อ ควรแยกให้ชัดขึ้นอีก:

• field ไหนถูก merge
• field ไหนถูก overwrite
• payload สุดท้ายหน้าตาเป็นอะไร

ตอนนี้ response มี appliedPayload เพิ่มมาแล้ว ทำให้ LLM เห็น payload ที่ส่งจริงได้ทันที update_page_translations ช่วยลดการเรียกซ้ำทีละภาษาได้มาก และคำอธิบายใหม่จะบอกชัดว่าควรใช้เมื่ออยากอัปเดตหลายภาษาใน request เดียว

3) ทำ error ให้ LLM-friendly

validation error ควรบอก:

• field
• expected
• got
• suggestion

ตอนนี้ backend/MCP ยังคืน error เป็นข้อความรวมอยู่เป็นหลัก จึงยังมีช่องให้ขยายต่อในรอบถัดไป

4) ชัดเจนเรื่อง supported shape

tool description ควรบอกตัวอย่าง payload ที่คาดหวังสำหรับแต่ละ block ให้ชัดขึ้น เพื่อให้ LLM ไม่ต้องเดาจาก schema ล้วน ๆ

ผลกระทบกับ user-facing CMS

ตอนนี้หน้า mega-showcase สามารถแปล section หลักได้ครบมากขึ้นแล้ว และ block ที่เคยค้างอยู่ฝั่ง data shape ก็ปิด gap ไปแล้ว

สิ่งที่เหลือเป็นเรื่องของ UX สำหรับผู้ใช้เครื่องมือและความชัดเจนของ MCP tool layer มากกว่าความสามารถในการ render จริง

จุดที่ควรทดสอบเพิ่ม

• เปิดหน้า mega-showcase ใน SPA แล้วสลับภาษาเพื่อตรวจ render จริง
• ตรวจว่าภาษา active ถูก resolve จาก object map ใน section ที่อัปเดตแล้ว
• ตรวจว่า product 16 แสดงชื่อ/description/details ตามภาษาที่เลือกจริง
• ตรวจว่า block ใหม่ทั้ง 8 แบบ บันทึกและแก้ไขได้ต่อเนื่องผ่าน admin แล้วไม่ทำให้หน้า error เมื่อสลับภาษา

รายการ Tools ที่เกี่ยวข้อง

• get_dynamic_page_detail
• update_page_translation
• update_page_section
• get_product_detail
• update_product_translation

บทสรุปสำหรับทีม Dev

MCP Tool ของ HomAroma ตอนนี้ใช้งานได้จริงมากขึ้นสำหรับการแปลหน้า CMS mega-showcase

gap ของ section ที่เคยค้างอยู่ถูกปิดด้วยการขยาย backend validation, admin forms, และ spa renderer แล้ว

ถ้าเป้าหมายถัดไปคือให้ LLM ใช้งาน MCP ได้ “ดีมาก” ไม่ใช่แค่ “ทำงานได้” ควรเพิ่ม dedicated tools, structured read-back, และ error messages ที่สื่อกับโมเดลได้ตรงขึ้น