SlimWeb-MCP

SlimWeb-MCP 是 SlimWeb / Webless 電商後台的 Remote MCP 閘道。主要目標是讓使用者透過自己的 AI Client，例如 Codex、ChatGPT、Claude、Gemini、Grok，直接操作 SlimWeb 後台，而不是被迫學習 SlimWeb 內部的頁面編輯邏輯、資料欄位或管理流程。

這個 repo 是 MCP 架構與實作的入口。SlimWeb / Webless 仍然是商品、訂單、頁面、素材、設定、會員與權限的 source of truth。

目標

• 提供 SlimWeb 後台可用的 Remote MCP Server。

• 透過 Google 登入驗證使用者身份。

• 讓每一次 MCP tool 呼叫都綁定使用者、帳號、站台與權限。

• 以明確的 MCP tools 開放常見電商後台操作。

• 讓 AI Client 只透過 tools 操作 SlimWeb，不直接碰資料庫、Storage 或內部後台路由。

• 將這份 README 當作持續維護的 tool contract。每新增或修改 MCP tool，都必須同步更新本文件。

非目標

• 不取代 SlimWeb / Webless 後端。

• 不另存一份商品、訂單、頁面或會員資料。

• 不繞過 SlimWeb 原本的角色與權限檢查。

• 不綁定單一 AI Client。

• 不提供 raw SQL、raw database、raw storage credential 類型的 MCP tool。

• 不把整個後台 UI 自動化暴露成不受控的瀏覽器操作。

架構總覽

flowchart LR
    Client["使用者 AI Client<br/>Codex / ChatGPT / Claude / Gemini / Grok"]
    MCP["SlimWeb Remote MCP Server"]
    Auth["Google 登入<br/>OAuth / OIDC"]
    Session["SlimWeb MCP Session<br/>Token Broker"]
    Policy["權限與站台 Scope Guard"]
    SlimWeb["SlimWeb / Webless Backend"]
    Storage["SlimWeb Data + Assets"]

    Client -->|"MCP over HTTPS"| MCP
    MCP --> Auth
    MCP --> Session
    MCP --> Policy
    Policy --> SlimWeb
    SlimWeb --> Storage

Remote MCP Server 是 SlimWeb 前方的受控 adapter。AI Client 不直接連資料庫、Cloud Storage 或內部 admin route。Client 先完成 Google 登入，取得被限制範圍的 MCP session，再透過 tool discovery 得到可用工具，最後用 tools 操作 SlimWeb。

核心元件

Remote MCP Server

Remote MCP Server 是 AI Client 對外連線的入口。

職責：

• 以 HTTPS 提供 MCP discovery 與 tool invocation。

• 對需要保護的 tools 強制要求登入。

• 驗證 tool input schema。

• 將 MCP request 轉成 SlimWeb 可執行的 application service 或 API 呼叫。

• 將 SlimWeb response 正規化成穩定的 MCP tool output。

• 回傳明確錯誤，例如未登入、權限不足、驗證失敗、需要確認、SlimWeb upstream error。

Google 登入

Google 登入是 Remote MCP 的主要身份驗證方式。

職責：

• 透過 OAuth / OIDC 驗證 Google identity。

• 將 Google account 對應到 SlimWeb user。

• 建立或更新 SlimWeb MCP session。

• 將 session scope 限制在使用者可操作的 account、site、role、permissions。

預期登入流程：

1. AI Client 連到 SlimWeb Remote MCP Server。

2. 如果沒有有效 MCP session，server 回傳 authentication required 與 login URL。

3. 使用者在瀏覽器完成 Google 登入。

4. SlimWeb 驗證 Google identity，並綁定 SlimWeb user。

5. MCP Server 建立 scoped MCP session。

6. AI Client 重新進行 tool discovery 或 tool invocation。

Session 與 Token Broker

Session layer 負責把 Google 驗證後的身份轉成 SlimWeb 可以接受的 MCP access。

規則：

• MCP session 必須是短效或可安全 refresh。

• token 不可包含 SlimWeb 內部 secret。

• session claims 至少要包含 user_id、account_id、可操作的 site_ids、role、permissions。

• 每次 tool 呼叫都要重新檢查權限，不可只依賴 discovery 時的結果。

權限與站台 Scope Guard

每個 tool 都必須在明確 scope 內執行。

最低 scope 欄位：

