fritzprix/rubiks-cube-mcp-server

Rubik's Cube MCP Server

A Model Context Protocol (MCP) server that provides AI agents with the ability to solve Rubi### 4. finish

Complete the Rubik's Cube game session.

Parameters:

• gameId (string): The game session ID

Returns:

• Final game statistics
• Move history
• Completion status with congratulations messageles through systematic manipulation and real-time visualization.

Features

• Interactive Cube Manipulation: Execute standard Rubik's Cube moves (U, D, L, R, F, B and their variations)
• Configurable Difficulty: Set scramble difficulty from 1-100 moves for varied challenge levels
• MCP UI Integration: Interactive web components delivered directly from the MCP server with clickable game links
• Game Session Management: Join existing games or create new ones with customizable settings
• 3D Real-time Visualization: Beautiful 3D cube visualization using Three.js and WebGL
• WebSocket Live Updates: Real-time state synchronization between MCP server and web interface
• Mouse Interaction: Rotate and examine the 3D cube with mouse controls
• Recursive Workflow: AI agents can systematically work through cube solving using nextAction guidance
• State Tracking: Complete move history and current cube state monitoring
• Solution Detection: Automatic detection when the cube is solved with celebration effects

Installation & Setup

Prerequisites

• Node.js 18.x or higher
• npm or yarn

Install Dependencies

cd rubiks-cube-mcp-server
npm install

Build the Project

npm run build

Run the Server

npx rubiks-cube-mcp-server

This will start both:

• MCP server on stdio (for AI agent communication)
• Web visualization server on http://localhost:3000

Claude Desktop Configuration

To use this MCP server with Claude Desktop, add the following to your claude_desktop_config.json:

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

Configuration file locations:

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

After adding the configuration, restart Claude Desktop to load the MCP server.

MCP Tools

1. startCube

Initialize a new Rubik's Cube game session.

Parameters:

• scramble (optional, boolean): Whether to scramble the cube initially (default: true)
• difficulty (optional, number): Number of scramble moves (1-100, default: 20)

Returns:

• MCP UI resource with clickable game link
• Game ID for the session
• Initial cube state with difficulty level
• Visualization URL
• Next action guidance

2. joinGame

Join an existing Rubik's Cube game session.

Parameters:

• gameId (string): The game session ID to join

Returns:

• Current cube state
• Game metadata including difficulty
• Next action guidance

3. manipulateCube

Execute a move on the Rubik's Cube.

Parameters:

• gameId (string): The game session ID
• move (string): Standard cube notation (U, D, L, R, F, B, U', D', L', R', F', B', U2, D2, L2, R2, F2, B2)

Returns:

• Updated cube state
• Move execution confirmation
• Total moves count
• Next action guidance

4. finish

Complete the Rubik's Cube game session.

Parameters:

• gameId (string): The game session ID

Returns:

• Final game statistics
• Move history
• Completion status

Cube Notation

The server uses standard Rubik's Cube notation:

• U: Up face clockwise
• D: Down face clockwise
• L: Left face clockwise
• R: Right face clockwise
• F: Front face clockwise
• B: Back face clockwise
• ': Counter-clockwise (e.g., U')
• 2: Double turn (e.g., U2)

Example Usage with 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 Visualization

Visit http://localhost:3000/game/{gameId} to see:

• Real-time 3D cube representation
• Color-coded faces (White, Yellow, Red, Orange, Blue, Green)
• Move counter and history
• Interactive move buttons
• Solution status indicator

MCP UI Features

The server now includes MCP UI integration for enhanced user experience:

• Clickable Game Links: When starting a new game, the server returns an interactive UI resource with a clickable link to the web visualization
• Game Session Management: Support for joining existing games created by other users or sessions
• Visual Feedback: Clear indication of game status, difficulty level, and next actions

Starting a Game with UI

When you call the startCube tool, you'll receive:

1. A clickable UI resource linking directly to the game
2. Complete game state data in JSON format
3. Metadata including difficulty level and next action guidance

Joining Existing Games

Use the joinGame tool with a game ID to participate in games created elsewhere:

• Perfect for collaborative solving
• Maintains full game state and history
• Seamless integration with existing MCP workflow

Architecture

• MCP Protocol: Standard Model Context Protocol for AI agent communication
• MCP UI Integration: Interactive web components with @mcp-ui/server for clickable resources
• 3D Rendering: Three.js WebGL-based 3D cube visualization
• Real-time Communication: Socket.io WebSocket server for live updates
• Web Server: Express.js server for HTTP API and static content
• State Management: In-memory game session tracking with live synchronization
• Configurable Difficulty: Scalable scramble complexity from beginner to expert levels

Workflow Pattern

The server follows the recursive MCP pattern:

1. Start → Returns nextAction: 'manipulateCube'
2. Manipulate → Returns nextAction: 'manipulateCube' (if not solved) or 'finish' (if solved)
3. Finish → Returns nextAction: null (workflow complete)

This allows AI agents to work autonomously through the solving process.

Development

Watch Mode

npm run dev

Building

npm run build

Project Structure

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

License

MIT License - see LICENSE file for details.