openmhp 0.5.0

The open protocol for AI agents to run lab instruments

Install it once. Tell your agent to find your instruments, onboard the rest by interview, rehearse a procedure, and run it within limits the instrument itself enforces.

Get started · Documentation · Cookbook · Instruments · Specification · Contributing

OpenMHP (Open Model Hardware Protocol) is MCP for lab equipment. It gives any AI agent harness one way to find a physical device among thousands, learn how to use it from the people who own it, operate it safely, and hand it long-running work.

npx @sinkush/openmhp setup

Then, in Claude Code, Codex, OpenClaw, Hermes, Claude Science, Open Science or any MCP client:

Try it with nothing plugged in: npx @sinkush/openmhp demo adds two simulated instruments.

Why

Every instrument has its own interface, and the knowledge that makes it safe to use lives in manuals and people's heads. OpenMHP takes the shape of MCP and Agent Skills and applies it to hardware:

• Five primitives. Describe, signals (read), settings (write), actions (jobs), safety.
• A device package per instrument, shaped like a skill: a card, operating instructions, and detail loaded only when asked. Two thousand devices cost the agent the same handful of tokens as two.
• Safety enforced in the driver. Limits, interlocks and "ask a person first" are checked on the device side of the wire, whatever the agent asks for. E-stop is always allowed.
• Bridge, don't replace. SiLA 2, PyLabRobot, MADSci, OPC UA and ROS 2 devices join through adapters in a few lines.
• Recipes and plan mode. Tested procedures the agent adapts, rehearsed through every gate before anything moves.

The full story is at openmhp.com; the protocol is in SPEC.md.

For developers

pip install "openmhp[all]"                     # runtime; [all] adds mDNS discovery and serial
python examples/pcr_run.py                     # orchestrate a robot arm and a thermocycler
python examples/scale_demo.py                  # 2,000 devices, ~1k tokens
python tests/test_adapters.py && python tests/test_runs.py
mhp serve pkg:openmhp/devices/thermocycler-01 --http 18921     # serve a device package on the LAN
mhp-mcp --http 18800                           # the MCP bridge over HTTP for remote harnesses

A device is a folder:

devices/hotplate-01/
├── DEVICE.md          card (YAML frontmatter) + operating instructions
├── descriptor.yaml    signals, settings with limits, actions, interlocks, safety
├── driver.py          code: a Driver subclass, a BoundDriver, or an adapter
├── sim.py             optional simulated twin
├── references/        SOPs, manual excerpts
└── scripts/           tested mhp_run scripts

Adapters: openmhp.adapters.sila2, .pylabrobot, .madsci, .opcua, .ros2, and BoundDriver for any Python callable. Community packages live in packages/; recipes in openmhp/recipes/; Agent Skills in openmhp/skills/.

Layout

openmhp/driver.py        Driver base class: primitives, six safety gates, jobs (pause/resume), detail tiers, resources
openmhp/package.py       device packages: DEVICE.md frontmatter + body, descriptor.yaml, resources, sim twins
openmhp/directory.py     card index + BM25 search + live state pings; serves directory/*
openmhp/fleet.py         the lab's device list (~/.openmhp/fleet.json); github: targets; in-process hosting
openmhp/discovery.py     mDNS advertise/browse (optional zeroconf) and HTTP probe of /mhp.json
openmhp/onboarding.py    server-side interview -> writes the device package
openmhp/drivers/         no-code drivers: manual (human-operated) and serial_ascii (declared commands)
openmhp/runs.py          runs (background, run_dir, stdout), the run log, plan mode
openmhp/recipes/         tested cross-instrument procedures
openmhp/safety.py        the safety card
openmhp/registry.py      community package index
openmhp/mcp_bridge.py    mhp-mcp: ten tools, elicitation, prompts, logging; stdio or HTTP
openmhp/transport.py     stdio and HTTP(+SSE) device transports; /mhp.json discovery
openmhp/client.py        Device / Lab client SDK
openmhp/cli.py           mhp: lab, validate, skills, serve, serve-directory, device verbs
openmhp/adapters/        BoundDriver; sila2, pylabrobot, madsci, opcua, ros2
openmhp/skills/          Agent Skills: onboard-device, adapt-fleet, operate
openmhp/devices/         bundled simulated thermocycler and arm, as packages
packages/                community packages: ika-c-mag-hs7, opentrons-flex, manual-benchtop-centrifuge
npm/                     the npx @sinkush/openmhp launcher

License

Apache 2.0. See CONTRIBUTING.md to add a device package or a recipe.