• account_id

• site_id

• user_id

• role

• permissions

以下情況必須拒絕 request：

• 使用者未登入。

• MCP session 已過期。

• 指定站台不屬於該 account。

• 使用者 role 沒有所需 permission。

• tool 嘗試修改 active site 以外的資料。

• 高風險操作需要 confirmation，但 request 沒有 confirmation token。

SlimWeb Backend Adapter

Adapter 是 MCP Server 與 SlimWeb / Webless 後端之間的唯一連接層。

職責：

• 將 MCP tool request 對應到 SlimWeb application service 或 HTTP API。

• 優先重用 SlimWeb 現有 business rule，不在 MCP Server 重寫一份規則。

• 隔離 SlimWeb 內部 controller、model、route 的變化。

• 對外提供穩定 output，讓 AI Client 可以可靠推理。

• 記錄 tool execution audit log，方便追蹤與客服支援。

資料流

Site Selection 與歧義處理

使用者帳號底下可能有多個 SlimWeb site。AI Client 不可在無法判斷目標網站時自行猜測。

規則：

• 使用者登入後，AI 應先呼叫 slimweb.sites.list 取得可操作網站。

• 若只有一個 site，可自動選定該 site。

• 若有多個 site，且使用者沒有明確說出網站名稱、網域、site ID 或足以唯一識別的線索，AI 必須向使用者確認要操作哪個網站。

• 若使用者描述能比對到多個 site，AI 必須列出候選網站並要求使用者選擇。

• Write tools 必須帶入 active site scope；沒有 active site 時，server 回傳 SITE_SCOPE_REQUIRED。

• AI Client 不需要知道 SlimWeb 的目錄結構，只需要透過 tools 查詢資料、選擇目標、提交結構化操作。

建議 AI 操作順序：

1. slimweb.auth.status

2. slimweb.sites.list

3. slimweb.site.select，或在無法唯一判斷時先問使用者

4. 依任務組合 read tools 與 write tools

Tool Discovery

1. AI Client 連到 Remote MCP endpoint。

2. MCP Server 檢查 session。

3. MCP Server 根據使用者 role、permissions、active site 回傳可用 tools。

4. AI Client 將 tools 提供給模型或使用者操作。

Read Tool

1. Client 呼叫 read-only tool，例如列出商品、類別、訂單或優惠。

2. MCP Server 驗證 session 與 site scope。

3. Scope Guard 檢查 read permission。

4. Adapter 呼叫 SlimWeb。

5. MCP Server 回傳正規化結果。

Write Tool

1. Client 呼叫 write tool，例如更新商品文案、替換商品圖片、調整訂單狀態或建立優惠。

2. MCP Server 驗證 input schema。

3. Scope Guard 檢查 write permission。

4. 高影響操作要求 confirmation。

5. Adapter 呼叫 SlimWeb。

6. MCP Server 回傳更新後摘要、warnings、audit ID。

初始 MCP Tools 規劃

第一階段先建立小而安全的 tool surface。每個 tool 都要具備權限檢查、input validation、錯誤處理、audit log 與文件更新，再進入可用狀態。

版型與頁面 tools 先不在本階段定義，之後獨立補上。

Tool 文件維護規範

每新增或修改一個 tool，都必須在同一個 PR 更新本 README。格式如下：

### `tool.name`

- 狀態:
- 權限:
- Scope:
- 用途:
- Input:
- Output:
- Side effects:
- 是否需要 confirmation:
- 錯誤情境:
- Audit fields:

規則：

• 實作 tool 的 PR 必須同步更新文件。

• experimental tool 要清楚標示。

• tool 尚未進入 MCP discovery 前，不可標成可用。

• 任何會修改客戶可見內容的 input，都要寫明 validation 與 rollback / recovery 行為。

• 任何會處理圖片的 tool，都要寫明圖片是 reference-only，還是會保存成 reusable asset。

Tool Contracts

共通 Tool Rules

• 所有 tools 預設都需要有效 Google 登入與 MCP session。

• 除 slimweb.auth.status、slimweb.sites.list 之外，tools 都需要 active site。

• 若 active site 無法從使用者語意唯一判斷，AI 必須先問使用者，不可猜測。

• Read tools 應回傳 stable IDs，讓 AI 後續 write tools 能精準指定目標。

