内容
# Chess MCP Server
一个模型上下文协议(Model Context Protocol,MCP)服务器,提供使用MCP-UI的互动国际象棋游戏体验。该服务器通过MCP工具暴露国际象棋游戏功能,并提供基于Web的棋盘界面以进行游戏。
## 特性
- ♟️ **完整国际象棋游戏**:使用 chess.js 完成的国际象棋实现
- 🔧 **MCP工具**:作为MCP工具暴露的国际象棋游戏操作
- 🎮 **互动用户界面**:使用 ChessBoard.js 的基于Web的棋盘
- 💾 **游戏状态管理**:基于会话的持久游戏状态保存
## 工作坊
在 `./workshop` 目录中,您可以找到创建此MCP服务器的逐步指南。
## 架构
该MCP服务器使用Express.js构建,并集成了MCP功能:
### 关键组件
- **MCP服务器** (`src/server.ts`): 具有国际象棋工具和UI生成的主服务器
- **存储** (`src/lib/store.ts`): 使用文件系统的游戏状态持久化
- **MCP框架** (`src/lib/mcp/`): 自定义MCP中间件实现与Express集成
### 可用的MCP工具
- `chess_get_board_state`: 获取当前棋盘状态及其可视化表示
- `chess_move`: 以标准代数记法(例如,e4,Nf3,O-O)进行移动或开始新游戏
## 开始使用
### 先决条件
- Node.js 18+
- npm
### 安装
安装依赖项:
```bash
npm install
```
### 开发
启动开发服务器:
```bash
npm run dev
```
服务器将在以下地址可用:
- MCP端点: `http://localhost:3000/mcp`
### 开发命令
- `npm run dev` - 启动开发服务器
## 使用
### 作为MCP服务器
该服务器暴露MCP工具,可以被MCP客户端使用:
```typescript
// 获取当前棋盘状态
{
"method": "tools/call",
"params": {
"name": "chess_get_board_state",
"arguments": {}
}
}
// 进行移动
{
"method": "tools/call",
"params": {
"name": "chess_move",
"arguments": {
"move": "e4"
}
}
}
// 开始新游戏
{
"method": "tools/call",
"params": {
"name": "chess_move",
"arguments": {
"move": "new"
}
}
}
```
### 互动棋盘
使用MCP工具时,每个响应包括:
- **文本表示**:带有有效移动的ASCII棋盘和FEN记法
- **互动用户界面**:允许通过鼠标交互进行移动的拖放棋盘
## 游戏规则
- 适用标准国际象棋规则
- 使用 chess.js 进行移动验证和游戏逻辑
- 支持所有合法的国际象棋移动,包括王车易位、过路兵和兵升变
- 游戏状态根据会话ID持久化
## 项目结构
```
src/
├── lib/
│ ├── mcp/ # 自定义MCP中间件框架
│ │ ├── index.ts # 主要导出
│ │ ├── middleware.ts # Express中间件集成
│ │ ├── header.ts # HTTP头部工具
│ │ └── uuid.ts # UUID验证
│ └── store.ts # 游戏状态持久化
├── server.ts # 具有国际象棋工具和UI的主服务器
games/ # 持久游戏文件(FEN记法)
```
## 游戏状态持久化
- 每个国际象棋游戏保存为 `games/` 目录中的JSON文件
- 游戏通过MCP会话ID进行识别
- 游戏状态以FEN(Forsyth-Edwards Notation)字符串存储
- 当使用相同会话重新连接时,游戏会自动恢复
## 依赖项
- **chess.js**: 国际象棋游戏逻辑和移动验证
- **@chrisoakman/chessboardjs**: 互动棋盘用户界面
- **@mcp-ui/server**: MCP UI资源创建
- **@modelcontextprotocol/sdk**: MCP服务器实现
- **express**: Web服务器框架
## 许可证
Apache 2.0 许可证 - 详见 LICENSE 文件。