# HardCI

HardCI is a local MCP stdio server that gives AI agents safe, policy-gated access to real embedded hardware: flashing, serial, CAN, and test-adapter stimuli/fault injection.

Run without installing (no admin rights, no PATH changes):

```bash
uvx hardci --version
uvx --from git+https://github.com/hp-8472/hardci hardci --version
```

Persistent user-local install: `uv tool install hardci` or `pipx install hardci`. Never sudo, never --break-system-packages. Requires Python 3.10+.

Bootstrap each firmware project from the project directory:

```bash
hardci init
hardci doctor
hardci mcp-config --output .mcp.json
```

Each firmware project keeps its own `.hardci/config.yaml` — the policy for that project's target, debugger, permissions, artifact roots, com_ports, can_buses, and adapters.

MCP stdio command:

```text
hardci mcp-stdio --config .hardci/config.yaml
```

Use MCP tools for hardware actions:

```text
hardci_debugger_info, hardci_probe_target, hardci_artifact_upload,
hardci_flash_firmware, hardci_reset_target,
hardci_com_session_start/_stop, hardci_com_write, hardci_com_read,
hardci_can_session_start/_stop, hardci_can_send, hardci_can_read,
hardci_adapter_session_start/_stop, hardci_adapter_set_value,
hardci_adapter_inject_fault, hardci_adapter_clear_fault, hardci_adapter_measure,
hardci_get_last_report, hardci_classify_last_error
```

Required workflow:

1. Build firmware.
2. Probe before flashing.
3. Flash only validated artifacts from allowed roots.
4. Stimulate via com/can/adapter tools, assert on feedback.
5. Read the structured result and last report; classify failures before changing code again.

pytest: installing hardci registers a plugin; the `hardci` fixture drives the same tools in CI regression suites.

Safety: do not request raw OpenOCD commands, do not open host serial/CAN/adapter devices directly, do not flash outside allowed artifact roots. Treat `permission_denied` as authoritative.

Agent setup guide: AI_AGENT_QUICKSTART.md. Human docs: README.md, TROUBLESHOOTING.md.
