chess-agent

Personal chess improvement assistant built in Kotlin. It combines:

• a command-line “coach” agent powered by koog-agents and OpenAI, and
• a small Swing UI for browsing Chess.com game histories, viewing profile summaries, and requesting training puzzles.

All Chess.com data fetching and engine analysis are delegated to external MCP (Model Context Protocol) servers, so this project stays small and focused on orchestration and presentation.

Features

• Download finished games from Chess.com via a dedicated MCP server (chess-mcp).
• Build long‑term profiles for a Chess.com user, including:
  • rating range over the selected window
  • results as White and Black
  • most‑played openings and their results
  • strongest and weakest openings
• Generate per‑game natural‑language reviews using a second MCP server (chessagine-mcp) backed by Stockfish and an LLM.
• Store profiles and game analyses on disk under profiles/<username>/.
• Swing UI that lets you:
  • manage local “profiles”
  • browse and replay games on a board with turning points highlighted
  • read profile summaries
  • fetch training puzzles tuned to your profile.

Project layout

• src/main/kotlin/Main.kt – core MCP clients and a CLI agent entrypoint that uses koog‑agents and OpenAI.
• src/main/kotlin/mcp/McpConnection.kt – minimal stdio‑based MCP client.
• src/main/kotlin/pgn – tiny PGN helpers (splitting games, parsing headers).
• src/main/kotlin/profile – simple data model for opening aggregates.
• src/main/kotlin/ui/ChessBoard.kt – board representation and PGN replay.
• src/main/kotlin/ui/ChessAgentUi.kt – Swing UI entrypoint and panels.
• src/main/kotlin/ui/GameAnalysisAgent.kt – small helper agent used by the UI to run a one‑off OpenAI analysis for a single game.
• profiles/ – example local profiles and analyses produced by the tool.

Prerequisites

• JDK 21+ (Gradle is configured with jvmToolchain(21)).
• Kotlin – handled by Gradle via the Kotlin JVM plugin.
• OpenAI API key via OPENAI_API_KEY environment variable.
• Two external MCP servers cloned and configured locally:
  • chess-mcp (Chess.com Published Data API MCP wrapper)
  • chessagine-mcp (chess analysis MCP server)
• For those MCP servers you will typically need:
  • Python + uv (or another way to run chess-mcp)
  • Node.js (to run chessagine-mcp)

Getting started

1. Clone this repository

git clone https://github.com/<your-account>/chess-agent.git
cd chess-agent

2. Clone and prepare the MCP servers

Follow the instructions in each project’s README; a typical setup looks like:

# chess-mcp
git clone https://github.com/pab1it0/chess-mcp.git

# chessagine-mcp
git clone https://github.com/jalpp/chessagine-mcp.git
cd chessagine-mcp
npm install
npm run build:mcp

3. Point the MCP paths in Main.kt to your local clones

In ChessComMcpClient and ChessAgineMcpClient (both in Main.kt) you will see command lists similar to:

command = listOf(
    "uv",
    "--directory",
    "/absolute/path/to/chess-mcp",
    "run",
    "src/chess_mcp/main.py",
)

and

command = listOf(
    "node",
    "/absolute/path/to/chessagine-mcp/build/runner/stdio.js",
)

Update these placeholder paths so they point to your local clones of chess-mcp and chessagine-mcp respectively.

Note: for a workshop/demo project this simple approach keeps the configuration explicit in code. For a more production‑grade setup you would likely move these to environment variables or a configuration file.

4. Configure your OpenAI credentials

Set the OPENAI_API_KEY environment variable before running either the CLI agent or the Swing UI:

export OPENAI_API_KEY=sk-...

5. Build and run tests

Use the included Gradle wrapper:

./gradlew clean test

You should see the ChessBoardTest suite run successfully.

Running the tools

Command‑line agent (profile builder)

The main agent entrypoint lives in Main.kt as fun main(). It:

1. Reads OPENAI_API_KEY from the environment.
2. Wires a koog‑agents AIAgent with the UserProfileToolSet tools.
3. Asks the agent to build a profile for a sample user (currently "flinca").

From an IDE such as IntelliJ IDEA, run the main function in ai.koog.workshop.intro.MainKt.

From the command line you can run the compiled jar once you have built it, for example:

./gradlew jar
java -cp build/libs/chess-agent-1.0-SNAPSHOT.jar ai.koog.workshop.intro.MainKt

You should see the agent build a profile using games fetched via chess-mcp and analyses produced via chessagine-mcp.

Swing UI

The Swing UI entrypoint is in ChessAgentUi.kt:

fun main() { /* ... */ }

Run ai.koog.workshop.intro.ui.ChessAgentUiKt from your IDE. The UI provides three tabs:

• Game history – manage profiles, download/analyse history via MCP tools, and replay games on a board.
• Profile – read the profile_summary.txt for the selected profile.
• Puzzles – infer suitable puzzle themes from a profile summary and call the fetch-chess-puzzle MCP tool.

Profiles and games are stored under profiles/<username>/games/ with game_N.pgn and game_N_analysis.txt pairs. Summaries live in profiles/<username>/profile_summary.txt.

Code quality and cleanup

The repository has been tidied for publication:

• Removed a legacy, unused overload from GameAnalysisAgent.
• Normalised indentation in several helper methods.
• Replaced hard‑coded, user‑specific MCP paths with generic placeholders.

The goal is to keep the codebase small and readable while remaining faithful to its original workshop/demo purpose.

License

No explicit license has been added yet. If you plan to publish this repository publicly, consider adding a license file (for example MIT, Apache 2.0, or similar) that matches how you want others to use this code.