cf-mcp-playground

A Model Context Protocol (MCP) service that runs in both Cloudflare Worker and Docker environments, with a built-in MCP Skills knowledge base and Redis query caching acceleration.

🌟 Core Features

1. Dual Runtime:

   • ⛅ Cloudflare Workers: Supports Edge global deployment with ultra-fast cold starts and low latency.

   • 🐳 Docker & Node.js: Provides a docker-compose.yml to start the MCP service and Redis container with one command.

2. MCP Skills Knowledge Base:

   • A complete introduction to what MCP is and what an MCP Skill is.

   • Detailed comparison of the differences and combination patterns between Tools, Resources, and Prompts.

   • Configuration guides for major clients (Claude Desktop, Cursor, Zed, Cloudflare).

3. Redis Instant Answers for Repeated Questions (Smart Caching):

   • When a user asks a question, the system automatically normalizes the question and computes a cache key.

   • Cache HIT: Returns the historical cached result directly from Redis in milliseconds, greatly saving Tokens and latency.

   • Cache MISS: Retrieves the knowledge base to generate a full answer and automatically caches it in Redis.

   • Supports automatic degradation to in-memory caching (Memory Fallback) when Redis is disconnected, ensuring high availability.

🛠️ MCP Tools & Capabilities

🚀 Quick Start

Option 1: Start with Docker (includes Redis)

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

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

# 停止服務
docker compose down

After the service starts:

• Service homepage / dashboard: http://localhost:3000/

• MCP streaming endpoint: http://localhost:3000/mcp or http://localhost:3000/sse

• Health check endpoint: http://localhost:3000/health

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

Option 2: Local Development Mode (Node.js)

# 安裝依賴
npm install

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

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

Option 3: Deploy to Cloudflare Workers

1. Log in to Cloudflare

Run the following in your terminal:

npx wrangler login

The browser will open automatically for Cloudflare account authorization.

If using CI/CD or API Token login:

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

2. Test the Worker locally with simulation

npm run dev:worker

3. Deploy to the Cloudflare global edge network

npm run deploy

After a successful deployment, you will get a dedicated Worker URL (e.g. https://cf-mcp-playground.<your-subdomain>.workers.dev/mcp).

🔌 Using with AI Clients

1. Claude Desktop Configuration

Edit 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 Configuration

In the Cursor interface, go to Settings -> Features -> MCP Servers -> Add New MCP Server:

• Name: cf-mcp-service

• Type: sse

• URL: http://localhost:3000/sse (local Docker) or https://<your-worker>.workers.dev/sse (remote Worker)

🧪 Test Verification Examples

1. Test the REST API with a question (first question - Cache MISS)

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

2. Test with the same question (repeated question - Cache HIT ⚡)

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

3. View cache statistics

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