What is Gomoku Ai Battle

gomoku-ai-battle is a Gomoku AI battle platform based on the MCP (Model Context Protocol) that enables real-time matches between AI players, such as Claude AI, through the MCP interface.

Use cases

Use cases include conducting AI vs AI tournaments, analyzing AI performance in strategic games, and providing a platform for developers to test and improve their AI algorithms.

How to use

To use gomoku-ai-battle, install the required dependencies, start the game server, and configure your AI client to connect to the MCP server. Access the web interface to observe live matches.

Key features

Key features include real AI battles, real-time viewing through a web interface, complete game logic adhering to standard 15x15 Gomoku rules, data statistics including player rankings and game history, and a modular design for easy extension.

Where to use

gomoku-ai-battle can be used in AI research, game development, educational purposes for learning AI strategies, and entertainment through AI competitions.

五子棋AI对战项目

基于MCP (Model Context Protocol) 的五子棋AI对战平台，让AI通过MCP接口进行五子棋对战。

✨ 项目亮点

• 🤖 真实AI对战: 支持Claude等AI通过MCP协议直接对战
• 👁️ 实时观战: 精美的Web界面实时显示对战过程
• 🎯 完整游戏逻辑: 标准15x15五子棋规则，支持胜负判断
• 📊 数据统计: 玩家排行榜、游戏历史、统计分析
• 🔧 易于扩展: 模块化设计，支持自定义AI算法

🎮 演示效果

已成功实现Claude AI vs Claude AI对战！

• ✅ 两个AI实例同时连接
• ✅ 实时下棋和状态更新
• ✅ Web界面完美显示棋盘
• ✅ 游戏逻辑完全正确

项目结构

gomoku-ai-battle/
├── README.md                    # 项目说明
├── requirements.txt             # Python依赖
├── GOMOKU_AI_BATTLE_PROJECT.md  # 详细项目文档
├──
├── game_server/                 # 游戏服务端
│   ├── main.py                  # FastAPI应用入口
│   ├── config.py                # 配置文件
│   ├── models/                  # 数据模型
│   ├── services/                # 业务逻辑
│   └── api/                     # API路由
│
├── mcp_server/                  # MCP服务器
│   ├── gomoku_mcp.py            # MCP服务器主文件
│   ├── config.py                # MCP配置
│   └── tools/                   # MCP工具
│
├── ai_client/                   # AI客户端
│   ├── mcp_client.py            # MCP客户端封装
│   └── simple_ai.py             # 简单AI实现
│
├── scripts/                     # 脚本工具
│   ├── start_game_server.py     # 启动游戏服务端
│   ├── start_mcp_server.py      # 启动MCP服务器
│   └── run_ai_battle.py         # 运行AI对战
│
└── tests/                       # 测试代码
    ├── test_game_logic.py       # 游戏逻辑测试
    └── test_mcp_server.py       # MCP服务器测试

🚀 快速开始

1. 安装依赖

pip install -r requirements.txt

2. 启动游戏服务端

python scripts/start_game_server.py

游戏服务端将在 http://localhost:8000 启动：

• 🌐 Web界面: http://localhost:8000
• 📚 API文档: http://localhost:8000/docs
• 🎮 观战台: http://localhost:8000/static/index.html

3. 配置Claude Desktop

在Claude Desktop配置文件中添加MCP服务器：

配置文件位置:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

配置内容:

{
  "mcpServers": {
    "gomoku-mcp-server": {
      "command": "python",
      "args": [
        "D:\\your\\project\\path\\scripts\\start_mcp_server.py"
      ],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "MCP_GAME_SERVER_URL": "http://localhost:8000"
      }
    }
  }
}

4. 启动MCP服务器

python scripts/start_mcp_server.py

5. 重启Claude Desktop

完全关闭并重新打开Claude Desktop，让配置生效。

6. 开始AI对战！

现在Claude AI可以直接通过MCP工具进行五子棋对战：

我想创建一个五子棋房间开始对战

或者运行示例AI客户端：

# 运行2个AI对战
python scripts/run_ai_battle.py --mode battle --ai-count 2

# 让AI加入指定房间
python scripts/run_ai_battle.py --mode join --room-id room_12345 --ai-id AI_Test

使用说明

游戏服务端API

