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 負荷テストセンター）

Model Context Protocol (MCP) に基づいて構築されたリモート AI サービスで、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 知識と Q&A（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 の現在の総 Key 数、Cache Hit / Miss 統計とサンプルを表示します。

• clear_cache(pattern)：条件に一致する Redis キャッシュを手動でクリアします。

• health_check()：サービスと Redis 接続の健全性を返し、ロード済みのデータファイルを一覧表示します。

⚡ パフォーマンス負荷テストガイド（Hydra + Grafana k6）

本プロジェクトは Hydra（YAML 設定ファイル） を使用して負荷テストパラメータを一元管理し、Python ネイティブ MCP SSE 並行負荷テスト と 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（Web インターフェース）： huggingface.co/new-space にアクセスし、名前を hf-mcp-playground と入力し、SDK で Docker を選択します。

2. ローカルバインドと更新プッシュ（Git Workflow）

ローカルプロジェクトにはリモート space が設定済みです。今後コードやデータを更新するたびに、3 ステップでオンラインデプロイを完了できます：

# 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 Build をトリガーします。

3. オンライン実行状態とログの確認

hf CLI を使用して、リモート Space のビルドと実行ログを確認できます：

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 並行負荷テストと k6 HTTP スループット負荷テストをサポート。

• v1.2.0（2026-08-24）：

  • データ分離アーキテクチャを完成させ、すべての講義情報、スキル SOP、Q&A を 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 プロトコルを統合し、Q&A 結果のミリ秒級キャッシュをサポート。

  • test_client.py 自動化テストクライアントを作成。

• v1.0.0（2026-08-24）：

  • プロジェクト初期化、Dockerfile と起動スクリプトを作成。