Metadata-Version: 2.4
Name: openmhp
Version: 0.5.0
Summary: OpenMHP: reference implementation of the Open Model Hardware Protocol (MHP), an open protocol for AI agents to operate physical devices safely.
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6
Provides-Extra: discovery
Requires-Dist: zeroconf>=0.130; extra == "discovery"
Provides-Extra: serial
Requires-Dist: pyserial>=3.5; extra == "serial"
Provides-Extra: all
Requires-Dist: zeroconf>=0.130; extra == "all"
Requires-Dist: pyserial>=3.5; extra == "all"
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/hero-dark.svg">
    <img src="assets/hero.svg" alt="OpenMHP" width="520">
  </picture>
</p>

<h3 align="center">The open protocol for AI agents to run lab instruments</h3>

<p align="center">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.</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@sinkush/openmhp"><img alt="npm" src="https://img.shields.io/npm/v/%40sinkush%2Fopenmhp?label=%40sinkush%2Fopenmhp&color=3FB59A"></a>
  <a href="https://pypi.org/project/openmhp/"><img alt="PyPI" src="https://img.shields.io/pypi/v/openmhp?label=openmhp&color=3FB59A"></a>
  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-Apache%202.0-blue"></a>
  <a href="https://openmhp.com"><img alt="docs" src="https://img.shields.io/badge/docs-openmhp.com-2B8F78"></a>
</p>

<p align="center">
  <a href="https://openmhp.com/quickstart">Get started</a> ·
  <a href="https://openmhp.com">Documentation</a> ·
  <a href="https://openmhp.com/cookbook">Cookbook</a> ·
  <a href="https://openmhp.com/instruments">Instruments</a> ·
  <a href="https://openmhp.com/spec">Specification</a> ·
  <a href="CONTRIBUTING.md">Contributing</a>
</p>

---

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

```bash
npx @sinkush/openmhp setup
```

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

| You say | What happens |
|---|---|
| "find the instruments on my network" | scans for devices that speak MHP and lists them |
| "onboard my hotplate" | the server interviews you, writes the device package itself, validates it, reads you a safety card, adds it. Hand-operated and USB-serial instruments need no code |
| "run a 30-cycle PCR at 95/58/72 and hold at 4 °C" | finds a recipe, rehearses it in plan mode and shows every step, then runs it and reports what it read |
| "watch the incubator overnight" | a background run logs readings and alerts; in the morning, ask what happened |

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](https://openmhp.com); the protocol is in [SPEC.md](SPEC.md).

## For developers

```bash
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/`](packages/); recipes in
[`openmhp/recipes/`](openmhp/recipes/); Agent Skills in [`openmhp/skills/`](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](CONTRIBUTING.md) to add a device package or a recipe.
