Welcome to MCP Docs

這是 GreenBox MCP (Model Context Protocol) 的使用文件。MCP 是一個將 AI 能力與業務流程自動化結合的工具協定。

本文件涵蓋內容

從設定到使用與開發的完整指南。歡迎貢獻與改進。

Where to Start

Quickstarts

快速開始使用 MCP 工具。透過實際範例學習如何呼叫 MCP Tools。

試用看看

Choose the Right MCP for You

了解不同 MCP 工具的使用場景與選擇建議。

查看選項

Explore Tools

瀏覽 MCP 工具庫。查看所有可用的 Tools 與整合方式。

查找工具

Build AI Functionality

MCP 支援建立 AI 功能與工具。直接在瀏覽器測試。

進階 AI

About MCP

MCP (Model Context Protocol) 是一個標準化的協定，讓 AI 模型能夠安全地與外部系統互動。在 GreenBox 系統中，我們實作了多個 MCP Tools 來處理訂單查詢、會員驗證等業務邏輯。

Architecture

MCP 採用 Client-Server 架構：

MCP Server: 運行在 http://localhost:5052/mcp，提供 Tools
MCP Client: AI 助手或測試頁面，透過 SSE 連線呼叫 Tools
Tools: 封裝業務邏輯的可呼叫函數

            ┌─────────────┐
│ AI Assistant│
└──────┬──────┘
       │ SSE
       ↓
┌─────────────┐      ┌──────────────┐
│ MCP Server  │─────→│  Database    │
│ /mcp        │      │  (SQL/Mongo) │
└──────┬──────┘      └──────────────┘
       │
       ↓
┌─────────────┐
│ MCP Tools   │
│ • Order     │
│ • Member    │
│ • ...       │
└─────────────┘
        

Quickstart

以下是使用 MCP 的基本步驟：

1. 連線到 MCP Server

            const eventSource = new EventSource('http://localhost:5052/mcp');

eventSource.addEventListener('endpoint', (event) => {
    console.log('MCP Server 已就緒');
});
        

2. 呼叫 Tool

            // 查詢會員最新訂單
const request = {
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
        name: "query_orders_by_mobile",
        arguments: {
            lineId: "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            mobile: "0935921058"
        }
    }
};

fetch('http://localhost:5052/mcp', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(request)
});
        

3. 處理回應

            eventSource.addEventListener('message', (event) => {
    const response = JSON.parse(event.data);
    
    if (response.result) {
        const toolResult = JSON.parse(response.result.content[0].text);
        console.log('最新 10 筆訂單:', toolResult.orders);
        // 顯示訂單編號、產品名稱、訂單時間、金額、付款狀態
    }
});
        

立即試用

Available Tools

點擊下方卡片查看詳細的 Tool 使用文件：

Basic Info Tool

伺服器時間查詢與訊息回應功能

查看文件

Order Query Tool

訂單查詢與管理功能

查看文件

Member Auth Tool

會員驗證與 Session 管理

查看文件

SMS Tools

簡訊發送、驗證碼與會員綁定

查看文件

RAG Search Tool New

企業知識庫 RAG 問答，支援 6 種分類搜尋

查看文件

Consumption Ranking New

月度消費 PR 排行榜查詢

查看文件

Consumption Analysis New

消費分析與購物人格分類

查看文件

Game Tools New

小遊戲管理 (開始遊戲、次數限制、歷史紀錄、獎品發送)

查看文件

Quick Overview

所有可用的 MCP Tools 簡介。點擊上方卡片查看詳細文件。

Tool Category	主要功能	Tools 數量
Basic Info	伺服器時間查詢、訊息回應測試	2 tools
Order Query	訂單查詢與管理 (訂單編號/手機號碼查詢最新訂單)	2 tools
Member Auth	會員登入驗證、Session 管理、LINE ID 綁定查詢	5 tools
SMS Tools	簡訊發送、驗證碼驗證、會員 LINE 綁定	9 tools (3 categories)
RAG Search New	企業知識庫 RAG 問答 (6 分類: 客服、生鮮、系統、物流、促銷、品牌)	1 tool
Consumption Ranking New	月度消費 PR 值排行榜 (需 LINE 綁定會員)	1 tool
Consumption Analysis New	消費分析與購物人格分類 (新手爸媽/健康模範生/效率養生族/肉食健身族/便利速食族)	2 tools
Game Tools New	小遊戲管理 (開始遊戲、次數限制、歷史紀錄、獎品發送)	8 tools
Red Point Query New	紅利點數查詢 (餘額查詢、異動紀錄、即將到期點數)	1 tool

