cf-mcp-playground

Servicio Model Context Protocol (MCP) con doble entorno de ejecución en Cloudflare Worker y Docker, con base de conocimientos de MCP Skills integrada y mecanismo de aceleración de caché de preguntas con Redis.

🌟 Características principales

1. Doble entorno de ejecución (Dual Runtime):

   • ⛅ Cloudflare Workers: soporta implementación global en el borde (Edge), arranque en frío ultrarrápido y baja latencia.

   • 🐳 Docker y Node.js: proporciona docker-compose.yml para iniciar el servicio MCP y el contenedor Redis con un solo clic.

2. Base de conocimientos de MCP Skills:

   • Explicación completa de qué es MCP y qué es MCP Skill.

   • Comparación detallada de las diferencias y patrones de combinación entre Tools (herramientas), Resources (recursos) y Prompts (indicaciones).

   • Proporciona guías de configuración para los principales clientes (Claude Desktop, Cursor, Zed, Cloudflare).

3. Respuesta instantánea a preguntas repetidas con Redis (Smart Caching):

   • Cuando el usuario hace una pregunta, el sistema normaliza automáticamente la consulta y calcula la clave de caché.

   • Cache HIT (acierto): devuelve directamente los resultados de caché históricos desde Redis en milisegundos, ahorrando significativamente tokens y latencia.

   • Cache MISS (fallo): recupera la base de conocimientos para generar una respuesta completa y la almacena automáticamente en caché en Redis.

   • Admite degradación automática a caché en memoria (Memory Fallback) cuando Redis se desconecta, garantizando alta disponibilidad.

🛠️ Herramientas y capacidades de MCP

🚀 Inicio rápido

Opción 1: Iniciar con Docker (incluye Redis)

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

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

# 停止服務
docker compose down

Una vez iniciado el servicio:

• Página de inicio / panel de control: http://localhost:3000/

• Endpoint de comunicación por streaming MCP: http://localhost:3000/mcp o http://localhost:3000/sse

• Endpoint de verificación de salud: http://localhost:3000/health

• API REST de preguntas y respuestas: POST http://localhost:3000/api/ask

Opción 2: Modo de desarrollo local (Node.js)

# 安裝依賴
npm install

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

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

Opción 3: Implementar en Cloudflare Workers

1. Iniciar sesión en Cloudflare

Ejecuta en la terminal:

npx wrangler login

El navegador se abrirá automáticamente para autorizar la cuenta de Cloudflare.

Si inicias sesión con CI/CD o API Token:

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

2. Probar la simulación local del Worker

npm run dev:worker

3. Implementar en la red global de borde de Cloudflare

npm run deploy

Una vez implementado correctamente, obtendrás la URL exclusiva de tu Worker (por ejemplo, https://cf-mcp-playground.<your-subdomain>.workers.dev/mcp).

🔌 Uso en clientes de IA

1. Configuración de Claude Desktop

Edita 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. Configuración de Cursor

En la interfaz de Cursor, ve a Settings -> Features -> MCP Servers -> Add New MCP Server:

• Name: cf-mcp-service

• Type: sse

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

🧪 Ejemplos de prueba y verificación

1. Probar la API REST de preguntas (primera pregunta - Cache MISS)

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

2. Probar la misma pregunta (pregunta repetida - Cache HIT ⚡)

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

3. Consultar estadísticas de caché

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