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文件。