Metadata-Version: 2.5
Name: mindcraft-mcp
Version: 0.1.1
Summary: A local MCP server that starts and watches Mindcraft research runs.
Project-URL: Homepage, https://mindcraft.latencylabs.ai
License: Proprietary
Requires-Python: >=3.10
Requires-Dist: jsonschema>=4.20
Requires-Dist: mcp<3,>=2.3
Description-Content-Type: text/markdown

# mindcraft-mcp

The local MCP server of Mindcraft by Latency Labs. It runs on your machine,
connects Codex or Claude Code to your Mindcraft account, and starts
research campaigns on your own repository. The server holds only your API
URL and your personal API token. Every durable decision stays in the
Mindcraft API.

## Setup

The procedure needs `uv`. It supplies Python by itself.

1. When `uv` is not installed, install it: `curl -LsSf https://astral.sh/uv/install.sh | sh`.
2. Register the server in your client: `claude mcp add mindcraft --scope user -- uvx mindcraft-mcp@latest` (Codex: `codex mcp add mindcraft -- uvx mindcraft-mcp@latest`).
3. Ask the client to show your Mindcraft account. On the first call a
   browser page opens: sign in with Google, then click **Connect**. The
   call then answers with your account.

The first call stores the token in `~/.config/mindcraft/credentials.json`
(mode 0600). If no browser can open (for example over SSH), the call
answers with the URL to open on another device; call the tool again after
you approved the request. `uvx mindcraft-mcp setup` does the same sign-in
from the terminal and also registers the server in each client that it
finds on your `PATH`. On a machine without a browser, run `uvx mindcraft-mcp setup
--no-browser`, open the URL on another device, and type the code that the
page shows. `uvx mindcraft-mcp logout` revokes the token and deletes the
file.

Caution: click **Connect** only for a command that you started on your own
machine.

## Your first campaign

This is the path from an empty machine to a measured model. It works for
any account, any budget and any repository that has the Mindcraft layout
(`setup/` and `eval/`; `uvx mindcraft-mcp` has an `inspect` tool that
tells you what is missing). An operator of the platform sets the budget;
everything else is yours.

1. **Budget.** Ask your operator for a campaign ceiling on your account.
   The operator sets it by your email address on the operator website,
   also before your first sign-in. Without a ceiling, the checks stop with
   `LIMIT_REQUIRED`. The ceiling, times nothing, is the most a campaign
   can cost you: the price is the recorded cost × 1.1, and the platform
   stops the run when it reaches the limit. A campaign can carry a lower
   limit of its own (`campaign_limit_usd` at creation).
2. **Install.** `claude mcp add mindcraft --scope user -- uvx mindcraft-mcp@latest`
   (Codex: `codex mcp add mindcraft -- uvx mindcraft-mcp@latest`). Check
   with `claude mcp list`: `mindcraft … Connected`. No browser opens yet.
3. **Sign in.** Ask the client: "Show my Mindcraft account." A browser
   page opens: sign in with Google and click **Connect**. The answer shows
   your email, your ceiling, your model keys and the names of your
   secrets. The token is stored in `~/.config/mindcraft/credentials.json`
   (mode 0600). Without a browser, the answer shows a URL to open on
   another device; then ask again.
4. **Secrets and keys.** On the website, `/settings/secrets` holds the
   values your training needs (for example `HF_TOKEN`, `WANDB_API_KEY`):
   saved once, never shown again, given only to the campaigns that name
   them. `/settings/connections` holds your model keys and the GitHub
   connection for private repositories.
5. **Inspect.** "Inspect this repository with mindcraft" (a local path or a
   GitHub reference). You get the layout, static and hardware checks, the
   objectives and a list of what is missing. Fix the findings before you
   create.
6. **Create and start.** "Create a campaign for it with the compute of
   `setup/compute.json`, give it the secrets `HF_TOKEN`, run the checks and
   start it." The reply names the run page
   (`https://mindcraft.latencylabs.ai/runs/<id>`): the chosen GPU class
   with its estimated cost and confidence, the price line against your
   limit, and the checks. A placement that finds no offer answers
   `PLACEMENT_NONE` with the reasons.
7. **Steer and watch.** "What is the status?", "Give the direction: try a
   smaller decoder", "Stop the campaign". The run page shows the price,
   the experiments and their measurements. A campaign with
   `eval/latency.toml` gets a trained latency measurement on a device and,
   with the engine scripts, an engine accuracy record; the final
   measurement runs when the campaign ends, within its two-hour deadline.
8. **Tokens.** `/settings/tokens` lists every MCP token; revoke one there
   or run `uvx mindcraft-mcp logout`. The next call signs in again.

## Tools

| Tool | Purpose |
| --- | --- |
| `mindcraft.account` | Your account, your spend and your limits |
| `mindcraft.run` | `inspect_repository`, then `create` a run |
| `mindcraft.status` | The state of a run, or your runs |
| `mindcraft.results` | The experiments and their metrics |
| `mindcraft.artifacts` | The files of an experiment |
| `mindcraft.control` | `stop`, `resume`, `retry`, or a `direction` |
| `mindcraft.benchmark` | The device latency of an experiment |

Each result has a link to the run page on `https://mindcraft.latencylabs.ai`.

## Settings

| Setting | Meaning |
| --- | --- |
| `MINDCRAFT_API_URL` | Default `https://mindcraft.latencylabs.ai` |
| `MINDCRAFT_API_TOKEN` | Optional. It replaces the stored token, for a script or a CI job |

The repository that a run uses must follow the Mindcraft repository
contract; the Mindcraft documentation describes it.
