# Dboard MCP Server - 真平語文與客戶責任區域查詢系統

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
[![Playwright](https://img.shields.io/badge/Playwright-Automated-red.svg)](https://playwright.dev/)

本專案為 **真平語文 Dashboard (https://dboard.jen-pin.com.tw/)** 的 Model Context Protocol (MCP) Server 與本地快速查詢系統。

讓 AI 助手（如 **Antigravity**, **Claude Desktop**, **Cowork**）能直接查詢真平語文網站中的即時與快取數據，包括：
1. **經銷商與客戶責任區域查詢**（依經銷商名稱、客戶編號、縣市或行政區查詢）
2. **多學制與語言版本切換**（國小台語、國中台語、高中台語、國小客語、國中客語、高中客語）
3. **班級數統計與訂量數據**（各版本真平班級數、實際班級數與預估訂量）
4. **線上即時爬蟲與資料自動同步**

---

## 🛠️ MCP Tools 工具清單

| 工具名稱 | 說明 | 範例查詢 |
|---|---|---|
| query_customer_areas | 查詢經銷商/客戶所負責的責任行政區域 | 查詢「環華」、「大漢」、「大安區」、「板橋」 |
| list_all_customers | 列出所有經銷商與責任區域數量總覽清單 | 列出所有經銷商列表 |
| switch_system_level | 切換學制與語言版本 (國小/國中/高中、台語/客語) | 切換至「高中台語」 |
| get_class_statistics | 擷取目前版本的班級數與訂量統計表 | 查詢「班級數統計」、「實際班級數」、「訂量統計」 |
| search_dboard | 綜合搜尋經銷商責任區域、版本與統計資訊 | 搜尋「國中台語 大漢」 |
| sync_live_data | 從網站線上重新爬取並同步最新經銷商責任區域資料 | 重新同步最新線上資料 |

---

## 🚀 快速開始 (Quick Start)

### 1. 安裝環境與依賴

本專案支援 Python 3.10+，請在終端機執行：

`ash
# 1. 複製專案庫 (或下載原始碼)
git clone https://github.com/your-username/dboard-mcp.git
cd dboard-mcp

# 2. 安裝 Python 依賴套件
pip install -r requirements.txt

# 3. 安裝 Playwright 瀏覽器驅動 (用於 Google OAuth 與爬蟲)
playwright install chromium
`

---

### 2. 設定您的個人帳號密碼 (Authentication Setup)

本專案採用**帳號隔離設計**，每位使用者使用前需配置自己的真平語文 Dboard 帳號與密碼。

#### 方式 A：使用互動式設定工具 (最推薦)
執行以下指令，系統會引導您輸入帳號密碼並自動完成登入測試與本機 Session 建立：
`ash
python setup_auth.py
`

#### 方式 B：手動建立 .env 檔案
將 .env.example 複製一份為 .env，並填入您的登入資訊：
`env
DBOARD_USERNAME=your_email@example.com
DBOARD_PASSWORD=your_password
`

> [!NOTE]
> .env 與登入憑證已由 .gitignore 自動保護，絕不會被上傳至 Git 倉庫。

---

## 🤖 在 Antigravity 中啟用此 MCP Server

### 步驟 1：編輯 Antigravity MCP 設定檔
開啟您的全域 MCP 設定檔：
- **Windows**: C:\Users\<您的使用者名稱>\.gemini\antigravity\mcp_config.json
- **macOS / Linux**: ~/.gemini/antigravity/mcp_config.json

### 步驟 2：加入 dboard 伺服器設定
在 mcpServers 物件中加入以下配置（請將路徑與帳密替換為您的實際資訊）：

`json
{
  "mcpServers": {
    "dboard": {
      "command": "python",
      "args": [
        "C:\\path\\to\\dboard-mcp\\server.py"
      ],
      "env": {
        "DBOARD_USERNAME": "your_email@example.com",
        "DBOARD_PASSWORD": "your_password",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
`

> [!TIP]
> 若您已在專案根目錄建立了 .env 或執行過 python setup_auth.py，則 env 中的 DBOARD_USERNAME 與 DBOARD_PASSWORD 可省略。

### 步驟 3：重啟 Antigravity 或重新載入 MCP
完成後即可在 Antigravity 對話框中直接要求 AI 查詢 Dboard 資料！

---

## 💻 本地命令列快速查詢工具 (CLI)

即使不啟動 MCP，您也可以在終端機直接使用 query.py 進行本地快速查詢：

`ash
# 查詢特定經銷商負責區域
python query.py 環華
python query.py 大漢

# 查詢特定行政區由哪家經銷商負責
python query.py 大安區
python query.py 板橋區

# 列出全台所有經銷商與責任區域總覽
python query.py 列表

# 執行帳號登入設定
python query.py auth
`

---

## 📁 專案目錄結構

`
dboard-mcp/
├── server.py              # MCP FastMCP 伺服器主程式 (提供 6 大 MCP 工具)
├── dboard_client.py       # Playwright 自動登入與線上爬取客戶端
├── data_manager.py        # 本地快取資料庫與跨學制搜尋引擎
├── setup_auth.py          # 帳號密碼互動式設定與登入驗證精靈
├── query.py               # 本地命令行快速查詢工具
├── requirements.txt       # Python 依賴套件表
├── mcp.template.json      # Antigravity / Claude Desktop 配置範本
├── .env.example           # 環境變數設定檔範本
├── .gitignore             # Git 敏感資料與快取排除規則
├── README.md              # 專案使用說明
└── data/
    └── dboard_cache.json  # 預載經銷商與責任區域快取資料 (支援開箱即用離線查詢)
`

---

## 🔒 安全性與隱私聲明

- 本專案不會上傳或共享任何使用者的帳號、密碼或 Session Token。
- 所有驗證 Cookie 均儲存於使用者的本機 data/storage_state.json，且已設定於 .gitignore 排除名單中。
- 連線至真平語文網站時，均透過 Playwright 在使用者本機安全執行。

---

## 📄 License
MIT License