WebMCP Chess Coach

Inspiration

Most chess engines are very good at telling players what the best move is, but not always at helping them understand why.

For beginner and intermediate players, an engine output like +3.2 or a long principal variation can be useful, but it often feels more like an answer sheet than a coach.

I wanted to build something that teaches the player how to think.

That led to WebMCP Chess Coach — an interactive chess-learning experience where an AI agent can inspect the live board, analyse the position with Stockfish, and then teach directly on the board using highlights, arrows, candidate lines, and short coaching guidance.

The goal is simple:

do not just reveal the move — help the player notice the idea.

What it does

The user can play or analyse a chess position and then ask natural-language questions such as:

• "What am I missing here?"
• "Give me a hint, but don't tell me the answer."
• "Show me the threat."
• "Why was my last move bad?"
• "Show me the candidate line."

The agent can then use WebMCP tools exposed by the page to understand and interact with the chessboard.

The current toolset includes:

• get_board_state — reads the current FEN, side to move, game state, and legal moves
• evaluate_position — analyses the live position using Stockfish running locally in WebAssembly
• get_move_history — reviews how the current position was reached
• highlight_squares — draws attention to important pieces or squares
• show_move_arrow — visually demonstrates a move or threat
• show_candidate_line — displays a legal continuation without changing the real game
• clear_annotations — removes agent-created visual annotations
• show_coach_message — displays coaching guidance directly inside the website

This creates a loop where the agent can read, analyse, explain, and visually teach on the same interface the player is using.

Why WebMCP

WebMCP is a strong fit for this project because chess coaching is not just a text problem.

An AI model can describe a chess position, but the experience becomes much more useful when the agent can interact with the board itself.

Instead of saying:

"Your queen on h5 is hanging."

the agent can:

1. inspect the current board
2. analyse it with Stockfish
3. highlight f6 and h5
4. draw the move arrow from f6 to h5
5. show the continuation only if the player asks for it

That turns the website into an agent-native teaching surface rather than a static chessboard with a chatbot beside it.

How I built it

The frontend is built with React, TypeScript, and Vite.

react-chessboard renders the interactive board, while chess.js acts as the authoritative game state and validates all legal moves.

For engine analysis, I use Stockfish 18 compiled to WebAssembly, running entirely client-side inside a Web Worker. This keeps the UI responsive and avoids requiring a backend for chess analysis.

The engine receives the current FEN through the UCI protocol and returns:

• evaluation
• search depth
• best move
• principal variation

The WebMCP layer is implemented using document.modelContext.registerTool(). Each tool connects an agent capability to either the chess state, Stockfish, or React UI state.

For example:

User asks a question
        ↓
get_board_state
        ↓
evaluate_position
        ↓
Stockfish WASM
        ↓
highlight_squares / show_move_arrow
        ↓
React chessboard updates visually

The real chess position is never mutated by coaching annotations. Candidate lines are validated on a temporary chess.js instance before they are displayed.

Elo-aware coaching

The interface also includes a player-level selector so the experience can be adapted for different skill levels.

A lower-rated player may need a guided hint such as:

"Before calculating your attack, check whether any of your pieces can be captured."

while a stronger player may prefer something more direct:

"Your queen is loose. Nxh5 wins material."

The long-term idea is for the same position to be taught differently depending on the player's level and preferred coaching style.

Challenges

One of the biggest challenges was connecting several independent systems cleanly:

• React UI state
• chess.js
• Stockfish WASM
• Web Workers
• WebMCP tool registration
• agent-triggered board annotations

The most important architectural decision was keeping a single authoritative chess state and making all coaching visuals non-destructive.

Another challenge was making WebMCP tools useful beyond simple data retrieval. The project became much more interesting once the agent could not only read the position, but also visually modify the teaching interface through highlights, arrows, and coaching messages.

I also had to handle browser-specific WebMCP behaviour, tool registration lifecycles, argument serialization during testing, and Stockfish's UCI messaging.

What I learned

This project changed how I think about agent interfaces.

The most useful agent experiences are not necessarily ones where an AI replaces the interface. In this case, the board remains important because chess is fundamentally spatial and visual.

WebMCP lets the agent and the user share the same interface:

• the human moves pieces normally
• the agent understands the exact live state
• the engine provides reliable chess analysis
• the agent decides how to teach
• the website visualises the explanation

That combination feels much closer to an actual coach than a traditional engine window.

What's next

The next steps would be:

• deeper Elo-adaptive coaching
• progressive hint levels
• automatic post-game review
• puzzle and training modes
• stronger mistake classification
• opening and endgame-specific coaching
• personalised learning based on recurring mistakes

The broader goal is to make engine-strength chess analysis easier to learn from, especially for players who understand the rules but still struggle to understand what the engine is trying to teach them.

Built With

• ai
• chatgpt
• chess
• chess.js
• css
• html
• javascript
• react
• react-chessboard
• stockfish
• typescript
• vite
• web-workers
• webassembly
• webmcp