# fuzzylabs/chess-agent architecture

> Architecture diagram of the GitHub repository fuzzylabs/chess-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fuzzylabs/chess-agent
- Repository: https://github.com/fuzzylabs/chess-agent

## Overview

Chess Agent is an MCP server that lets an LLM client operate Lichess games. The user-to-result workflow is login, create an AI or person game, inspect the board and move history, check whose turn it is, submit moves, and optionally resign. The server also exposes account information and returns structured game and board data. The graph separates MCP entry points, game operations, and shared domain types. Source excerpts show the Lichess calls and internal helper calls; README statements support the client interaction and documented game modes.

Main entry points: [`chess_agent/core/schemas.py`](https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/core/schemas.py) (Response schemas), [`chess_agent/server.py`](https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py) (Board representation), [`chess_agent/core/exceptions.py`](https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/core/exceptions.py) (Game errors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP entry"]
  node_server["MCP server<br/>[server.py]"]
end

subgraph group_game["Game operations"]
  node_session["Login session<br/>[server.py]"]
  node_account["Account lookup<br/>[server.py]"]
  node_create_ai["Create AI game<br/>[server.py]"]
  node_create_person["Create person game<br/>[server.py]"]
  node_turn["Turn status<br/>[server.py]"]
  node_game_state["Game state<br/>[server.py]"]
  node_previous_moves["Move history<br/>[server.py]"]
  node_board["Board representation<br/>[server.py]"]
  node_move["Submit move<br/>[server.py]"]
  node_resign["End game<br/>[server.py]"]
end

subgraph group_core["Shared domain"]
  node_schemas["Response schemas<br/>[schemas.py]"]
  node_exceptions["Game errors<br/>[exceptions.py]"]
end

node_client(("LLM client"))
node_lichess["Lichess API"]
node_python_chess["Chess board parser"]

node_client -->|"calls tools"| node_server
node_server -->|"registers tools"| node_session
node_session -->|"authenticates"| node_lichess
node_account -->|"fetches account"| node_lichess
node_account -->|"returns account data"| node_schemas
node_create_ai -->|"creates AI game"| node_lichess
node_create_ai -->|"validates response"| node_schemas
node_create_person -->|"creates person game"| node_lichess
node_create_person -->|"validates response"| node_schemas
node_turn -->|"checks history"| node_previous_moves
node_previous_moves -->|"reads state"| node_game_state
node_game_state -->|"streams state"| node_lichess
node_game_state -->|"parses state"| node_schemas
node_turn -->|"returns turn status"| node_schemas
node_board -->|"reads game moves"| node_lichess
node_board -->|"parses FEN"| node_python_chess
node_board -->|"loads history"| node_previous_moves
node_board -->|"returns board data"| node_schemas
node_move -->|"submits move"| node_lichess
node_resign -->|"resigns game"| node_lichess
node_server -->|"raises game errors"| node_exceptions
node_exceptions -->|"uses game messages"| node_schemas

click node_server "https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py"
click node_session "https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py"
click node_account "https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py"
click node_create_ai "https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py"
click node_create_person "https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py"
click node_turn "https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py"
click node_game_state "https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py"
click node_previous_moves "https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py"
click node_board "https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py"
click node_move "https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py"
click node_resign "https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py"
click node_schemas "https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/core/schemas.py"
click node_exceptions "https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/core/exceptions.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_client toneBlue
class node_session,node_account,node_create_ai,node_create_person,node_turn,node_game_state,node_previous_moves,node_board,node_move,node_resign toneAmber
class node_schemas,node_exceptions,node_lichess toneMint
class node_python_chess toneIndigo
```

## Components

### MCP entry

- [MCP server](https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py): `chess_agent/server.py`

### Game operations

- [Login session](https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py): `chess_agent/server.py`
- [Account lookup](https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py): `chess_agent/server.py`
- [Create AI game](https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py): `chess_agent/server.py`
- [Create person game](https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py): `chess_agent/server.py`
- [Turn status](https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py): `chess_agent/server.py`
- [Game state](https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py): `chess_agent/server.py`
- [Move history](https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py): `chess_agent/server.py`
- [Board representation](https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py): `chess_agent/server.py`
- [Submit move](https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py): `chess_agent/server.py`
- [End game](https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/server.py): `chess_agent/server.py`

### Shared domain

- [Response schemas](https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/core/schemas.py): `chess_agent/core/schemas.py`
- [Game errors](https://github.com/fuzzylabs/chess-agent/blob/main/chess_agent/core/exceptions.py): `chess_agent/core/exceptions.py`

### Other components

- **LLM client**
- **Lichess API**
- **Chess board parser**

## Connections

- LLM client → MCP server: calls tools (evidence: `README.md`)
- MCP server → Login session: registers tools (evidence: `chess_agent/server.py`)
- Login session → Lichess API: authenticates (evidence: `chess_agent/server.py`)
- Account lookup → Lichess API: fetches account (evidence: `chess_agent/server.py`)
- Account lookup → Response schemas: returns account data (evidence: `chess_agent/server.py`)
- Create AI game → Lichess API: creates AI game (evidence: `chess_agent/server.py`)
- Create AI game → Response schemas: validates response (evidence: `chess_agent/server.py`)
- Create person game → Lichess API: creates person game (evidence: `chess_agent/server.py`)
- Create person game → Response schemas: validates response (evidence: `chess_agent/server.py`)
- Turn status → Move history: checks history (evidence: `chess_agent/server.py`)
- Move history → Game state: reads state (evidence: `chess_agent/server.py`)
- Game state → Lichess API: streams state (evidence: `chess_agent/server.py`)
- Game state → Response schemas: parses state (evidence: `chess_agent/server.py`)
- Turn status → Response schemas: returns turn status (evidence: `chess_agent/server.py`)
- Board representation → Lichess API: reads game moves (evidence: `chess_agent/server.py`)
- Board representation → Chess board parser: parses FEN (evidence: `chess_agent/server.py`)
- Board representation → Move history: loads history (evidence: `chess_agent/server.py`)
- Board representation → Response schemas: returns board data (evidence: `chess_agent/server.py`)
- Submit move → Lichess API: submits move (evidence: `chess_agent/server.py`)
- End game → Lichess API: resigns game (evidence: `chess_agent/server.py`)
- MCP server → Game errors: raises game errors (evidence: `chess_agent/server.py`)
- Game errors → Response schemas: uses game messages (evidence: `chess_agent/core/exceptions.py`)
