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 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"]}}}

Then open your agent and talk to it.

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 agent interviews you about the instrument, writes its device package, validates it and adds it; 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"	find, read the operating procedure, check the lid, dry-run, run, report the temperature it actually read

Requires Node 18 and Python 3.10 or newer. Nothing else 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 demo
npx openmhp list

Or clone the repository and run them as network devices, which is also how a bench PC serves a real instrument:

git clone https://github.com/kushalsinha/openmhp && cd openmhp && pip install -e ".[discovery]"
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 scan                                                # finds both; then: npx openmhp 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: 937,845 tokens the naive way, about 1,100 the MHP way
python tests/test_adapters.py      # adapters, live directory, device packages, against fakes