rubiks-cube-mcp

An MCP server that exposes a Rubik's cube to an agent, plus a small dashboard to watch agent runs in the browser.

Quickstart

uv sync
make build-web
make serve   # dashboard at http://localhost:8000
make mcp     # MCP server (stdio)

Layout

Five uv workspace packages under packages/: cube, observe, mcp_server, harness (stub), dashboard. See docs/architecture/LAYOUT.md for the single source of truth and docs/design/mvp.md for the framing.

Run logs live in $XDG_DATA_HOME/rubiks-cube-mcp/ (default ~/.local/share/rubiks-cube-mcp/), never in the repo.

A note on the solver

The solve_hint tool wraps kociemba, which ships an x86_64 C extension. On machines where that wheel doesn't load (notably arm64 macOS without a matching wheel), kociemba transparently falls back to a pure-Python implementation of the same algorithm. We use that fallback path by default — it works on every architecture with no build step and solves in ~1 second.

Want the native C extension speed? Run make solver-fast once. That rebuilds kociemba from source against your local architecture (sub-millisecond solves afterward). Requires a C compiler on your PATH — on macOS install with xcode-select --install; on Linux apt install build-essential; on Windows install MSVC build tools. Purely opt-in; nothing else needs to change in our code, our wrapper picks up the C extension automatically when it loads.