nanobot-ai/blackjack

Blackjack MCP Server

A Model Context Protocol (MCP) server that provides an interactive blackjack game experience using MCP-UI. This server exposes blackjack game functionality through MCP tools and provides a web-based UI for playing the game.

Features

• 🃏 Full Blackjack Game: Complete blackjack implementation with standard rules
• 🔧 MCP Tools: Blackjack game actions exposed as MCP tools
• 🎮 Interactive UI: React-based web interface using MCP-UI
• 📱 Responsive Design: Mobile-friendly interface that scales appropriately
• 🎨 Realistic Cards: Beautiful card designs with gradients and shadows
• 💰 Game State Management: Persistent game state and money tracking
• ⚡ Real-time Updates: Live game state synchronization

Architecture

This MCP server is built using a full-stack React Router application with integrated MCP capabilities:

Key Components

• MCP Tools (src/tools/): Game actions exposed as MCP tools for external clients
• UI Routes (src/ui/routes/): React Router components for the web interface
• Game Engine (src/lib/game.ts): Core blackjack game logic and state management
• MCP Framework (src/framework/): Custom MCP server implementation with Express integration

MCP Tools Available

• blackjack-new-game: Start a new blackjack game
• blackjack-hit: Hit (take another card)
• blackjack-stand: Stand (end turn)
• blackjack-double: Double down
• blackjack-split: Split pairs
• blackjack-surrender: Surrender hand
• blackjack-take-insurance: Take insurance bet
• blackjack-decline-insurance: Decline insurance

Getting Started

Prerequisites

• Node.js 18+
• npm or pnpm

Installation

Install the dependencies:

npm install

Development

Start the development server:

npm run dev

The server will be available at:

• Web UI: http://localhost:5173/game/:id
• MCP endpoint: http://localhost:5173/mcp

Building for Production

Create a production build:

npm run build

Start the production server:

npm run start

Development Commands

• npm run dev - Start development server with HMR
• npm run build - Create production build
• npm run start - Run production server
• npm run typecheck - Run TypeScript type checking
• npm run lint - Run ESLint and Prettier checks
• npm run format - Format code with Prettier

Usage

As a Web Application

1. Navigate to http://localhost:5173
2. Click "Deal Cards" to start a new game
3. Use the action buttons to play (Hit, Stand, Double, etc.)
4. Game state persists across sessions

As an MCP Server

The server exposes MCP tools that can be consumed by MCP clients:

// Example MCP tool call
{
  "method": "tools/call",
  "params": {
    "name": "blackjack-new-game",
    "arguments": {
      "bet": 10
    }
  }
}

Game Rules

• Standard blackjack rules apply
• Dealer stands on 17
• Blackjack pays 3:2
• Insurance pays 2:1
• Double down allowed on any first two cards
• Split allowed on pairs
• Surrender allowed

Project Structure

src/
├── framework/          # Custom MCP framework
│   ├── mcp-server.ts   # MCP server implementation
│   └── middleware.ts   # Express middleware integration
├── lib/               # Utility libraries
│   ├── game.ts        # Core blackjack game logic
│   ├── db.ts          # Game state persistence
│   └── shell.ts       # Shell execution utilities
├── tools/             # MCP tools definitions
│   ├── index.ts       # Tool exports
│   └── blackjack.ts   # Blackjack game tools
└── ui/               # React Router frontend
    ├── routes/        # Route components
    │   └── blackjack.tsx  # Main game interface
    └── welcome/       # Welcome page assets

Deployment

Docker Deployment

Build and run using Docker:

docker build -t blackjack-mcp .
docker run -p 3000:3000 blackjack-mcp

The containerized application can be deployed to any platform supporting Docker:

• AWS ECS
• Google Cloud Run
• Azure Container Apps
• Fly.io
• Railway

Environment Variables

• PORT - Server port (default: 3000 in production, 5173 in development)
• NODE_ENV - Environment mode

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting: npm run lint && npm run typecheck
5. Submit a pull request

License

Apache 2.0 License - see LICENSE file for details.

Built with ❤️ using React Router, MCP, and the engine-blackjack library.