Chess MCP

# Chess MCP App A ChatGPT Chess application built with OpenAI Apps SDK, allowing you to play chess through conversation with an interactive board widget. **Now following OpenAI Apps SDK best practices!** ## Features - 🎮 Play chess using algebraic notation (e4, Nf3, O-O, etc.) - 📊 Interactive chess board widget in ChatGPT - 🤖 AI opponent suggestions (ChatGPT can play moves) - 🔍 Stockfish engine analysis integration - 📝 Move history tracking - ✅ Full move validation and game state management - 📋 Game status and player information display - 🧩 Mate in 1 tactical puzzles (Easy, Medium, Hard) ## Architecture - **Backend**: Python MCP Server using FastMCP with python-chess - **Frontend**: React component with chess.js + react-chessboard - **Build System**: Vite for optimal development experience - **Integration**: OpenAI Apps SDK patterns with proper hooks ## Project Structure ``` ChessMCP/ ├── server/ │ ├── main.py # Python MCP server (renamed from server.py) │ └── requirements.txt # Python dependencies ├── src/ │ ├── chess-board/ # Chess board component │ │ └── index.tsx │ ├── types.ts # Shared TypeScript types │ ├── use-openai-global.ts # Hook for window.openai access │ ├── use-widget-state.ts # Hook for widget state │ └── use-widget-props.ts # Hook for tool props ├── assets/ # Build output (generated by Vite) │ └── chess-board.html ├── vite.config.mts # Vite configuration ├── package.json # Root dependencies ├── tsconfig.json # TypeScript config └── README.md ``` ## Installation ### Prerequisites - Python 3.8+ - Node.js 18+ - Stockfish chess engine (optional, for analysis) ### Setup Steps 1. **Install Python dependencies**: ```bash cd server pip3 install -r requirements.txt ``` 2. **Install Stockfish** (optional, for engine analysis): ```bash # macOS brew install stockfish # Ubuntu/Debian sudo apt-get install stockfish ``` 3. **Install Node.js dependencies**: ```bash npm install ``` 4. **Build the frontend component**: ```bash npm run build ``` This generates `assets/chess-board.html` which the server loads. 5. **The MCP server is configured** in your `~/.cursor/mcp.json`: ```json { "mcpServers": { "chess": { "command": "python3", "args": ["/path/to/ChessMCP/server/main.py"], "env": { "PYTHONPATH": "/path/to/ChessMCP/server" } } } } ``` ## Development Workflow ### Build Once (Production) ```bash npm run build ``` ### Development Mode (with hot reload) ```bash # Terminal 1: Start Vite dev server npm run dev # Terminal 2: Start Python server cd server python3 main.py ``` ### Serve Built Assets (for testing) ```bash npm run serve ``` ## Testing Locally (No ChatGPT Required!) ### Option 1: Direct Local Tester (Recommended) Play chess directly without server/OAuth: ```bash python3 chess_local_test.py ``` Commands: ``` ♟️ > move e4 ♟️ > move e5 ♟️ > status ♟️ > stockfish ♟️ > puzzle medium ``` 📖 **See:** [LOCAL_TESTING.md](./LOCAL_TESTING.md) ### Option 2: HTTP Client Test via HTTP (requires server running): ```bash # Terminal 1: Start server cd server && python3 main.py # Terminal 2: Start client python3 chess_client.py ``` 📖 **See:** [CLIENT_USAGE.md](./CLIENT_USAGE.md) ## Testing with ChatGPT The Chess MCP server now includes **Google OAuth 2.1 authentication** for secure ChatGPT integration! 📖 **Quick Start:** [OAUTH_QUICK_START.md](./OAUTH_QUICK_START.md) (5 minutes) 📖 **Detailed Setup:** [GOOGLE_OAUTH_SETUP.md](./GOOGLE_OAUTH_SETUP.md) (Step-by-step) 📖 **Next Steps:** [NEXT_STEPS.md](./NEXT_STEPS.md) (What to do now) 📖 **Troubleshooting:** [CHATGPT_CONNECTOR_TROUBLESHOOTING.md](./CHATGPT_CONNECTOR_TROUBLESHOOTING.md) Quick start: ```bash # 1. Set up Google OAuth credentials (see GOOGLE_OAUTH_SETUP.md) # 2. Create server/.env with credentials # Terminal 1: Start server cd server pip3 install -r requirements.txt python3 main.py # Terminal 2: Expose with ngrok ngrok http 8000 # Update server/.env with ngrok URL, restart server # Then add connector in ChatGPT Settings > Connectors # URL format: https://YOUR-SUBDOMAIN.ngrok-free.app (no /mcp suffix) ``` ## Usage ### Starting a Game In ChatGPT, start a chess game by making your first move: ``` ChessMCP e4 ``` or ``` Let's play chess! I'll start with e4 ``` The interactive chess board will appear showing your move. ### Making Moves Simply type your move in algebraic notation: ``` Nf3 e5 Bc4 Nc6 ``` Supported notation: - Basic moves: `e4`, `Nf3`, `d5` - Captures: `exd5`, `Nxf7` - Castling: `O-O` (kingside), `O-O-O` (queenside) - Pawn promotion: `e8=Q`, `a1=N` - Check: `Qh5+` - Checkmate: `Qf7#` ### Additional Commands **Check game status:** ``` chess_status What's the current status? ``` **Load a puzzle:** ``` Show me a chess puzzle Give me a hard puzzle ``` **Get engine analysis:** ``` Ask Stockfish for the best move ``` **Reset game:** ``` chess_reset Let's start a new game ``` ## MCP Tools The server exposes five tools: ### `chess_move` - **Input**: `move` (string) - Algebraic notation - **Output**: Updated board state with FEN, move history, game status - **Widget**: Renders interactive chess board ### `chess_stockfish` - **Input**: `depth` (int, default: 15) - Analysis depth - **Output**: Best move, evaluation, principal variation - **Widget Accessible**: Can be called from the widget UI ### `chess_reset` - **Input**: None - **Output**: Confirmation of reset - **Widget**: Shows fresh starting position ### `chess_status` ⭐ - **Input**: None - **Output**: Game status, current turn, player names, move count, recent moves - **Use**: Check game progress and who's moving ### `chess_puzzle` ⭐ - **Input**: `difficulty` (string: "easy", "medium", "hard") - **Output**: Mate-in-1 puzzle position with hint - **Widget**: Shows puzzle position on the board - **Use**: Practice tactical patterns and checkmate recognition ## React Hooks (Apps SDK Patterns) The component uses OpenAI Apps SDK hooks for clean, reactive code: ### `useOpenAiGlobal(key)` Access window.openai properties reactively: ```tsx const theme = useOpenAiGlobal("theme"); const displayMode = useOpenAiGlobal("displayMode"); ``` ### `useToolOutput<T>()` Get the current tool output: ```tsx const toolOutput = useToolOutput<ChessToolOutput>(); // Returns: { fen, move, status, turn } ``` ### `useToolResponseMetadata<T>()` Get tool response metadata: ```tsx const metadata = useToolResponseMetadata<ChessMetadata>(); // Returns: { move_history_list, legal_moves, etc. } ``` ### `useWidgetState<T>(defaultState)` Persist component state across sessions: ```tsx const [widgetState, setWidgetState] = useWidgetState<ChessWidgetState>({ lastDepth: 15, analysisVisible: false }); ``` ## Build System (Vite) ### Why Vite? - ⚡️ Fast hot module replacement during development - 📦 Optimized production builds - 🎯 TypeScript support out of the box - 🔧 Better error messages - 🎨 Source maps for debugging ### Build Output The build creates a single HTML file containing: - Bundled React component - All JavaScript dependencies - Inline CSS - Proper structure for Skybridge runtime ### Configuration See `vite.config.mts` for the build configuration. The setup: 1. Bundles `src/chess-board/index.tsx` 2. Includes all dependencies 3. Wraps in HTML with proper structure 4. Outputs to `assets/chess-board.html` ## Server Architecture ### Resource Handling The server follows Apps SDK patterns: ```python # Load HTML from assets @lru_cache(maxsize=None) def load_widget_html(component_name: str) -> str: html_path = ASSETS_DIR / f"{component_name}.html" return html_path.read_text(encoding="utf8") # Proper MIME type MIME_TYPE = "text/html+skybridge" # Resource registration @mcp._mcp_server.list_resources() async def list_resources() -> List[types.Resource]: return [types.Resource(...)] # Resource handler async def handle_read_resource(req) -> types.ServerResult: html = load_widget_html("chess-board") return types.ServerResult(types.ReadResourceResult(...)) ``` ### Tool Metadata All tools include proper metadata: ```python { "openai/outputTemplate": "ui://widget/chess-board.html", "openai/widgetAccessible": True, "openai/resultCanProduceWidget": True, "openai/toolInvocation/invoking": "Making move...", "openai/toolInvocation/invoked": "Move played" } ``` ## Troubleshooting ### Widget Not Rendering 1. Ensure component is built: `npm run build` 2. Verify `assets/chess-board.html` exists 3. Check server logs for errors ### Stockfish Not Found Update the path in `server/main.py`: ```python STOCKFISH_PATH = "/path/to/stockfish" ``` ### Build Errors If TypeScript errors occur: ```bash npm run typecheck ``` ### Server Won't Start Make sure all Python dependencies are installed: ```bash cd server pip3 install -r requirements.txt ``` ## What's New in This Version ### ✨ Restructured Project - Moved from `web/` to `src/` directory - Root-level `package.json` and `vite.config.mts` - Proper Apps SDK project structure ### 🎣 React Hooks - `useOpenAiGlobal` for reactive window.openai access - `useWidgetState` for persistent state management - `useToolOutput` and `useToolResponseMetadata` for props ### ⚡ Vite Build System - Replaced esbuild with Vite - Hot module replacement in development - Better TypeScript support - Faster builds ### 🏗️ Server Improvements - Proper resource loading from `assets/` - Correct MIME type (`text/html+skybridge`) - Better error handling - CORS middleware for development ### 📝 Better Types - Comprehensive TypeScript types - Apps SDK-compatible interfaces - Chess-specific type definitions ## Contributing Feel free to enhance the app with: - Opening analysis and endgame tablebases - Multiple game sessions - PGN import/export - Time controls - Online multiplayer - More puzzle types ## License MIT License - feel free to use and modify! ## Resources - [OpenAI Apps SDK Documentation](https://developers.openai.com/apps-sdk) - [Apps SDK Examples](https://github.com/openai/openai-apps-sdk-examples) - [python-chess Documentation](https://python-chess.readthedocs.io/) - [chess.js](https://github.com/jhlywa/chess.js) - [react-chessboard](https://github.com/Clariity/react-chessboard)