---
title: HF MCP Server with Redis Cache & Course Hub
emoji: ⚡
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---

# 🧩 HF MCP Server (Redis 快取、技能、上課資訊與 k6 壓測中心)

基於 **Model Context Protocol (MCP)** 打造的遠端 AI 服務，託管於 **Hugging Face Spaces (Docker 模式)**。  
具備 **FastMCP SSE 協定**、**內建 Redis 毫秒級快取**、**資料分離架構 (`data/`)**，並提供 **MCP 知識庫、結構化技能 (Skills)、最新上課資訊查詢** 以及 **Hydra + Grafana k6 效能壓測套件**。

---

## 🌐 MCP 服務端點是什麼？(API Endpoints)

本服務在 Hugging Face Spaces 上運行於 **`7860` 埠號**，基於標準 **MCP SSE (Server-Sent Events) 協議** 暴露以下核心端點：

| 端點 (Endpoint) | HTTP 方法 | 說明 |
| :--- | :--- | :--- |
| **`/sse`** | `GET` | **MCP 連線入口**。客戶端（Claude/Cursor/Agent）發起長連線，伺服器立即回傳初始 Event，包含本次 Session 專屬的訊息發送位址（如 `data: /messages/?session_id=<UUID>`）。 |
| **`/messages/?session_id=<UUID>`** | `POST` | **JSON-RPC 2.0 訊息通道**。客戶端發送 `initialize`、`tools/list`、`tools/call` 等請求，伺服器經由 Redis 快取處理後透過 SSE 串流返回結果。 |
| **`/`** | `GET` | **伺服器首頁與基礎健康偵測**。可用於負載平衡器、監控探針或 k6 基礎連線吞吐量測試。 |

> **線上網址格式**：
> - 完整 URL：`https://<你的帳號>-hf-mcp-playground.hf.space/sse`
> - 本地 URL：`http://127.0.0.1:7860/sse`

---

## 📁 專案目錄結構

```text
hf-mcp-playground/
├── config/                    # ⚙️ 系統與壓測設定檔
│   └── benchmark.yaml         # 壓測規格配置（目標端點、並發數、SLA 門檻等）
├── data/                      # 📦 獨立資料資產庫（無敏感資訊，可版控）
│   ├── courses.json           # 🎓 上課資訊與課程大綱
│   ├── skills.json            # 🎯 結構化技能與學習路徑 SOP
│   └── mcp_knowledge.json     # 📖 MCP 觀念與問答知識庫
├── benchmarks/                # ⚡ 壓測腳本與成果報告
│   ├── k6_mcp_benchmark.js    # Grafana k6 負載測試腳本
│   └── results/               # 壓測產出之 JSON 報告
├── server.py                  # 🚀 FastMCP 主伺服器核心邏輯
├── start.sh                   # ⚙️ 容器啟動腳本（守護 Redis + 啟動 Python）
├── Dockerfile                 # 🐳 容器映像檔定義（Debian + Redis + uv + Python）
├── requirements.txt           # 📦 Python 依賴清單
├── test_client.py             # 🧪 MCP 功能與快取驗證腳本
├── run_benchmark.py           # 📊 Hydra + k6 壓測執行引擎
└── README.md                  # 📄 Hugging Face Space 元數據與完整手冊
```

---

## 🛠️ 提供之 MCP 工具清單 (Tools)

### 1. 🎓 上課資訊工具 (Course Information)
- **`list_courses(category)`**：列出所有最新開課清單（支援類別篩選，如 `MCP 實戰`、`AI Agent 開發`）。
- **`get_course_detail(course_id)`**：查詢指定課程的完整課堂大綱 (Syllabus)、時數與報名狀態（例如 `mcp-101`）。
- **`search_courses(keyword)`**：使用關鍵字搜尋相關課程（如 `redis`、`docker`、`fastapi`）。

