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 元數據與完整手冊

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 有什麼差別？"

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"

================================================================
📊 【壓測成果摘要分析 (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 門檻！)

# 1. 檢查變更
git status

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

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

conda activate toby
hf spaces logs tobytoy/hf-mcp-playground

# 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

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

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