HAI-MCP

HAI-MCP · 面向 Human Agent Interface (HAI) 方法的模型无关 MCP 控制平面

---

为什么有这个仓库

如今，Agent 正在操作 shell、编辑器、浏览器和 CI。大多数 Agent 在没有人工参与的情况下持续工作很久，以至于人类会失去对进展的把握。HAI——即 Human Agent Interface——是一种有明确主张且以证据为基础的方法，用于让 Agent 工作可观察、有边界、经所有者把关且可恢复，这样即使工作由 Agent 执行，人类仍能掌控工作。

HAI-MCP 是这种方法的开源、模型无关实现。它是 Samuel Fleig 的 HAI 技术栈中的一部分——任何支持 Model Context Protocol 的客户端都可以与之交互，无论其背后使用的是哪种 LLM。

官方网站：https://www.human-agent-interface.com/ · 关于 Samuel：https://www.human-agent-interface.com/samuel/

---

此处的“MCP 控制平面”是什么意思

MCP——即 Model Context Protocol——是一种标准的 JSON-RPC 接口，允许工具服务向由 LLM 驱动的客户端（Claude Code、Codex、Cursor、Grok、OpenCode、Hermes 等）提供工具、资源和提示词。客户端会发现服务的工具，并在对话中调用它们；从模型的角度来看，服务是无状态的。

控制平面服务不会亲自执行工作——它负责管理工作如何获得授权、限定范围、记录并交还给人类。具体来说，MCP 控制平面提供：

关注事项	HAI-MCP 提供的功能
任务约定	hai_open_mission、hai_get_contract、hai_recontract
会话租用	hai_authorize_session — 有时限，且与约定版本绑定
活动分类	hai_check_activity / hai_drift_check — 判断活动是否符合约定
焦点与通道	hai_set_focus、hai_status — 最多 2 个 ACTIVE 通道
所有者把关	通过带外一次性 nonce（HAI_OWNER_HOME 或 ntfy），或在 macOS 上使用 Touch ID，对 accept / recontract / abandon 进行把关
证据与收尾	hai_proof、hai_close_mission、hai_stop
收件箱与接收	hai_intake、hai_distill、hai_park、hai_park_item
恢复	hai_checkpoint、hai_recover

HAI-MCP 刻意不作为 Agent 运行时。它从不调用 LLM、运行 shell、推送到 git 或删除文件。它是裁决者——Agent 调用它来询问*“我可以吗？”并记录“我做了。”*

---

功能

• 一个状态引擎，23 个工具——三个界面（旧版控制平面、任务生命周期、日常循环封装）共享一个经过强化的核心。
• 严格的失败关闭边界——输入经过类型检查，不会被强制转换。String "2" 会因不符合 Integer 字段而遭拒；服务仍可访问，不会悄悄篡改类型。
• 有版本的任务契约——每个任务都有一个单调递增版本的契约。重新制定契约会生成清晰可见的字段级差异，并撤销所有现有租约。
• 有时限的会话租约——hai_authorize_session 将租约绑定到任务 ID、契约版本、时长、角色、贡献和声明的标准集合。
• 确定性偏移检查——hai_check_activity 根据契约对计划中或已观察到的活动进行分类，过程中绝不会调用大模型。
• 双主体所有者门控：
  • **默认方式（nonce）：**服务会向所有者频道（HAI_OWNER_HOME / file 或 ntfy）发送一次性代码。客户端不会看到该代码。代码绑定到具体变更，只能使用一次，且会过期；HAI_HOME 中只存储哈希。
  • **touchid（macOS）：**服务进程会针对具体变更显示 Touch ID 提示。没有代码。Agent 后续调用时应用变更；客户端无法自行批准。
  • **ack_legacy：**旧的自我声明 owner_ack 标志——一种荣誉机制，hai_health 会明确说明这一点。
• 挂载表——hai_bind_project 在 owner_ack + reason 的前提下，将逻辑 project_id 关联到设备本地目录。
• 与模型无关——相同的二进制文件、工具和契约。无需重写治理逻辑即可切换大模型。
• 两种传输方式——stdio（默认）和 streamable-http，可选绑定持有者令牌（默认仅限环回地址）。
• 检查点与恢复——hai_checkpoint 创建上下文快照；hai_recover 返回最精简的下一步恢复操作。
• 203 项测试全部通过——引擎已覆盖测试；学习预算和所有者工具后续工作仍待完成。