Authentication

RAG Search Tool New

search_knowledge_base 是企業知識庫 RAG 問答工具，使用 Google Gemini File Search API 進行智慧問答。支援 6 個知識分類，可單選或多選搜尋。

Tool 名稱

search_knowledge_base

參數說明

參數	類型	必填	說明
`query`	string	✅	問題內容
`categories`	string	❌	分類代碼，多個用逗號分隔。不填則搜尋所有分類

可用分類

分類代碼	中文名稱	說明
`customer_service`	客服對話	客服相關知識與對話範例
`fresh_product`	生鮮產品與料理	生鮮產品知識、保存方式與料理教學
`system_operation`	系統操作	系統操作說明與使用指南
`shipping`	物流配送	物流配送相關知識與常見問題
`promotion`	促銷活動	促銷活動規則與說明
`brand`	品牌相關	公司文化、理念、品牌使命願景

呼叫範例

            // 搜尋單一分類
const request = {
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
        name: "search_knowledge_base",
        arguments: {
            query: "如何處理退貨問題？",
            categories: "customer_service"
        }
    }
};

// 搜尋多個分類
const request2 = {
    jsonrpc: "2.0",
    id: 2,
    method: "tools/call",
    params: {
        name: "search_knowledge_base",
        arguments: {
            query: "牛排的最佳料理方式？",
            categories: "fresh_product,customer_service"
        }
    }
};

// 搜尋所有分類 (不指定 categories)
const request3 = {
    jsonrpc: "2.0",
    id: 3,
    method: "tools/call",
    params: {
        name: "search_knowledge_base",
        arguments: {
            query: "公司的配送範圍有哪些？"
        }
    }
};
        

回傳格式

            {
    "success": true,
    "query": "如何處理退貨問題？",
    "answer": "根據我們的退貨政策，您可以在收到商品後 7 天內申請退貨...",
    "sources": [
        {
            "fileName": "退貨政策.pdf",
            "displayName": "退貨政策.pdf",
            "chunkText": "退貨須於收到商品後 7 日內提出申請...",
            "segments": [
                {
                    "text": "您可以在收到商品後 7 天內申請退貨",
                    "startIndex": 12,
                    "endIndex": 45
                }
            ]
        }
    ],
    "tokensUsed": 856,
    "categoriesSearched": ["customer_service"],
    "elapsedMs": 1234,
    "timestamp": "2025-11-28T15:30:00"
}
        

錯誤處理

分類不存在時

如果指定的分類尚未建立知識庫（FileSearchStore），會回傳錯誤訊息並列出有效的分類清單。

            // 錯誤回傳範例
{
    "success": false,
    "error": "指定的分類尚未建立知識庫: invalid_category",
    "invalidCategories": ["invalid_category"],
    "availableCategories": ["customer_service", "fresh_product", ...],
    "elapsedMs": 150,
    "timestamp": "2025-11-28T15:30:00"
}
        

效能說明

Store 快取: 分類對應的 Store 名稱會快取 60 分鐘，減少 API 呼叫
查詢時間: elapsedMs 欄位顯示完整查詢時間（毫秒）
Token 使用: tokensUsed 欄位顯示 Gemini API 消耗的 Token 數

測試 RAG Search

Consumption Ranking Tool New

GetMonthlyConsumptionRanking 是月度消費排行 PR 值查詢工具。需要會員先完成 LINE ID 綁定（透過 SMS 驗證），才能查詢消費排行。

前置條件：LINE ID 綁定

此工具需要使用者先透過 send_verification_code 和 verify_line_member_binding 完成 LINE ID 與會員手機的綁定。

