chess-mcp-server 0.1.0__py3-none-any.whl

chess_mcp_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: chess-mcp-server
+Version: 0.1.0
+Summary: A Model Context Protocol (MCP) server for playing Chess with AI Agents.
+Project-URL: Homepage, https://github.com/fritzprix/chess-mcp-server
+Project-URL: Issues, https://github.com/fritzprix/chess-mcp-server/issues
+Author-email: fritzprix <your-email@example.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: fastapi
+Requires-Dist: jinja2
+Requires-Dist: mcp[cli]
+Requires-Dist: python-chess
+Requires-Dist: uvicorn
+Description-Content-Type: text/markdown
+
+# ♟️ Chess MCP Server
+
+**Give your AI Agent eyes to see the board and hands to make the move.**
+
+This is not just a chess API. It's a **Model Context Protocol (MCP)** server designed to let Large Language Models (LLMs) like Claude play chess *agentically*. 
+
+Capable of visualizing the board in real-time HTML, understanding spatial relationships via Markdown, and challenging you with a hybrid difficulty engine (Levels 1-10)—or simply facilitating a game between you and your Agent.
+
+## 🚀 Features
+
+-   **MCP-UI Support**: Interactive HTML board embedded directly in the chat (where supported).
+-   **Hybrid AI Engine**: Adjustable difficulty from "Random Blunderer" (Level 1) to "Minimax Master" (Level 10).
+-   **Agent vs. Agent**: Let two AI personalities battle it out.
+-   **Web Dashboard**: Automatically launches a local sidecar dashboard (`http://localhost:8080`) to monitor all active games.
+
+## 📦 Installation
+
+### Prerequisites
+-   Python 3.10+
+-   An MCP Client (e.g., [Claude Desktop](https://claude.ai/download), [Cursor](https://cursor.sh/))
+
+### 1. Installation
+You can install directly from PyPI:
+
+```bash
+pip install chess-mcp-server
+```
+
+### 2. Configure MCP Client
+
+Add the following to your MCP Client configuration file (e.g., `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "chess": {
+      "command": "uvx",
+      "args": ["chess-mcp-server"]
+    }
+  }
+}
+```
+
+*Alternatively, using pip installation:*
+```json
+{
+  "mcpServers": {
+    "chess": {
+      "command": "python",
+      "args": ["-m", "src.mcp_server"]
+    }
+  }
+}
+```
+
+## 🛠️ Development
+
+If you want to modify the code:
+
+1.  **Clone & Setup**
+    ```bash
+    git clone https://github.com/fritzprix/chess-mcp-server.git
+    cd chess-mcp-server
+    
+    python -m venv .venv
+    source .venv/bin/activate
+    pip install -r requirements.txt
+    ```
+
+## 🎮 How to Play
+
+Once the server is connected, you can ask your Agent to start a game.
+
+### Start a Game
+Ask: *"Start a new chess game against the computer at level 5."*
+-   The Agent calls `createGame`.
+-   **Pro Tip**: You can also ask *"I want to play against YOU. Create a game where you are White."*
+
+### The Game Loop
+1.  **Your Move**:
+    -   Interact with the **HTML Board** if shown. Drag your piece and click **Confirm**.
+    -   *Or* tell the Agent: *"Move pawn to e4."*
+2.  **Agent's Turn**:
+    -   The Agent calls `waitForNextTurn`.
+    -   It sees the board (Markdown or HTML) and thinks about the move.
+    -   It calls `finishTurn` to submit its move.
+3.  **Checkmate**:
+    -   If you deliver the final blow, you can check the **"Claim Checkmate"** box on the UI or tell the Agent *"Checkmate!"*.
+
+### Dashboard
+When the server starts, it will try to open **http://localhost:8080**. You can view the list of all active games and spectator views there.

chess_mcp_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+src/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/chess_engine.py,sha256=VO3JAfVSJq3MG-qlMwr2TI4nPYBt8eGr0IBtMCO8FhQ,4707
+src/game_state.py,sha256=h5uvGRB75OqhGat9bYRzg-EtJHYb9Idz_r_hNTxbiC4,4510
+src/mcp_server.py,sha256=NcL0NE4yCagILm9hDvVM7D1mGgcUMUEObx1umwCzoM0,7739
+src/rendering.py,sha256=Yrh6z-Uq14DR2iXpnYna-QlZQYyLZ7uuRwrv04xz60o,9570
+src/web_dashboard.py,sha256=oFwsjIz6U6E_UekxfMax8o-dG16-irvLvZKCfMMgEbk,2048
+chess_mcp_server-0.1.0.dist-info/METADATA,sha256=0f2S4R7Vi013jonmyhnjKQCnzqh03dEbBawUHJxPcVY,3596
+chess_mcp_server-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+chess_mcp_server-0.1.0.dist-info/entry_points.txt,sha256=_vYs2ugzerBvNKlCJb5BmABHOBAtE1qVwGwV_PZ5LTI,57
+chess_mcp_server-0.1.0.dist-info/licenses/LICENSE,sha256=V6qi4H9nPJfHJh1BzEW77U3yh7l8vd_IOrNJbo93TFQ,1066
+chess_mcp_server-0.1.0.dist-info/RECORD,,

chess_mcp_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

chess_mcp_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+chess-mcp-server = src.mcp_server:main

chess_mcp_server-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fritzprix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/chess_engine.py

@@ -0,0 +1,132 @@
+import chess
+import math
+import random
+
+class ChessAI:
+    def __init__(self):
+        # Configuration for 10 levels
+        self.levels = {
+            1:  {"depth": 1, "error_rate": 0.60},
+            2:  {"depth": 1, "error_rate": 0.40},
+            3:  {"depth": 1, "error_rate": 0.20},
+            4:  {"depth": 2, "error_rate": 0.20},
+            5:  {"depth": 2, "error_rate": 0.10},
+            6:  {"depth": 3, "error_rate": 0.10},
+            7:  {"depth": 3, "error_rate": 0.05},
+            8:  {"depth": 3, "error_rate": 0.00},
+            9:  {"depth": 4, "error_rate": 0.05},
+            10: {"depth": 4, "error_rate": 0.00},
+        }
+        
+        # Piece values for evaluation
+        # Simple material evaluation
+        self.piece_values = {
+            chess.PAWN: 10, chess.KNIGHT: 30, chess.BISHOP: 30,
+            chess.ROOK: 50, chess.QUEEN: 90, chess.KING: 900
+        }
+
+    def get_move(self, board: chess.Board, level: int) -> chess.Move:
+        """
+        Returns the best move based on the difficulty level (1-10).
+        """
+        if level not in self.levels:
+            level = 5 # Default to medium
+            
+        settings = self.levels[level]
+        depth = settings["depth"]
+        error_rate = settings["error_rate"]
+
+        # 1. Error Chance (Simulate Blunder)
+        # If the random roll is within the error rate, pick a random legal move.
+        legal_moves = list(board.legal_moves)
+        if not legal_moves:
+            return None # No moves available (Checkmate/Stalemate)
+
+        if random.random() < error_rate:
+            return random.choice(legal_moves)
+
+        # 2. Strategic Calculation (Minimax)
+        # Otherwise, calculate the best move using Minimax.
+        return self._get_best_move_minimax(board, depth)
+
+    def _evaluate_board(self, board):
+        if board.is_checkmate():
+            return -9999 if board.turn else 9999
+        if board.is_stalemate() or board.is_insufficient_material():
+            return 0
+
+        score = 0
+        for square in chess.SQUARES:
+            piece = board.piece_at(square)
+            if piece:
+                value = self.piece_values[piece.piece_type]
+                if piece.color == chess.WHITE:
+                    score += value
+                else:
+                    score -= value
+        return score
+
+    def _minimax(self, board, depth, alpha, beta, maximizing):
+        if depth == 0 or board.is_game_over():
+            return self._evaluate_board(board)
+
+        legal_moves = list(board.legal_moves)
+        
+        if maximizing:
+            max_eval = -math.inf
+            for move in legal_moves:
+                board.push(move)
+                eval = self._minimax(board, depth - 1, alpha, beta, False)
+                board.pop()
+                max_eval = max(max_eval, eval)
+                alpha = max(alpha, eval)
+                if beta <= alpha:
+                    break
+            return max_eval
+        else:
+            min_eval = math.inf
+            for move in legal_moves:
+                board.push(move)
+                eval = self._minimax(board, depth - 1, alpha, beta, True)
+                board.pop()
+                min_eval = min(min_eval, eval)
+                beta = min(beta, eval)
+                if beta <= alpha:
+                    break
+            return min_eval
+
+    def _get_best_move_minimax(self, board, depth):
+        best_move = None
+        best_value = -math.inf if board.turn == chess.WHITE else math.inf
+        alpha = -math.inf
+        beta = math.inf
+        
+        legal_moves = list(board.legal_moves)
+        if not legal_moves:
+            return None
+        
+        # Simple optimization: shuffle moves to prevent deterministic behavior on equal scores
+        random.shuffle(legal_moves)
+
+        for move in legal_moves:
+            board.push(move)
+            # Pass opposite of current turn because we just pushed a move and now it's opponent's turn to minimize/maximize
+            value = self._minimax(board, depth - 1, alpha, beta, not board.turn)
+            board.pop()
+
+            if board.turn == chess.WHITE:
+                if value > best_value:
+                    best_value = value
+                    best_move = move
+                alpha = max(alpha, best_value)
+            else:
+                if value < best_value:
+                    best_value = value
+                    best_move = move
+                beta = min(beta, best_value)
+                
+        # Fallback if no best move found (should rely on random legal or standard)
+        if best_move is None and legal_moves:
+            return random.choice(legal_moves)
+            
+        return best_move

src/game_state.py

@@ -0,0 +1,134 @@
+import asyncio
+import uuid
+import chess
+from typing import Dict, Optional
+from dataclasses import dataclass, field
+from .chess_engine import ChessAI
+
+@dataclass
+class GameInstance:
+    id: str
+    board: chess.Board
+    config: dict
+    # Event to notify when a move is made (wakes up waitForNextTurn)
+    move_event: asyncio.Event = field(default_factory=asyncio.Event)
+    
+    # AI Engine if playing vs Computer
+    ai: Optional[ChessAI] = None
+    
+    @property
+    def is_game_over(self):
+        return self.board.is_game_over()
+    
+    @property
+    def result(self):
+        if not self.is_game_over:
+            return None
+        outcome = self.board.outcome()
+        if outcome.winner == chess.WHITE:
+            return "White wins"
+        elif outcome.winner == chess.BLACK:
+            return "Black wins"
+        else:
+            return "Draw"
+
+class GameManager:
+    _instance = None
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super(GameManager, cls).__new__(cls)
+            cls._instance.games: Dict[str, GameInstance] = {}
+        return cls._instance
+
+    def create_game(self, config: dict) -> GameInstance:
+        game_id = str(uuid.uuid4())[:8]
+        board = chess.Board()
+        
+        ai = None
+        if config.get("type") == "computer":
+            ai = ChessAI()
+            
+        game = GameInstance(
+            id=game_id,
+            board=board,
+            config=config,
+            ai=ai
+        )
+        self.games[game_id] = game
+        return game
+
+    def get_game(self, game_id: str) -> Optional[GameInstance]:
+        return self.games.get(game_id)
+        
+    def list_games(self):
+        return [
+            {
+                "id": g.id, 
+                "fen": g.board.fen(), 
+                "type": g.config.get("type"),
+                "turn": "White" if g.board.turn == chess.WHITE else "Black"
+            } 
+            for g in self.games.values()
+        ]
+
+    async def make_move(self, game_id: str, move_uci: str, claim_win: bool = False) -> str:
+        """
+        Executes a move. 
+        Returns 'OK' or raises generic exceptions.
+        Triggers computer move if applicable.
+        """
+        game = self.get_game(game_id)
+        if not game:
+            raise ValueError(f"Game {game_id} not found")
+        
+        # Parse Move
+        try:
+            move = chess.Move.from_uci(move_uci)
+        except ValueError:
+            raise ValueError(f"Invalid UCI move format: '{move_uci}'. Please use standard format like 'e2e4' (start_square+end_square).")
+            
+        if move not in game.board.legal_moves:
+             # Create a helpful list of some legal moves
+            sample_moves = ", ".join([str(m) for m in list(game.board.legal_moves)[:3]])
+            raise ValueError(f"Illegal move: '{move_uci}'. Review the board state. Sample legal moves: {sample_moves}...")
+            
+        # Execute Move
+        game.board.push(move)
+        
+        # Check Claim
+        if claim_win:
+            if not game.board.is_checkmate():
+                 # Revert? No, usually valid move but false claim is just an error message, 
+                 # but spec said "Error - Failed Claim: Move rejected". So we should revert.
+                 game.board.pop()
+                 raise ValueError("Move rejected: You claimed Checkmate, but this move does not result in Checkmate.")
+        
+        # Notify waiters (User or Agent waiting for this move)
+        game.move_event.set()
+        game.move_event.clear() # Reset for next turn
+        
+        # If vs Computer and it's Computer's turn now (and game not over)
+        if game.config.get("type") == "computer" and not game.board.is_game_over():
+            # Trigger Background AI Move
+            # We use asyncio.create_task to run it without blocking the return of this function
+            asyncio.create_task(self._computer_turn(game))
+            
+        return "Move accepted"
+
+    async def _computer_turn(self, game: GameInstance):
+        """
+        Calculates and executes computer move.
+        """
+        # Simulate thinking time?
+        await asyncio.sleep(0.5)
+        
+        difficulty = game.config.get("difficulty", 5)
+        ai_move = game.ai.get_move(game.board, difficulty)
+        
+        if ai_move:
+            game.board.push(ai_move)
+            # Notify waiters (Agent waiting for computer)
+            game.move_event.set()
+            game.move_event.clear()
+            

src/mcp_server.py

@@ -0,0 +1,215 @@
+import asyncio
+import threading
+import webbrowser
+import logging
+from typing import Optional, Literal
+from mcp.server.fastmcp import FastMCP, Context
+from pydantic import BaseModel, Field
+
+# We use relative imports assuming this is run as a module (python -m src.mcp_server)
+# or ensure PYTHONPATH is set.
+try:
+    from .game_state import GameManager
+    from .rendering import render_board_to_markdown, render_board_to_html
+    from .web_dashboard import start_dashboard
+except ImportError:
+    # Fallback for direct execution if path not set
+    import sys
+    import os
+    sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    from src.game_state import GameManager
+    from src.rendering import render_board_to_markdown, render_board_to_html
+    from src.web_dashboard import start_dashboard
+
+# Initialize FastMCP
+mcp = FastMCP("Chess Server")
+manager = GameManager()
+DASHBOARD_PORT = 8080
+
+# --- Pydantic Models for Tools ---
+
+class GameConfig(BaseModel):
+    type: Literal["computer", "agent"] = Field(..., description="Play against 'computer' (AI) or 'agent' (another tool/human)")
+    color: Literal["white", "black"] = Field("white", description="Your color. 'white' moves first. If 'black', computer will move first.")
+    showUi: bool = Field(False, description="If true, returns an interactive HTML board in waitForNextTurn. Required for human players.")
+    difficulty: int = Field(5, ge=1, le=10, description="AI Difficulty Level (1-10), if type is 'computer'.")
+
+class WaitForTurnRequest(BaseModel):
+    game_id: str = Field(..., description="The ID of the active game.")
+
+class FinishTurnRequest(BaseModel):
+    game_id: str = Field(..., description="The ID of the active game.")
+    move: str = Field(..., description="The move in UCI format (e.g., 'e2e4').")
+    claim_win: bool = Field(False, description="Set to true if you are claiming Checkmate or Win with this move.")
+
+# --- Background Helper ---
+
+def launch_dashboard_thread():
+    try:
+        start_dashboard(port=DASHBOARD_PORT)
+    except Exception as e:
+        print(f"Failed to start dashboard: {e}")
+
+# --- Tools ---
+
+@mcp.tool()
+def createGame(config: GameConfig) -> str:
+    """
+    Initializes a new chess game session.
+    Returns the Game ID and instructions.
+    """
+    # Convert Pydantic model to dict
+    game = manager.create_game(config.model_dump())
+    
+    # Logic: If Player chose Black against Computer, Computer must move NOW (White).
+    first_move_msg = ""
+    if config.type == "computer" and config.color == "black":
+        # Trigger computer move immediately as it is White
+        # We can't await in sync tool? FastMCP tools can be sync or async. 
+        # But create_game is sync in manager?
+        # We need to trigger it. Manager.make_move is async.
+        # But we can just trigger the background task manually.
+        
+        # NOTE: We need to access the event loop or just run it synchronously?
+        # Better: Implementation in Manager to "start_computer_as_white".
+        # For now, let's use the background task approach if we have loop access.
+        # Simpler: Just set a flag or call a sync helper.
+        
+        # HACK for Sync Tool spawning Async Task:
+        try:
+             loop = asyncio.get_running_loop()
+             loop.create_task(manager._computer_turn(game))
+             first_move_msg = " Computer (White) is making the first move..."
+        except RuntimeError:
+             # No running loop? FastMCP wraps sync tools? 
+             # If createGame is sync, it might not have loop.
+             # But uvicorn runs loop.
+             pass
+
+    info = (
+        f"Game Created Successfully!\n"
+        f"- Game ID: {game.id}\n"
+        f"- Type: {config.type}\n"
+        f"- You are: {config.color.title()}\n"
+        f"- Difficulty: Level {config.difficulty} (if computer)\n\n"
+        f"{first_move_msg}\n"
+        f"Next action: Call `waitForNextTurn(game_id='{game.id}')` to start."
+    )
+    return info
+
+@mcp.tool()
+async def waitForNextTurn(game_id: str) -> list:
+    """
+    Blocks until it is the Agent's turn (or User's turn via Agent proxy).
+    Waits up to 30 seconds for the opponent to move.
+    
+    Returns:
+    - Board state (Markdown)
+    - UI Board (HTML) if showUi is true
+    - Or 'Timeout' message if no move happens.
+    """
+    game = manager.get_game(game_id)
+    if not game:
+        return ["Error: Game not found"]
+
+    try:
+        # Check if game over immediately
+        if game.is_game_over:
+            return [f"Game Over: {game.result}"]
+
+        # --- Side Logic ---
+        # If I am 'color', is it my turn?
+        my_color = chess.WHITE if game.config.get("color", "white") == "white" else chess.BLACK
+        is_my_turn = (game.board.turn == my_color)
+        
+        # If it is NOT my turn, I should probably wait.
+        # Exception: If I am an "Agent" playing vs "Agent", maybe I am the OTHER agent?
+        # But config only has ONE color. 
+        # Assumption: This tool is called by the "Owner" of the game session.
+        
+        if not is_my_turn:
+             # It's opponent's turn.
+             # Wait for move event.
+             try:
+                 await asyncio.wait_for(game.move_event.wait(), timeout=30.0)
+             except asyncio.TimeoutError:
+                 return ["Timeout: No move received yet. Please call this tool again immediately."]
+    
+    except Exception as e:
+        return [f"Error during wait: {str(e)}"]
+
+    # Generate Content
+    md = render_board_to_markdown(game.board.fen())
+    
+    # Add Guidance
+    md += "\n\n**Next Action**: Decide your move and call `finishTurn(game_id, move)`."
+    
+    content = []
+    content.append(md)
+    
+    # 2. UI Resource
+    if game.config.get("showUi"):
+        # Pass perspective based on config
+        is_white = (game.config.get("color", "white") == "white")
+        html = render_board_to_html(game.board.fen(), game.id, is_white_perspective=is_white)
+        
+        resource = {
+            "type": "resource",
+            "resource": {
+                "uri": f"ui://chess/{game.id}",
+                "mimeType": "text/html",
+                "text": html
+            }
+        }
+        content.append(resource)
+        
+    return content
+
+@mcp.tool()
+async def finishTurn(game_id: str, move: str, claim_win: bool = False) -> str:
+    """
+    Submits a move to the game server.
+    Arguments:
+    - game_id: ID of the game
+    - move: UCI format (e.g. e2e4)
+    - claim_win: Set to true to claim checkmate/win.
+    """
+    try:
+        result = await manager.make_move(game_id, move, claim_win)
+        
+        # Check game over after move
+        game = manager.get_game(game_id)
+        if game and game.is_game_over:
+            return f"Move accepted. Game Over: {game.result}. No further actions needed."
+            
+        return f"{result}\nNext action: Call `waitForNextTurn(game_id='{game_id}')` to wait for opponent's move."
+    except ValueError as e:
+        return f"Error: {str(e)}\nAdvice: Please review the error, check the board state in the previous turn, and try a different move."
+    except Exception as e:
+        return f"System Error: {str(e)}"
+
+# --- Entry Point ---
+
+# --- Entry Point ---
+
+def main():
+    """
+    Main entry point for the Chess MCP Server.
+    """
+    # Start Dashboard
+    t = threading.Thread(target=launch_dashboard_thread, daemon=True)
+    t.start()
+    
+    # Open Browser (Best Effort)
+    try:
+        webbrowser.open(f"http://localhost:{DASHBOARD_PORT}")
+    except:
+        pass
+        
+    print(f"Chess MCP Server Running. Dashboard at http://localhost:{DASHBOARD_PORT}")
+    
+    # Run MCP
+    mcp.run(transport="stdio")
+
+if __name__ == "__main__":
+    main()

src/rendering.py

@@ -0,0 +1,233 @@
+import chess
+
+def render_board_to_markdown(fen: str) -> str:
+    """
+    Converts a FEN string into a Markdown formatted table representation of the board.
+    
+    Args:
+        fen (str): The Forsyth-Edwards Notation string of the game state.
+        
+    Returns:
+        str: A multi-line string containing the Markdown table.
+    """
+    board = chess.Board(fen)
+    
+    lines = []
+    lines.append("| Rank | a | b | c | d | e | f | g | h |")
+    lines.append("|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|")
+    
+    # 8(rank 7) to 1(rank 0)
+    for rank in range(7, -1, -1):
+        row_content = f"| **{rank + 1}** |"
+        for file in range(8):
+            piece = board.piece_at(chess.square(file, rank))
+            symbol = piece.unicode_symbol() if piece else " " 
+            row_content += f" {symbol} |"
+        lines.append(row_content)
+    
+    # 5. Join lines to form the final string
+    output = "\n".join(lines)
+    
+    # 6. Append State Info
+    turn_text = "White" if board.turn == chess.WHITE else "Black"
+    output += f"\n\n**Turn**: {turn_text} to move"
+    output += f"\n**FEN**: `{fen}`"
+    
+    return output
+
+def render_board_to_html(fen: str, game_id: str, is_white_perspective: bool = True) -> str:
+    """
+    Renders an interactive HTML chess board for MCP-UI.
+    Includes 'postMessage' logic for finishTurn.
+    """
+    board = chess.Board(fen)
+    
+    # Simple CSS/JS Board
+    # We will use chess.js and chessboard.js via CDN or a simple SVG approach?
+    # For a self-contained "resource", using a library via CDN is standard for web views.
+    # However, MCP UI in tools might be sandboxed without external network access depending on Host.
+    # Safe approach: Pure HTML/CSS Grid + Vanilla JS Drag Drop (Complex) OR use library.
+    # Let's use a robust library: Chessboard.js + Chess.js (CDN).
+    # If offline is required (as per mcp_reference_en hints), we might need to inline or stick to simple clicks.
+    
+    # Let's implement a simple "Click to Move" table-based UI with JS, 
+    # as it's dependency-free and follows the "Production-level... without internet connectivity" hint in reference.
+    
+    display_turn = "White" if board.turn == chess.WHITE else "Black"
+    user_side = "White" if is_white_perspective else "Black"
+    
+    html = f"""
+    <!DOCTYPE html>
+    <html>
+    <head>
+    <style>
+        body {{ font-family: sans-serif; display: flex; flex-direction: column; align-items: center; background-color: #2c2c2c; color: #f0f0f0; }}
+        h2 {{ margin-bottom: 5px; }}
+        .info {{ margin-bottom: 15px; text-align: center; }}
+        .board {{ display: grid; grid-template-columns: repeat(8, 45px); grid-template-rows: repeat(8, 45px); border: 5px solid #4a4a4a; }}
+        .square {{ width: 45px; height: 45px; display: flex; justify-content: center; align-items: center; font-size: 35px; cursor: pointer; user-select: none; }}
+        .white {{ background-color: #eeeed2; color: black; }}
+        .black {{ background-color: #769656; color: black; }}
+        .selected {{ background-color: #bbcb2b !important; }}
+        .controls {{ margin-top: 20px; display: flex; flex-direction: column; gap: 10px; background: #3c3c3c; padding: 15px; border-radius: 8px; }}
+        input, button {{ padding: 8px; border-radius: 4px; border: none; }}
+        button {{ background-color: #769656; color: white; cursor: pointer; font-weight: bold; }}
+        button:hover {{ background-color: #567636; }}
+        #status {{ margin-top: 10px; font-weight: bold; color: #ffd700; height: 20px; }}
+    </style>
+    </head>
+    <body>
+        <h2>Chess MCP</h2>
+        <div class="info">
+            <div>Game ID: {game_id}</div>
+            <div style="font-size: 1.1em; margin-top: 5px;">You are: <strong>{user_side}</strong></div>
+            <div style="color: #aaa;">To Move: {display_turn}</div>
+        </div>
+        
+        <div id="board" class="board"></div>
+        
+        <div class="controls">
+            <div>
+                <label>Move (UCI): <input type="text" id="uciInput" placeholder="e.g. e2e4"></label>
+            </div>
+            <div>
+                <label><input type="checkbox" id="chkClaimWin"> Claim Checkmate/Win</label>
+            </div>
+            <button onclick="submitMove()">Submit Move</button>
+        </div>
+        <div id="status"></div>
+
+    <script>
+        const fen = "{fen}";
+        const gameId = "{game_id}";
+        const isWhitePerspective = {'true' if is_white_perspective else 'false'};
+        
+        function renderBoard() {{
+            const boardEl = document.getElementById('board');
+            boardEl.innerHTML = '';
+            
+            const rows = fen.split(' ')[0].split('/');
+            
+            // FEN rows are Rank 8 down to Rank 1
+            // If White Perspective: Render Row 0 (Rank 8) to Row 7 (Rank 1)
+            // If Black Perspective: Render Row 7 (Rank 1) to Row 0 (Rank 8) ? 
+            // Actually, we just need to iterate the grid differently.
+            
+            // Let's create a 2D array first for easier manipulation
+            let grid = [];
+            for (let r = 0; r < 8; r++) {{
+                let rowArr = [];
+                const rankStr = rows[r];
+                for (let i = 0; i < rankStr.length; i++) {{
+                    const char = rankStr[i];
+                    if (isNaN(char)) {{
+                        rowArr.push(char);
+                    }} else {{
+                        const empties = parseInt(char);
+                        for (let k = 0; k < empties; k++) {{
+                            rowArr.push(null);
+                        }}
+                    }}
+                }}
+                grid.push(rowArr);
+            }}
+            
+            // Render Loops
+            // White: r=0 (Rank 8) -> r=7 (Rank 1). c=0 (File a) -> c=7 (File h)
+            // Black: r=7 (Rank 1) -> r=0 (Rank 8). c=7 (File h) -> c=0 (File a)
+            
+            const startR = isWhitePerspective ? 0 : 7;
+            const endR = isWhitePerspective ? 8 : -1;
+            const stepR = isWhitePerspective ? 1 : -1;
+            
+            const startC = isWhitePerspective ? 0 : 7;
+            const endC = isWhitePerspective ? 8 : -1;
+            const stepC = isWhitePerspective ? 1 : -1;
+            
+            for (let r = startR; r !== endR; r += stepR) {{
+                for (let c = startC; c !== endC; c += stepC) {{
+                     createSquare(r, c, grid[r][c]);
+                }}
+            }}
+        }}
+        
+        const pieceMap = {{
+            'r': '♜', 'n': '♞', 'b': '♝', 'q': '♛', 'k': '♚', 'p': '♟',
+            'R': '♖', 'N': '♘', 'B': '♗', 'Q': '♕', 'K': '♔', 'P': '♙'
+        }};
+
+        let selectedSq = null;
+
+        function createSquare(row, col, pieceChar) {{
+            const div = document.createElement('div');
+            // Color logic: (row+col)%2==0 is Light.
+            // But 'row' index from FEN (0=Rank8) matches standard odd/even check?
+            // Rank 8 (index 0) + File a (index 0) = 0 -> Light. Correct (a8 is light).
+            const isLight = (row + col) % 2 === 0;
+            div.className = 'square ' + (isLight ? 'white' : 'black');
+            
+            // Store logical coordinates for click handling
+            div.dataset.row = row;
+            div.dataset.col = col;
+            
+            if (pieceChar) {{
+                div.textContent = pieceMap[pieceChar] || pieceChar;
+            }}
+            
+            div.onclick = () => onSquareClick(row, col, div);
+            document.getElementById('board').appendChild(div);
+        }}
+
+        function onSquareClick(row, col, divElement) {{
+            const file = String.fromCharCode(97 + col);
+            const rank = 8 - row;
+            const coord = file + rank;
+            
+            // Clear previous selection highlight
+            document.querySelectorAll('.selected').forEach(el => el.classList.remove('selected'));
+            
+            if (!selectedSq) {{
+                // Select From
+                selectedSq = coord;
+                divElement.classList.add('selected');
+                document.getElementById('status').innerText = "Selected: " + coord;
+            }} else {{
+                // Select To
+                const move = selectedSq + coord;
+                document.getElementById('uciInput').value = move;
+                selectedSq = null; // Reset selection
+                 document.getElementById('status').innerText = "Ready to submit: " + move;
+            }}
+        }}
+
+        function submitMove() {{
+            const move = document.getElementById('uciInput').value;
+            if (!move) {{
+                alert("Please enter or select a move");
+                return;
+            }}
+            
+            const claimWin = document.getElementById('chkClaimWin').checked;
+            
+            // Post Message to MCP Host
+            window.parent.postMessage({{
+                type: 'action',
+                action: 'finishTurn',
+                payload: {{
+                    game_id: gameId,
+                    move: move,
+                    claim_win: claimWin
+                }}
+            }}, '*');
+            
+            document.getElementById('status').innerText = "Submitted: " + move + "...";
+            // Disable button to prevent double submit
+            document.querySelector('button').disabled = true;
+        }}
+
+        renderBoard();
+    </script>
+    </body>
+    </html>
+    """
+    return html

src/web_dashboard.py

@@ -0,0 +1,66 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import HTMLResponse
+import uvicorn
+import asyncio
+from typing import List
+from .game_state import GameManager
+from .rendering import render_board_to_html
+
+app = FastAPI(title="Chess MCP Dashboard")
+manager = GameManager()
+
+@app.get("/", response_class=HTMLResponse)
+async def index():
+    games = manager.list_games()
+    
+    rows = ""
+    for g in games:
+        rows += f"""
+        <tr>
+            <td><a href="/game/{g['id']}">{g['id']}</a></td>
+            <td>{g['type']}</td>
+            <td>{g['turn']}</td>
+            <td>{g['fen']}</td>
+        </tr>
+        """
+    
+    html = f"""
+    <html>
+    <head><title>Chess MCP Dashboard</title>
+    <style>table {{ width: 100%; border-collapse: collapse; }} th, td {{ border: 1px solid #ddd; padding: 8px; }} tr:nth-child(even){{background-color: #f2f2f2;}}</style>
+    </head>
+    <body>
+    <h1>Active Chess Games</h1>
+    <table>
+        <tr><th>ID</th><th>Type</th><th>Turn</th><th>FEN</th></tr>
+        {rows}
+    </table>
+    <br><a href="/" style="background:#eee; padding:5px;">Refresh</a>
+    </body>
+    </html>
+    """
+    return html
+
+@app.get("/game/{game_id}", response_class=HTMLResponse)
+async def view_game(game_id: str):
+    game = manager.get_game(game_id)
+    if not game:
+        raise HTTPException(status_code=404, detail="Game not found")
+        
+    # We reuse the render logic but disable interaction for spectator? 
+    # Or keep it interactive but actions won't work if not via MCP?
+    # Actually, the postMessage logic won't work in a normal browser (no parent).
+    # So we should render a read-only version or one that logs to console.
+    
+    # For now, let's just reuse the HTML generator
+    html = render_board_to_html(game.board.fen(), game.id)
+    
+    # Wrap in a back link
+    wrapper = f"""
+    <div><a href="/"><< Back to Dashboard</a></div>
+    {html}
+    """
+    return wrapper
+
+def start_dashboard(port=8080):
+    uvicorn.run(app, host="0.0.0.0", port=port, log_level="error")