[FA-32] Implement Dockerfile

Dockerfile

@@ -0,0 +1,37 @@
+# Use a Python image with uv pre-installed
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS uv
+
+# Install the project into `/app`
+WORKDIR /app
+
+# Enable bytecode compilation
+ENV UV_COMPILE_BYTECODE=1
+
+# Copy from the cache instead of linking since it's a mounted volume
+ENV UV_LINK_MODE=copy
+
+# Install the project's dependencies using the lockfile and settings
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --frozen --no-install-project --no-dev --no-editable
+
+# Then, add the rest of the project source code and install it
+# Installing separately from its dependencies allows optimal layer caching
+ADD . /app
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev --no-editable
+
+FROM python:3.12-slim-bookworm
+
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY --from=uv --chown=app:app /app/.venv /app/.venv
+
+# Place executables in the environment at the front of the path
+ENV PATH="/app/.venv/bin:$PATH"
+
+# when running the container, add --db-path and a bind mount to the host's db file
+ENTRYPOINT ["agent-uno"]

README.md

@@ -24,16 +24,40 @@ make project-setup
 
 ## Quick Start
 
-### 1. Install server in Claude Desktop:
+### 1. Add server config in client environment:
+
+<details>
+<summary>Docker (Recommended)</summary>
 
 ```bash
-cd agent_uno
+docker build -t mcp-chess .
+```
+
+```json
+{
+    "mcpServers": {
+        "mcp-chess": {
+            "command": "docker",
+            "args": ["run", "-i", "--rm", "mcp-chess"]
+        }
+    }
+}
 ```
+</details>
+
+<details>
+<summary>uv</summary>
 
 ```bash
-uv run mcp install server.py
+cd src/agent_uno
 ```
 
+```python
+uv run mcp install server.py:mcp_server
+```
+
+</details>
+
 > [!TIP]
 > The above command updates the MCP config in Claude desktop. Whilst Claude Desktop only supports `stdio` transport the server can be directly executed with communication via `sse` transport and HTTP requests. For documentation on how to do this see [direct_execution.md](docs/direct_execution.md).
 

application_tests/tests.py

@@ -9,8 +9,8 @@
 OKGREEN = "\033[92m"
 ENDC = "\033[0m"
 
