Metadata-Version: 2.5
Name: mindcraft-mcp
Version: 0.2.5
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
and connects Codex or Claude Code to your Mindcraft account. Your assistant
can then prepare your own repository and start, watch and steer research
campaigns on it. The server holds only your API URL and your personal API
token. The Mindcraft service keeps all campaign state.

## Setup

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

1. If `uv` is not installed, install it:
   `curl -LsSf https://astral.sh/uv/install.sh | sh`.
2. Register the server in your client.
   - Claude Code: `claude mcp add mindcraft --scope user -- uvx mindcraft-mcp@latest`
   - Codex: `codex mcp add mindcraft -- uvx mindcraft-mcp@latest`
3. Ask the client: "Show my Mindcraft account." A browser page opens.
   Sign in with Google, then click **Connect**.

The first sign-in stores the token in `~/.config/mindcraft/credentials.json`
(mode 0600). If no browser can open, the call gives a URL to open on another
device. Call the tool again after you approve the request.

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

Terminal commands:

| Command | Purpose |
| --- | --- |
| `uvx mindcraft-mcp setup` | Sign in and register the server in each client on your `PATH`. |
| `uvx mindcraft-mcp setup --no-browser` | Sign in without a browser. Open the URL on another device and type the code. |
| `uvx mindcraft-mcp logout` | Revoke the token and delete the credentials file. |
| `uvx mindcraft-mcp --version` | Show the package version and the schema version. |

## First campaign

1. Ask your operator for a campaign spend limit on your account. Without a
   limit, the checks stop with `LIMIT_REQUIRED`.
2. On the website, save the secret values that your training needs at
   `/settings/secrets`. Add model keys and the GitHub connection for
   private repositories at `/settings/connections`.
3. Ask the assistant to prepare your repository for Mindcraft. The
   assistant reads `mindcraft.guide` with `topic: "setup"`, edits your
   local files and runs `inspect_repository`.
4. Confirm the objectives, the compute and the secrets. Then ask the
   assistant to create the campaign. The create action starts the campaign
   after the required checks pass. A campaign can cost money.
5. Watch the run page at `https://mindcraft.latencylabs.ai/runs/<id>`, or
   ask the assistant for the status.

## Tools

| Tool | Purpose |
| --- | --- |
| `mindcraft.account` | Show your account, your spend and your limits. |
| `mindcraft.guide` | Read the setup procedure and the repository rules. |
| `mindcraft.compute` | List GPU types and estimate the cost of a campaign. |
| `mindcraft.run` | Inspect a repository, upload or attach models, read project context and create a campaign. |
| `mindcraft.status` | Show the state of a run, or list your runs. |
| `mindcraft.results` | Show the experiments and their metrics. |
| `mindcraft.artifacts` | Show the files of an experiment. |
| `mindcraft.control` | Send `stop`, `resume`, `retry`, `direction` or `retire_direction`. |
| `mindcraft.benchmark` | Show the device latency of an experiment. |

## What is new in 0.2.5

Version `0.2.5` agrees with the release 2 backend, which uses only bounded
GPU acquisition. The `create` action of `mindcraft.run` accepts
`compute.min_vram_gb` without a GPU type. The server then chooses the
cheapest exact GPU type with that memory. The receipt shows the chosen
type. It also shows the requested memory when the call or a local
`setup/compute.json` gave it.

A GPU name without its variant is a family, for example `h100`. The
variant is optional: `compute.gpu` and `setup/compute.json` accept an exact
type or a family. A family permits each variant of the chip. The
acquisition uses the cheapest first and moves to another variant when one
has no stock. The name `a100` alone is refused; send `a100-40gb` or
`a100-80gb`. `mindcraft.compute` lists the families and shows the price
and availability of each variant. The create receipt shows the chosen type
and the family. The status shows the family of the selected node, and
`mindcraft.results` shows the exact type of each experiment.

The `setup/compute.json` example of `inspect_repository` now gives
`min_vram_gb`. Without `expected_duration_minutes`, the estimate uses a
reference duration of 30 minutes.

`mindcraft.compute` and `mindcraft.run` no longer accept the deprecated
`extra_spend_limit_usd` and `data_cost_estimate` fields. Each GPU
acquisition has a 30-minute deadline. After `CAPACITY_TIMEOUT`, `resume`
starts a new acquisition. The API schema remains at version `2`.

## What is new in 0.2.4

Version `0.2.4` adds the optional `hourly_price_preference_usd` field to
`mindcraft.compute` and `mindcraft.run`. The preference is soft; an eligible
node can exceed it. The campaign allowance still controls admission.
Earlier clients can retain the deprecated extra allowance and estimate fields.
The API schema remains at version `2`.

The status tool reports the selected node, provider, region, exact hardware,
hourly customer price, and separate transfer estimate. The hourly price
includes compute and storage. Transfer details distinguish estimates from
confirmed charges and expose bounded evidence without private connection IDs.

The compatible backend automatically permits at most two unresolved
allocation requests. It targets a verified worker within 15 minutes and
ends an unsuccessful acquisition after 30 minutes. Setup, dataset preparation,
and the baseline retain separate stages. Customer use requires package
publication and a compatible backend deployment.

If acquisition expires, read the failure and cleanup status before an explicit retry.
Expiry preserves the accepted source and request; cleanup obligations can continue to incur charges.

## What is new in 0.2.3

- A new `setup` topic in `mindcraft.guide` gives the complete procedure
  from a local repository to a started campaign. The guide works before
  sign-in.
- You can keep the confirmed objectives in a repository-root
  `objectives.json` file. `inspect_repository` shows the declarations that
  the service reads from that file.
- An objective can name its measurement source: `eval` or `orin_tensorrt`.
- The `create` action accepts `objective_source` (`"request"` or `"file"`)
  when `objectives.json` and the objectives array differ.
- The objectives array has no count limit. The service still limits its
  size in bytes.
- The error messages give clearer recovery steps after an uncertain
  `create`. These steps help you prevent a duplicate paid campaign.

## 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 |

## Links

- Website: https://mindcraft.latencylabs.ai
- API tokens: revoke a token at `/settings/tokens` on the website, or run
  `uvx mindcraft-mcp logout`.