Tool 名稱

GetMonthlyConsumptionRanking

參數說明

參數	類型	必填	說明
`lineId`	string	✓	LINE User ID (需已綁定會員)

PR 等級說明

根據消費金額在所有消費者中的排名百分位數，分為以下等級：

PR 等級	百分位數範圍	稱號	圖示
`PR99`	≥ 99%	頂尖消費者	🏆
`PR95`	≥ 95%	超級消費者	🥇
`PR90`	≥ 90%	高級消費者	🥈
`PR80`	≥ 80%	資深消費者	🥉
`PR70`	≥ 70%	優質消費者	⭐
`PR60`	≥ 60%	活躍消費者	✨
`PR50`	< 60% 或無消費	消費者	👍

使用範例

            // 查詢月度消費排行
const request = {
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
        name: "GetMonthlyConsumptionRanking",
        arguments: {
            lineId: "U1234567890abcdef..."
        }
    }
};
        

回傳格式 (有消費記錄)

            {
    "success": true,
    "hasConsumption": true,
    "yearMonth": "2025-05",
    "mobile": "0912****56",
    "consumption": {
        "totalAmount": 15680,
        "formattedAmount": "NT$ 15,680"
    },
    "ranking": {
        "prValue": 80,
        "prLabel": "PR80",
        "prEmoji": "🥉",
        "prDescription": "資深消費者",
        "beatPercentage": 80,
        "message": "您勝過了 80% 的消費者！"
    },
    "statistics": {
        "rankPosition": 156,
        "totalMembers": 782,
        "percentile": 80.05
    },
    "fromCache": false,
    "timestamp": "2025-06-09T10:30:00"
}
        

回傳格式 (無消費記錄)

            {
    "success": true,
    "hasConsumption": false,
    "message": "您在 2025-05 沒有消費記錄",
    "yearMonth": "2025-05",
    "mobile": "0912****56",
    "timestamp": "2025-06-09T10:30:00"
}
        

錯誤處理

LINE ID 未綁定

如果 LINE ID 尚未綁定會員或綁定已過期，會回傳錯誤並提示用戶進行綁定。

            // 錯誤回傳範例
{
    "success": false,
    "message": "此 LINE ID 尚未綁定會員或綁定已過期。請先透過 SMS 驗證綁定會員身份。",
    "hint": "請先使用「會員手機驗證」功能綁定您的會員身份",
    "timestamp": "2025-06-09T10:30:00"
}
        

快取機制

永久快取: 每個會員每月的消費排行會永久儲存在 MongoDB
快取識別: 以 memberId + yearMonth 為唯一鍵值
fromCache 標記: 回傳結果中的 fromCache 欄位指示是否來自快取

排除條件

已取消訂單: states = '4' 的訂單不計入
嬰兒用品訂單: IsBaby = 1 的訂單不計入

Consumption Analysis Tool New

GetConsumptionAnalysis 是消費分析與購物人格分類工具。需要會員先完成 LINE ID 綁定（透過 SMS 驗證），分析過去 3 個月的消費記錄並分類為購物人格。

前置條件：LINE ID 綁定

此工具需要使用者先透過 send_verification_code 和 verify_line_member_binding 完成 LINE ID 與會員手機的綁定。

Tool 名稱

GetConsumptionAnalysis

參數說明

參數	類型	必填	說明
`lineUserId`	string	✓	LINE User ID (需已綁定會員)
`forceRefresh`	boolean	✗	是否強制重新計算（預設 false，使用快取）

購物人格說明

根據消費分類佔比，會員可能被分配一個或多個購物人格標籤：

人格代碼	中文名稱	判定條件	圖示
`nurturing_parent`	新手爸媽	有購買嬰兒產品 (Type=9 粥寶寶)	👶
`balanced_achiever`	健康模範生	(蔬果乾貨+產地直送) / 總金額 > 50%	🥗
`efficient_health`	效率養生族	益菓保 / 總金額 > 40%	💊
`protein_focused`	肉食健身族	生鮮肉舖 / 總金額 > 50%	🥩
`convenience_seeker`	便利速食族	無明顯偏好或偏好加工即食	🍱