-COMMAND = "python"
-ARGS = ["agent_uno/server.py"]
+COMMAND = "uv"
+ARGS = ["run", "agent-uno"]
 SERVER_PARAMS = StdioServerParameters(
     command=COMMAND,
     args=ARGS,
@@ -88,7 +88,7 @@
     {
         "name": "get_board_representation",
         "description": "Get the current board as an ASCII representation and all "
-        "previous\n    moves.",
+        "previous moves.",
         "inputSchema": {
             "properties": {},
             "title": "get_board_representationArguments",

docs/direct_execution.md

@@ -5,7 +5,7 @@
 Currently testing of endpoints can be performed with the following command:
 
 ```bash
-uv run mcp dev server.py
+uv run mcp dev src/agent_uno/server.py:mcp_server
 ```
 
 This will start a local server running `Inspector` than can be used to interact with the MCP tools.
@@ -17,7 +17,7 @@ This will start a local server running `Inspector` than can be used to interact
 You can run the server directly with the following command:
 
 ```bash
-uv run mcp run server.py --transport sse
+uv run agent-uno --transport sse
 ```
 
 > [!NOTE]

pyproject.toml

@@ -7,12 +7,16 @@ readme = "README.md"
 requires-python = ">=3.12,<4.0"
 dependencies = [
     "berserk>=0.13.2",
+    "click>=8.1.8",
     "mcp[cli]>=1.6.0",
     "pydantic>=2.11.1",
     "python-chess>=1.999",
     "python-dotenv (>=1.1.0,<2.0.0)",
 ]
 
+[project.scripts]
+agent-uno = "agent_uno:main"
+
 [dependency-groups]
 dev = ["pytest>=7.2.0", "pytest-cov>=4.0.0", "licensecheck>=2024.1.2"]
 

src/agent_uno/__init__.py

@@ -0,0 +1,20 @@
+"""Top-level package for agent_uno."""  # noqa: N999
+
+from typing import Literal
+
+import click
+
+from .server import mcp_server
+
+Transport = Literal["stdio", "sse"]
+
+
+@click.command()  # type: ignore
+@click.option("--transport", default="stdio", help="The MCP transport type.")  # type: ignore
+def main(transport: Transport) -> None:
+    """Main function to run the MCP server."""
+    mcp_server.run(transport=transport)
+
+
+if __name__ == "__main__":
+    main()

src/agent_uno/__main__.py

@@ -0,0 +1,5 @@
+"""Main entry point for the Agent UNO project."""
+
+from agent_uno import main
+
+main()

agent_uno/server.py → src/agent_uno/server.py

@@ -29,7 +29,7 @@
 load_dotenv()
 
 logger = logging.getLogger(__name__)
-mcp = FastMCP("chess-mcp", dependencies=["berserk", "python-chess"])
+mcp_server = FastMCP("chess-mcp", dependencies=["berserk", "python-chess"])
 
 BOT_LEVEL = 3
 LICHESS_ADDRESS = "https://lichess.org"
@@ -63,7 +63,7 @@ def is_set_wrapper(*args: Any, **kwargs: dict[str, Any]) -> Any:
     return is_set_wrapper
 
 
-@mcp.tool(description="Login to LiChess.")  # type: ignore
+@mcp_server.tool(description="Login to LiChess.")  # type: ignore
 async def login() -> None:
     """Login to LiChess using the provided API key.
 
@@ -81,14 +81,14 @@ async def login() -> None:
 
 
 @client_is_set_handler
-@mcp.tool(description="Get account info.")  # type: ignore
+@mcp_server.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 against an AI.")  # type: ignore
+@mcp_server.tool(description="Create a new game against an AI.")  # type: ignore
 async def create_game_against_ai(level: int = BOT_LEVEL) -> UIConfig:
     """An endpoint for creating a new game."""
     response = CreatedGameAI(
@@ -103,7 +103,7 @@ async def create_game_against_ai(level: int = BOT_LEVEL) -> UIConfig:
 
 
 @client_is_set_handler
-@mcp.tool(description="Create a new game against a person.")  # type: ignore
+@mcp_server.tool(description="Create a new game against a person.")  # type: ignore
 async def create_game_against_person(username: str) -> UIConfig:
     """An endpoint for creating a new game."""
     response = CreatedGamePerson(
@@ -119,7 +119,7 @@ async def create_game_against_person(username: str) -> UIConfig:
 
 
 @client_is_set_handler
-@mcp.tool(description="Whether the opponent had made there first move or not.")  # type: ignore
+@mcp_server.tool(description="Whether the opponent had made there first move or not.")  # type: ignore
 async def is_opponent_turn() -> GameStateMsg:
     """Whether the opponent had made there first move or not."""
     moves = await get_previous_moves()
@@ -136,7 +136,7 @@ async def is_opponent_turn() -> GameStateMsg:
 
 @client_is_set_handler
 @id_is_set_handler
-@mcp.tool(description="End game.")  # type: ignore
+@mcp_server.tool(description="End game.")  # type: ignore
 async def end_game() -> None:
     """End the current game."""
     SESSION_STATE["client"].board.resign_game(SESSION_STATE["id"])
@@ -154,7 +154,7 @@ async def get_game_state() -> CurrentState:
 
 @client_is_set_handler
 @id_is_set_handler
-@mcp.tool(description="Make a move.")  # type: ignore
+@mcp_server.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)
@@ -185,19 +185,15 @@ async def get_board() -> Board:
     return Board(fen)
 
 
-@mcp.tool(
-    description="""Get the current board as an ASCII representation and all previous
-    moves."""
+@mcp_server.tool(
+    description="Get the current board as an ASCII representation and all previous "
+    "moves."
 )  # type: ignore
-async def get_board_representation() -> BoardRepresentation | GameStateMsg:
+async def get_board_representation() -> BoardRepresentation:
     """An endpoint for getting the current board as an ASCII representation."""
     board = await get_board()
     previous_moves = await get_previous_moves()
 
     return BoardRepresentation(
         board=board.__str__(), previous_moves=previous_moves, check=board.is_check()
     )
-
-
-if __name__ == "__main__":
-    mcp.run()