### 2. 🎯 技能與工作流工具 (Skills & Workflow)
- **`list_skills(category)`**：列出所有專家技能 SOP（如 `mcp-server-dev`、`course-recommender`、`cache-optimization`）。
- **`get_skill_detail(skill_id)`**：取得特定技能的完整執行步驟與規範。
- **`recommend_learning_path(background)`**：輸入學員背景或目標，由技能規則自動推薦最適學習路徑。

### 3. 📖 MCP 知識與問答 (MCP Knowledge & QA)
- **`explain_mcp(topic)`**：解說 MCP 核心架構（`overview` 總覽、`core_primitives` 三大概念、`transports` 傳輸、`use_cases` 應用）。
- **`ask_mcp_qa(question, force_refresh)`**：智能回答 MCP 問題，自動執行 Redis 快取。

### 4. ⚡ 快取與系統監控 (Cache & Monitor)
- **`get_cache_stats()`**：檢視 Redis 目前總 Key 數、Cache Hit / Miss 統計與樣本。
- **`clear_cache(pattern)`**：手動清除符合條件的 Redis 快取。
- **`health_check()`**：回傳服務與 Redis 連線健康度，並列出已載入的資料檔案。

---

## ⚡ 效能壓測指南 (Hydra + Grafana k6)

本專案使用 **Hydra (YAML 設定檔)** 統一管理壓測參數，並支援 **Python 原生 MCP SSE 併發壓測** 與 **Grafana k6 負載測試**。

### 1. 壓測設定檔 (`config/benchmark.yaml`)
```yaml
server:
  host: "127.0.0.1"
  port: 7860
  base_url: "http://${server.host}:${server.port}"
  sse_endpoint: "${server.base_url}/sse"

# 壓測引擎：'async_mcp' (原生 MCP 協定壓測) 或 'k6' (Grafana k6 負載測試)
engine: "async_mcp"

benchmark:
  concurrency: 10          # 併發客戶端數 (VUs)
  requests_per_client: 10  # 每個客戶端調用 Tool 次數
  duration: "10s"          # 壓測時間 (k6 模式使用)
  thresholds:
    p95_latency_ms: 200    # P95 延遲需小於 200ms
    p99_latency_ms: 500    # P99 延遲需小於 500ms
    max_error_rate: 0.01   # 錯誤率需小於 1%

scenario:
  target_tool: "ask_mcp_qa"
  question: "什麼是 MCP？跟傳統 API 有什麼差別？"
```

### 2. 執行壓測指令

```bash
conda activate toby

# 1. 預設執行原生 MCP SSE 併發壓測 (10 clients * 10 reqs = 100 Tool Calls)
python run_benchmark.py

# 2. 透過 Hydra 覆寫參數 (例如：將併發調高至 20、改測 200 次)
python run_benchmark.py benchmark.concurrency=20 benchmark.requests_per_client=10

# 3. 切換為 Grafana k6 負載測試引擎 (持續 10 秒)
python run_benchmark.py engine=k6 benchmark.duration=10s

# 4. 對 Hugging Face 遠端線上 Space 進行壓測
python run_benchmark.py server.host="tobytoy-hf-mcp-playground.hf.space" server.port=443 server.base_url="https://tobytoy-hf-mcp-playground.hf.space"
```

### 3. 壓測輸出報表示例
```text
================================================================
📊 【壓測成果摘要分析 (ASYNC_MCP 引擎)】
================================================================
• 總請求數 (Total Requests)     : 100
• 吞吐量 (Throughput RPS)       : 107.25 req/s
• 平均延遲 (Average Latency)    : 64.59 ms
• 中位數延遲 (Median P50)       : 57.50 ms
• P95 延遲 (95% 請求)           : 152.06 ms (SLA: < 200 ms)
• P99 延遲 (99% 請求)           : 192.09 ms (SLA: < 500 ms)
• 錯誤率 (Error Rate)           : 0.0%
----------------------------------------------------------------
🎉 【壓測評估】: PASS (Redis 毫秒級快取成功發揮效能，符合 SLA 門檻！)
```

