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

Install Python dependencies:

cd server
pip3 install -r requirements.txt

Install Stockfish (optional, for engine analysis):

# macOS
brew install stockfish

# Ubuntu/Debian
sudo apt-get install stockfish

Install Node.js dependencies:

npm install

Build the frontend component:

npm run build

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

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

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:

Bundles src/chess-board/index.tsx
Includes all dependencies
Wraps in HTML with proper structure
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

Ensure component is built: npm run build
Verify assets/chess-board.html exists
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

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

Install Python dependencies:

cd server
pip3 install -r requirements.txt

Install Stockfish (optional, for engine analysis):

# macOS
brew install stockfish

# Ubuntu/Debian
sudo apt-get install stockfish

Install Node.js dependencies:

npm install

Build the frontend component:

npm run build

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

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:

# 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

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:

Bundles src/chess-board/index.tsx
Includes all dependencies
Wraps in HTML with proper structure
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

Ensure component is built: npm run build
Verify assets/chess-board.html exists
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!

Chess MCP

Chess MCP App

Features

Architecture

Project Structure

Installation

Prerequisites

Setup Steps

Development Workflow

Build Once (Production)

Development Mode (with hot reload)

Serve Built Assets (for testing)

Testing Locally (No ChatGPT Required!)

Option 1: Direct Local Tester (Recommended)

Option 2: HTTP Client

Testing with ChatGPT

Usage

Starting a Game

Making Moves

Additional Commands

MCP Tools

chess_move

chess_stockfish

chess_reset

chess_status ⭐

chess_puzzle ⭐

React Hooks (Apps SDK Patterns)

useOpenAiGlobal(key)

useToolOutput<T>()

useToolResponseMetadata<T>()

useWidgetState<T>(defaultState)

Build System (Vite)

Why Vite?

Build Output

Configuration

Server Architecture

Resource Handling

Tool Metadata

Troubleshooting

Widget Not Rendering

Stockfish Not Found

Build Errors

Server Won't Start

What's New in This Version

✨ Restructured Project

🎣 React Hooks

⚡ Vite Build System

🏗️ Server Improvements

📝 Better Types

Contributing

License

Resources

Chess MCP App

Features

Architecture

Project Structure

Installation

Prerequisites

Setup Steps

Development Workflow

Build Once (Production)

Development Mode (with hot reload)

Serve Built Assets (for testing)

Testing Locally (No ChatGPT Required!)

Option 1: Direct Local Tester (Recommended)

Option 2: HTTP Client

Testing with ChatGPT

Usage

Starting a Game

Making Moves

Additional Commands

MCP Tools

chess_move

chess_stockfish

chess_reset

chess_status ⭐

chess_puzzle ⭐

React Hooks (Apps SDK Patterns)

useOpenAiGlobal(key)

useToolOutput<T>()

`chess_move`

`chess_stockfish`

`chess_reset`

`chess_status` ⭐

`chess_puzzle` ⭐

`useOpenAiGlobal(key)`

`useToolOutput<T>()`

`useToolResponseMetadata<T>()`

`useWidgetState<T>(defaultState)`

`chess_move`

`chess_stockfish`

`chess_reset`

`chess_status` ⭐

`chess_puzzle` ⭐

`useOpenAiGlobal(key)`

`useToolOutput<T>()`

`useToolResponseMetadata<T>()`

`useWidgetState<T>(defaultState)`