Chess MCP (Model Context Protocol)

A powerful chess engine and game server built with the Model Context Protocol (MCP). Play chess against AI, analyze positions, and integrate chess functionality into your AI applications.

🎯 Features

Core Chess Engine

• Full Chess Rules: Complete implementation of all chess rules including castling, en passant, and pawn promotion
• Move Validation: Automatic validation of all chess moves
• Game State Tracking: Track check, checkmate, stalemate, and draw conditions
• Move History: Complete move history with algebraic notation

Multiple Game Modes

• Human vs Human: Classic two-player chess
• Human vs AI: Play against computer with adjustable difficulty (1-5 levels)
• AI vs AI: Watch AI play against itself

Advanced AI Features

• Smart AI Engine: Minimax algorithm with alpha-beta pruning
• Transposition Tables: 2-5x performance improvement through position caching
• Iterative Deepening: Progressive depth search with optimal time management
• Memory Optimization: LRU eviction and controlled memory usage
• 5 Difficulty Levels: From beginner (random) to expert (depth 8)
• Automatic Play: AI responds automatically in human-vs-ai mode
• Manual Control: Use ai command for manual AI moves
• Position Analysis: AI can analyze positions and suggest best moves

Advanced Features

• Position Analysis: Analyze positions and get best move suggestions
• FEN Support: Load and save positions using FEN notation
• PGN Support: Import and export games in PGN format
• Move Undo: Undo moves to explore variations
• Legal Move Display: Show all legal moves for any position

Beautiful UI

• ASCII Chess Board: Clean, readable board representation with Unicode chess pieces
• Color-coded Output: Different colors for different types of information
• Interactive Commands: Easy-to-use command system
• Real-time Status: Live game status updates

🚀 Installation

Prerequisites

• Node.js 18+
• npm or yarn

Setup

# Clone the repository
git clone <repository-url>
cd Chess-MCP

# Install dependencies
npm install

# No build step needed - uses tsx for direct TypeScript execution

📖 Usage

Interactive CLI Mode (Recommended for Playing)

Start playing chess immediately:

# Start the interactive chess interface
npm run cli

# You'll see the chess prompt: chess>
# Type 'help' to see all available commands

As an MCP Server

The chess MCP can be integrated into any MCP-compatible client:

# Run the MCP server directly with tsx
npx tsx src/index.ts

# Or use the npm script
npm start

📚 Documentation

For detailed documentation, see the docs folder:

• Documentation Overview - Complete documentation index
• Quick Start Guide - Get up and running quickly
• User Guide - Complete user manual
• Developer Guide - For developers and contributors
• API Reference - Complete API documentation
• Architecture - System architecture and design
• AI Implementation - Chess AI details
• Testing Guide - Testing and quality assurance
• Performance Guide - Performance optimization
• Project Analysis - Detailed project analysis
• MCP Setup - Model Context Protocol setup
• Cool Features - Advanced features showcase

🎮 Available Commands

Basic Game Commands

• move <move> - Make a move (e.g., move e2e4, move Nf3)
• board - Display the current board
• status - Show game status
• history - Show move history
• undo - Undo the last move
• reset - Reset to starting position

Analysis Commands

• moves <square> - Show legal moves for a square (e.g., moves e2)
• all-moves - Show all legal moves
• analyze [depth] - Analyze position (default depth: 3)

Game Mode Commands

• mode <type> [ai-level] - Set game mode:
  • mode human-vs-human - Two human players
  • mode human-vs-ai 3 - Play against AI (level 1-5)
  • mode ai-vs-ai 5 - Watch AI play against itself
• ai - Make AI play a move (for manual control)

Import/Export Commands

• fen <position> - Load position from FEN
• pgn <game> - Load game from PGN
• save - Save current game to PGN

🔧 MCP Tools

The chess MCP provides the following tools for AI integration:

Game Management

• start_new_game - Start a new game with specified mode
• reset_game - Reset to starting position
• get_game_status - Get current game status

Move Operations

• make_move - Make a chess move
• get_legal_moves - Get legal moves for a square or all pieces
• undo_move - Undo the last move

Board and Analysis

• get_board_state - Get current board state
• analyze_position - Analyze position and suggest moves
• get_move_history - Get complete move history

AI Features

• ai_move - Make AI play a move
• load_position - Load position from FEN
• save_game - Save game to PGN
• load_game - Load game from PGN

🎯 Example Usage

Playing Against AI

Quick Start:

# Start the interactive CLI
npm run cli