• Write tools 不接受模糊目標，例如「第一個商品」；AI 必須先用 read tool 取得候選，再讓使用者或語意唯一指定。

• 需要圖片的 tools 必須明確收到圖片附件、可下載 image URL、或前一步 slimweb.assets.upload 回傳的 asset_id。

• AI 不需要知道 SlimWeb 檔案目錄或後端 route，只需依 tool contract 使用 tools。

slimweb.auth.status

• 狀態: Planned

• 權限: authenticated user

• Scope: user session

• 用途: 回傳目前登入與 scope 狀態。

• Input: none

• Output: login status、user summary、account summary、active site summary、available site count、session expiry

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: expired session、invalid token

• Audit fields: request ID、user ID、session ID

slimweb.sites.list

• 狀態: Planned

• 權限: account read

• Scope: authenticated account

• 用途: 列出使用者可透過 MCP 操作的 sites。

• Input: optional pagination、keyword filter

• Output: site IDs、names、domains、status、role、permission summary

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: unauthorized、no linked SlimWeb account

• Audit fields: request ID、user ID、account ID

slimweb.site.select

• 狀態: Planned

• 權限: account read

• Scope: authenticated account

• 用途: 設定後續 MCP tool calls 的 active site。

• Input: site_id

• Output: active site summary、available tool categories

• Side effects: updates MCP session scope

• 是否需要 confirmation: no

• 錯誤情境: site not found、site not accessible

• Audit fields: request ID、user ID、account ID、site ID

slimweb.dashboard.summary

• 狀態: Planned

• 權限: dashboard read

• Scope: active site

• 用途: 回傳後台首頁摘要，讓 AI 快速理解目前站台狀況。

• Input: optional date range

• Output: KPI summary、latest orders、latest members、low stock products、traffic summary if available

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、permission denied

• Audit fields: request ID、user ID、account ID、site ID

slimweb.settings.get

• 狀態: Planned

• 權限: settings read

• Scope: active site

• 用途: 讀取 AI 後台操作需要的站台基本設定。

• Input: optional fields list

• Output: site status、country、product loading mode、return days allowed、editable field hints

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、permission denied

• Audit fields: request ID、user ID、account ID、site ID

slimweb.settings.update

• 狀態: Planned

• 權限: settings write

• Scope: active site

• 用途: 更新允許 MCP 修改的基本設定。

• Input: patch object，僅允許 allowlist 欄位，例如 site status、country、product loading mode、return days allowed

• Output: updated settings summary、changed fields、warnings、audit ID

• Side effects: modifies site settings

• 是否需要 confirmation: yes for disabling site、changing return policy、or settings that affect storefront behavior

• 錯誤情境: validation failed、permission denied、unsupported field、conflict

• Audit fields: request ID、user ID、account ID、site ID、changed fields

slimweb.admins.list

• 狀態: Planned

• 權限: admin read

• Scope: active site

• 用途: 列出站台管理員與權限摘要，讓 AI 在權限問題上能先查清楚現況。

• Input: optional keyword、role、pagination

• Output: admin summaries、roles、permission summary、status、last updated time

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、permission denied

• Audit fields: request ID、user ID、account ID、site ID

slimweb.admins.upsert

• 狀態: Planned

• 權限: admin write

• Scope: active site

• 用途: 新增或更新站台管理員與權限。

• Input: optional admin ID、email or user identifier、role、permissions、status

• Output: admin summary、changed permissions、audit ID

• Side effects: creates or modifies admin access

• 是否需要 confirmation: yes

• 錯誤情境: validation failed、admin not found、duplicate admin、cannot modify owner、permission denied、conflict

• Audit fields: request ID、user ID、account ID、site ID、target admin ID、changed permissions

slimweb.categories.list

• 狀態: Planned

• 權限: product read

• Scope: active site

• 用途: 列出商品分類，支援「目前商品有哪些類別？」這類問題。

• Input: optional status、keyword、include product counts

• Output: category IDs、names、parent IDs、sort order、status、product counts

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、permission denied

• Audit fields: request ID、user ID、account ID、site ID

slimweb.categories.create

• 狀態: Planned

• 權限: product write

• Scope: active site

• 用途: 新增商品分類。

• Input: name、optional parent category ID、status、sort order

• Output: created category summary、audit ID

• Side effects: creates category

• 是否需要 confirmation: no, unless category will be immediately visible on storefront