分類代碼對應

Type 代碼	分類名稱
`0`	產地直送
`2`	蔬果乾貨
`7`	生鮮肉舖
`9`	粥寶寶
`11`	益菓保

使用範例

            // 查詢消費分析與購物人格
const request = {
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
        name: "GetConsumptionAnalysis",
        arguments: {
            lineUserId: "U1234567890abcdef...",
            forceRefresh: false
        }
    }
};
        

回傳格式

            {
    "success": true,
    "cached": false,
    "data": {
        "memberId": 12345,
        "mobile": "0912****56",
        "analysisMonth": "202512",
        "periodStart": "2025-09-01",
        "periodEnd": "2025-12-01",
        "totalAmount": 25680,
        "totalOrders": 15,
        "categoryAmounts": {
            "0": 8500,
            "2": 6200,
            "7": 5980,
            "11": 3000,
            "9": 2000
        },
        "categoryPercentages": {
            "0": 33.1,
            "2": 24.14,
            "7": 23.29,
            "11": 11.68,
            "9": 7.79
        },
        "personalityTags": ["nurturing_parent", "balanced_achiever"],
        "primaryPersonality": "nurturing_parent",
        "personalityNames": {
            "nurturing_parent": "新手爸媽",
            "balanced_achiever": "健康模範生"
        },
        "hasBabyProducts": true,
        "updatedAt": "2025-12-01 10:30:00"
    }
}
        

購物人格說明工具

另有 GetShoppingPersonalityInfo 工具可取得完整的購物人格說明：

            // 取得購物人格說明
const request = {
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
        name: "GetShoppingPersonalityInfo",
        arguments: {}
    }
};
        

快取機制

月度快取: 每個會員每月的分析結果會儲存在 MongoDB
快取識別: 以 memberId + analysisMonth 為唯一鍵值
強制更新: 傳入 forceRefresh: true 可重新計算
滾動期間: 分析期間為過去 3 個月的消費資料

排除條件

已取消訂單: States = '4' 的訂單不計入

Game Tools New

Game Tools 提供 LINE Bot 小遊戲功能，包含開始遊戲、次數限制查詢、遊戲歷史紀錄、獎品發送等 8 個 MCP 工具。目前支援的遊戲類型：吃角子老虎 (slot-machine)

前提條件

玩家必須先完成 LINE ID 綁定手機號碼，才能參與小遊戲。每種遊戲每日有次數限制（預設 3 次）。

Game Tools 一覽

Tool Name	功能說明	主要參數
`StartGame`	開始遊戲，建立 Session 並回傳遊戲連結	`lineId`, `gameType`
`CheckDailyLimit`	查詢玩家今日剩餘遊戲次數	`lineId`, `gameType`
`GetGameHistory`	查詢玩家的遊戲歷史紀錄	`lineId`, `gameType`, `limit`
`GetAvailableGames`	取得目前可用的小遊戲列表	(無必填參數)
`StartGameFlow`	遊戲流程入口 (驗證 + 遊戲列表 + 剩餘次數)	`lineId`
`GetGameResult`	查詢遊戲結果	`sessionId`
`GetPendingPrizes`	查詢玩家待領取的獎品	`lineId`
`SendGamePrize`	發送獎品給玩家	`sessionId`

1. StartGame - 開始遊戲

為玩家建立遊戲 Session 並回傳遊戲連結。

            // 開始遊戲
const request = {
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
        name: "StartGame",
        arguments: {
            lineId: "U1234567890abcdef...",
            gameType: "slot-machine"
        }
    }
};
        

            // 回傳範例
{
    "success": true,
    "message": "遊戲連結已建立，請點擊連結開始遊戲",
    "data": {
        "gameUrl": "https://enzo-gb.net/htmls/games/game-slot-machine.html?session=abc123",
        "sessionId": "abc123",
        "expiresAt": "2025-06-14 15:30:00",
        "expiresInMinutes": 10,
        "instruction": "請在 10 分鐘內點擊連結開始遊戲，逾時連結將失效"
    },
    "timestamp": "2025-06-14 15:20:00"
}
        

