rubiks-cube-mcp-server

🚀 魔方MCP服务器

这是一个模型上下文协议（MCP）服务器，它能让AI智能体通过系统操作和实时可视化来解决魔方谜题。

✨ 主要特性

• 交互式魔方操作：可执行标准的魔方转动操作（U、D、L、R、F、B及其变体）
• 3D实时可视化：利用Three.js和WebGL实现精美的3D魔方可视化效果
• WebSocket实时更新：实现MCP服务器和网页界面之间的实时状态同步
• 鼠标交互：可通过鼠标控制旋转和查看3D魔方
• 递归工作流：AI智能体可根据nextAction指导，系统地完成魔方求解
• 状态跟踪：完整记录转动历史并监控当前魔方状态
• 解法检测：当魔方被成功还原时，自动检测并展示庆祝效果

📦 安装指南

前提条件

• Node.js 18.x或更高版本
• npm或yarn

安装依赖

cd rubiks-cube-mcp-server
npm install

构建项目

npm run build

启动服务器

npx rubiks-cube-mcp-server

这将同时启动以下两个服务：

• 通过标准输入输出（stdio）启动MCP服务器（用于与AI智能体通信）
• 在http://localhost:3000启动网页可视化服务器

📚 详细文档

Claude桌面配置

要将此MCP服务器与Claude桌面版配合使用，请在claude_desktop_config.json文件中添加以下内容：

{
  "mcpServers": {
    "rubiks-cube": {
      "command": "npx",
      "args": ["rubiks-cube-mcp-server"]
    }
  }
}

配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json 添加配置后，重启Claude桌面版以加载MCP服务器。

MCP工具

1. startCube

初始化一个新的魔方游戏会话。 参数：

• scramble（可选，布尔值）：是否在初始时打乱魔方（默认值：true） 返回值：
• 会话的游戏ID
• 初始魔方状态
• 可视化URL
• 下一步操作指导

2. manipulateCube

在魔方上执行一次转动操作。 参数：

• gameId（字符串）：游戏会话ID
• move（字符串）：标准的魔方转动符号（U、D、L、R、F、B、U'、D'、L'、R'、F'、B'、U2、D2、L2、R2、F2、B2） 返回值：
• 更新后的魔方状态
• 转动操作执行确认
• 总转动次数
• 下一步操作指导

3. finish

结束魔方游戏会话。 参数：

• gameId（字符串）：游戏会话ID 返回值：
• 最终游戏统计信息
• 转动历史记录
• 完成状态

魔方符号说明

服务器使用标准的魔方转动符号：

• U：顶面顺时针转动
• D：底面顺时针转动
• L：左面顺时针转动
• R：右面顺时针转动
• F：前面顺时针转动
• B：后面顺时针转动
• '：逆时针转动（例如，U'）
• 2：转动两次（例如，U2）

与AI智能体的使用示例

智能体: "开始一个新的魔方谜题"
→ 调用startCube工具
→ 返回打乱后的魔方状态和游戏ID

智能体: "执行转动U"
→ 调用manipulateCube工具，转动为 "U"
→ 返回更新后的状态和下一步操作指导

智能体: "继续求解..."
→ 递归调用manipulateCube，直到魔方被还原
→ 完成后调用finish工具

网页可视化

访问http://localhost:3000/game/{gameId}可查看：

• 实时的3D魔方展示
• 颜色编码的面（白色、黄色、红色、橙色、蓝色、绿色）
• 转动计数器和历史记录
• 交互式转动按钮
• 解法状态指示器

架构

• MCP协议：用于与AI智能体通信的标准模型上下文协议
• 3D渲染：基于Three.js WebGL的3D魔方可视化
• 实时通信：使用Socket.io WebSocket服务器实现实时更新
• Web服务器：使用Express.js服务器提供HTTP API和静态内容
• 状态管理：通过内存中的游戏会话跟踪实现实时同步

工作流模式

服务器遵循递归MCP模式：

1. 开始 → 返回nextAction：'manipulateCube'
2. 操作 → 返回nextAction：'manipulateCube'（未还原时）或 'finish'（还原时）
3. 结束 → 返回nextAction：null（工作流完成） 这允许AI智能体自主完成求解过程。

开发

监听模式

npm run dev

构建

npm run build

项目结构

src/
  ├── app.ts              # 主MCP服务器设置
  ├── cubeLogic.ts        # 魔方模拟逻辑
  ├── visualizationServer.ts  # 网页可视化服务器
  └── types.ts            # TypeScript接口

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。