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