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 Cache, Skills, Course Information & k6 Load Testing Hub)

A remote AI service built on the Model Context Protocol (MCP), hosted on Hugging Face Spaces (Docker mode).
It features the FastMCP SSE protocol, built-in Redis millisecond-level caching, data separation architecture (data/), and provides an MCP knowledge base, structured Skills, latest course information queries, as well as a Hydra + Grafana k6 performance load testing suite.

Related MCP server: skills-mcp-server

🌐 What are the MCP service endpoints? (API Endpoints)

This service runs on port 7860 on Hugging Face Spaces and exposes the following core endpoints based on the standard MCP SSE (Server-Sent Events) protocol:

Online URL format:

• Full URL: https://<your-account>-hf-mcp-playground.hf.space/sse

• Local URL: http://127.0.0.1:7860/sse

📁 Project Directory Structure

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

🛠️ List of Provided MCP Tools

1. 🎓 Course Information Tools

• list_courses(category): Lists all the latest course offerings (supports category filtering, e.g. MCP 实战, AI Agent 开发).

• get_course_detail(course_id): Queries the complete syllabus, hours, and enrollment status of a specified course (e.g. mcp-101).

• search_courses(keyword): Searches for related courses using keywords (e.g. redis, docker, fastapi).

2. 🎯 Skills & Workflow Tools

• list_skills(category): Lists all expert skill SOPs (e.g. mcp-server-dev, course-recommender, cache-optimization).

• get_skill_detail(skill_id): Retrieves the complete execution steps and specifications of a specific skill.

• recommend_learning_path(background): Automatically recommends the most suitable learning path based on the learner's background or goals, using skill rules.

3. 📖 MCP Knowledge & QA

• explain_mcp(topic): Explains the core MCP architecture (overview, core_primitives (the three core concepts), transports, use_cases).

• ask_mcp_qa(question, force_refresh): Intelligently answers MCP questions with automatic Redis caching.

4. ⚡ Cache & System Monitoring

• get_cache_stats(): Views the current total number of Redis keys, Cache Hit/Miss statistics, and samples.

• clear_cache(pattern): Manually clears Redis cache entries matching the given condition.

• health_check(): Returns service and Redis connection health, and lists the loaded data files.

⚡ Performance Load Testing Guide (Hydra + Grafana k6)

This project uses Hydra (YAML config files) to centrally manage load testing parameters, and supports both native Python MCP SSE concurrency load testing and Grafana k6 load testing.

1. Load Testing Config File (config/benchmark.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. Running the Load Test Commands

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. Load Test Output Report Example

================================================================
📊 【壓測成果摘要分析 (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 Deployment & Maintenance Manual

1. Creating a Space (Initial Setup)

• Method A (CLI command):

  conda activate toby
  hf repos create tobytoy/hf-mcp-playground --type space --sdk docker

• Method B (Web interface): Go to huggingface.co/new-space, name it hf-mcp-playground, and select Docker as the SDK.

2. Local Binding and Update Push (Git Workflow)

The local project already has the remote space configured. After each future code or data update, only three steps are needed to complete the online deployment:

# 1. 檢查變更
git status

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

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

Note: After pushing to space, Hugging Face will automatically trigger a cloud Docker Build.

3. Viewing Online Runtime Status and Logs

You can use the hf CLI to view the build and runtime logs of the remote Space:

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

4. Setting Environment Variables and Secrets

If you later need to switch to an external cloud Redis (e.g. Upstash or Redis Cloud), you can add the following in the Hugging Face Space's Settings -> Variables and secrets:

• REDIS_URL = rediss://default:xxxx@your-redis-host:6379 The program will automatically detect and switch to the external Redis.

🧪 Local Development and Functional Testing

1. One-Click Local Run with Docker

# 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. Running the Functional Verification Script (test_client.py)

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

🔌 Client Connection Setup (MCP Clients)

1. Claude Desktop / Cursor / Antigravity IDE

Add the following to the client configuration file (e.g. claude_desktop_config.json):

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

(For local testing, change the url to http://127.0.0.1:7860/sse)

📜 Changelog

• v1.3.0 (2026-08-24):

  • Integrated the Hydra (YAML) + Grafana k6 performance load testing suite (config/benchmark.yaml, benchmarks/k6_mcp_benchmark.js, run_benchmark.py).

  • Added support for native MCP SSE concurrency load testing and k6 HTTP throughput load testing.

• v1.2.0 (2026-08-24):

  • Completed the data separation architecture, extracting all course information, skill SOPs, and Q&A into data/*.json.

  • Added the list_courses, get_course_detail, and search_courses course query tools.

  • Added the list_skills, get_skill_detail, and recommend_learning_path skill recommendation tools.

• v1.1.0 (2026-08-24):

  • Integrated the built-in redis-server and FastMCP protocol in a single container, supporting millisecond-level caching of Q&A results.

  • Wrote the test_client.py automated test client.

• v1.0.0 (2026-08-24):

  • Project initialization, created the Dockerfile and startup script.