# Hwcontract

> Hwcontract is a free MCP server for developer tools. Judge hardware pulse timing and serial logs against a contract: pass, marginal or fail. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Free
- **Platforms:** CLI, macOS, Linux, Windows
- **Repository:** https://github.com/mohibshaikh/hwcontract
- **MCP Registry name:** io.github.MohibShaikh/hwcontract
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools), [engineering simulation](https://ai-powered.com/categories/engineering-simulation)
- **Listing updated:** 2026-11-18

## About

The problem it targets is firmware that looks right in review but misbehaves on a real chip. hwcontract takes a capture of what the hardware actually did, such as a logic-analyzer trace of a WS2812 LED strip, a DShot bitstream or a boot log, and compares it to a contract. Each edge gets PASS, MARGINAL, FAIL or MISSING, with the measured value and distance from the limit. MARGINAL means in spec but too close to a boundary to ship.

Every pulse is judged rather than only the median, and a verdict is never finer than the capture can resolve: a width known only to one sample period cannot be called a clear fail or pass inside that margin. Each verdict carries contract and capture hashes, parameters, tool version and timestamp, so a green CI build traces to exact inputs.

There are 28 bundled contract templates covering LED chips, DShot, servo, I2C, sensors, steppers, serial boot logs and SPI pin ordering, which the README says must be checked against your part's datasheet. New hardware is described in a YAML file. Offline demos replay a recorded WS2812B signal.

## Features

- **Four-state verdicts:** PASS, MARGINAL, FAIL or MISSING with measured values.
- **Every pulse judged:** A glitchy tail is not hidden by the median.
- **Sample-aware limits:** Verdicts respect the capture's sampling resolution.
- **28 contract templates:** Covers LEDs, DShot, servos, serial logs and SPI ordering.
- **YAML contracts:** Describe new pulse protocols from datasheet numbers.
- **Evidence hashes:** Traces a verdict to exact contract and capture bytes.

## Good for

- Check a WS2812 driver against a real capture
- Gate a CI build on measured pin timing
- Detect a DMA ordering fault in SPI pin timing
- Verify a boot log for panics or required lines
- Describe a new chip's timing in YAML

## Install

### Claude Code (Terminal)

```sh
claude mcp add hwcontract -- uvx hwcontract
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "hwcontract": {
      "command": "uvx",
      "args": [
        "hwcontract"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "hwcontract": {
      "command": "uvx",
      "args": [
        "hwcontract"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "hwcontract": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "hwcontract"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "hwcontract": {
      "command": "uvx",
      "args": [
        "hwcontract"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "hwcontract": {
      "command": "uvx",
      "args": [
        "hwcontract"
      ]
    }
  }
}
```

## Tools

- `judge_contract`: Judges a timing or event capture against a contract.
- `judge_serial`: Judges a serial log against a contract.
- `check_capture`: Captures from a logic analyzer and judges it.

## FAQ

### How do I install it?

Install the hwcontract package from PyPI; extras add live serial capture and a ReDoS-safe regex engine.

### Does it need hardware?

Not for the demos, which replay recorded or synthetic signals.

### What is needed for live logic-analyzer capture?

sigrok-cli on the PATH.

### Can I rely on the bundled contracts?

They are a spec library; the README says to verify each against your exact part and datasheet.

### Is Hwcontract free?

Yes. Hwcontract is free to use.

### How do I add Hwcontract to Claude Code?

Run this command in your terminal: claude mcp add hwcontract -- uvx hwcontract

### What are the best alternatives to Hwcontract?

The closest alternatives to Hwcontract are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/hwcontract