游戏服务端提供REST API接口：

• POST /api/v1/rooms - 创建房间
• GET /api/v1/rooms - 获取房间列表
• POST /api/v1/rooms/{room_id}/join - 加入房间
• POST /api/v1/rooms/{room_id}/move - 下棋
• GET /api/v1/rooms/{room_id}/game - 获取游戏状态

🛠️ MCP工具

MCP服务器提供以下工具供AI调用：

游戏操作工具：

• create_room(creator_id, room_name) - 创建房间
• join_room(room_id, player_id) - 加入房间
• leave_room(room_id, player_id) - 离开房间
• start_game(room_id, player_id) - 开始游戏
• make_move(room_id, player_id, x, y) - 下棋
• get_move_suggestions(room_id, player_id, count) - 获取下棋建议
• get_leaderboard(limit, sort_by) - 获取排行榜
• get_server_status() - 获取服务器状态

信息查询资源：

• board_state://{room_id} - 获取棋盘状态
• game_info://{room_id} - 获取游戏信息
• gomoku://room_list - 获取房间列表
• player_info://{player_id} - 获取玩家信息

🎯 AI对战示例

创建房间并开始对战：

Claude: 我想创建一个五子棋房间
AI: 成功创建房间 'Claude的AI对战房间'，房间ID: room_3b93ac16

Claude: 让另一个AI加入房间
AI: 成功加入房间 room_3b93ac16

Claude: 开始游戏并下第一步棋在中心位置
AI: 下棋成功

Claude: 查看当前棋盘状态
AI: [显示15x15棋盘，中心有黑子●]

实际演示结果：

• ✅ 成功创建房间：room_3b93ac16
• ✅ 两个AI同时对战：Claude_AI_1 vs Claude_AI_2
• ✅ 已进行7步对战，游戏进行中
• ✅ Web界面实时显示棋盘状态

AI客户端开发

使用 GomokuMCPClient 类可以轻松开发AI客户端：

from ai_client.mcp_client import GomokuMCPClient

async def my_ai():
    async with GomokuMCPClient() as client:
        # 创建房间
        result = await client.create_room("my_ai", "测试房间")

        # 获取棋盘状态
        board = await client.get_board_state("room_id")

        # 下棋
        result = await client.make_move("room_id", "my_ai", 7, 7)

配置

游戏服务端配置

在 game_server/config.py 中可以配置：

• 服务器地址和端口
• 棋盘大小和获胜条件
• 房间和玩家限制
• 日志级别

MCP服务器配置

在 mcp_server/config.py 中可以配置：

• 游戏服务器连接地址
• 连接超时和重试设置
• AI建议数量限制
• 日志级别

开发和测试

运行测试

# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_game_logic.py
pytest tests/test_mcp_server.py

开发模式

# 启动游戏服务端（开发模式）
python scripts/start_game_server.py --debug --reload

# 启动MCP服务器（调试模式）
python scripts/start_mcp_server.py --debug --log-level DEBUG

🏗️ 架构说明

系统架构

┌─────────────┐    MCP     ┌─────────────┐    HTTP    ┌─────────────┐
│   Claude AI  │ ←────────→ │  MCP 服务器   │ ←────────→ │  游戏服务端   │
│  (黑子玩家)   │            │             │            │             │
└─────────────┘            └─────────────┘            └─────────────┘
                                  ↑                           ↑
                                  │ MCP                       │ HTTP
                                  ↓                           ↓
┌─────────────┐            ┌─────────────┐            ┌─────────────┐
│   Claude AI  │ ←────────→ │  MCP 服务器   │            │   Web 观战台  │
│  (白子玩家)   │            │   (同一个)    │            │             │
└─────────────┘            └─────────────┘            └─────────────┘

数据流

1. AI连接: Claude AI通过MCP协议连接到MCP服务器
2. 指令转换: MCP服务器将AI指令转换为HTTP API调用
3. 游戏处理: 游戏服务端处理五子棋逻辑并更新状态
4. 结果返回: MCP服务器将游戏结果返回给AI
5. 实时观战: Web界面实时显示棋盘状态

技术栈

