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)

Удалённый AI-сервис, построенный на основе Model Context Protocol (MCP), размещённый на Hugging Face Spaces (режим Docker).
Включает протокол FastMCP SSE, встроенный Redis-кэш с миллисекундной задержкой, архитектуру с разделением данных (data/) и предоставляет базу знаний MCP, структурированные навыки (Skills), актуальную информацию о курсах, а также набор для нагрузочного тестирования Hydra + Grafana k6.

Related MCP server: skills-mcp-server

🌐 Что такое конечные точки MCP-сервиса? (API Endpoints)

Сервис работает на Hugging Face Spaces на порту 7860 и на основе стандартного протокола MCP SSE (Server-Sent Events) предоставляет следующие основные конечные точки:

Формат онлайн-URL:

• Полный URL: https://<ваш-аккаунт>-hf-mcp-playground.hf.space/sse

• Локальный URL: http://127.0.0.1:7860/sse

📁 Структура каталога проекта

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, статистики Cache Hit / Miss и примеров.

• clear_cache(pattern): ручная очистка Redis-кэша, соответствующего условиям.

• health_check(): возвращает состояние работоспособности сервиса и подключения к Redis, а также перечисляет загруженные файлы данных.

⚡ Руководство по нагрузочному тестированию (Hydra + Grafana k6)

В этом проекте используется Hydra (YAML-конфигурация) для единообразного управления параметрами нагрузочного тестирования, а также поддерживаются нативное нагрузочное тестирование параллельных подключений MCP SSE на Python и нагрузочное тестирование Grafana k6.

1. Файл конфигурации нагрузочного тестирования (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. Команды запуска нагрузочного тестирования

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. Пример отчёта о результатах нагрузочного тестирования

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

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

• Способ B (веб-интерфейс): Перейдите на huggingface.co/new-space, укажите имя hf-mcp-playground, выберите SDK Docker.

2. Локальная привязка и обновление (Git Workflow)

В локальном проекте уже настроен удалённый space. В дальнейшем после каждого обновления кода или данных для завершения онлайн-развёртывания достаточно трёх шагов:

# 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.

3. Просмотр онлайн-статуса и журналов

Для просмотра журналов сборки и работы удалённого Space можно использовать CLI hf:

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

# 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)

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) добавьте:

{
  "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 и нагрузочного тестирования пропускной способности HTTP через k6.

• 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 и скрипта запуска.