Metadata-Version: 2.5
Name: mindcraft-mcp
Version: 0.2.2
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/`; `mindcraft.run` has an `inspect_repository` action 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 bounds the initial campaign allowance.

   The price is the recorded cost × 1.1. The platform stops ordinary work
   when the live price reaches the effective limit. Final measurement can
   add a charge above that 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` | Read research models, inspect dependencies, read project context, upload models, and create a campaign |
| `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 |

Use `mindcraft.run` with `action: "list_models"` to read the backend research model catalog.
The result supplies `items` and `default` from the backend.
For `create`, optional `agent_model` selects a listed model for the new campaign.
Omit `agent_model` to use the backend default, currently `gpt-6.1-sol` in the standard catalog.
An operator catalog can change the default through its first entry.
A model choice does not change an existing or parent campaign.

Package 0.2.1 adds these optional inputs and retains protocol schema version 2.
Older package requests omit `agent_model` and retain the backend default behavior.

A created campaign receipt includes a link to its run page.

## Local campaign inputs

The current assistant asks questions and edits local files. The guide supplies
instructions. The MCP tools expose deterministic operations. Offer a separate
Git worktree before local edits. Prefer adapters before necessary code moves
into `train/`.

A local project association uses the API server, account, repository identity,
and selected subdirectory. Branches and worktrees share that association.
The local store uses `~/.config/mindcraft/local-projects.sqlite3` with mode `0600`.
It stores no credentials.

Repositories without remotes use their Git common directory. Non-Git folders
use durable local identities for their resolved paths.
A folder move can require explicit project selection.

Use `source.subdirectory` to select a folder within `source.path`.
An explicit `project_id` selects an owned existing project of any source type.
Ask the user when several associations conflict. Complete local LFS objects
and submodules before submission. Complete these dependencies locally.

The actions below use the existing backend operations. A successful local
test does not establish deployment of their required backend routes.

| Action | Inputs and result |
| --- | --- |
| `project_context` | Send a local source or `project_id`. Read same-project campaigns and prior experiment summaries. |
| `prior_result_context` | Send an `experiment_id`. Read inherited inputs, the retained checkpoint selector, and source identity. |
| `upload_model` | Send `project_id`, `request_id`, and `model_path`. Upload a file, archive, or complete package folder. |
| `model_upload_status` | Send `project_id` and `upload_id`. Read the durable operation after a timeout or process restart. |
| `attach_model` | Send `run_id`, `request_id`, and `model_path` or a same-project `artifact_id`. Attach a model for future research. |
| `attachment_status` | Send `run_id` and `attachment_id`. Read verification and publication status. |
| `list_attachments` | Send `run_id`. Use integer `after` and `limit` for another page. |
| `attachment_file_choice` | Send `run_id` and `attachment_id`. Read at most 50 exact files with package and policy hashes. |
| `choose_attachment_files` | Send the owner decision, exact file paths, both expected hashes, and a stable `request_id`. |
| `create` | Send explicit campaign choices. The receipt preserves artifact roles, ancestry, and the selected source identity. |

The local MCP checks paths, size, hashes, and known missing shards before upload.
It sends binary bytes directly to object storage. Stdio arguments and results
contain paths and receipts, not binary payloads. Existing backend intake verifies
and normalizes each new upload once. The backend remains the validation authority.
Its durable operation continues after the client closes.

The MCP creates folder archives but does not extract or normalize packages.

The attachment action requires an explicit owned run. Ask when multiple runs match.
Do not select the newest run automatically. Local attachment uploads use the
research intake path. The action records its durable intent before file completion.
A paused campaign accepts attachments without a research Pod.
An existing `PENDING` artifact still needs its original raw upload completion.
Verification does not start until that upload completes.

Unsupported package files require an explicit owner choice before publication.
Show the exact paths and hashes to the owner. Read each page through
`attachment_file_choice` with an integer `after`. Partial choices retain
`AWAITING_FILE_CHOICE`. No omitted unsupported file can publish.
Package content cannot authorize tools or file permissions. Owner permission
does not remove mandatory path, secret, link, size, shard, or plugin checks.

Repeat an uncertain attachment request with the same arguments and `request_id`.
Use `attachment_status` or `list_attachments` to recover its durable identity.
After session loss, read `model_upload_status` with the original upload locator.
Use a new request only if the original upload cannot resume.
An attachment reaches `READY` after publication. Artifact verification alone
does not establish publication. Attachments support future experiments. They do
not resume research, replace baseline or initializer choices, or change queued or active inputs.

Wait for a model upload to reach `READY` before campaign submission.
Reuse its `artifact_id` for later campaigns without another intake job.
After a transport failure, read the upload status with its durable identities.
Repeat an incomplete upload with the same arguments and `request_id`.

The upload limit is 10 GiB. The extracted limit is 20 GiB.
The folder file limit is 20000. Upload receipts show at most 50 useful
entries with `entry_count` and `entries_truncated`. The backend retains the
complete manifest.

The backend also enforces known execution limits. Some runtime incompatibilities
can appear during paid execution. Unused completed uploads expire after seven days.
The backend protects required campaign artifacts.

A model artifact contains a checkpoint, engine, or related package files.
The baseline measurement supplies reference metrics for subsequent experiments.
A supplied baseline uses `baseline_model` with `action: evaluate|train`.

For `action: train`, `baseline_model.mode` is required.
For `action: evaluate`, that mode is absent. The separate
`training_initializer` uses `mode: weights_only|training_state`.
Ask for the two restoration choices separately.

Both policies require an explicit experiment initializer for an uploaded baseline.
Under `original`, legacy `starting_model` can supply its fixed `weights_only`
source. `current_best` requires the new `training_initializer`.
The same compatible uploaded artifact can fill both roles. A second file is
not required.

Legacy `starting_model` retains its existing weights-only behavior.
Present its repository, revision, and fixed experiment mode before create,
alongside the baseline artifact and baseline mode.

`weights_only` restores model weights alone. `training_state` restores compatible
saved optimizer state, schedule state, and counters that the adapter requires.
Present both artifact identities and selected modes before the create tool call.

The create action performs Start automatically. Existing user authorization
covers the call once the choices are explicit. Do not request another approval
when that authorization already covers the call.

Do not substitute a mode between roles. An engine cannot supply training weights.
The original initializer remains separate from a trained baseline output.

A saved model can await AGX Orin availability. An offline device does not
fail the campaign. Required engine metrics precede keep or discard.
The backend retains progress without the MCP session. It releases idle
training resources where durable recovery permits release.

The campaign selects `candidate_initialization: original|current_best` and
`metric_basis: framework|engine`. Requested `additional_training` is additional
to saved counters. Each experiment retry retains its pinned checkpoint.

A child campaign records ancestry from an exact prior campaign result.
It uses explicit `parent_result` campaign and experiment identities.
Ask for exact `prior_result` code or current `local` code with prior weights.
Use the checkpoint selector from `prior_result_context` for the initializer.

The child requires an explicit restoration mode, baseline action, checkpoint
policy, and metric authority. Inherited objectives apply unless the user
changes them. The child measures a fresh baseline.

The source operation inherits dataset and evaluation inputs by default.
Set `parent_result.inherit_evaluation` to false only after the user selects
changed inputs. The receipt preserves that choice and the materialized source.
The backend protects required child inputs independently of parent deletion.

The adapter declaration uses `setup/model_adapter.json`. It identifies supported
formats, restoration modes, required state components, and a compatibility command.
The evaluation contract must freeze that file or `setup/`.
The adapter receives `MINDCRAFT_MODEL_INPUT_JSON` and writes
`MINDCRAFT_ADAPTER_RECEIPT`. Preflight uses `MINDCRAFT_ADAPTER_PHASE=preflight`.

The worker verifies restored components, saved counters, and additional work.
A train receipt echoes the sealed `training_bound` and records
`bound_applies_to_additional_work=true`. Saved counters remain separate from
that bound. The worker infers no absent step or epoch count.

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

The [customer reference](../docs/design/customer-mindcraft-mcp-lld.md) gives
the implemented contracts. The [feature reference](../docs/features.md#campaign-inputs-and-ancestry)
summarizes campaign inputs and their limits. The
[campaign inputs plan](../docs/plan/campaign-inputs/plan.md) retains accepted
choices and incomplete release evidence. Deployment and live acceptance remain Unknown.