# Set up Human vs AI (Level 2 - moderate difficulty)
chess> mode human-vs-ai 2

# Make your first move
chess> move e2e4
# AI automatically responds!

# Continue playing
chess> move g1f3
# AI automatically responds!

# Check the board
chess> board

# See game status
chess> status

AI Difficulty Levels:

• Level 1: Random moves (perfect for beginners)
• Level 2: Basic strategy (good for casual play)
• Level 3: Moderate difficulty (challenging)
• Level 4: Advanced strategy (very challenging)
• Level 5: Expert level (extremely challenging)

Manual AI Control:

# Set mode but control when AI plays
chess> mode human-vs-ai 3
chess> move e2e4
chess> ai  # Tell AI to play now
chess> move g1f3
chess> ai  # Tell AI to play again

Watch AI vs AI:

chess> mode ai-vs-ai 3
chess> ai  # First AI move
chess> ai  # Second AI move
chess> ai  # Continue watching...

Starting a Game

chess> mode human-vs-ai 3
Game mode set to: human-vs-ai (AI level: 3)

chess> move e2e4
Move e2e4 made successfully!

  Chess Board
    a b c d e f g h
  ┌─────────────────┐
 8│ ♜ ♞ ♝ ♛ ♚ ♝ ♞ ♜ │ 8
 7│ ♟ ♟ ♟ ♟ ♟ ♟ ♟ ♟ │ 7
 6│ · · · · · · · · │ 6
 5│ · · · · · · · · │ 5
 4│ · · · · ♙ · · · │ 4
 3│ · · · · · · · · │ 3
 2│ ♙ ♙ ♙ ♙ · ♙ ♙ ♙ │ 2
 1│ ♖ ♘ ♗ ♕ ♔ ♗ ♘ ♖ │ 1
  └─────────────────┘
    a b c d e f g h

Current turn: Black

AI played: e7e5

Analyzing a Position

chess> analyze 4
Position Analysis (Depth: 4):
Evaluation: +0.3

Best moves:
1. Nf3
2. Nc3
3. d4

Getting Legal Moves

chess> moves e2
Legal moves for e2:
1. e3
2. e4

🏗️ Architecture

The chess MCP is built with a modular architecture:

• ChessEngine: Core chess logic using chess.js
• ChessUI: User interface and display logic
• ChessAI: AI opponent with minimax algorithm
• ChessMCPServer: MCP protocol implementation
• InteractiveCLI: Local testing interface

🎨 User Experience Tips

Making it Cooler from a User Perspective

1. Visual Appeal

   • Beautiful Unicode chess pieces
   • Color-coded output for different information types
   • Clean, readable board layout

2. Ease of Use

   • Simple, intuitive commands
   • Helpful error messages
   • Auto-completion suggestions

3. Advanced Features

   • Position analysis with evaluation scores
   • Multiple AI difficulty levels
   • Game import/export capabilities

4. Interactive Elements

   • Real-time game status updates
   • Move validation with helpful feedback
   • Undo functionality for exploration

5. Educational Value

   • Legal move highlighting
   • Position analysis explanations
   • Move history tracking

🔮 Future Enhancements

• Web Interface: Browser-based chess interface
• Opening Database: Built-in opening book
• Endgame Tablebases: Perfect endgame play
• Network Play: Multiplayer over network
• Tournament Mode: Round-robin tournaments
• Puzzle Mode: Chess puzzles and tactics
• Voice Commands: Voice-controlled chess
• Mobile App: iOS/Android chess app

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• chess.js - Chess logic library
• Model Context Protocol - MCP specification
• Unicode chess symbols for beautiful display

🔧 Troubleshooting

Common Issues

"Command not found: npm"

• Make sure Node.js is installed: node --version
• Install Node.js from nodejs.org

"Cannot find module" errors

• Run npm install to install dependencies
• Run npm run build to compile TypeScript

Interactive CLI not starting

• Use npm run cli (not npm run dev)
• Make sure you're in the Chess-MCP directory

AI not responding

• Check game mode: mode human-vs-ai 2
• In human-vs-ai mode, AI responds automatically
• Use ai command for manual AI moves

Move not working

• Check legal moves: moves <square>
• Use correct format: move e2e4 or move Nf3
• Check game status: status

Getting Help

• Type help in the chess CLI for command list
• Use status to see current game state
• Use moves <square> to see legal moves
• Use undo if you make a mistake

---

Happy Chess Playing! ♔♕♖♗♘♙