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: personalknowhow

🌐 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 3대 개념, 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 (웹 인터페이스): 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 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 및 시작 스크립트 생성.