cf-mcp-playground

Cloudflare Worker と Docker の二重実行環境を備えた Model Context Protocol (MCP) サービスで、MCP Skills ナレッジベース と Redis 質問キャッシュ高速化 メカニズムを内蔵しています。

🌟 コア機能

1. 二重実行環境 (Dual Runtime)：

   • ⛅ Cloudflare Workers: エッジでのグローバル展開をサポートし、超高速コールドスタートと低遅延を実現します。

   • 🐳 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 ツールと機能

🚀 クイックスタート

方法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