# 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:

```bash
npm install
```

### Development

Start the development server:

```bash
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:

```bash
npm run build
```

Start the production server:

```bash
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:

```typescript
// 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:

```bash
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.