2. CheckDailyLimit - 查詢每日剩餘次數

查詢玩家今日剩餘的遊戲次數。

            // 查詢每日限制
const request = {
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
        name: "CheckDailyLimit",
        arguments: {
            lineId: "U1234567890abcdef...",
            gameType: "slot-machine"
        }
    }
};
        

            // 回傳範例
{
    "success": true,
    "message": "您今天還可以玩 2 次",
    "data": {
        "gameType": "slot-machine",
        "dailyLimit": 3,
        "playedToday": 1,
        "remainingToday": 2,
        "canPlay": true
    },
    "timestamp": "2025-06-14 15:20:00"
}
        

3. GetGameHistory - 查詢遊戲歷史

查詢玩家的遊戲歷史紀錄，包含遊戲結果和中獎資訊。

            // 查詢遊戲歷史
const request = {
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
        name: "GetGameHistory",
        arguments: {
            lineId: "U1234567890abcdef...",
            gameType: "slot-machine",  // 可選
            limit: 10  // 可選，預設 10 筆
        }
    }
};
        

            // 回傳範例
{
    "success": true,
    "message": "共找到 5 筆遊戲紀錄",
    "data": {
        "records": [
            {
                "gameType": "slot-machine",
                "isWin": true,
                "prizeName": "購物金 50 元",
                "status": "completed",
                "displayResult": "🎰 7️⃣7️⃣7️⃣ → 恭喜中獎！",
                "playedAt": "2025-06-14 15:10:00"
            }
        ],
        "totalCount": 5,
        "completedCount": 5,
        "winCount": 2,
        "winRate": "40.0%"
    },
    "timestamp": "2025-06-14 15:20:00"
}
        

4. GetAvailableGames - 取得遊戲列表

取得目前可用的小遊戲列表和說明。

            // 取得遊戲列表
const request = {
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
        name: "GetAvailableGames",
        arguments: {}
    }
};
        

            // 回傳範例
{
    "success": true,
    "message": "共有 1 個遊戲開放中",
    "data": {
        "games": [
            {
                "gameType": "slot-machine",
                "displayName": "幸運吃角子老虎",
                "description": "轉動輪盤試試手氣！",
                "dailyLimit": 3,
                "prizeName": "購物金 50 元",
                "prizeDescription": "可折抵消費",
                "prizeType": "credit",
                "prizeAmount": 50,
                "winProbabilityDisplay": "10.0%"
            }
        ]
    },
    "timestamp": "2025-06-14 15:20:00"
}
        

5. StartGameFlow - 遊戲流程入口 (推薦)

推薦使用：一步取得玩家可玩遊戲的完整資訊。自動驗證 LINE ID 是否已綁定手機、取得所有可用遊戲、計算各遊戲今日剩餘次數。

            // 遊戲流程入口
const request = {
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
        name: "StartGameFlow",
        arguments: {
            lineId: "U1234567890abcdef..."
        }
    }
};
        

            // 回傳範例
{
    "success": true,
    "message": "您好 王小明！目前有 1 個遊戲開放中，您還可以玩 1 種遊戲",
    "data": {
        "isBound": true,
        "playerName": "王小明",
        "playerId": "12345",
        "mobile": "0912345678",
        "games": [
            {
                "gameType": "slot-machine",
                "displayName": "幸運吃角子老虎",
                "description": "轉動輪盤試試手氣！",
                "dailyLimit": 3,
                "remainingToday": 2,
                "canPlay": true,
                "prizeName": "購物金 50 元",
                "prizeAmount": 50,
                "prizeType": "credit"
            }
        ],
        "playableCount": 1,
        "nextStep": "請選擇要玩的遊戲"
    },
    "timestamp": "2025-06-14 15:20:00"
}
        

6. GetGameResult - 查詢遊戲結果

查詢遊戲完成後的詳細結果，供 LINE Bot 主動通知玩家。

            // 查詢遊戲結果
