以 Anthropic 的 Model Context Protocol 為介面，將 Uedu Public API v1 包裝成 LLM 可直接呼叫的工具。支援 stdio 與 streamable-http 雙傳輸、SHA-256 雜湊金鑰、雙層 rate limit，嚴格區隔公開與敏感資料。
大學教師與研究者常常需要查詢平台資料（「NCU 通識中心 114-2 開哪些課？」「Uedu 團隊今年發了哪些論文？」），但不熟悉 REST API、不想寫 Python 腳本。以往的解法是做很多查詢頁面，UI 開發成本高、維護不易。
Model Context Protocol（MCP）是 Anthropic 於 2024 年提出的開放協定，允許 LLM client（Claude Desktop、Claude Code、Cursor、VS Code 等）透過標準化工具介面取得外部資料。Uedu 將 Public API v1 包裝成 MCP server，讓研究者以自然語言查詢資料、由 LLM 自主決定該呼叫哪個工具。
這是 Uedu 實踐「人機共學」（Human-AI Collaboration）設計哲學的基礎設施。研究者無需寫任何程式碼，即可讓 Claude、Cursor 等 AI 助手變身為熟悉 Uedu 資料的研究助理。這降低了非工程背景學者使用平台資料的門檻。
MCP Server 並非獨立的資料源，而是 Public API v1（/api/v1/*）的包裝層：
LLM Client (Claude/Cursor/VS Code)
│ (MCP protocol, JSON-RPC over stdio/HTTP)
▼
Uedu MCP Server ← 本文件討論的對象
│ (HTTPS, Bearer token)
▼
Uedu Public API v1 (/api/v1/*)
│
▼
MySQL 資料庫（僅查詢低敏感欄位）實際的資料查詢、權限驗證、rate limit 皆發生在 API 層。MCP server 只負責：
這個分層設計讓 MCP 的變更不會影響核心 API，反之亦然。若未來 MCP 協定改版，僅需重寫 wrapper。
Uedu 同時提供兩種 MCP 傳輸實作，位於 mcp_server/ 目錄：
| 面向 | stdio（uedu_mcp_server.py） | HTTP（uedu_mcp_http.py） |
|---|---|---|
| 傳輸 | stdin / stdout JSON-RPC | streamable-http（Starlette / ASGI） |
| 部署 | 使用者本機（需裝 Python + mcp[cli]、httpx） | Uedu 伺服器上長駐，反向代理為 https://uedu.tw/mcp |
| Client 設定 | 須寫明 Python 絕對路徑 | 只填 URL + Bearer token |
| API key 來源 | 環境變數 UEDU_API_KEY | HTTP Authorization header，per-request 取出 |
| 多用戶並發 | 每個 client 自己跑一份 | 單一 server 支援多 key 並發 |
| 適用對象 | 離線、私密部署、開發 | 一般研究者、不想裝相依套件 |
stdio 版有兩份：mcp_server/uedu_mcp_server.py（開發版）與 static/mcp/uedu_mcp_server.py（供使用者 curl 下載）。每次新增 / 修改 tool 時，兩份檔案與 HTTP 版共三處都必須同步。
目前提供 6 個 tools，全部針對公開資料：
| Tool | 對應 Endpoint | 用途 |
|---|---|---|
list_universities | GET /api/v1/universities | 列出收錄的大學（可依地區篩選） |
search_courses | GET /api/v1/courses | 搜尋公開課程（關鍵字、學期、學校、分頁） |
get_course | GET /api/v1/courses/<id> | 取得單一公開課程詳情 |
get_course_stats | GET /api/v1/course_stats | 開課統計（依學期 / 學年 / 學校分組） |
list_papers | GET /api/v1/papers | Uedu 團隊發表的學術論文 |
list_conferences | GET /api/v1/conferences | Uedu 團隊參與的學術研討會 |
所有 tool 遵循以下約定：
@mcp.tool() decorator 宣告str（JSON 序列化，ensure_ascii=False 以保留中文）Context 參數，用於取出 per-request Bearer tokenuedu_<48 hex>（共 53 字元）Authorization: Bearer <key> → 計算 SHA-256 → 查 api_v1_keys.key_hash → 檢查 is_active=1每次 API 請求會同時更新兩個 bucket（INSERT ... ON DUPLICATE KEY UPDATE，原子化）：
bucket_minute = DATETIME.replace(second=0, microsecond=0)bucket_day = DATE| 層級 | 預設上限 | 可 override |
|---|---|---|
| 每分鐘 | 60 次 | api_v1_keys.rate_limit_per_minute（NULL = 用預設） |
| 每天 | 10,000 次 | api_v1_keys.rate_limit_per_day（NULL = 用預設） |
管理員可透過 /api/developers/admin/keys/<id> 對個別 key 提高或降低限額，例如信任的研究機構金鑰可放寬到 300/min。
每次 API 呼叫寫入 api_v1_request_log（含 endpoint、HTTP 狀態碼、IP、User-Agent），保留 30 天，供濫用偵測與除錯。
MCP Server 是 Uedu 對外的「入口」，資料邊界規範必須嚴格：
| 類型 | 欄位範例 |
|---|---|
| 大學 metadata | code、name_zh、name_en、region |
公開課程（is_public=1） | class_name、instructor、semester、department、teaching_goal |
| 開課統計 | 依學期 / 學年 / 學校聚合的 course_count、instructor_count |
| 論文 metadata | 標題、作者、會議、年份、DOI、分類 |
| 研討會 metadata | 名稱、地點、日期、參與論文數 |
is_public=0）資料邊界不靠「請求時判斷」，而是從 SQL 層面就不取敏感欄位。每個 Public API endpoint 的 SELECT 語句是白名單式設計，敏感欄位從未進入 API 回應路徑。WHERE is_public = 1 AND deleted = 0 硬編碼於每個 course endpoint，防止列舉攻擊。
新增一個 tool 時，以下三處必須同步修改：
mcp_server/uedu_mcp_server.py（stdio 開發版）static/mcp/uedu_mcp_server.py（使用者下載版）mcp_server/uedu_mcp_http.py（HTTP 版）並視需要更新 app_api_v1.py（加新 endpoint）與 templates/developers/index.html（使用者文件）。
目前 Flask-Limiter 預設使用 in-memory storage。多 worker 部署時需改 Redis，否則每個 worker 的計數獨立，實際限額會變成 N 倍。
HTTP MCP server 需另起獨立程序綁定 127.0.0.1:5050（由 supervisord 管理），並在 nginx 加 location /mcp/ 反向代理規則。目前標示為 experimental。
MCP 規格除了 tools 外，還定義了 Resources 與 Prompts 兩種能力。Uedu 規劃逐步補上：
以 URI 方式暴露結構化資源，讓使用者在 LLM client 端「Add Context → MCP Resources」掛入：
uedu://courses/<id> → 課程大綱uedu://papers/<id> → 論文 metadata 與摘要uedu://universities/<code>/courses → 某校所有公開課程預先定義互動式 prompt template，使用者在 LLM client 打 /uedu.xxx 觸發：
/uedu.find_advisor（對應 advisor_match 模組）/uedu.summarize_course（對應 course 模組）/uedu.related_papers（依興趣關鍵字搜尋 Uedu 論文集）計劃提交至 GitHub MCP Registry，讓使用者在 VS Code 以 @mcp uedu 一鍵安裝。
Uedu MCP Server 本身即為研究題材。可探索的議題：
引用本系統時，請標註：「Uedu MCP Server: an educational-data MCP implementation with dual transport (stdio + streamable-http) (https://uedu.tw/developers)」。若使用 API v1 取得資料，請同時說明使用的 endpoint、查詢時段與資料范圍。論文發表前務必確認使用的所有資料皆屬於「公開」類別，私密欄位不得出現在研究素材中。