# HomAroma MCP Server

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

## Run

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

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

```bash
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:

```text
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.

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:

```text
Root -> Column -> Link -> Child Link
```

Supported localized text keys are:

```text
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:

```json
{
  "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:

```text
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`