---

## 🚀 Hugging Face Spaces 部署與維護手冊

### 1. 建立 Space (首次配置)
- **方法 A (CLI 指令)**：
  ```bash
  conda activate toby
  hf repos create tobytoy/hf-mcp-playground --type space --sdk docker
  ```
- **方法 B (網頁介面)**：
  前往 [huggingface.co/new-space](https://huggingface.co/new-space)，名稱填寫 `hf-mcp-playground`，SDK 選擇 **Docker**。

### 2. 本地綁定與更新推播 (Git Workflow)
本地專案已配置遠端 `space`，日後每次更新代碼或資料後，只需三步即可完成線上部署：

```bash
# 1. 檢查變更
git status

# 2. 提交變更
git add .
git commit -m "feat: 更新課程資訊與新增技能"

# 3. 推播至 GitHub 與 Hugging Face Space
git push origin main
git push space main
```

> **注意**：當推播至 `space` 後，Hugging Face 會自動觸發雲端 Docker Build。

### 3. 查看線上運行狀態與日誌
可以使用 `hf` CLI 查看遠端 Space 的建置與運行日誌：
```bash
conda activate toby
hf spaces logs tobytoy/hf-mcp-playground
```

### 4. 設定環境變數與機密 (Secrets)
若日後需要改用外部雲端 Redis（例如 Upstash 或 Redis Cloud），可在 Hugging Face Space 的 **Settings -> Variables and secrets** 新增：
- **`REDIS_URL`** = `rediss://default:xxxx@your-redis-host:6379`
程式會自動偵測並切換至外部 Redis。

---

## 🧪 本地開發與功能測試

### 1. 使用 Docker 本地一鍵運行
```bash
# 1. 建置本地 Docker 映像檔
docker build -t hf-mcp-playground .

# 2. 啟動容器 (映射 7860 埠號)
docker run -d --name mcp_server -p 7860:7860 hf-mcp-playground

# 3. 檢視容器日誌
docker logs -f mcp_server
```

### 2. 執行功能驗證腳本 (`test_client.py`)
```bash
conda activate toby

# 測試本機服務：
python test_client.py http://127.0.0.1:7860/sse

# 測試 Hugging Face 線上服務：
python test_client.py https://tobytoy-hf-mcp-playground.hf.space/sse
```

---

## 🔌 客戶端連線設定 (MCP Clients)

### 1. Claude Desktop / Cursor / Antigravity IDE
在客戶端設定檔（如 `claude_desktop_config.json`）中加入：

```json
{
  "mcpServers": {
    "hf-mcp-course-hub": {
      "url": "https://tobytoy-hf-mcp-playground.hf.space/sse"
    }
  }
}
```

*(若為本地測試，將 url 改為 `http://127.0.0.1:7860/sse`)*

---

## 📜 版本紀錄 (Changelog)

- **v1.3.0 (2026-08-24)**：
  - 整合 **Hydra (YAML) + Grafana k6** 效能壓測套件 (`config/benchmark.yaml`, `benchmarks/k6_mcp_benchmark.js`, `run_benchmark.py`)。
  - 支援原生 MCP SSE 併發壓測與 k6 HTTP 吞吐量壓測。
- **v1.2.0 (2026-08-24)**：
  - 完成資料分離架構，將所有上課資訊、技能 SOP、問答抽離至 `data/*.json`。
  - 新增 `list_courses`、`get_course_detail`、`search_courses` 課程查詢工具。
  - 新增 `list_skills`、`get_skill_detail`、`recommend_learning_path` 技能推薦工具。
- **v1.1.0 (2026-08-24)**：
  - 整合單容器內建 `redis-server` 與 FastMCP 協定，支援問答結果毫秒級快取。
  - 撰寫 `test_client.py` 自動化測試客戶端。
- **v1.0.0 (2026-08-24)**：
  - 專案初始化，建立 Dockerfile 與啟動腳本。