Getting started

Quickstart

One command installs OpenMHP into any agent harness. Then you add instruments by talking to your agent. No hardware needed to try it.

The short version

npx openmhp-cli setup

That is the whole install for a scientist. It puts the runtime in ~/.openmhp, installs three Agent Skills where your harness looks for them, and registers the OpenMHP MCP server with Claude Code and Codex. For any other harness (OpenClaw, Hermes, Claude Science, Open Science, or your own) it prints the one line to paste:

{"mcpServers": {"openmhp": {"command": "npx", "args": ["-y", "openmhp-cli"]}}}

Then open your agent and talk to it. If your harness shows MCP prompts, /setup-my-lab starts the whole thing.

You say	What happens
"find the instruments on my network"	the agent scans for devices that speak MHP (mDNS and a probe of `/mhp.json`) and lists what it found
"add the thermocycler"	it joins your lab, is searchable from then on, and its owner's instructions are one call away
"onboard my hotplate"	the server interviews you through the agent, about ten plain-language questions, then writes the device package itself, validates it and adds it; hand-operated and serial/USB instruments need no code, and the hotplate is now under the same safety gates as everything else
"run a 30-cycle PCR at 95/58/72 and hold at 4 °C"	the agent finds the matching recipe, rehearses it in plan mode and shows you every step and every point where it will ask you, then runs it and reports the temperature it actually read
"log the incubator overnight"	a background run writes readings to a CSV in the run folder; in the morning "what happened last night?" reads the run log and the file
"is it safe to let the agent use the hotplate?"	a safety card: the limits the driver enforces, which actions need a person, whether e-stop and watchdog exist, and live probes showing an out-of-range request being refused

Requires Node 18 and Python 3.10 or newer. The launcher is openmhp-cli on npm and pulls the openmhp runtime from PyPI into ~/.openmhp; nothing is installed globally.

Try it with no hardware

The package ships two simulated instruments, a thermocycler and a plate-handling arm. Add them to your lab and use them exactly like real ones:

npx openmhp-cli demo
npx openmhp-cli list

Or clone the repository and run them as network devices. For a real bench PC with instruments on it, npx openmhp-node setup does this properly and keeps it running — see lab nodes.

pip install "openmhp[discovery]"                              # from PyPI; or clone github.com/kushalsinha/openmhp
mhp serve pkg:openmhp/devices/thermocycler-01 --http 18921     # advertises _mhp._tcp on the LAN
mhp serve pkg:openmhp/devices/arm-01 --http 18922
npx openmhp-cli scan                                                # finds both; then: npx openmhp-cli add http://127.0.0.1:18921

Check it from the shell

mhp http://localhost:18921 describe card                    # level 1
mhp http://localhost:18921 describe summary                 # level 2: operating instructions
mhp http://localhost:18921 write target_temperature 200     # refused: above the 105 degC limit
mhp http://localhost:18921 invoke run_protocol '{"steps":[{"temp":95,"hold_s":5}],"cycles":3}' --wait
mhp http://localhost:18921 estop

First conversation

Ask the agent something concrete: "Run a 3-cycle PCR at 95/58/72 on a thermocycler in bay 3, then hold at 4 °C." A well-behaved agent will:

call mhp_find with that sentence and get a card for thermocycler-01;
call mhp_describe and read the owner's operating procedure, which says to close the lid and pre-heat it;
call mhp_read for lid_closed, then mhp_write for lid_heater;
call mhp_invoke for run_protocol and poll mhp_job, or hand the whole sequence to mhp_run using the package's scripts/pcr.py;
report the block temperature it read, not the temperature it intended.

Try asking for 200 °C. The driver refuses with a LimitViolation that names the limits, and the agent has to come back to you.

Big labs: a shared directory

When devices are served from many bench PCs, run one directory that indexes them all and point every harness at it. The bridge then loads nothing until an agent searches.

python skills/openmhp-adapt-fleet/scripts/build_manifest.py fleet.json tc=http://bench3:18921 arm=http://bench3:18922 ...
mhp serve-directory fleet.json --http 18900
mhp-mcp --directory http://lab-server:18900 --http 18800      # MCP over HTTP for remote harnesses

See it scale

python examples/scale_demo.py      # 2,000 devices: 1,224,382 tokens the naive way, about 1,300 the MHP way
python tests/test_adapters.py      # adapters, live directory, device packages, against fakes

Add an instrumentPut your own hardware behind MHP. Lab nodesServe a bench PC's instruments; find them from your laptop. AdaptersAlready on OPC UA, ROS 2, SiLA 2, MADSci or PyLabRobot.