• 錯誤情境: validation failed、duplicate name、parent not found、permission denied

• Audit fields: request ID、user ID、account ID、site ID、category ID

slimweb.categories.update

• 狀態: Planned

• 權限: product write

• Scope: active site

• 用途: 更新分類名稱、排序、啟用狀態或父層。

• Input: category ID、patch object

• Output: updated category summary、changed fields、audit ID

• Side effects: modifies category

• 是否需要 confirmation: yes for disabling category、moving category with products、or changing storefront-visible navigation

• 錯誤情境: validation failed、category not found、cycle detected、permission denied、conflict

• Audit fields: request ID、user ID、account ID、site ID、category ID、changed fields

slimweb.products.list

• 狀態: Planned

• 權限: product read

• Scope: active site

• 用途: 列出商品，讓 AI 可協助搜尋、審查與編輯前確認。

• Input: status、category、keyword、pagination、sort

• Output: product summaries、stable IDs、editable field hints

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、unauthorized

• Audit fields: request ID、user ID、account ID、site ID

slimweb.products.get

• 狀態: Planned

• 權限: product read

• Scope: active site

• 用途: 讀取單一商品完整可編輯摘要，讓 AI 在修改前知道目前資料。

• Input: product ID

• Output: product fields、categories、primary images、content images、videos、variants、quantity discounts、add-ons、editable field hints

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: product not found、permission denied

• Audit fields: request ID、user ID、account ID、site ID、product ID

slimweb.products.update

• 狀態: Planned

• 權限: product write

• Scope: active site

• 用途: 透過 SlimWeb validation 更新商品欄位。

• Input: product ID、patch object、optional client note

• Output: updated product summary、changed fields、warnings、audit ID

• Side effects: modifies product data

• 是否需要 confirmation: price、inventory、publication status、破壞性客戶可見內容修改都需要

• 錯誤情境: validation failed、conflict、unauthorized、product not found

• Audit fields: request ID、user ID、account ID、site ID、product ID、changed fields

slimweb.products.images.replace

• 狀態: Planned

• 權限: product write + asset write

• Scope: active site

• 用途: 替換商品圖片，例如「把商品 xxx 的第一張圖換成這張」。

• Input: product ID、image target、replacement image、optional alt text、optional client note

• Input 條件:

  • image target 必須指定 primary_image、content_image 或 variant_image

  • 若指定第一張主圖，使用 image target = primary_image 與 position = 1

  • replacement image 必須是圖片附件、可下載 image URL、或 asset_id

  • 若使用者只說商品名稱，AI 必須先呼叫 slimweb.products.list 或 slimweb.products.get 找到唯一 product_id

• Output: updated product image summary、old image reference、new image reference、warnings、audit ID

• Side effects: uploads or links image、updates product image list、may affect storefront

• 是否需要 confirmation: yes when replacing customer-facing image、removing old image、or product match is based on fuzzy search

• 錯誤情境: product not found、image missing、unsupported file type、file too large、target image not found、permission denied、validation failed

• Audit fields: request ID、user ID、account ID、site ID、product ID、image target、old image ID、new image ID

slimweb.products.variants.update

• 狀態: Planned

• 權限: product write

• Scope: active site

• 用途: 更新商品規格模式、規格名稱、規格價格、特價與庫存。

• Input: product ID、variant mode、variants patch、optional client note

• Output: updated variants summary、stock sync result、warnings、audit ID

• Side effects: modifies product variants and may sync product total stock

• 是否需要 confirmation: yes for price changes、stock changes、or switching variant mode

• 錯誤情境: product not found、invalid variant mode、validation failed、conflict、permission denied

• Audit fields: request ID、user ID、account ID、site ID、product ID、changed variants

slimweb.products.quantity_discounts.update

• 狀態: Planned

• 權限: product write

• Scope: active site

• 用途: 更新商品數量折扣。

• Input: product ID、quantity discount rules

• Output: updated discount rules、warnings、audit ID

• Side effects: modifies product pricing behavior

• 是否需要 confirmation: yes

• 錯誤情境: product not found、validation failed、overlapping rules、permission denied

• Audit fields: request ID、user ID、account ID、site ID、product ID

slimweb.products.import.analyze

• 狀態: Planned

• 權限: product write

• Scope: active site

• 用途: 分析使用者提供的商品匯入資料，回傳可確認的商品草稿。

