chess-mcp CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Model Context Protocol (MCP) server that implements an interactive chess game. It exposes chess functionality through MCP tools and provides a web-based chessboard interface using MCP-UI.

Development Commands

• npm run dev - Start the development server (runs tsx src/server.ts)
• npm run format - Format code with Biome
• npm run lint - Lint and fix code with Biome

The server runs on http://localhost:3000/mcp

Architecture

MCP Server with Express Integration

This project uses a custom MCP middleware framework that integrates MCP servers with Express.js. Understanding this architecture is critical:

1. Server Creation Pattern (src/server.ts:76-130):

   • newServer() creates a new McpServer instance for each session
   • Tools are registered using server.registerTool() with Zod schemas for validation
   • Tool handlers receive arguments and a context object with sessionId

2. Custom MCP Middleware (src/lib/mcp/middleware.ts):

   • Middleware(newServer) function wraps the server creation function
   • Manages session lifecycle and transport layer
   • Maps HTTP requests to MCP protocol using StreamableHTTPServerTransport
   • Session IDs come from mcp-session-id header (see src/lib/mcp/header.ts)
   • Maintains a registry of active transports keyed by session ID

3. Game State Management (src/lib/store.ts):

   • Games persist to ./games/{sessionId}.json as FEN strings
   • loadGame(sessionId) retrieves existing games or returns null
   • saveGame(sessionId, game) persists the current game state
   • Session ID from MCP context ties games to specific clients

MCP Tool Implementation

Two tools are exposed:

• chess_get_board_state: Returns current board state (no arguments)
• chess_move: Makes a move or starts new game
  • Takes move string (algebraic notation like "e4" or "new")
  • Validates moves using chess.js library