Rubik's Cube MCP Server

魔方MCP服务器

一个模型上下文协议（MCP）服务器，为AI代理提供解决Rubi###4的能力。 finish

完成魔方游戏。

参数：

• gameId （string）：游戏会话ID

退货：

• 最终比赛统计
• 移动历史记录
• 通过系统操作和实时可视化，显示祝贺消息的完成状态。

特性

• 交互式立方体操作：执行标准魔方移动（U、D、L、R、F、B及其变体）
• 可配置难度：为不同的挑战级别设置1-100步的难度
• MCP UI集成：直接从MCP服务器交付的交互式web组件，带有可点击的游戏链接
• 游戏会话管理：加入现有游戏或使用可自定义设置创建新游戏
• 3D实时可视化：使用Three.js和WebGL实现美丽的3D立方体可视化
• WebSocket实时更新：MCP服务器和web界面之间的实时状态同步
• 鼠标交互：使用鼠标控件旋转和检查三维立方体
• 递归工作流：AI代理可以使用nextAction指导系统地解决立方体问题
• 状态跟踪：完整的移动历史记录和当前多维数据集状态监控
• 溶液检测：使用庆祝效果解决立方体问题时自动检测

安装和设置

先决条件

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

再进行

cd rubiks-cube-mcp-server
npm install

构建项目

npm run build

运行服务器

npx rubiks-cube-mcp-server

这将同时开始：

• stdio上的MCP服务器（用于AI代理通信）
• Web可视化服务器已打开 http://localhost:3000

Claude桌面配置

要将此MCP服务器与Claude Desktop一起使用，请将以下内容添加到您的 claude_desktop_config.json:

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

配置文件位置：

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

添加配置后，重新启动Claude Desktop以加载MCP服务器。

MCP工具

1. startCube

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

参数：

• scramble （可选，布尔值）：是否对多维数据集进行初始加密（默认值：true）
• difficulty （可选，数字）：加扰移动次数（1-100，默认值：20）

退货：

• 带有可点击游戏链接的MCP UI资源
• 会话的游戏ID
• 具有难度级别的初始多维数据集状态
• 可视化URL
• 下一步行动指南

2. joinGame

加入现有的魔方游戏会话。

参数：

• gameId （string）：要加入的游戏会话ID

退货：

• 当前多维数据集状态
• 游戏元数据，包括难度
• 下一步行动指南

3. manipulateCube

在魔方上执行一个动作。

参数：

• gameId （string）：游戏会话ID
• move （字符串）：标准立方体表示法（U、D、L、R、F、B、U'、D'、L'、R'、F'、B'、U2、D2、L2、R2、F2、B2）

退货：

• 已更新多维数据集状态
• 移动执行确认
• 总移动次数
• 下一步行动指南

4. finish

完成魔方游戏。

参数：

• gameId （string）：游戏会话ID

退货：

• 最终比赛统计
• 移动历史记录
• 完成状态

立方体符号

服务器使用标准的魔方表示法：

• U：顺时针朝上
• D：顺时针朝下
• L：左表面顺时针
• R：右面顺时针
• F：正面顺时针
• B：背面顺时针
• '：逆时针（例如U’）
• 2：双转弯（例如U2）

AI Agent使用示例

Agent: "Start a new Rubik's cube puzzle with easy difficulty"
→ startCube tool called with { scramble: true, difficulty: 5 }
→ Returns MCP UI resource with clickable game link + game state

Agent: "Join existing game cube_123456789_abc"
→ joinGame tool called with gameId
→ Returns current cube state and game metadata

Agent: "Execute move U"
→ manipulateCube tool called with move "U"
→ Returns updated state and nextAction guidance

Agent: "Continue solving..."
→ Recursive manipulateCube calls until solved
→ finish tool called when complete with celebration message

Web可视化

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

• 实时三维立方体表示
• 颜色编码的面孔（白色、黄色、红色、橙色、蓝色、绿色）
• 移动计数器和历史记录
• 交互式移动按钮
• 解决方案状态指示器

MCP UI功能

服务器现在包括MCP UI集成，以增强用户体验：

• 可点击的游戏链接：启动新游戏时，服务器返回一个交互式UI资源，其中包含指向web可视化的可点击链接
• 游戏会话管理：支持加入其他用户或会话创建的现有游戏
• 视觉反馈：明确显示游戏状态、难度级别和下一步行动

用UI开始游戏

当你打电话给 startCube 工具，您将收到：

1. 一个可点击的UI资源，直接链接到游戏
2. JSON格式的完整游戏状态数据
3. 元数据，包括难度级别和下一步行动指南

加入现有游戏

使用 joinGame 使用游戏ID参与其他地方创建的游戏的工具：

• 非常适合协作解决
• 保持完整的游戏状态和历史记录
• 与现有MCP工作流程无缝集成

建筑

• MCP协议：用于AI代理通信的标准模型上下文协议
• MCP UI集成：交互式web组件 @mcp-ui/server 可点击资源
• 三维渲染：Three.js基于WebGL的三维立方体可视化
• 实时通信：Socket.io WebSocket服务器用于实时更新
• Web服务器：用于HTTP API和静态内容的Express.js服务器
• 状态管理：具有实时同步功能的内存游戏会话跟踪
• 可配置难度：从初学者到专家级别的可扩展的混乱复杂性

工作流模式

服务器遵循递归MCP模式：

1. 开始 → 返回nextAction：'manipulateKube'
2. 操纵 → 返回nextAction：'manipulateKube'（如果未解决）或'finish'（如果已解决）
3. 完成 → 返回nextAction:null（工作流完成）

这允许AI代理在解决过程中自主工作。

发展

观看模式

npm run dev

建筑

npm run build

项目结构

src/
  ├── app.ts              # Main MCP server setup
  ├── cubeLogic.ts        # Rubik's Cube simulation logic
  ├── visualizationServer.ts  # Web visualization server
  └── types.ts            # TypeScript interfaces

许可证

MIT许可证-有关详细信息，请参阅许可证文件。