• 游戏服务端: Python + FastAPI + Pydantic + Uvicorn
• MCP服务器: MCP Python SDK (FastMCP) + httpx
• Web界面: HTML5 + CSS3 + JavaScript + 实时刷新
• AI客户端: Claude Desktop + MCP协议
• 通信协议: HTTP REST API + MCP stdio + WebSocket(可选)

核心特性

• 🔄 实时同步: 游戏状态实时同步到所有客户端
• 🎯 精确控制: 坐标系统(0-14)，支持精确下棋
• 🛡️ 错误处理: 完善的异常处理和重试机制
• 📊 状态管理: 完整的游戏状态和房间管理
• 🎮 多模式: 支持AI vs AI、观战、统计等多种模式

🎉 成功案例

实际对战记录

房间信息:

• 房间ID: room_3b93ac16
• 房间名: “Claude的AI对战房间”
• 对战双方: Claude_AI_1 (黑子) vs Claude_AI_2 (白子)

对战进程:

1. ✅ Claude_AI_1 创建房间
2. ✅ Claude_AI_2 成功加入
3. ✅ 游戏自动开始
4. ✅ 已进行7步对战
5. ✅ Web界面实时显示

棋盘状态:

当前棋盘 (第7步后):
   0  1  2  3  4  5  6  7  8  9 10 11 12 13 14
 0  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·
 1  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·
 ...
 7  ·  ·  ·  ·  ○  ●  ●  ●  ○  ○  ·  ·  ·  ·  ·
 8  ·  ·  ·  ·  ·  ·  ·  ·  ●  ·  ·  ·  ·  ·  ·
 ...

技术验证:

• ✅ MCP协议通信正常
• ✅ 游戏逻辑完全正确
• ✅ Web界面实时更新
• ✅ 多AI并发支持
• ✅ 错误处理机制有效

🚀 扩展功能

项目支持以下扩展：

• 🧠 更复杂的AI算法 (已有基础框架)
• 👁️ Web界面观战 (✅ 已实现)
• 📹 游戏回放功能
• 🎲 多种棋类支持 (象棋、围棋等)
• 💾 数据库持久化
• 🔐 用户认证系统
• 📊 高级统计分析
• 🏆 AI算法评分系统
• 🌐 多人在线对战
• 📱 移动端支持

🔧 故障排除

常见问题及解决方案

1. MCP服务器无法启动

   错误: URL validation error
   解决: 检查资源URI格式，确保使用有效的URL scheme
   

2. HTTP 307重定向错误

   错误: 游戏服务器错误: 307 Temporary Redirect
   解决: 在httpx请求中添加 follow_redirects=True
   

3. Claude Desktop看不到MCP工具

   问题: 配置文件修改后工具不显示
   解决:
   - 确保配置文件路径正确
   - 完全重启Claude Desktop
   - 检查MCP服务器是否启动
   

4. 游戏服务端连接失败

   错误: 连接游戏服务器失败
   解决:
   - 确保游戏服务端在 http://localhost:8000 运行
   - 检查端口是否被占用
   - 查看防火墙设置
   

5. 下棋失败

   错误: 无效的下棋位置
   解决:
   - 确保坐标在0-14范围内
   - 检查位置是否已被占用
   - 确认轮到当前玩家
   

调试步骤

1. 验证服务端状态

   curl http://localhost:8000/api/v1/health
   # 应返回: {"status":"healthy",...}
   

2. 检查MCP连接

   python scripts/start_mcp_server.py --debug
   # 查看详细日志输出
   

3. 测试API调用

   curl http://localhost:8000/api/v1/rooms/
   # 应返回房间列表JSON
   

日志查看

# 查看游戏服务端日志
python scripts/start_game_server.py --log-level DEBUG

# 查看MCP服务器日志
python scripts/start_mcp_server.py --debug --log-level DEBUG

# 查看AI对战日志
tail -f ai_battle.log

成功验证清单

• ✅ 游戏服务端启动: http://localhost:8000
• ✅ MCP服务器启动: 显示"启动五子棋MCP服务器"
• ✅ Claude Desktop重启: 配置生效
• ✅ MCP工具可见: 在Claude中可以调用工具
• ✅ 创建房间成功: 返回房间ID
• ✅ 下棋成功: 返回"下棋成功"
• ✅ Web界面显示: 棋盘实时更新

贡献

欢迎提交Issue和Pull Request来改进项目！

许可证

MIT License