• Input: source file or structured rows、default status、optional category mapping、optional image handling policy

• Output: import draft ID、detected products、category candidates、validation warnings、required confirmations

• Side effects: creates temporary import draft only

• 是否需要 confirmation: no

• 錯誤情境: unsupported file type、parse failed、validation failed、permission denied

• Audit fields: request ID、user ID、account ID、site ID、import draft ID

slimweb.products.import.commit

• 狀態: Planned

• 權限: product write

• Scope: active site

• 用途: 將已分析且使用者確認的商品匯入草稿寫入 SlimWeb。

• Input: import draft ID、confirmed product IDs or all、conflict strategy

• Output: created products、updated products、skipped rows、warnings、audit ID

• Side effects: creates or updates products、categories、images、variants depending on confirmed draft

• 是否需要 confirmation: yes

• 錯誤情境: import draft not found、expired draft、validation failed、conflict、permission denied

• Audit fields: request ID、user ID、account ID、site ID、import draft ID

slimweb.orders.list

• 狀態: Planned

• 權限: order read

• Scope: active site

• 用途: 依狀態、日期區間、關鍵字與分頁列出訂單。

• Input: status、date range、keyword、pagination、sort

• Output: order summaries、customer summary、grand total、status、created time、return flags

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、permission denied、invalid filter

• Audit fields: request ID、user ID、account ID、site ID

slimweb.orders.get

• 狀態: Planned

• 權限: order read

• Scope: active site

• 用途: 讀取單一訂單完整摘要。

• Input: order ID

• Output: order detail、items、image snapshots、customer、payment、shipping、status logs、return eligibility

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: order not found、permission denied

• Audit fields: request ID、user ID、account ID、site ID、order ID

slimweb.orders.status.update

• 狀態: Planned

• 權限: order write

• Scope: active site

• 用途: 更新訂單狀態，例如待處理、已完成、退貨中、已退貨。

• Input: order ID、target status、reason、optional client note

• Output: updated order summary、status log、member total spent adjustment if any、audit ID

• Side effects: modifies order status and may update member total spent amount according to SlimWeb rules

• 是否需要 confirmation: yes

• 錯誤情境: invalid transition、order not found、permission denied、conflict

• Audit fields: request ID、user ID、account ID、site ID、order ID、old status、new status

slimweb.returns.list

• 狀態: Planned

• 權限: order read

• Scope: active site

• 用途: 列出退貨中與已退貨訂單。

• Input: status、date range、keyword、pagination

• Output: return order summaries、customer summary、grand total、return status、confirmed time

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、permission denied

• Audit fields: request ID、user ID、account ID、site ID

slimweb.returns.confirm

• 狀態: Planned

• 權限: order write

• Scope: active site

• 用途: 確認退貨，執行 returning -> returned，並套用 SlimWeb 會員消費總額調整規則。

• Input: order ID、reason、optional client note

• Output: updated return summary、member total spent adjustment、audit ID

• Side effects: changes order status、may reduce member total spent amount

• 是否需要 confirmation: yes

• 錯誤情境: order not found、order not returning、permission denied、conflict

• Audit fields: request ID、user ID、account ID、site ID、order ID

slimweb.members.list

• 狀態: Planned

• 權限: member read

• Scope: active site

• 用途: 列出會員，支援客服、行銷與訂單查詢。

• Input: keyword、tier、created date range、pagination、sort

• Output: member summaries、tier、total spent、coupon count、latest order summary

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、permission denied

• Audit fields: request ID、user ID、account ID、site ID

slimweb.members.get

• 狀態: Planned

• 權限: member read

• Scope: active site

• 用途: 讀取單一會員摘要。

• Input: member ID

• Output: member profile summary、tier、total spent、orders summary、available coupons

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: member not found、permission denied

• Audit fields: request ID、user ID、account ID、site ID、member ID

slimweb.members.coupons.issue

• 狀態: Planned

• 權限: member write + promotion write

• Scope: active site

• 用途: 手動發券給指定會員。

• Input: member ID、coupon template ID、quantity、optional expiry override、reason

• Output: issued coupon summary、member coupon count、audit ID

• Side effects: creates member coupon records

• 是否需要 confirmation: yes

• 錯誤情境: member not found、coupon template not found、inactive template、validation failed、permission denied

