MCP 接入交付包（給第三方電商）

本頁是給第三方電商／業務平台透過 Model Context Protocol（MCP） 接入 Webnav.ai 的交付清單：明確列出 Webnav.ai 提供什麼、你需要交付什麼、需要拍板的決策，以及上線驗收清單。

完整通訊協議與逐欄位的工具規格，請見 MCP 接入指南。本頁是接入總覽，那頁是參考手冊。

MCP 模式為 Enterprise 專屬功能。

---

運作方式（一張圖）

訪客 → Widget → Webnav.ai ──JSON-RPC 2.0 over HTTPS──► 你的 MCP 伺服器
                            ◄────────────────────────── （工具結果）

你只需暴露一個 HTTP 端點，使用 JSON-RPC 2.0。Webnav.ai 是 MCP 用戶端，你是 MCP 伺服器。Webnav 只呼叫三個方法：initialize、tools/list、tools/call。你不需要回呼我們。

---

1. Webnav.ai 提供給你的

項目	說明
協議規範	MCP 接入指南——握手、工具發現、工具呼叫通訊格式、錯誤碼。
Canonical 工具契約	Webnav 原生理解的 5 個標準工具（見下）。可全做或做子集。
參考實作	examples/mcp_server.py（獨立，連接埠 4100）與演示商城整合的 /mcp（examples/shop/shop_server.py，連接埠 4000）——可直接照抄的起點。
測試連接工具	後台 → AI Actions → MCP → 測試連接。我們經後端對你的端點發 initialize + tools/list，並顯示發現的工具與 annotations。瀏覽器永不直連你的端點。
SSRF 安全代理	所有對你端點的呼叫都經我們後端，後端會 pin 解析到的 IP 並拒絕私網／loopback／metadata 位址。
確認流	寫操作在執行前會向訪客彈出確認卡——全部由 Webnav 處理，你方無需開發。
呼叫日誌	後台 → AI Actions → 呼叫日誌，記錄每次工具呼叫（名稱、脫敏參數、狀態、延遲、錯誤）。
錯誤歸一化	傳輸／協議層失敗統一映射為穩定的 MCP_* 碼（見指南）。

---

2. 你需要交付給 Webnav.ai 的

完成接入，請回交以下四項：

1. MCP 端點 URL——單一 HTTPS URL，例如 https://mcp.yourshop.com/mcp。
2. 工具清單——你實作了哪些 canonical 工具（以及任何自訂工具）。
3. 鑑權標頭（若有）——標頭名稱與 token 取得方式。Webnav 按域名儲存並逐請求轉發。
4. 沙箱／測試存取——測試環境 + 範例資料（商品、一個測試訂單號），供我們在上線前跑測試連接與一筆端到端下單。

硬性要求

要求	原因
HTTPS、公網主機	我們會 pin 解析 IP 並拒絕私網／loopback（SSRF 防護）。http://localhost 僅在本地開發且設 ACTIONS_ALLOW_INSECURE=true 時可用。
initialize 回傳受支援的 protocolVersion	用 2024-11-05（也接受 2025-03-26、2025-06-18）。其他值仍可用，但會觸發 versionMismatch 警告。
inputSchema 為 JSON Schema 物件（"type": "object"）	否則我們會把它重設為空 schema，模型將拿不到你的參數。
寫操作具冪等性	我們只發一次已確認的呼叫，但網路重試可能發生。create_order / create_refund 要設計成收到兩次也安全（用冪等鍵）。
list_products 回傳真實商品目錄	我們在彈確認卡前會以它校驗每個 SKU。未知 SKU 會被拒絕，不會下單。
標記寫操作	在下單／退款／取消／支付類工具上設 annotations.destructiveHint: true（見下方確認模型）。

---

3. Canonical 工具（契約）

工具	類型	需確認	用途
list_products	讀	否	回傳目錄供 SKU 校驗 + 商品卡
query_order	讀	否	按 order_id 查訂單狀態／詳情
query_logistics	讀	否	按 order_id 查物流
create_order	寫	是	下單——所有商品放進一個 items[] 一次提交
create_refund	寫	是	按 order_id 發起退款

