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, Kursinformationen und k6-Lasttestzentrum)

Ein Model Context Protocol (MCP)-basierter Remote-AI-Dienst, gehostet auf Hugging Face Spaces (Docker-Modus).
Ausgestattet mit FastMCP-SSE-Protokoll, integriertem Redis-Cache im Millisekundenbereich, datengetrennter Architektur (data/) sowie MCP-Wissensdatenbank, strukturierten Skills, aktuellen Kursinformationen und einem Hydra + Grafana k6-Leistungstestpaket.

Related MCP server: skills-mcp-server

🌐 Was sind die MCP-Dienstendpunkte? (API-Endpunkte)

Dieser Dienst läuft auf Hugging Face Spaces auf Port 7860 und stellt basierend auf dem Standard-MCP-SSE-Protokoll (Server-Sent Events) die folgenden Kernendpunkte bereit:

Online-URL-Format:

• Vollständige URL: https://<dein-konto>-hf-mcp-playground.hf.space/sse

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

📁 Projektverzeichnisstruktur

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

🛠️ Liste der bereitgestellten MCP-Tools

1. 🎓 Kursinformationstools (Course Information)

• list_courses(category): Listet alle aktuellen Kursangebote auf (unterstützt Kategoriefilter wie MCP 實戰, AI Agent 開發).

• get_course_detail(course_id): Ruft den vollständigen Lehrplan (Syllabus), die Stundenanzahl und den Anmeldestatus eines bestimmten Kurses ab (z. B. mcp-101).

• search_courses(keyword): Sucht mit Schlüsselwörtern nach relevanten Kursen (z. B. redis, docker, fastapi).

2. 🎯 Skill- und Workflow-Tools (Skills & Workflow)

• list_skills(category): Listet alle Experten-Skill-SOPs auf (z. B. mcp-server-dev, course-recommender, cache-optimization).

• get_skill_detail(skill_id): Ruft die vollständigen Ausführungsschritte und Spezifikationen eines bestimmten Skills ab.

• recommend_learning_path(background): Gibt den Hintergrund oder das Ziel eines Lernenden ein; die Skill-Regeln empfehlen automatisch den optimalen Lernpfad.

3. 📖 MCP-Wissen und Q&A (MCP Knowledge & QA)

• explain_mcp(topic): Erläutert die MCP-Kernarchitektur (overview Überblick, core_primitives drei Kernkonzepte, transports Übertragung, use_cases Anwendungen).

• ask_mcp_qa(question, force_refresh): Beantwortet MCP-Fragen intelligent und nutzt automatisch den Redis-Cache.

4. ⚡ Cache- und Systemüberwachung (Cache & Monitor)

• get_cache_stats(): Zeigt die aktuelle Gesamtzahl der Redis-Keys, Cache-Hit-/Miss-Statistiken und Stichproben an.

• clear_cache(pattern): Löscht manuell Redis-Cache-Einträge, die dem Muster entsprechen.

• health_check(): Gibt den Gesundheitsstatus des Dienstes und der Redis-Verbindung zurück und listet die geladenen Datendateien auf.

⚡ Leistungstest-Leitfaden (Hydra + Grafana k6)

Dieses Projekt verwendet Hydra (YAML-Konfigurationsdatei) zur einheitlichen Verwaltung der Lasttestparameter und unterstützt sowohl natives Python-MCP-SSE-Concurrency-Lasttest als auch Grafana-k6-Lasttests.

1. Lasttest-Konfigurationsdatei (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. Ausführen der Lasttest-Befehle

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. Beispiel für Lasttest-Ausgabeberichte

================================================================
📊 【壓測成果摘要分析 (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-Bereitstellungs- und Wartungshandbuch

1. Space erstellen (Erstkonfiguration)

• Methode A (CLI-Befehl):

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

• Methode B (Weboberfläche): Gehe zu huggingface.co/new-space, gib als Namen hf-mcp-playground ein und wähle als SDK Docker.

2. Lokales Binden und Update-Push (Git-Workflow)

Das lokale Projekt ist bereits mit dem Remote-space konfiguriert. Nach jedem zukünftigen Update von Code oder Daten genügen drei Schritte für die Online-Bereitstellung:

# 1. 檢查變更
git status

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

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

Hinweis: Nach dem Push an space löst Hugging Face automatisch einen Cloud-Docker-Build aus.

3. Online-Status und Logs anzeigen

Mit der hf-CLI können die Build- und Laufzeit-Logs des Remote-Spaces eingesehen werden:

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

4. Umgebungsvariablen und Secrets festlegen

Falls später ein externer Cloud-Redis (z. B. Upstash oder Redis Cloud) verwendet werden soll, können unter Settings -> Variables and secrets im Hugging-Face-Space folgende Einträge hinzugefügt werden:

• REDIS_URL = rediss://default:xxxx@your-redis-host:6379 Das Programm erkennt dies automatisch und wechselt zum externen Redis.

🧪 Lokale Entwicklung und Funktionstests

1. Lokaler Ein-Klick-Start mit 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. Funktionsvalidierungsskript ausführen (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-Verbindungskonfiguration (MCP-Clients)

1. Claude Desktop / Cursor / Antigravity IDE

In der Client-Konfigurationsdatei (z. B. claude_desktop_config.json) hinzufügen:

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

(Bei lokalen Tests die URL in http://127.0.0.1:7860/sse ändern)

📜 Versionshistorie (Changelog)

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

  • Integration des Hydra (YAML) + Grafana k6-Leistungstestpakets (config/benchmark.yaml, benchmarks/k6_mcp_benchmark.js, run_benchmark.py).

  • Unterstützung für natives MCP-SSE-Concurrency-Lasttest und k6-HTTP-Durchsatz-Lasttest.

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

  • Abschluss der datengetrennten Architektur; alle Kursinformationen, Skill-SOPs und Q&A wurden in data/*.json ausgelagert.

  • Neue Kursabfragetools list_courses, get_course_detail, search_courses hinzugefügt.

  • Neue Skill-Empfehlungstools list_skills, get_skill_detail, recommend_learning_path hinzugefügt.

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

  • Integration von integriertem redis-server im Einzelcontainer mit dem FastMCP-Protokoll; Unterstützung für Millisekunden-Caching von Q&A-Ergebnissen.

  • test_client.py für automatisierte Testclients geschrieben.

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

  • Projektinitialisierung; Dockerfile und Startskript erstellt.