Fa 2 allowing login (#7)

* feat: adding login func to mcp server

* docs: updating README

* docs: adding steps for creating lichess account and API key

* chore: fixing link to chess UI

* chore: fixing incorrect types

* [FA-3] enable starting game and playing (#2)

* feat: adding game start and play functionality

* docs: updating documentation

* docs: updating documentation

* docs: fixing issue with markdwon image

* docs: formatting readme

* docs: removing trailing semi-colon

* docs: making prompt block-quote

* chore: removing trailing slash

* Fa 3 enable starting game (#6)

* feat: adding game start and play functionality

* docs: updating documentation

* docs: updating documentation

* docs: fixing issue with markdwon image

* docs: formatting readme

* docs: removing trailing semi-colon

* docs: making prompt block-quote

* chore: removing trailing slash

* [FA-9] improving responses from LLM with board representation (#4)

* feat: adding string representation of the board

* feat: fixing issues with running module in claude desktop

* docs: updating readme

* feat: adding schema for UI config

* feat: reduced the bot level to 3

* docs: adding video to readme

* docs: removing video

* chore: fixing pre-commit issues

Author: scott-clare1

.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
         files: "\\.(py|txt|yaml|json|md|toml|lock|cfg|html|sh|js|yml)$"
       - id: end-of-file-fixer
       - id: check-added-large-files
-        args: ["--maxkb=1000"]
+        args: ["--maxkb=50000"]
       - id: check-case-conflict
       - id: requirements-txt-fixer
 

README.md

@@ -4,9 +4,6 @@
 
 An LLM agent built using Model Context Protocol to play online games
 
-# 🏃 How do I get started?
-If you haven't already done so, please read [DEVELOPMENT.md](DEVELOPMENT.md) for instructions on how to set up your virtual environment using Poetry.
-
 # Pre-requisites
 
 - `uv` installable via brew.
@@ -29,14 +26,18 @@ make project-setup
 1. Install server in Claude Desktop:
 
 ```bash
-uv run mcp install agent_uno/server.py
+cd agent_uno
+```
+
+```bash
+uv run mcp install server.py
 ```
 
 2. Interact with MCP server with Claude Desktop.
 
 Example prompt:
 
-> Can you please log into the Chess API with the following API key ************ and then create a game. Once the game has been created the opponent will make the first move. Can you use the state to determine what an optimal next move will be and then make your own move playing continuously back and forth until completion? Please use the UCI chess standard for your moves, e.g., e2e4.
+> Can you please log into the Chess API with the following API key ************ and then create a game. Once the game has been created the opponent will make the first move. Can you use the previous moves and the layout of the board to determine what an optimal next move will be and then make your own move playing continuously back and forth until completion? Please use the UCI chess standard for your moves, e.g., e2e4.
 
 > [!NOTE]
 > If you face issues with server starting in the Claude desktop this could be because of the relative path for the `command` in the server config. This will need to be changed to the absolute path to `uv` on your machine in this case. See [GH issue](https://github.com/cline/cline/issues/1160) for more details.

agent_uno/core/__init__.py

@@ -0,0 +1 @@
+"""Core functionality for the MCP server."""

agent_uno/core/schemas.py

@@ -0,0 +1,73 @@
+"""MCP endpoint schemas."""
+
+import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class AccountInfo(BaseModel):
+    """The account info of a LiChess user."""
+
+    id: str
+    username: str
+    perfs: dict[str, dict[str, int | bool]]
+    created_at: datetime.datetime = Field(alias="createdAt")
+    seen_at: datetime.datetime = Field(alias="seenAt")
+    play_time: dict[str, int] = Field(alias="playTime")
+    url: str
+    count: dict[str, int]
+    followable: bool
+    following: bool
+    blocking: bool
+
+
+class CreatedGame(BaseModel):
+    """The response of creating a new game."""
+
+    id: str
+    rated: bool
+    variant: dict[str, str]
+    fen: str
+    turns: int
+    source: str
+    speed: str
+    perf: str
+    created_at: datetime.datetime = Field(alias="createdAt")
+    status: dict[str, str | int]
+    player: str
+    full_id: str = Field(alias="fullId")
+
+
+class UIConfig(BaseModel):
+    """The UI configuration of a game."""
+
+    url: str
+
+
+class State(BaseModel):
+    """A representation of the game state."""
+
+    type: str
+    moves: str
+    wtime: datetime.datetime
+    btime: datetime.datetime
+    winc: int
+    binc: int
+    status: str
+
+
+class CurrentState(BaseModel):
+    """The current state of a game."""
+
+    id: str
+    variant: dict[str, str]
+    speed: str
+    perf: dict[str, str]
+    rated: bool
+    created_at: datetime.datetime = Field(alias="createdAt")
+    white: dict[str, int]
+    black: dict[str, Optional[str | bool | int]]
+    initial_fen: str = Field(alias="initialFen")
+    type: str
+    state: State

agent_uno/server.py

@@ -5,50 +5,46 @@
 # 2. Agent is able to start a game
 # 3. Agent is able to play the game by getting the current state and making moves.
 """
-import datetime
-from typing import cast
+from collections.abc import Callable
+from typing import Any, cast
 
 from berserk import Client, TokenSession  # type: ignore [import-not-found]
+from chess import Board  # type: ignore [import-not-found]
+from core.schemas import (  # type: ignore [import-not-found]
+    AccountInfo,
+    CreatedGame,
+    CurrentState,
+    UIConfig,
+)
 from mcp.server.fastmcp import FastMCP  # type: ignore [import-not-found]
-from pydantic import BaseModel, Field
 
+mcp = FastMCP("chess-mcp", dependencies=["berserk", "python-chess"])
 
-class AccountInfo(BaseModel):
-    """The account info of a LiChess user."""
+BOT_LEVEL = 3
 
-    id: str
-    username: str
-    perfs: dict[str, dict[str, int | bool]]
-    created_at: datetime.datetime = Field(alias="createdAt")
-    seen_at: datetime.datetime = Field(alias="seenAt")
-    play_time: dict[str, int] = Field(alias="playTime")
-    url: str
-    count: dict[str, int]
-    followable: bool
-    following: bool
-    blocking: bool
+session_state = {}
 
 
-class CreatedGame(BaseModel):
-    """The response of creating a new game."""
+def client_is_set_handler(func: Callable[[], Any]) -> Callable[[], Any]:
+    """A decorator to check if the client is set."""
 
-    id: str
-    rated: bool
-    variant: dict[str, str]
-    fen: str
-    turns: int
-    source: str
-    speed: str
-    perf: str
-    created_at: datetime.datetime = Field(alias="createdAt")
-    status: dict[str, str | int]
-    player: str
-    full_id: str = Field(alias="fullId")
+    def is_set_wrapper(*args: Any, **kwargs: dict[str, Any]) -> Any:
+        if "client" not in session_state:
+            raise Exception("Client is not set. You need to log in first.")
+        return func(*args, **kwargs)
 
+    return is_set_wrapper
 
-mcp = FastMCP("chess-mcp", dependencies=["berserk"])
 
-session_state = {}
+def id_is_set_handler(func: Callable[[], Any]) -> Callable[[], Any]:
+    """A decorator to check if the ID is set."""
+
+    def is_set_wrapper(*args: Any, **kwargs: dict[str, Any]) -> Any:
+        if "id" not in session_state:
+            raise Exception("ID is not set. You need to start a game first.")
+        return func(*args, **kwargs)
+
+    return is_set_wrapper
 
 
 @mcp.tool(description="Login to LiChess.")  # type: ignore
@@ -62,40 +58,63 @@ async def login(api_key: str) -> None:
     session_state["client"] = Client(session)
 
 
+@client_is_set_handler
 @mcp.tool(description="Get account info.")  # type: ignore
 async def get_account_info() -> AccountInfo:
     """Get the account info of the logged in user."""
     return AccountInfo(**session_state["client"].account.get())
 
 
+@client_is_set_handler
 @mcp.tool(description="Create a new game.")  # type: ignore
-async def create_game() -> str:
+async def create_game() -> UIConfig:
     """An endpoint for creating a new game."""
     response = CreatedGame(
-        **session_state["client"].challenges.create_ai(color="black")
+        **session_state["client"].challenges.create_ai(color="black", level=BOT_LEVEL)
     )
-
     session_state["id"] = response.id
 
-    return f"You can view the game taking place here: https://lichess-org.github.io/api-demo/#!/game/{response.id}"
+    return UIConfig(url=f"https://lichess-org.github.io/api-demo/#!/game/{response.id}")
 
 
+@client_is_set_handler
+@id_is_set_handler
 @mcp.tool(description="End game.")  # type: ignore
 async def end_game() -> None:
     """End the current game."""
     session_state["client"].board.resign_game(session_state["id"])
 
 
-@mcp.tool(description="Get the current game state.")  # type: ignore
-async def get_game_state() -> str:
+@client_is_set_handler
+@id_is_set_handler
+async def get_game_state() -> CurrentState:
     """Get the current game state."""
-    current_state = next(
-        session_state["client"].board.stream_game_state(session_state["id"])
+    return CurrentState(
+        **next(session_state["client"].board.stream_game_state(session_state["id"]))
     )
-    return cast(str, current_state["state"]["moves"])
 
 
+@mcp.tool(description="Get all previous moves in the match.")  # type: ignore
+async def get_previous_moves() -> list[str]:
+    """Get all previous moves in the match."""
+    current_state = await get_game_state()
+    return cast(list[str], current_state.state.moves.split())
+
+
+@client_is_set_handler
+@id_is_set_handler
 @mcp.tool(description="Make a move.")  # type: ignore
 async def make_move(move: str) -> None:
     """Make a move in the current game."""
     session_state["client"].board.make_move(session_state["id"], move)
+
+
+@mcp.tool(description="Get the current board.")  # type: ignore
+async def get_board() -> str:
+    """An endpoint for getting the current board as an ASCII representation."""
+    board = Board()
+
+    for move in await get_previous_moves():
+        board.push_uci(move)
+
+    return cast(str, board.__str__())

pyproject.toml

@@ -5,7 +5,12 @@ description = "An LLM agent built using Model Context Protocol to play online ga
 authors = [{ name = "Fuzzy Labs", email = "info@fuzzylabs.ai" }]
 readme = "README.md"
 requires-python = ">=3.12,<4.0"
-dependencies = ["berserk>=0.13.2", "mcp[cli]>=1.6.0", "pydantic>=2.11.1"]
+dependencies = [
+    "berserk>=0.13.2",
+    "mcp[cli]>=1.6.0",
+    "pydantic>=2.11.1",
+    "python-chess>=1.999",
+]
 
 [dependency-groups]
 dev = ["pytest>=7.2.0", "pytest-cov>=4.0.0", "licensecheck>=2024.1.2"]