cf-mcp-playground

Cloudflare Worker와 Docker 이중 실행 환경을 지원하는 Model Context Protocol (MCP) 서비스로, MCP Skills 지식 베이스와 Redis 질문 캐시 가속 메커니즘이 내장되어 있습니다.

🌟 핵심 특징

1. 이중 실행 환경 (Dual Runtime):

   • ⛅ Cloudflare Workers: Edge 전 세계 배포를 지원하며, 초고속 콜드 스타트와 낮은 지연 시간을 제공합니다.

   • 🐳 Docker & Node.js: docker-compose.yml을 제공하여 MCP 서비스와 Redis 컨테이너를 원클릭으로 시작할 수 있습니다.

2. MCP Skills 지식 베이스:

   • MCP가 무엇인지, MCP Skill이 무엇인지 완전히 소개합니다.

   • Tools (도구), Resources (리소스), Prompts (프롬프트) 의 차이점과 조합 패턴을 자세히 비교합니다.

   • 주요 클라이언트 (Claude Desktop, Cursor, Zed, Cloudflare) 의 구성 가이드를 제공합니다.

3. Redis 반복 질문 초고속 응답 (Smart Caching):

   • 사용자가 질문하면 시스템이 자동으로 질문을 표준화하고 캐시 키를 계산합니다.

   • Cache HIT (적중): Redis에서 직접 밀리초 단위로 이전 캐시 결과를 반환하여 토큰과 지연 시간을 크게 절약합니다.

   • Cache MISS (미적중): 지식 베이스를 검색하여 완전한 답변을 생성하고 자동으로 Redis에 캐시합니다.

   • Redis 연결 끊김 시 메모리 캐시로 자동 다운그레이드 (Memory Fallback) 를 지원하여 높은 가용성을 보장합니다.

🛠️ MCP Tools & Capabilities

🚀 빠른 시작

방법 1: Docker로 시작 (Redis 포함)

# 啟動 MCP 服務與 Redis 容器
docker compose up --build -d

# 查看運行日誌
docker compose logs -f

# 停止服務
docker compose down

서비스 시작 후:

• 서비스 홈페이지 / 대시보드: http://localhost:3000/

• MCP 스트리밍 통신 엔드포인트: http://localhost:3000/mcp 또는 http://localhost:3000/sse

• 상태 확인 엔드포인트: http://localhost:3000/health

• REST Q&A API: POST http://localhost:3000/api/ask

방법 2: 로컬 개발 모드 (Node.js)

# 安裝依賴
npm install

# 執行單元測試 (驗證 MCP Tools & 快取機制)
npm test

# 啟動本機開發伺服器
npm run dev:node

방법 3: Cloudflare Workers에 배포

1. Cloudflare 로그인

터미널에서 실행:

npx wrangler login

브라우저가 자동으로 열리며 Cloudflare 계정 인증을 진행합니다.

CI/CD 또는 API Token으로 로그인하는 경우:

export CLOUDFLARE_API_TOKEN="你的 Cloudflare API Token"
export CLOUDFLARE_ACCOUNT_ID="你的 Cloudflare Account ID"

2. Worker 로컬 시뮬레이션 테스트

npm run dev:worker

3. Cloudflare 글로벌 엣지 네트워크에 배포

npm run deploy

배포가 성공하면 전용 Worker URL을 얻을 수 있습니다 (예: https://cf-mcp-playground.<your-subdomain>.workers.dev/mcp).

🔌 AI 클라이언트에서 사용

1. Claude Desktop 구성

claude_desktop_config.json 편집:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cf-mcp-remote": {
      "url": "https://<your-worker>.workers.dev/sse"
    },
    "cf-mcp-docker": {
      "command": "docker",
      "args": ["exec", "-i", "cf-mcp-service", "node", "dist/node-server.js"]
    }
  }
}

2. Cursor 구성

Cursor 인터페이스에서 Settings -> Features -> MCP Servers -> Add New MCP Server로 이동:

• Name: cf-mcp-service

• Type: sse

• URL: http://localhost:3000/sse (로컬 Docker) 또는 https://<your-worker>.workers.dev/sse (원격 Worker)

🧪 테스트 검증 예시

1. REST API 질문 테스트 (첫 질문 - Cache MISS)

curl -X POST http://localhost:3000/api/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "什麼是 MCP Skill？"}'

2. 동일한 질문 테스트 (반복 질문 - Cache HIT ⚡)

curl -X POST http://localhost:3000/api/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "什麼是 MCP Skill？"}'

3. 캐시 통계 확인

curl http://localhost:3000/api/cache/stats