Clash Royale MCP Server

Chat Royale

Gemini 2.0 と MCP ツールを活用し、リアルタイムのゲームデータにアクセスする AI 搭載の Clash Royale エージェントです。

技術的な詳細解説

このプロジェクトのアーキテクチャや構築プロセス、そのほか興味深い点について、技術的な解説記事を書きました。以下のウェブサイトでご覧いただけます。

技術的な詳細解説

アーキテクチャ

3 つのコンテナ化されたサービスで構成されています。

MCP サーバー（src/mcp/）- Clash Royale API ツールを公開する Python FastMCP サーバー：

• プレイヤー、クラン、カード、ランキング

バックエンド API（src/backend/）- Node.js/Express サーバー：

• @modelcontextprotocol/sdk を介して Gemini と MCP クライアントを統合
• 標準的な JSON リクエスト／レスポンス（ストリーミングなし）
• ツールの実行は、Gemini を反復的に呼び出して内部で処理

フロントエンド（src/frontend/）- React/TypeScript UI：

• Markdown に対応したシンプルなチャットインターフェース
• バックエンド API への標準的な HTTP リクエスト

動作の仕組み

1. ユーザーがフロントエンドにメッセージを送信します
2. フロントエンドがバックエンドの /api/chat に POST します
3. バックエンドが MCP サーバーに接続し、ツールを検出します
4. Gemini が利用可能なツールを使ってメッセージを処理します
5. ツールが必要な場合：バックエンドが MCP 経由で実行し、結果を OpenAI に返します
6. 最終応答が JSON としてフロントエンドに返されます

デプロイ

本番環境：Cloudflare CDN を使用した AWS Lightsail

CI/CD：main ブランチへのプッシュ／マージ時に GitHub Actions で自動デプロイ

# Deploy
docker-compose -f docker-compose.prod.yml up -d --build

開発

# Environment setup
# Backend: src/backend/.env - GEMINI_API_KEY
# MCP: src/mcp/.env - CR_API_KEY

# Run all services
docker-compose up -d

技術スタック

• MCP サーバー：Python 3.12、FastMCP、Clash Royale API
• バックエンド：Node.js、Express、TypeScript、Gemini SDK
• フロントエンド：React、TypeScript、Vite、TailwindCSS
• デプロイ：Docker、AWS Lightsail、Cloudflare、GitHub Actions