• Audit fields: request ID、user ID、account ID、site ID、member ID、coupon template ID、quantity

slimweb.coupon_templates.list

• 狀態: Planned

• 權限: promotion read

• Scope: active site

• 用途: 列出優惠券模板。

• Input: status、issue trigger、keyword、pagination

• Output: coupon template summaries、validity rules、threshold amount、active status

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、permission denied

• Audit fields: request ID、user ID、account ID、site ID

slimweb.coupon_templates.upsert

• 狀態: Planned

• 權限: promotion write

• Scope: active site

• 用途: 新增或更新優惠券模板。

• Input: optional coupon template ID、name、discount rule、issue trigger、validity rule、threshold amount、active status

• Output: coupon template summary、changed fields、audit ID

• Side effects: creates or modifies coupon template

• 是否需要 confirmation: yes when activating, changing discount value, or changing validity rule

• 錯誤情境: validation failed、template not found、permission denied、conflict

• Audit fields: request ID、user ID、account ID、site ID、coupon template ID、changed fields

slimweb.discount_codes.list

• 狀態: Planned

• 權限: promotion read

• Scope: active site

• 用途: 列出折扣碼。

• Input: status、keyword、platform、pagination

• Output: discount code summaries、ratio、platform、active status、usage summary

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、permission denied

• Audit fields: request ID、user ID、account ID、site ID

slimweb.discount_codes.upsert

• 狀態: Planned

• 權限: promotion write

• Scope: active site

• 用途: 新增或更新折扣碼。

• Input: optional discount code ID、code、ratio or amount、platform、active status、validity rule

• Output: discount code summary、changed fields、audit ID

• Side effects: creates or modifies discount code

• 是否需要 confirmation: yes when activating or changing discount value

• 錯誤情境: duplicate code、validation failed、discount code not found、permission denied、conflict

• Audit fields: request ID、user ID、account ID、site ID、discount code ID、changed fields

slimweb.member_tiers.list

• 狀態: Planned

• 權限: promotion read

• Scope: active site

• 用途: 列出會員等級、門檻、折抵百分比與各等級會員數。

• Input: none or pagination

• Output: member tier summaries、thresholds、discount percentages、member counts

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、permission denied

• Audit fields: request ID、user ID、account ID、site ID

slimweb.member_tiers.upsert

• 狀態: Planned

• 權限: promotion write

• Scope: active site

• 用途: 新增或更新會員等級。

• Input: optional tier ID、name、threshold amount、discount percentage、sort order

• Output: member tier summary、affected members estimate if available、audit ID

• Side effects: creates or modifies member tier and may affect future cart discount behavior

• 是否需要 confirmation: yes

• 錯誤情境: validation failed、tier not found、overlapping threshold、permission denied、conflict

• Audit fields: request ID、user ID、account ID、site ID、tier ID、changed fields

slimweb.threshold_gifts.list

• 狀態: Planned

• 權限: promotion read

• Scope: active site

• 用途: 列出滿額禮規則。

• Input: status、pagination

• Output: threshold gift summaries、threshold amount、gift product summary、active status

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、permission denied

• Audit fields: request ID、user ID、account ID、site ID

slimweb.threshold_gifts.upsert

• 狀態: Planned

• 權限: promotion write

• Scope: active site

• 用途: 新增或更新滿額禮規則。

• Input: optional threshold gift ID、threshold amount、gift product ID、active status

• Output: threshold gift summary、changed fields、audit ID

• Side effects: creates or modifies threshold gift behavior in cart and orders

• 是否需要 confirmation: yes when activating or changing gift product

• 錯誤情境: validation failed、gift product not found、threshold gift not found、permission denied、conflict

• Audit fields: request ID、user ID、account ID、site ID、threshold gift ID、changed fields

slimweb.product_add_ons.list

• 狀態: Planned

• 權限: promotion read

• Scope: active site

• 用途: 列出單品加購規則。

• Input: product ID、status、pagination

• Output: add-on summaries、main product、add-on product、add-on price、max quantity、active status

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、permission denied

• Audit fields: request ID、user ID、account ID、site ID

slimweb.product_add_ons.upsert

• 狀態: Planned

• 權限: promotion write

• Scope: active site

• 用途: 新增或更新單品加購規則。

• Input: optional add-on ID、main product ID、add-on product ID、add-on price、max quantity、active status

• Output: add-on summary、changed fields、audit ID