回傳格式——回傳 canonical { ok, data, display }（卡片更豐富）或標準 MCP { content, isError } 區塊。業務錯誤用 { ok: false, error_code, message }，採用描述性碼（ORDER_NOT_FOUND、OUT_OF_STOCK、SKU_NOT_FOUND）。完整欄位規格與 JSON 範例見 MCP 接入指南 → 工具規格。

確認模型（重要）

Webnav 以三個訊號 OR 來決定是否彈確認卡——寫操作絕不會被意外略過：

1. annotations.destructiveHint: true（你自報），或
2. 工具名匹配 create_* / refund_* / cancel_* / pay_*，或
3. 該工具在商家於後台配置的 確認工具 清單中。

所以即使你忘了打 annotation，create_order 仍會確認。反之，讀工具（readOnlyHint: true）直接呼叫、不彈卡。

---

4. 接入問題清單

你（接入方）在開發前／中需要拍板的決策，逐項勾掉。

端點與協議

• [ ] 端點 URL + 路徑（單一 JSON-RPC HTTP 端點）。
• [ ] initialize 回傳的 protocolVersion（建議 2024-11-05）。
• [ ] serverInfo.name / version。

工具與 schema

• [ ] 實作哪些 canonical 工具（全 5 個或子集）？
• [ ] 每個 inputSchema 皆為 type: "object"。
• [ ] create_order 接受多商品 items[] 陣列（一次呼叫、一張卡）。

確認與 annotations

• [ ] 寫工具帶 destructiveHint: true；讀工具帶 readOnlyHint: true。
• [ ] 設定 title 作為確認卡的友善標籤。

回傳與錯誤

• [ ] canonical {ok,data,display} 或 MCP content 區塊——擇一。
• [ ] 定義業務錯誤碼（ORDER_NOT_FOUND、OUT_OF_STOCK…）。

鑑權與安全

• [ ] 鑑權標頭——是否逐請求校驗 bearer token / API key？
• [ ] 是否需要訪客身份（如「我的訂單」）？若需要，user token 如何傳遞／校驗？
• [ ] 寫工具冪等（冪等鍵策略）？
• [ ] 已確認 HTTPS + 公網主機。

多租戶與資料

• [ ] 若一個端點服務多個 Webnav 域名／商家，如何隔離（標頭帶 per-tenant token）？
• [ ] 讀工具（query_order 等）讀的是真實訂單資料，非模擬儲存。

---

5. 接入步驟

1. 建端點。 實作 POST /mcp，分發 initialize / tools/list / tools/call，包裝你既有的訂單／目錄邏輯——參考 examples/shop/shop_server.py，其 /mcp 端點與店面共用同一份訂單儲存。
2. 自測通訊協議 用 curl（握手／發現／呼叫）——見指南。
3. 部署 於公網 HTTPS 後。如使用鑑權標頭，加上校驗。
4. 後台配置： AI Actions → 模式 = MCP → 填入端點 → 加鑑權標頭 → 保存，再點測試連接（須列出你的工具）。在 確認工具 勾選寫操作。
5. 端到端測試 於線上 widget：讓 AI 瀏覽、下單（確認卡 → 提交）、查物流、退款。確認訂單落到你的真實系統。

操作順序很重要：先保存、再測試連接——探測讀取的是「已保存」的端點，而非輸入框裡尚未保存的值。

---

6. 上線驗收清單

• [ ] 測試連接列出全部預期工具與正確 annotations，無 versionMismatch。
• [ ] list_products 回傳線上目錄；非法 SKU 在下單前被拒。
• [ ] 多商品 create_order 只產生一張確認卡與一筆訂單。
• [ ] query_order / query_logistics 反映真實系統狀態。
• [ ] create_refund 具冪等性並反映到你的系統。
• [ ] 鑑權標頭已校驗；未鑑權呼叫被拒。
• [ ] 端點為公網 HTTPS；私網位址被拒。
• [ ] 呼叫日誌顯示成功呼叫且延遲正常。

全部勾選後，接入即達生產就緒。