# 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

```sh
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`](docs/architecture/LAYOUT.md) for the
single source of truth and [`docs/design/mvp.md`](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`](https://github.com/muodov/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.