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 壓測中心)

Servicio de IA remoto construido sobre el Model Context Protocol (MCP), alojado en Hugging Face Spaces (modo Docker).
Incluye protocolo FastMCP SSE, caché Redis integrada a nivel de milisegundos, arquitectura de datos separada (data/), y ofrece base de conocimientos MCP, habilidades estructuradas (Skills), consulta de información actualizada de cursos y un paquete de pruebas de rendimiento Hydra + Grafana k6.

Related MCP server: skills-mcp-server

🌐 ¿Cuáles son los endpoints del servicio MCP? (API Endpoints)

Este servicio se ejecuta en Hugging Face Spaces en el puerto 7860 y expone los siguientes endpoints principales basados en el protocolo estándar MCP SSE (Server-Sent Events):

Formato de URL en línea:

• URL completa: https://<tu-cuenta>-hf-mcp-playground.hf.space/sse

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

📁 Estructura de directorios del proyecto

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

🛠️ Lista de herramientas MCP proporcionadas (Tools)

1. 🎓 Herramienta de información de cursos (Course Information)

• list_courses(category): Lista todos los cursos más recientes disponibles (admite filtrado por categoría, como MCP 實戰, AI Agent 開發).

• get_course_detail(course_id): Consulta el temario completo (Syllabus), las horas y el estado de inscripción de un curso específico (por ejemplo, mcp-101).

• search_courses(keyword): Busca cursos relacionados mediante palabras clave (como redis, docker, fastapi).

2. 🎯 Herramientas de habilidades y flujos de trabajo (Skills & Workflow)

• list_skills(category): Lista todos los SOP de habilidades expertas (como mcp-server-dev, course-recommender, cache-optimization).

• get_skill_detail(skill_id): Obtiene los pasos de ejecución completos y las especificaciones de una habilidad específica.

• recommend_learning_path(background): Ingresa el perfil u objetivo del estudiante y las reglas de habilidades recomiendan automáticamente la ruta de aprendizaje más adecuada.

3. 📖 Conocimiento y preguntas frecuentes sobre MCP (MCP Knowledge & QA)

• explain_mcp(topic): Explica la arquitectura central de MCP (overview visión general, core_primitives tres conceptos principales, transports transporte, use_cases aplicaciones).

• ask_mcp_qa(question, force_refresh): Responde inteligentemente preguntas sobre MCP, ejecutando automáticamente la caché Redis.

4. ⚡ Caché y monitoreo del sistema (Cache & Monitor)

• get_cache_stats(): Muestra el número total de claves en Redis, estadísticas de Cache Hit / Miss y ejemplos.

• clear_cache(pattern): Limpia manualmente la caché Redis que coincida con las condiciones.

• health_check(): Devuelve el estado de salud del servicio y de la conexión Redis, y lista los archivos de datos cargados.

⚡ Guía de pruebas de rendimiento (Hydra + Grafana k6)

Este proyecto utiliza Hydra (archivo de configuración YAML) para gestionar de forma unificada los parámetros de las pruebas de rendimiento, y admite pruebas de concurrencia MCP SSE nativas en Python y pruebas de carga con Grafana k6.

1. Archivo de configuración de pruebas de rendimiento (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. Comandos para ejecutar las pruebas de rendimiento

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. Ejemplo de informe de salida de las pruebas de rendimiento

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

🚀 Manual de implementación y mantenimiento en Hugging Face Spaces

1. Crear un Space (configuración inicial)

• Método A (comando CLI):

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

• Método B (interfaz web): Ve a huggingface.co/new-space, escribe hf-mcp-playground como nombre y selecciona Docker como SDK.

2. Vinculación local y actualización mediante push (Git Workflow)

El proyecto local ya tiene configurado el remoto space. En el futuro, después de cada actualización de código o datos, solo se necesitan tres pasos para completar la implementación en línea:

# 1. 檢查變更
git status

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

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

Nota: Después de hacer push a space, Hugging Face activará automáticamente el Docker Build en la nube.

3. Ver el estado de ejecución en línea y los registros

Puedes usar la CLI hf para ver los registros de construcción y ejecución del Space remoto:

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

4. Configurar variables de entorno y secretos (Secrets)

Si en el futuro necesitas cambiar a un Redis externo en la nube (como Upstash o Redis Cloud), puedes agregar en Settings -> Variables and secrets del Hugging Face Space:

• REDIS_URL = rediss://default:xxxx@your-redis-host:6379 El programa detectará automáticamente y cambiará al Redis externo.

🧪 Desarrollo local y pruebas de funcionalidad

1. Ejecución local con un solo comando usando 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. Ejecutar el script de verificación de funcionalidad (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

🔌 Configuración de conexión de clientes (MCP Clients)

1. Claude Desktop / Cursor / Antigravity IDE

En el archivo de configuración del cliente (como claude_desktop_config.json), agrega:

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

(Si es una prueba local, cambia la url a http://127.0.0.1:7860/sse)

📜 Registro de versiones (Changelog)

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

  • Integración del paquete de pruebas de rendimiento Hydra (YAML) + Grafana k6 (config/benchmark.yaml, benchmarks/k6_mcp_benchmark.js, run_benchmark.py).

  • Soporte para pruebas de concurrencia MCP SSE nativas y pruebas de rendimiento de throughput HTTP con k6.

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

  • Finalización de la arquitectura de datos separada, extrayendo toda la información de cursos, SOP de habilidades y preguntas frecuentes a data/*.json.

  • Nuevas herramientas de consulta de cursos: list_courses, get_course_detail, search_courses.

  • Nuevas herramientas de recomendación de habilidades: list_skills, get_skill_detail, recommend_learning_path.

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

  • Integración de redis-server integrado en un solo contenedor con el protocolo FastMCP, con soporte de caché a nivel de milisegundos para resultados de preguntas y respuestas.

  • Creación de test_client.py como cliente de pruebas automatizadas.

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

  • Inicialización del proyecto, creación del Dockerfile y del script de inicio.