Rubiks Cube MCP Server

🚀 ルービックキューブMCPサーバー

Model Context Protocol (MCP)サーバーです。このサーバーは、AIエージェントに対して、体系的な操作とリアルタイムの可視化を通じてルービックキューブのパズルを解く能力を提供します。

✨ 主な機能

• インタラクティブなキューブ操作：標準的なルービックキューブの操作（U, D, L, R, F, B およびその変形）を実行できます。
• 3Dリアルタイム可視化：Three.jsとWebGLを使用した美しい3Dキューブの可視化を実現します。
• WebSocketによるリアルタイム更新：MCPサーバーとWebインターフェース間でのリアルタイムの状態同期を行います。
• マウス操作：マウスで3Dキューブを回転させ、詳細を確認できます。
• 再帰的なワークフロー：AIエージェントはnextActionのガイダンスを使用して、体系的にキューブを解くことができます。
• 状態追跡：完全な操作履歴と現在のキューブの状態を監視します。
• 解決検出：キューブが解かれたことを自動検出し、祝祭エフェクトを表示します。

📦 インストール

前提条件

• Node.js 18.x 以上
• npmまたはyarn

依存関係のインストール

cd rubiks-cube-mcp-server
npm install

プロジェクトのビルド

npm run build

サーバーの起動

npx rubiks-cube-mcp-server

これにより、以下の2つが起動します。

• 標準入出力でのMCPサーバー（AIエージェントとの通信のため）
• http://localhost:3000でのWeb可視化サーバー

Claude Desktopの設定

この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
• Windows：%APPDATA%\Claude\claude_desktop_config.json

設定を追加した後、Claude Desktopを再起動して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：2回転（例: U2）

💻 使用例

基本的な使用法

エージェント: "新しいルービックキューブのパズルを開始して"
→ startCubeツールが呼び出される
→ シャッフルされたキューブの状態とgameIdが返される

エージェント: "操作Uを実行して"
→ manipulateCubeツールが操作 "U" で呼び出される
→ 更新された状態とnextActionのガイダンスが返される

エージェント: "解き続ける..."
→ 解かれるまで再帰的にmanipulateCubeが呼び出される
→ 完了したらfinishツールが呼び出される

ウェブ可視化

http://localhost:3000/game/{gameId}にアクセスすると、以下を確認できます。

• リアルタイムの3Dキューブの表示
• 色分けされた面（白、黄、赤、橙、青、緑）
• 操作カウンターと履歴
• インタラクティブな操作ボタン
• 解決ステータスのインジケーター

🔧 技術詳細

• MCPプロトコル：AIエージェントとの通信に使用される標準的なModel Context Protocol
• 3Dレンダリング：Three.jsのWebGLベースの3Dキューブの可視化
• リアルタイム通信：リアルタイム更新のためのSocket.io WebSocketサーバー
• ウェブサーバー：HTTP APIと静的コンテンツのためのExpress.jsサーバー
• 状態管理：リアルタイム同期を伴うメモリ内のゲームセッションの追跡

ワークフローパターン

サーバーは再帰的なMCPパターンに従っています。

1. 開始 → 次のアクションとしてmanipulateCubeが返される
2. 操作 → 解かれていない場合は次のアクションとしてmanipulateCubeが、解かれた場合はfinishが返される
3. 終了 → 次のアクションとしてnullが返され（ワークフロー完了）

これにより、AIエージェントは解くプロセスを自律的に進めることができます。

開発

ウォッチモード

npm run dev

ビルド

npm run build

プロジェクト構造

src/
  ├── app.ts              # メインのMCPサーバーの設定
  ├── cubeLogic.ts        # ルービックキューブのシミュレーションロジック
  ├── visualizationServer.ts  # ウェブ可視化サーバー
  └── types.ts            # TypeScriptのインターフェース

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。