• Side effects: creates or modifies product add-on behavior on product page and cart

• 是否需要 confirmation: yes when activating or changing price

• 錯誤情境: product not found、invalid relation、validation failed、permission denied、conflict

• Audit fields: request ID、user ID、account ID、site ID、add-on ID、changed fields

slimweb.articles.list

• 狀態: Planned

• 權限: content read

• Scope: active site

• 用途: 列出文章，支援 AI 查詢既有內容或挑選要更新的文章。

• Input: status、keyword、category、pagination、sort

• Output: article summaries、status、published time、editable field hints

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、permission denied

• Audit fields: request ID、user ID、account ID、site ID

slimweb.articles.upsert

• 狀態: Planned

• 權限: content write

• Scope: active site

• 用途: 新增或更新文章內容。這不是頁面/版型工具，僅處理文章資料。

• Input: optional article ID、title、summary、body、status、category、published time、SEO fields

• Output: article summary、changed fields、preview URL if available、audit ID

• Side effects: creates or modifies article content

• 是否需要 confirmation: yes for publish、unpublish、or replacing customer-facing body content

• 錯誤情境: validation failed、article not found、permission denied、conflict

• Audit fields: request ID、user ID、account ID、site ID、article ID、changed fields

slimweb.faqs.list

• 狀態: Planned

• 權限: content read

• Scope: active site

• 用途: 列出 FAQ，讓 AI 可查詢既有問答。

• Input: status、keyword、category、pagination、sort

• Output: FAQ summaries、status、sort order、editable field hints

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、permission denied

• Audit fields: request ID、user ID、account ID、site ID

slimweb.faqs.upsert

• 狀態: Planned

• 權限: content write

• Scope: active site

• 用途: 新增或更新 FAQ。

• Input: optional FAQ ID、question、answer、category、status、sort order

• Output: FAQ summary、changed fields、audit ID

• Side effects: creates or modifies FAQ content

• 是否需要 confirmation: yes for publishing or destructive answer replacement

• 錯誤情境: validation failed、FAQ not found、permission denied、conflict

• Audit fields: request ID、user ID、account ID、site ID、FAQ ID、changed fields

slimweb.customer_service.logs.list

• 狀態: Planned

• 權限: customer service read

• Scope: active site

• 用途: 查詢 AI 客服紀錄，支援客服追蹤與品質檢查。

• Input: keyword、date range、customer identifier、pagination

• Output: log summaries、customer summary、message excerpts、resolution status、timestamps

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、permission denied、invalid filter

• Audit fields: request ID、user ID、account ID、site ID

slimweb.customer_service.settings.get

• 狀態: Planned

• 權限: customer service read

• Scope: active site

• 用途: 讀取 AI 客服設定摘要。

• Input: none or fields list

• Output: enabled status、response policy summary、knowledge source summary、handoff settings、editable field hints

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、permission denied

• Audit fields: request ID、user ID、account ID、site ID

slimweb.customer_service.settings.update

• 狀態: Planned

• 權限: customer service write

• Scope: active site

• 用途: 更新 AI 客服設定。

• Input: patch object for allowlisted customer service settings

• Output: updated settings summary、changed fields、warnings、audit ID

• Side effects: modifies customer service behavior

• 是否需要 confirmation: yes when enabling/disabling AI customer service or changing response policy

• 錯誤情境: validation failed、unsupported field、permission denied、conflict

• Audit fields: request ID、user ID、account ID、site ID、changed fields

slimweb.exports.create

• 狀態: Planned

• 權限: export read

• Scope: active site

• 用途: 建立會員、訂單或退貨資料匯出檔。

• Input: export type (members, orders, returns)、filters、format (xlsx, csv, sql)

• Output: export job ID、download URL if ready、expires at、row count if available

• Side effects: creates export job or file

• 是否需要 confirmation: yes for exports containing member personal data

• 錯誤情境: unsupported export type、permission denied、too many rows、export failed

• Audit fields: request ID、user ID、account ID、site ID、export type、export job ID

slimweb.assets.upload

• 狀態: Planned

• 權限: asset write

• Scope: active site

• 用途: 只有在 AI flow 明確需要保存圖片或檔案時，才建立 reusable asset。

• Input: file metadata、source reference、target usage、suggested filename、alt text

• Output: asset ID、URL、thumbnail URL、usage、alt text、audit ID