---

安装与运行

需要 Python ≥ 3.12 和 uv。

git clone https://github.com/smlfg/hai-mcp.git
cd hai-mcp
uv sync --all-extras
uv run hai-mcp          # stdio transport, default

Streamable-HTTP 传输方式：

HAI_TRANSPORT=streamable-http \
HAI_HTTP_HOST=127.0.0.1 \
HAI_HTTP_PORT=8765 \
HAI_HTTP_TOKEN="$(openssl rand -hex 32)" \
uv run hai-mcp

除非设置了 HAI_HTTP_TOKEN，否则拒绝将 HTTP 绑定到非环回主机。请参阅 docs/OWNER_GATE.md 和 --help 输出。

---

使用示例——将服务接入客户端

该服务与传输方式无关；每个 MCP 客户端都能使用相同的 23 个工具。将代码片段放入客户端的 MCP 配置并重启。

Claude Code / Claude Desktop

{
  "mcpServers": {
    "hai": {
      "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"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "hai": {
      "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"
      }
    }
  }
}

Codex / Hermes / 任意 MCP stdio 客户端

配置格式相同——指向 uv run --directory … hai-mcp 命令，并传入两个环境变量。更多代码片段请见 docs/client-snippets/。

---

使用示例——驱动协议

典型的 Agent 循环会在执行操作前和执行操作后调用 HAI-MCP。

1. 开启有界任务

hai_mission_start(
  problem   = "Refactor the evaluator harness to be deterministic.",
  artifact  = "Pull request titled 'evaluator: deterministic harness'.",
  done_criteria = [
    {"id": "C1", "description": "Two A/B cases produce identical verdicts on three reruns."},
    {"id": "C2", "description": "Harness runs offline; no live network calls."},
  ],
  owner             = "samuel",
  time_limit_hours  = 6,
  non_goals         = ["Do not touch the MCP server.", "Do not change contract shapes."],
  constraints       = {"python": ">=3.12", "branch": "slice/eval-determinism"},
)

2. 授权会话租约

hai_authorize_session(
  mission_id         = "<from open>",
  contract_version   = 1,
  agent_identity     = "codex-cli",
  role               = "implementer",
  contribution       = "Deterministic A/B harness",
  expected_result    = "Green pytest with frozen inputs.",
  duration_minutes   = 90,
  criterion_ids      = ["C1", "C2"],
  device_id          = "mbp-mirgraatin",
  harness_id         = "codex-cli/0.45",
)

3. 运行活动前进行检查

hai_check_activity(
  session_id     = "<from lease>",
  activity_step  = "Replace random.seed with a seeded fixture in tests/test_eval_ab.py",
  criterion_id   = "C1",
  affected_paths = ["tests/test_eval_ab.py", "tests/fixtures/ab/case1.json"],
)
# → {"verdict": "on_contract", ...}

4. 提供证据并关闭

hai_proof(
  mission_id        = "<from open>",
  contract_version  = 1,
  outcome_summary   = "A/B cases produce identical verdicts on three reruns; harness offline.",
  evidence          = {
    "C1": {"command": "pytest tests/test_eval_ab.py -q", "exit_code": 0,
           "reruns": [0, 0, 0]},
    "C2": {"command": "pytest tests/test_eval_ab.py -q --offline", "exit_code": 0},
  },
)

5. 由所有者授权的晋级

对于 hai_accept_next_step、hai_recontract 或放弃任务，首次调用不带 owner_code 时，会通过带外方式向所有者发起请求。

• **file / ntfy：**一次性验证码会发送到 HAI_OWNER_HOME 或 ntfy 主题。将其作为 owner_code=<code> 传回即可完成操作。客户端永远看不到验证码；只有其哈希会存储在 HAI_HOME 中。
• **touchid（macOS）：**在服务端设置 HAI_OWNER_CHANNEL=touchid。服务端会显示 Touch ID 提示，并返回 status: owner_approved。使用相同参数（不带验证码）再次调用同一工具，即可应用这项确切的更改。可选项：HAI_OWNER_TOUCHID_TIMEOUT（默认值为 60）、HAI_OWNER_TOUCHID_HELPER（已编译的二进制文件），以及仅在 Touch ID 无法运行时使用的 HAI_OWNER_TOUCHID_FALLBACK=file。

