smlflg/hai-mcp-public

HAI-MCP

HAI-MCP is the open-source MCP control-plane implementation of Human Agent Interface (HAI), created by Samuel Fleig.

Human Agent Interface is an approach for keeping agentic AI work observable, bounded, owner-gated, and evidence-based so a human can still own the work. HAI-MCP implements that approach as a model-agnostic Model Context Protocol (MCP) server.

Any client (Claude Code, Codex, Cursor, Grok, OpenCode, Hermes, …) can use the same tools. The server never calls an LLM.

Canonical website: https://www.human-agent-interface.com/

Canonical HAI-MCP page: https://www.human-agent-interface.com/hai-mcp/

About Samuel Fleig: https://www.human-agent-interface.com/samuel/

Install / run

cd HAI-MCP
uv sync --all-extras
uv run hai-mcp

stdio MCP. Point your client at:

{
  "command": "uv",
  "args": ["run", "--directory", "/absolute/path/to/HAI-MCP", "hai-mcp"],
  "env": {
    "HAI_HOME": "/home/you/.hai",
    "HAI_OWNER_HOME": "/home/you/.hai-owner"
  }
}

Owner gate

The owner is a separate principal from the agent. Owner-gated actions (hai_accept_next_step, hai_recontract, abandoning a mission) are passed only with a one-time code the server delivers to the owner, never to the client: into HAI_OWNER_HOME (file, default) or to your phone via ntfy (HAI_OWNER_CHANNEL=ntfy + HAI_OWNER_NTFY_TOPIC). The code is bound to the exact change, single-use, expires, and only its hash is stored in HAI_HOME. HAI_OWNER_GATE=ack_legacy restores the old self-asserted owner_ack (an honor system — hai_health says so). Details: docs/OWNER_GATE.md.

Tools (v0.1 — 23 tools, one state engine)

Control plane (legacy surface):

Tool	Role
hai_health	Server + HAI_HOME health (incl. owner-gate mode)
hai_status	Active lanes, focus, inbox, pending owner challenges
hai_get_next_step	Canonical NEXT_STEP
hai_read_artifacts	Run-contract artifact summary
hai_park	Park a thought (no lane steal)
hai_set_focus	Set/switch focus (max 2 ACTIVE)
hai_propose_next_step	Write proposed next step
hai_accept_next_step	Promote proposed → canonical (owner gate)
hai_checkpoint	Snapshot context
hai_recover	Smallest recovery next action

Mission lifecycle (canonical engine):

Tool	Role
hai_open_mission	Open a bounded mission with a versioned contract
hai_bind_project	Bind a logical project id to a device mount (owner_ack + reason)
hai_authorize_session	Time-bounded session lease on an exact contract version
hai_get_contract	Exact contract for a valid lease
hai_check_activity	Deterministic drift classification
hai_park_item	Mission-linked parking, no execution right
hai_recontract	Visible field-level diff, revokes leases (owner gate)
hai_close_mission	Complete with evidence, or abandon (owner gate)

Daily loop (thin wrappers over the engine):

Tool	Role
hai_intake	Capture a raw thought immutably
hai_distill	Exactly one decision + one next step; the rest is parked
hai_mission_start	Fast start → hai_open_mission
hai_drift_check	→ hai_check_activity
hai_proof	→ hai_close_mission(completed)
hai_stop	Hard day terminal; revokes leases, no next-day plan

See docs/TOOL_CONTRACT.md.

State

• Global: $HAI_HOME (default ~/.hai)
• Per project: <project>/Projek-Managment/

Legacy

~/.config/hai-agent-mcp is Hermes-coupled prior art. This repo replaces that role for control-plane work; coexistence is fine until you switch clients deliberately.

Tests

uv run pytest