const request = {
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
        name: "GetGameResult",
        arguments: {
            sessionId: "abc123"
        }
    }
};
        

            // 回傳範例 (中獎)
{
    "success": true,
    "message": "🎉 恭喜中獎！獲得「購物金 50 元」",
    "data": {
        "sessionId": "abc123",
        "gameType": "slot-machine",
        "status": "completed",
        "isWin": true,
        "displayResult": "🎰 7️⃣7️⃣7️⃣ → 恭喜中獎！",
        "prize": {
            "type": "credit",
            "name": "購物金 50 元",
            "amount": 50,
            "description": "可折抵消費"
        },
        "prizeSent": false,
        "completedAt": "2025-06-14 15:15:00"
    },
    "timestamp": "2025-06-14 15:20:00"
}
        

7. GetPendingPrizes - 查詢待領獎品

查詢玩家所有待領取的獎品清單。

            // 查詢待領獎品
const request = {
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
        name: "GetPendingPrizes",
        arguments: {
            lineId: "U1234567890abcdef..."
        }
    }
};
        

            // 回傳範例
{
    "success": true,
    "message": "您有 1 個獎品待領取",
    "data": {
        "prizes": [
            {
                "sessionId": "abc123",
                "gameType": "slot-machine",
                "prizeName": "購物金 50 元",
                "prizeType": "credit",
                "prizeAmount": 50,
                "wonAt": "2025-06-14 15:15:00"
            }
        ],
        "count": 1
    },
    "timestamp": "2025-06-14 15:20:00"
}
        

8. SendGamePrize - 發送獎品

發送遊戲獎品給玩家。目前功能開發中，會記錄發獎請求，實際發獎需人工處理。

            // 發送獎品
const request = {
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
        name: "SendGamePrize",
        arguments: {
            sessionId: "abc123"
        }
    }
};
        

遊戲流程建議

LINE Bot 整合小遊戲的推薦流程：

使用者說「我要玩遊戲」 → 呼叫 StartGameFlow
驗證通過，顯示遊戲選單 → 根據回傳的 games 列表顯示
使用者選擇遊戲 → 呼叫 StartGame
回傳遊戲連結 → 使用者點擊進入遊戲頁面
遊戲完成 → 呼叫 GetGameResult 取得結果
中獎通知 → 呼叫 SendGamePrize 發送獎品

錯誤處理

錯誤情境	回傳訊息
未綁定手機	您尚未綁定手機號碼，請先完成手機驗證後再參加遊戲
今日次數已用完	您今天的遊戲次數已用完，明天再來吧！
遊戲連結過期	遊戲連結已過期（10 分鐘）
Session 不存在	找不到此遊戲 Session

Red Point Query (紅利點數查詢)

查詢會員紅利點數餘額、異動紀錄、即將到期點數等資訊。此功能需要會員已完成 LINE 綁定。

紅利點數查詢功能

餘額查詢：查看目前可用紅利點數
異動紀錄：查詢最近一個月的點數變動
即將到期：查看未來 30 天內即將到期的點數

query_redpoint_balance

查詢會員紅利點數餘額與相關資訊。

Parameters

參數	類型	必填	說明
`lineId`	string	是	會員的 LINE User ID，用於查詢綁定的會員資料

Response 範例

{
  "success": true,
  "data": {
    "memberInfo": {
      "memberId": 12345,
      "mobile": "0935****58"
    },
    "balance": {
      "availableBalance": 150,
      "totalEarned": 500,
      "totalUsed": 300,
      "expiredPoints": 50
    },
    "recentHistory": [
      {
        "date": "2025-01-15",
        "description": "購物回饋",
        "points": 50,
        "type": "earn"
      },
      {
        "date": "2025-01-10",
        "description": "折抵消費",
        "points": -30,
        "type": "use"
      }
    ],
    "expiringPoints": [
      {
        "expiryDate": "2025-02-15",
        "points": 20
      }
    ]
  }
}

Response 欄位說明