批准与确切的更改绑定，且只能使用一次。在 Mac 上运行 uv run python scripts/manual_touchid.py prompt 和 … gate 可测试真实传感器；CI 会模拟该辅助程序。详情见：docs/OWNER_GATE.md。

---

状态布局

• 全局：$HAI_HOME — 默认值为 ~/.hai
• 所有者通道：$HAI_OWNER_HOME — 默认值为 ~/.hai-owner（刻意置于 HAI_HOME 之外，以便 Agent 无法读取）
• 每个项目：<project_path>/Projek-Managment/（旧版），或在绑定 project_id 时使用设备挂载点 + 相对前缀
• 挂载表：HAI_HOME/core/projects.json

所有写入都会解析并限制在这些根目录内。

---

项目布局

hai-mcp/
├── docs/
│   ├── TOOL_CONTRACT.md      # normative tool contract (gates, errors, schemas)
│   ├── OWNER_GATE.md         # nonce + ack_legacy owner-gate spec
│   ├── BUILD_HANDOFF.md
│   ├── client-snippets/      # ready-to-paste mcp.json snippets
│   ├── eval/                 # A/B harness contract
│   ├── plans/                # dated design slices
│   └── visuals/              # mission-lifecycle banner assets
├── scripts/                  # stdio smoke + impact-eval runner
├── src/hai_mcp/              # the server
└── tests/                    # 203 tests

---

局限性

HAI-MCP 的设计范围刻意保持狭窄。它不会：

• **调用任何大模型。**服务端有意保持简单——治理与生成是不同的关注点。
• **执行代码、运行 shell、推送 git 或删除文件。**它会拒绝类似 “commit & push”、“run pytest”、“rm -rf” 的工具。Agent 应执行这些操作，并通过 hai_check_activity / hai_proof 汇报。
• **与 hai-intake 软件包合并。**intake 流水线是独立的技术栈；可以共存，但不会融合。
• **提供 UI。**没有仪表板。控制平面使用 MCP 通信并写入 JSON；可视化由客户端负责。
• 支持多个任务并发。全局恰好只能有一个活动任务。只有在前一个任务已关闭（已完成或已放弃）后，才能开启新任务。
• **跨设备写入。**每台设备只能看到自己的挂载点。挂载表按设备区分；合约是全局的。
• **保证与主要版本升级后的 MCP 向前兼容。**服务端固定使用 mcp>=1.9.0,<2；MCP v2 需要单独的迁移切片。
• **提供撤销列表 / kill-switch API。**租约失效通过重新签订合约、关闭任务或使用 hai_stop 实现；没有可带外使用的 “立即撤销所有内容” 工具。
• **自动恢复损坏的 HAI_HOME。**如果全局状态目录损坏，服务端会按设计采取失败关闭策略，但恢复需要手动进行（参见 hai_recover）。

完整的门控矩阵见 docs/TOOL_CONTRACT.md，所有者授权合约见 docs/OWNER_GATE.md。

---

测试

uv run pytest                       # full suite
uv run python scripts/stdio_smoke.py  # stdio round-trip smoke

截至 Touch ID 所有者通道切片，仓库包含 203 项通过的测试。CI 状态可在仓库的 GitHub Actions 页面查看。

---

贡献

控制平面刻意保持精简——新增内容需通过合约切片：

1. 阅读 docs/TOOL_CONTRACT.md。
2. 提交 issue，说明工具 / 门控 / 状态变更。
3. 在 fail-closed 切片后落地，并在 docs/plans/ 中附上测试和计划。

如果 Pull Request 更改了门控、架构或挂载表，却没有配套计划，我们会要求按相同流程进行。

---

许可证

MIT — 参见 LICENSE。版权所有 © 2026 Samuel Fleig。

---

致谢

HAI-MCP 是 Samuel Fleig 的 HAI 技术栈的一部分。它基于以下项目：

• Model Context Protocol 规范；
• mcp Python SDK（mcp>=1.9.0,<2）；
• 以及旧版 ~/.config/hai-agent-mcp Hermes 桥接服务；本服务取代它来处理控制平面工作。两者可以共存；无需使用该桥接服务。

HAI 官方网站： https://www.human-agent-interface.com/ · 关于 Samuel Fleig： https://www.human-agent-interface.com/samuel/