国际象棋MCP应用程序
使用OpenAI Apps SDK构建的ChatGPT国际象棋应用程序，允许您通过与交互式棋盘小部件的对话下棋。
现在遵循OpenAI Apps SDK最佳实践！
特性
- 🎮 使用代数符号（e4、Nf3、O-O等）下棋
- 📊 ChatGPT中的交互式棋盘小部件
- 🤖 AI对手建议（ChatGPT可以玩招式）
- 🔍 Stockfish引擎分析集成
- 📝 移动历史跟踪
- ✅ 完整的移动验证和游戏状态管理
- 📋 游戏状态和玩家信息显示
- 🧩 配对1个战术谜题（简单、中等、困难）
建筑
- 后端：使用FastMCP和Python象棋的Python MCP服务器
- 前端：使用chess.js+React棋盘的React组件
- 构建系统：Vite提供最佳开发体验
- 整合：带有适当钩子的OpenAI Apps SDK模式
项目结构
ChessMCP/
├── server/
│ ├── main.py # Python MCP server (renamed from server.py)
│ └── requirements.txt # Python dependencies
├── src/
│ ├── chess-board/ # Chess board component
│ │ └── index.tsx
│ ├── types.ts # Shared TypeScript types
│ ├── use-openai-global.ts # Hook for window.openai access
│ ├── use-widget-state.ts # Hook for widget state
│ └── use-widget-props.ts # Hook for tool props
├── assets/ # Build output (generated by Vite)
│ └── chess-board.html
├── vite.config.mts # Vite configuration
├── package.json # Root dependencies
├── tsconfig.json # TypeScript config
└── README.md安装
先决条件
- Python 3.8+
- Node.js 18+
- Stockfish象棋引擎（可选，用于分析）
设置步骤
- 安装Python依赖项:
cd server
pip3 install -r requirements.txt- 安装Stockfish （可选，用于发动机分析）：
# macOS
brew install stockfish
# Ubuntu/Debian
sudo apt-get install stockfish- 安装Node.js依赖项:
npm install- 构建前端组件:
npm run build这会产生 assets/chess-board.html 由服务器加载。
- MCP服务器已配置 在你的
~/.cursor/mcp.json:
{
"mcpServers": {
"chess": {
"command": "python3",
"args": ["/path/to/ChessMCP/server/main.py"],
"env": {
"PYTHONPATH": "/path/to/ChessMCP/server"
}
}
}
}开发工作流程
一次构建（生产）
npm run build开发模式（热重载）
# Terminal 1: Start Vite dev server
npm run dev
# Terminal 2: Start Python server
cd server
python3 main.py为已建资产提供服务（用于测试）
npm run serve本地测试（不需要ChatGPT！）
选项1：直接本地测试仪（推荐）
直接下棋，无需服务器/Outh:
python3 chess_local_test.py命令：
♟️ > move e4
♟️ > move e5
♟️ > status
♟️ > stockfish
♟️ > puzzle medium📖 请参阅： 位置_测试.md
选项2:HTTP客户端
通过HTTP进行测试（需要服务器运行）：
# Terminal 1: Start server
cd server && python3 main.py
# Terminal 2: Start client
python3 chess_client.py📖 请参阅： CLIENT_USAGE.md
使用ChatGPT进行测试
国际象棋MCP服务器现在包括 Google OAuth 2.1身份验证 用于安全的ChatGPT集成！
📖 快速入门： OAUTH_QUICK_START.md （5分钟）\ 📖 详细设置： GOOGLE_OAUTH_SETUP.md （一步一步）\ 📖 下一步： NEXT_STEPS.md （现在该怎么办）\ 📖 故障排除： CHATGPT_CONNECTOR_TROUBESHOTING.md
快速启动：
# 1. Set up Google OAuth credentials (see GOOGLE_OAUTH_SETUP.md)
# 2. Create server/.env with credentials
# Terminal 1: Start server
cd server
pip3 install -r requirements.txt
python3 main.py
# Terminal 2: Expose with ngrok
ngrok http 8000
# Update server/.env with ngrok URL, restart server
# Then add connector in ChatGPT Settings > Connectors
# URL format: https://YOUR-SUBDOMAIN.ngrok-free.app (no /mcp suffix)用法
开始游戏
在ChatGPT中，通过第一步开始下棋：
ChessMCP e4或
Let's play chess! I'll start with e4交互式棋盘将显示您的移动。
采取行动
只需在代数符号中键入您的移动：
Nf3
e5
Bc4
Nc6支持的符号：
- 基本动作：
e4,Nf3,d5 - 捕获：
exd5,Nxf7 - 铸造：
O-O（国王），O-O-O（答案） - 典当促销：
e8=Q,a1=N - 检查：
Qh5+ - 核对：
Qf7#
附加命令
检查游戏状态：
chess_status
What's the current status?加载拼图：
Show me a chess puzzle
Give me a hard puzzle获取发动机分析：
Ask Stockfish for the best move重置游戏：
chess_reset
Let's start a new gameMCP工具
服务器公开了五个工具：
chess_move
- 输入:
move（字符串）-代数记数法 - 输出：更新了FEN、移动历史、游戏状态的棋盘状态
- 小部件：渲染交互式棋盘
chess_stockfish
- 输入:
depth（int，默认值：15）-分析深度 - 输出：最佳移动、评估、主要变化
- 小部件可访问：可以从小部件UI调用
chess_reset
- 输入：无
- 输出：重置确认
- 小部件：显示新的起始位置
chess_status ⭐
- 输入：无
- 输出：游戏状态、当前回合、玩家姓名、移动次数、最近移动
- 使用：检查游戏进度和谁在移动
chess_puzzle ⭐
- 输入:
difficulty（字符串：“易”、“中”、“难”） - 输出：带提示的一对一拼图位置
- 小部件：显示棋盘上的拼图位置
- 使用：练习战术模式和对垒识别
React Hooks（应用程序SDK模式）
该组件使用OpenAI Apps SDK挂钩来实现干净、反应式的代码：
useOpenAiGlobal(key)
被动访问window.openai属性：
const theme = useOpenAiGlobal("theme");
const displayMode = useOpenAiGlobal("displayMode");useToolOutput()
获取当前工具输出：
const toolOutput = useToolOutput();
// Returns: { fen, move, status, turn }useToolResponseMetadata()
获取工具响应元数据：
const metadata = useToolResponseMetadata();
// Returns: { move_history_list, legal_moves, etc. }useWidgetState(defaultState)
跨会话持久化组件状态：
const [widgetState, setWidgetState] = useWidgetState({
lastDepth: 15,
analysisVisible: false
});构建系统（Vite）
为什么选择Vite？
- ⚡️ 开发过程中快速更换热模块
- 📦 优化生产构建
- 🎯 开箱即用的TypeScript支持
- 🔧 更好的错误消息
- 🎨 用于调试的源映射
构建输出
该构建创建了一个HTML文件，其中包含：
- 捆绑的React组件
- 所有JavaScript依赖项
- 内联CSS
- 天桥运行时的适当结构
配置
看 vite.config.mts 对于构建配置。设置：
- 捆绑包
src/chess-board/index.tsx - 包括所有依赖项
- 用具有适当结构的HTML包装
- 输出到
assets/chess-board.html
服务器架构
资源处理
服务器遵循Apps SDK模式：
# Load HTML from assets
@lru_cache(maxsize=None)
def load_widget_html(component_name: str) -> str:
html_path = ASSETS_DIR / f"{component_name}.html"
return html_path.read_text(encoding="utf8")
# Proper MIME type
MIME_TYPE = "text/html+skybridge"
# Resource registration
@mcp._mcp_server.list_resources()
async def list_resources() -> List[types.Resource]:
return [types.Resource(...)]
# Resource handler
async def handle_read_resource(req) -> types.ServerResult:
html = load_widget_html("chess-board")
return types.ServerResult(types.ReadResourceResult(...))工具元数据
所有工具都包含适当的元数据：
{
"openai/outputTemplate": "ui://widget/chess-board.html",
"openai/widgetAccessible": True,
"openai/resultCanProduceWidget": True,
"openai/toolInvocation/invoking": "Making move...",
"openai/toolInvocation/invoked": "Move played"
}故障排除
小部件未渲染
- 确保组件已构建：
npm run build - 验证
assets/chess-board.html存在 - 检查服务器日志是否有错误
未找到Stockfish
更新中的路径 server/main.py:
STOCKFISH_PATH = "/path/to/stockfish"构建错误
如果发生TypeScript错误：
npm run typecheck服务器无法启动
确保所有Python依赖项都已安装：
cd server
pip3 install -r requirements.txt此版本的新变化
✨ 重组项目
- 从移动
web/到src/目录 - 根水平
package.json和vite.config.mts - 正确的Apps SDK项目结构
🎣 React挂钩
useOpenAiGlobal用于反应式窗口.openai访问useWidgetState用于持久状态管理useToolOutput和useToolResponseMetadata用于道具
⚡ Vite构建系统
- 将esbuild替换为Vite
- 开发中的热模块更换
- 更好的TypeScript支持
- 更快的构建
🏗️ 服务器改进
- 从以下位置加载适当的资源
assets/ - 正确的MIME类型(
text/html+skybridge) - 更好的错误处理
- 用于开发的CORS中间件
📝 更好的类型
- 全面的TypeScript类型
- Apps SDK兼容接口
- 国际象棋特定类型定义
贡献
您可以通过以下方式增强应用程序：
- 开局分析和残局表库
- 多个游戏会话
- PGN进口/出口
- 时间控制
- 在线多人游戏
- 更多拼图类型
许可证
MIT许可证-随意使用和修改！