cf-mcp-playground

Сервис Model Context Protocol (MCP) с двойной средой выполнения: Cloudflare Worker и Docker. Встроенная база знаний 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.

   • Поддержка автоматического переключения на кэш в памяти (Memory Fallback) при обрыве соединения с Redis для обеспечения высокой доступности.

🛠️ 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 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. Развертывание на глобальной Edge-сети Cloudflare

npm run deploy

После успешного развертывания вы получите专属 URL Worker (например, 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