欄位	類型	說明
memberInfo - 會員基本資訊
`memberId`	number	會員編號
`mobile`	string	手機號碼（中間 4 碼以 * 遮罩保護隱私）
balance - 紅利點數餘額統計
`availableBalance`	number	目前可用紅利點數，這是會員實際可以使用的點數餘額
`totalEarned`	number	歷史累計獲得的總點數（含已使用、已過期）
`totalUsed`	number	歷史累計已使用（折抵）的總點數
`expiredPoints`	number	歷史累計已過期作廢的總點數
recentHistory - 最近異動紀錄（近一個月）
`date`	string	異動日期 (YYYY-MM-DD)
`description`	string	異動說明（如：購物回饋、折抵消費、活動贈點）
`points`	number	異動點數（正數=獲得，負數=扣除）
`type`	string	異動類型：`earn`=獲得點數，`use`=使用點數
expiringPoints - 即將到期點數（未來 30 天）
`expiryDate`	string	到期日期 (YYYY-MM-DD)
`points`	number	該日期將到期的點數

點數計算公式

availableBalance ≈ totalEarned - totalUsed - expiredPoints
（實際餘額以 availableBalance 為準）

錯誤處理

錯誤訊息	說明
`找不到會員資料，此 LINE 帳號尚未綁定會員`	LINE ID 尚未與會員帳號綁定
`查詢紅利點數時發生錯誤`	系統內部錯誤，請稍後再試

注意事項

此 Tool 僅供已綁定 LINE 的會員使用
手機號碼會以遮罩方式顯示以保護隱私
異動紀錄預設顯示最近一個月內的資料

Authentication (原有內容)

某些 MCP Tools 需要會員驗證才能使用。使用 authenticate_member 取得 Session Token 後，將 Token 傳遞給需要驗證的 Tools。

Session Token 有效期

Session Token 有效期為 30 分鐘。過期後需重新登入。

Testing

我們提供多個測試頁面方便開發與測試：

簡易測試工具

基本的 MCP 連線與工具呼叫測試

完整測試工具

進階功能測試，包含所有 Tools

訂單查詢測試

專門測試訂單查詢相關功能

會員驗證測試

測試會員登入與 Session 管理

SMS 工具測試

測試簡訊發送與驗證碼功能

會員驗證與綁定測試

測試 SMS 會員驗證與 LINE ID 綁定功能

安全驗證測試

測試 MCP 安全機制與頻率限制功能

會員訂單查詢測試

測試根據手機號碼查詢最新 10 筆訂單功能

RAG 知識庫搜尋測試 New

測試企業知識庫 RAG 問答功能

Integration

MCP 可以整合到各種 AI 應用中。以下是一些常見的整合方式：

整合到 AI 聊天機器人

            // 當使用者詢問訂單時
if (userMessage.includes('我的訂單') || userMessage.includes('查詢訂單')) {
    // 查詢會員最新 10 筆訂單
    const result = await callMCPTool('query_orders_by_mobile', {
        lineId: userLineId,
        mobile: userMobile
    });
    
    if (result.success && result.orders.length > 0) {
        let response = `您最近的訂單:\n`;
        result.orders.forEach(order => {
            response += `• ${order.name} - NT$ ${order.totalPrice} (${order.paymentStatus})\n`;
        });
        return response;
    }
}
        

查詢會員消費統計

            // 當使用者詢問消費記錄或統計時
if (userMessage.includes('消費') || userMessage.includes('花了多少')) {
    // 查詢會員消費統計
    const result = await callMCPTool('query_member_stats_by_mobile', {
        lineId: userLineId,
        mobile: userMobile
    });
    
    if (result.success) {
        const stats = result.statistics;
        return `📊 您的消費統計:\n` +
               `• 總訂單數: ${stats.totalOrders} 筆\n` +
               `• 總消費金額: NT$${stats.totalAmount.toLocaleString()}\n` +
               `• 已付款: NT$${stats.paidAmount.toLocaleString()}\n` +
               `• 待付款: NT$${stats.unpaidAmount.toLocaleString()}\n` +
               `• 平均訂單金額: NT$${stats.averageOrderAmount.toLocaleString()}`;
    }
}
        

整合到客服系統

客服人員可以透過 MCP 快速查詢客戶訂單、驗證會員身份等。

相關文件

最後更新: 2025-11-28 | 維護者: Development Team