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

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

讓 AI 助手（如 Antigravity, Claude Desktop, Cowork）能直接查詢真平語文網站中的即時與快取數據，包括：

1. 經銷商與客戶責任區域查詢（依經銷商名稱、客戶編號、縣市或行政區查詢）

2. 多學制與語言版本切換（國小台語、國中台語、高中台語、國小客語、國中客語、高中客語）

3. 班級數統計與訂量數據（各版本真平班級數、實際班級數與預估訂量）

4. 線上即時爬蟲與資料自動同步

🛠️ MCP Tools 工具清單

🚀 快速開始 (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

🤖 在 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" } } } }

步驟 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