Chat Royale

AI-powered Clash Royale agent using Gemini 2.0 with MCP tools for real-time game data access.

Full Technical Deep Dive

I recently wrote a technical breakdown on the architecture, my building process and other cool things about this project. You can read it on my websites here:

Full Technical Deep Dive

Architecture

Three containerized services:

MCP Server (`src/mcp/`) - Python FastMCP server exposing Clash Royale API tools:

• Players, Clans, Cards, Rankings

Backend API (`src/backend/`) - Node.js/Express server:

• Integrates Gemini with MCP client via `@modelcontextprotocol/sdk`
• Standard JSON request/response (no streaming)
• Tool execution handled internally with iterative Gemini calls

Frontend (`src/frontend/`) - React/TypeScript UI:

• Simple chat interface with markdown support
• Standard HTTP requests to backend API

How It Works

1. User sends message to frontend

2. Frontend posts to backend `/api/chat`

3. Backend connects to MCP server and discovers tools

4. Gemini processes message with available tools

5. If tools needed: backend executes via MCP, feeds results back to OpenAI

6. Final response returned as JSON to frontend

Deployment

Production: AWS Lightsail with Cloudflare CDN

CI/CD: GitHub Actions auto-deploy on `main` branch push/merge

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

Development

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

# Run all services
docker-compose up -d

Tech Stack

• MCP Server: Python 3.12, FastMCP, Clash Royale API
• Backend: Node.js, Express, TypeScript, Gemini SDK
• Frontend: React, TypeScript, Vite, TailwindCSS
• Deployment: Docker, AWS Lightsail, Cloudflare, GitHub Actions