chess-mcp

# Chess MCP Server A Model Context Protocol (MCP) server that provides an interactive chess game experience using MCP-UI. This server exposes chess game functionality through MCP tools and provides a web-based chessboard interface for playing games. ## Features - ♟️ **Full Chess Game**: Complete chess implementation using chess.js - 🔧 **MCP Tools**: Chess game actions exposed as MCP tools - 🎮 **Interactive UI**: Web-based chessboard using ChessBoard.js - 💾 **Game State Management**: Persistent game state with session-based saves ## Workshop In the `./workshop` directory, you can find a step by step to creating this MCP server. ## Architecture This MCP server is built using Express.js with integrated MCP capabilities: ### Key Components - **MCP Server** (`src/server.ts`): Main server with chess tools and UI generation - **Store** (`src/lib/store.ts`): Game state persistence using file system - **MCP Framework** (`src/lib/mcp/`): Custom MCP middleware implementation with Express integration ### MCP Tools Available - `chess_get_board_state`: Get the current state of the chess board with visual representation - `chess_move`: Make a move in standard algebraic notation (e.g., e4, Nf3, O-O) or start a new game ## Getting Started ### Prerequisites - Node.js 18+ - npm ### Installation Install the dependencies: ```bash npm install ``` ### Development Start the development server: ```bash npm run dev ``` The server will be available at: - MCP endpoint: `http://localhost:3000/mcp` ### Development Commands - `npm run dev` - Start development server ## Usage ### As an MCP Server The server exposes MCP tools that can be consumed by MCP clients: ```typescript // Get current board state { "method": "tools/call", "params": { "name": "chess_get_board_state", "arguments": {} } } // Make a move { "method": "tools/call", "params": { "name": "chess_move", "arguments": { "move": "e4" } } } // Start a new game { "method": "tools/call", "params": { "name": "chess_move", "arguments": { "move": "new" } } } ``` ### Interactive Chessboard When using the MCP tools, each response includes: - **Text representation**: ASCII board and FEN notation with valid moves - **Interactive UI**: Drag-and-drop chessboard that allows moves via mouse interaction ## Game Rules - Standard chess rules apply - Uses chess.js for move validation and game logic - Supports all legal chess moves including castling, en passant, and pawn promotion - Game state persists per session ID ## Project Structure ``` src/ ├── lib/ │ ├── mcp/ # Custom MCP middleware framework │ │ ├── index.ts # Main exports │ │ ├── middleware.ts # Express middleware integration │ │ ├── header.ts # HTTP header utilities │ │ └── uuid.ts # UUID validation │ └── store.ts # Game state persistence ├── server.ts # Main server with chess tools and UI games/ # Persistent game files (FEN notation) ``` ## Game State Persistence - Each chess game is saved to a JSON file in the `games/` directory - Games are identified by MCP session ID - Game state is stored as FEN (Forsyth-Edwards Notation) strings - Games automatically resume when reconnecting with the same session ## Dependencies - **chess.js**: Chess game logic and move validation - **@chrisoakman/chessboardjs**: Interactive chessboard UI - **@mcp-ui/server**: MCP UI resource creation - **@modelcontextprotocol/sdk**: MCP server implementation - **express**: Web server framework ## License Apache 2.0 License - see LICENSE file for details.