• Side effects: stores asset in SlimWeb-managed storage

• 是否需要 confirmation: replacing existing customer-facing asset 時需要

• 錯誤情境: unsupported file type、file too large、missing usage、unauthorized

• Audit fields: request ID、user ID、account ID、site ID、asset ID、usage

slimweb.audit.list

• 狀態: Planned

• 權限: audit read

• Scope: active site

• 用途: 列出近期 MCP tool execution 紀錄，支援追蹤、除錯與客服。

• Input: tool name、date range、actor user ID、result、pagination

• Output: audit entries、tool names、actors、targets、results、timestamps、request IDs

• Side effects: none

• 是否需要 confirmation: no

• 錯誤情境: missing active site、permission denied、invalid filter

• Audit fields: request ID、user ID、account ID、site ID

圖片與素材政策

AI Client 收到或引用的圖片預設是 reference-only。只有當 tool call 明確要求保存，且使用情境合理時，MCP Server 才應該把圖片寫入 SlimWeb reusable asset。

圖片相關 tools 建議使用下列欄位：

• image_usage: reference、product_image、brand_asset

• save_image: boolean

• asset_scope: site、product

• target: product 或 site 的 stable ID

• suggested_filename

• alt_text

頁面與版型相關素材會在 page/template tools 定義時再補充。

安全要求

• Remote MCP traffic 必須使用 HTTPS。

• 除非明確文件化為 public tool，所有 tool calls 都必須登入。

• 每次 tool call 都要做 authorization。

• MCP Server 不可暴露 SlimWeb secrets、database credentials、storage credentials。

• Write tools 必須有 server-side schema validation。

• 高影響 write tools 必須有 confirmation 機制。

• Tool execution 必須記錄 request ID、user ID、account ID、site ID、tool name、result、timestamp。

• Error message 要可供使用者修正問題，但不可洩漏內部實作細節。

錯誤模型

MCP tools 應回傳可預期的錯誤類型：

開發原則

• SlimWeb / Webless 是資料與商業規則的 source of truth。

• 優先做 structured tools，不做不受控的 free-form admin automation。

• 先做 read tools，再逐步加入窄範圍 write tools。

• Tool output 要穩定，讓 AI Client 可以可靠推理。

• Tool surface 要保持小，直到權限、audit、validation、rollback 行為可靠。

• 每次新增或改動 tool，都要更新這份 README。

Repo 狀態

此 repo 目前包含初版 MCP 架構文件，以及可部署到 Cloud Run 的最小 Remote MCP HTTP service。

目前服務入口：

• GET /healthz: Cloud Run health check / service metadata

• GET /readyz: readiness check

• POST /mcp: MCP JSON-RPC endpoint，目前支援 initialize 與 tools/list

目前 tools/list 回傳空陣列，因為上方 tools 仍是 planned contracts，尚未進入 MCP discovery。

Docker 與 Cloud Run 部署

本專案使用 Dockerfile 部署，不依賴 Cloud Run source deploy 自動偵測 runtime。

本機啟動：

npm test
PORT=8080 npm start

建立 image：

docker build -t slimweb-mcp:local .

Cloud Build / Cloud Run 設定：

• GCP project: webless-489821

• Region: asia-east1

• Cloud Run service: slimweb-mcp

• Artifact Registry repository: cloud-run-source-deploy

• Build config: cloudbuild.yaml

GitHub push 自動部署需要在 GCP 建立 Cloud Build Trigger，指向 ericchen1972/SlimWeb-MCP 的 main branch，並使用本 repo 的 cloudbuild.yaml。

初期部署使用 --no-allow-unauthenticated。等 Google Login 與 MCP auth 邊界完成後，再決定是否開放 public HTTPS entrypoint。

下一步

1. 建立 GCP Cloud Build Trigger，讓 main push 自動部署 slimweb-mcp。

2. 定義 Google Login callback、session model、token refresh 策略。

3. 將 planned tools 逐步接進 MCP discovery。

4. 實作 slimweb.auth.status、slimweb.sites.list、slimweb.site.select。

5. 建立 SlimWeb Backend Adapter，連接現有 Webless / SlimWeb application service 或 API。

6. 補上 authentication、permission、validation、error mapping 的 tests。

7. 每新增一個 tool，同步更新本 README 的 tool matrix 與 tool contract。