README.md

---
title: Tic-Tac-Toe MCP Server
emoji: 🎮
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
---

# 🎮 Tic-Tac-Toe MCP Server for LeChat

A sophisticated tic-tac-toe game server with **MCP (Model Context Protocol)** integration for use with LeChat.

## 🚀 Features

- **MCP Tools Integration** - Direct use with LeChat via MCP
- **Room-based Gameplay** - Multiple isolated game sessions  
- **AI Opponent** - Powered by Mistral AI with personality
- **Real-time Chat** - Interactive conversations with the AI
- **Live Markdown State** - Perfect representation for AI consumption
- **Multi-room Support** - Create and switch between multiple games

## 🔧 MCP Tools Available

### Core Game Tools
- `create_room()` - Create a new tic-tac-toe game room
- `make_move(position)` - Make your move (0-8) and get AI response
- `send_chat(message)` - Chat with Mistral AI in your game
- `get_room_state()` - Get current game state in markdown
- `list_rooms()` - See all your active games
- `switch_room(room_id)` - Change between games

### Utility Tools  
- `get_help()` - Game instructions and board layout
- `wait_5_seconds()` - Timing utility for operations

## 🎯 How to Play with LeChat

1. **Connect to this MCP server** in LeChat
2. **Start a game**: `create_room()`
3. **Make moves**: `make_move(4)` (center square)
4. **Chat with AI**: `send_chat("Good move!")`
5. **Check state**: `get_room_state()`

### Board Layout (Positions 0-8):
```
0 | 1 | 2
---------
3 | 4 | 5  
---------
6 | 7 | 8
```

## 📋 Example Game Flow

```python
# Start a new game
create_room()
# Output: Created room abc12345, you are X, AI is O

# Make your first move (center)
make_move(4)
# Output: You played X at 4, AI played O at 2 with trash talk!

# Chat with the AI
send_chat("Nice try, but I've got this!")
# Output: Your message + AI's witty response

# Check current state anytime
get_room_state()
# Output: Full markdown representation of game
```

## 📊 Markdown State Format

The AI receives game state in this format:
```markdown
# Game Room: abc12345
## Status: Your turn (X to play)
Moves: 4/9

```
 X |   | O 
-----------
   | X |   
-----------
 O |   |   
```

## Recent Chat
**You:** Nice try!
**Mistral AI:** Just wait and see! 😏
```

## 🔐 Setup Requirements

1. **Mistral API Key**: Required for AI functionality
   - Get from [console.mistral.ai](https://console.mistral.ai)
   - Set as `MISTRAL_API_KEY` environment variable

2. **MCP Connection**: Configure in LeChat
   - Server URL: This Hugging Face Space URL
   - Transport: SSE (Server-Sent Events)
   - Port: 7860

## 🌐 Web UI (Optional)

While designed for MCP, there's also a web interface at `/rooms-ui` for testing and manual play.

## 🏗️ Technical Details

- **Backend**: Python Flask + FastMCP
- **AI**: Mistral AI with competitive personality
- **Protocol**: MCP (Model Context Protocol)
- **Transport**: SSE for real-time communication
- **State Management**: In-memory room storage
- **Format**: Markdown for AI-friendly representation

## 🎮 Game Features

- **Competitive AI**: Mistral trash talks and celebrates
- **Multiple Rooms**: Play several games simultaneously  
- **Chat Integration**: Full conversation with game context
- **State Persistence**: Games persist during session
- **Error Handling**: Graceful handling of invalid moves
- **Turn Management**: Automatic turn switching and validation

## 🤖 Perfect for AI Assistants

This MCP server is specifically designed for LeChat:
- **Structured Output**: All responses in consistent JSON format
- **Markdown Representation**: Perfect for AI understanding
- **Context Preservation**: Room state maintained between calls
- **Error Messages**: Clear feedback for invalid operations
- **Multi-session**: Each AI conversation can have multiple games

## 🚀 Get Started

1. **In LeChat**: Connect to this MCP server
2. **Type**: `create_room()` to start your first game
3. **Play**: Use `make_move(position)` to play
4. **Enjoy**: Chat and compete with Mistral AI!

---

**Built for the MCP ecosystem** 🤖 **Ready for AI-powered gaming** 🎮