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:

cd server
pip3 install -r requirements.txt

2. Install Stockfish (optional, for engine analysis):

# macOS
brew install stockfish

# Ubuntu/Debian
sudo apt-get install stockfish

3. Install Node.js dependencies:

npm install

4. Build the frontend component:

npm run build

This generates assets/chess-board.html which the server loads.

5. The MCP server is configured in your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "chess": {
      "command": "python3",
      "args": ["/path/to/ChessMCP/server/main.py"],
      "env": {
        "PYTHONPATH": "/path/to/ChessMCP/server"
      }
    }
  }
}

Development Workflow

Build Once (Production)

npm run build

Development Mode (with hot reload)

# Terminal 1: Start Vite dev server
npm run dev

# Terminal 2: Start Python server
cd server
python3 main.py

Serve Built Assets (for testing)

npm run serve

Testing Locally (No ChatGPT Required!)

Option 1: Direct Local Tester (Recommended)

Play chess directly without server/OAuth:

python3 chess_local_test.py

Commands:

♟️  > move e4
♟️  > move e5
♟️  > status
♟️  > stockfish
♟️  > puzzle medium

📖 See: LOCAL_TESTING.md

Option 2: HTTP Client

Test via HTTP (requires server running):

# Terminal 1: Start server
cd server && python3 main.py

# Terminal 2: Start client
python3 chess_client.py

📖 See: 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 (5 minutes)
📖 Detailed Setup: GOOGLE_OAUTH_SETUP.md (Step-by-step)
📖 Next Steps: NEXT_STEPS.md (What to do now)
📖 Troubleshooting: CHATGPT_CONNECTOR_TROUBLESHOOTING.md

Quick start:

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

const theme = useOpenAiGlobal("theme");
const displayMode = useOpenAiGlobal("displayMode");

useToolOutput<T>()

Get the current tool output:

const toolOutput = useToolOutput<ChessToolOutput>();
// Returns: { fen, move, status, turn }

useToolResponseMetadata<T>()

Get tool response metadata:

const metadata = useToolResponseMetadata<ChessMetadata>();
// Returns: { move_history_list, legal_moves, etc. }

useWidgetState<T>(defaultState)

Persist component state across sessions:

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:

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

{
    "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:

STOCKFISH_PATH = "/path/to/stockfish"

Build Errors

If TypeScript errors occur:

npm run typecheck

Server Won't Start

Make sure all Python dependencies are installed:

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
• Apps SDK Examples
• python-chess Documentation
• chess.js
• react-chessboard