MCP Tic-Tac-Toe

1# MCP Tic-Tac-Toe
2 
3A Model Context Protocol (MCP) server that enables AI assistants to play tic-tac-toe through standardized tool interfaces. Perfect for demonstrating AI-human collaboration and MCP integration.
4 
5![mcp-tic-tac-toe screenshot](./mcp-tic-tac-toe-screenshot.png)
6 
7## Overview
8 
9This project implements a complete tic-tac-toe game as an MCP server, allowing AI assistants like Claude to:
10- Create and manage multiple game sessions
11- Make strategic moves and analyze positions  
12- Provide game commentary and suggestions
13- Play against humans or other AIs
14 
15## Quick Start
16 
17### Prerequisites
18- Go 1.19+ installed
19- Claude Code or other MCP-compatible client
20 
21### Installation
22```bash
23git clone https://github.com/tomholford/mcp-tic-tac-toe
24cd mcp-tic-tac-toe
25go mod tidy
26go build -o bin/server cmd/server.go
27```
28 
29### Basic Usage
30```bash
31# Start MCP server (stdio transport)
32./bin/server
33 
34# Or specify transport method
35./bin/server -transport=sse -addr=:8080
36```
37 
38## MCP Configuration
39 
40### Claude Code Setup
41 
421. **Build the server:**
43   ```bash
44   go build -o bin/server cmd/server.go
45   ```
46 
472. **Add to your MCP configuration:**
48   
49   Create or edit your MCP configuration file:
50   ```bash
51   # For macOS/Linux
52   ~/.config/claude-code/mcp_servers.json
53   
54   # For Windows  
55   %APPDATA%\claude-code\mcp_servers.json
56   ```
57 
583. **Add the server configuration:**
59   ```json
60   {
61     "mcpServers": {
62       "tic-tac-toe": {
63         "command": "/full/path/to/mcp-tic-tac-toe/bin/server",
64         "args": ["-transport=stdio"],
65         "env": {}
66       }
67     }
68   }
69   ```
70 
714. **Restart Claude Code** and the tic-tac-toe tools will be available.
72c
73### Claude Desktop
74 
75```json
76"tic-tac-toe": {
77  "command": "/full/path/to/mcp-tic-tac-toe/bin/server",
78  "args": [""]
79}
80```
81 
82## Available MCP Tools
83 
84The server exposes 8 tools for complete game management:
85 
86### Game Management
87- **`new_game`** - Create a new tic-tac-toe game
88  - Optional: `game_id` (string) - Custom game identifier
89  - Returns: Game ID, starting player, initial board
90 
91- **`list_games`** - Show all active game sessions  
92  - Returns: List of active game IDs
93 
94- **`reset_game`** - Reset a game to initial state
95  - Required: `game_id` (string)
96  - Returns: Confirmation and fresh board
97 
98### Gameplay  
99- **`make_move`** - Execute a move on the board
100  - Required: `game_id` (string), `position` (A1-C3), `player` (X/O)
101  - Returns: Updated board, game status, next player
102 
103- **`get_board`** - Get current board state
104  - Required: `game_id` (string)  
105  - Returns: Board display, current player, move count
106 
107- **`get_available_moves`** - List all valid moves
108  - Required: `game_id` (string)
109  - Returns: Available positions for current player
110 
111### Analysis
112- **`get_status`** - Check game status and winner
113  - Required: `game_id` (string)
114  - Returns: Game status (ongoing/won/draw), winner if applicable
115 
116- **`analyze_position`** - Get strategic analysis  
117  - Required: `game_id` (string)
118  - Returns: Position analysis and board state
119 
120## Usage Examples
121 
122### Start a New Game
123```
124AI: Use the new_game tool
125→ New game created with ID: game-a1b2c3d4
126  Starting player: X
127  Initial board:
128    A B C
129  1 · · ·
130  2 · · ·  
131  3 · · ·
132```
133 
134### Make Strategic Moves
135```
136Human: I'll take the center
137AI: Use make_move tool with {"game_id": "game-a1b2c3d4", "position": "B2", "player": "X"}
138 
139AI: Let me analyze the position first
140AI: Use analyze_position tool → Shows current state and opportunities
141 
142AI: I'll take a corner for strategic advantage  
143AI: Use make_move tool with {"game_id": "game-a1b2c3d4", "position": "A1", "player": "O"}
144```
145 
146### Get Game Status
147```
148AI: Use get_status tool → Game Status: Ongoing, Current player: X, Move count: 2
149AI: Use get_available_moves tool → Available moves (7): A2, A3, B1, B3, C1, C2, C3
150```
151 
152## Transport Options
153 
154The server supports three transport methods:
155 
156### 1. Stdio (Default)
157Best for local MCP clients like Claude Code:
158```bash
159./bin/server -transport=stdio
160```
161 
162### 2. Server-Sent Events (SSE)  
163For web applications and real-time updates:
164```bash
165./bin/server -transport=sse -addr=:8080
166```
167 
168### 3. Streamable HTTP
169For traditional HTTP integrations:
170```bash  
171./bin/server -transport=http -addr=:8080
172```
173 
174## Development
175 
176### Project Structure
177```
178mcp-tic-tac-toe/
179├── cmd/
180│   ├── server.go          # MCP server main entry point
181│   └── demo.go            # Game logic demonstration  
182├── game/                  # Core tic-tac-toe logic
183│   ├── types.go           # Game data structures
184│   ├── engine.go          # Game rules and validation
185│   └── engine_test.go     # Game logic tests
186├── server/                # MCP server implementation  
187│   ├── server.go          # MCP server setup and tools
188│   ├── handlers.go        # Tool request handlers
189│   └── server_test.go     # MCP integration tests
190└── bin/                   # Built executables
191```
192 
193### Running Tests
194```bash
195# Test all packages
196go test ./game ./server -v
197 
198# Test specific functionality
199go test ./game -run TestWinConditions
200go test ./server -run TestMakeMoveTool
201```
202 
203### Building from Source
204```bash
205# Build server
206go build -o bin/server cmd/server.go
207 
208# Build demo
209go build -o bin/demo cmd/demo.go
210 
211# Run demo (no MCP required)
212./bin/demo
213```
214 
215## Resources
216 
217- [MCP Specification](https://modelcontextprotocol.io/) - Official MCP documentation
218- [mcp-go Library](https://github.com/mark3labs/mcp-go) - Go MCP implementation used in this project