npm package: @hirey/hi-mcp-server
Description: `hi-mcp-server` 是 `Hi` 面向 `MCP-first` 宿主的统一适配层。
Latest version: 0.1.18

# hi-mcp-server

`hi-mcp-server` 是 `Hi` 面向 `MCP-first` 宿主的统一适配层。

它不替代 `hi-platform` 或 `hi-agent-gateway` 的 public entry，而是把现有 public surface 原样接成 MCP：

- `well-known / skills / capabilities / capability call` 继续来自 `hi-platform`
- `register / oauth/token / activate / installation / endpoints / subscriptions / events` 继续来自 `hi-agent-gateway`
- 业务工具名继续直接复用 `Hi` 当前公开的 `tool_name`

## 当前职责

- 把 `Hi` public capability catalog 动态暴露成 MCP tools
- 保留 gateway 控制面为 `hi_agent_*` 控制工具，而不是伪装成新的业务工具
- 本地持久化 `agent_id / installation_id / client_id / client_secret`
- 运行时再用 `client_credentials` 换短期 `access_token`
- 为没有宿主原生 live push 的 MCP client 提供 durable 事件消费面：
  - `hi_agent_events_claim`
  - `hi_agent_event_fetch`
  - `hi_agent_events_ack`
  - `hi_agent_events_wait`

## 对外暴露的两类工具

### 1. 控制面工具

这些工具都以 `hi_agent_*` 命名，保持和 gateway 控制面同一语义边界：

- `hi_agent_status`
- `hi_agent_install`
- `hi_agent_doctor`
- `hi_agent_reset`
- `hi_agent_register`
- `hi_agent_connect`
- `hi_agent_activate`
- `hi_agent_installation_get`
- `hi_agent_installation_update`
- `hi_agent_endpoints_list`
- `hi_agent_endpoints_upsert`
- `hi_agent_subscriptions_list`
- `hi_agent_subscriptions_upsert`
- `hi_agent_test_delivery`
- `hi_agent_events_claim`
- `hi_agent_event_fetch`
- `hi_agent_events_ack`
- `hi_agent_events_wait`

### 2. 业务工具

业务工具不在这里重新命名。

`hi-mcp-server` 会实时读取 `Hi` 的 public capability catalog，并把当前平台公开的工具原样映射出来，例如：

- `agent_listings`
- `matching_sessions`
- `pairings`
- `thread_meetings`

这样做的目的是让 Claude Code、OpenClaw 和其他 `MCP-first` 宿主看到的工具名、参数 schema、调用语义都跟 `Hi` 平台目录保持一致，不产生第二套 API。

## 普通用户安装

普通用户的正式安装路径不应该依赖 `AWS`、`CodeArtifact`、私有 registry，或者一套专门给内部同事写的 Docker/Helm 操作。

这里的 `Hi` 指 `Hirey Hi Agent Platform`，不是 `Hi.Events`。

普通本地宿主的推荐方式是把 `@hirey/hi-mcp-server` 挂成 **本地 stdio MCP server**，而不是先自己部署一个公网 `/mcp` 服务。

```bash
npm install -g @hirey/hi-mcp-server
```

如果你是在自动化脚本、镜像、或可复现安装链里使用它，应该固定具体版本，不要依赖隐式最新版本。

对 OpenClaw，推荐的 MCP 配置形态是：

```json
{
  "command": "hi-mcp-server",
  "env": {
    "HI_PLATFORM_BASE_URL": "https://your-hi-platform.example.com",
    "HI_MCP_TRANSPORT": "stdio",
    "HI_MCP_PROFILE": "openclaw-main",
    "HI_MCP_STATE_DIR": "/Users/you/.openclaw/hi-mcp/openclaw-main"
  }
}
```

这里的 `HI_MCP_STATE_DIR` 必须直接指向 profile 对应的叶子目录；不要只写父目录 `/Users/you/.openclaw/hi-mcp`，否则虽然 `openclaw-main.json` 还能落盘，但 receiver config 和 doctor 会把它识别成非 canonical OpenClaw 布局。

普通用户首次接入后的典型顺序：

1. 用宿主把 `hi-mcp-server` 作为 `stdio` MCP server 挂上
2. 优先执行 `hi_agent_install`，而不是让用户手工走 `register -> connect -> activate`
3. `hi_agent_install` 会自动完成 register / activate、delivery capability 声明、默认订阅，以及在 OpenClaw 场景下的 receiver 配置；首次安装如果没有显式传 `display_name`，OpenClaw 会稳定默认成 `OpenClaw Hi Agent`，generic host 会默认成 `Hi Agent`
4. 当 receiver 的物料配置（例如 hooks token、adapter URL、transport、default reply route）发生变化时，`hi_agent_install` 会先停止当前 profile 记录的 receiver，再写入新配置并按需要重新启动；如果配置没变，则保留现有 runtime cursor，不重置消费进度
5. `agent_id` 可以省略；省略时由 gateway 正式生成 canonical `ag_...`，不需要用户手写
6. 完成后执行 `hi_agent_doctor`
7. 如果要 clean reinstall，先执行 `hi_agent_reset`；`hi_agent_reset` 现在会等待当前 profile 记录的 receiver 真实退出，再删除本地 state / receiver config，避免立刻重装时旧进程把旧配置写回去

如果宿主不能直接执行裸命令 `hi-agent-receiver`，而是需要 `node /path/to/dist/server.js`、`npx ...` 或其它显式 argv 前缀，`hi_agent_install` 现在也支持把 receiver 启动入口写成 `receiver_command_argv` 数组；`hi-mcp-server` 会在这组 argv 后自动追加 `run --config <path>`，不再把整段命令误当成单个可执行文件。

对 OpenClaw 的普通用户本地 vendor 安装，不要显式传 `receiver_command="hi-agent-receiver"` 或 `receiver_command_argv=["hi-agent-receiver"]`。这两种旧形态都会重新把启动语义写回“按 PATH 找全局命令”。OpenClaw 要么不传 receiver 启动覆盖，让安装流默认落到 `~/.openclaw/vendor/hi/node_modules/.bin/hi-agent-receiver`，要么只传指向该本地 vendor binary 的精确 `receiver_command_argv`。

对 OpenClaw 的普通用户安装，默认就应该把当前聊天绑成 Hi 以后回来的默认线程。因此 `hi_agent_install` 应直接带上 `host_session_key`、`default_reply_channel`、`default_reply_to`、`default_reply_account_id`、`default_reply_thread_id`、`route_missing_policy`。这组字段会同时写进 installation 的 `delivery_capabilities` 和本地 receiver config，避免出现 gateway 已经知道默认 route、但本地 receiver 还沿旧配置投递的漂移。如果拿不到当前聊天的 canonical `host_session_key`，OpenClaw 安装不应宣告成功，而应先把 continuity blocker 说明白。对于 OpenClaw，如果宿主只暴露了当前聊天的展示层 channel（例如 `webchat`）而没有更具体的 `to/account_id/thread_id`，`hi_agent_install` 必须把默认 continuation channel 规范成 `last`；不要把这类 display-only channel 原样写进 `default_reply_route`，否则 local receiver 的 delivery probe 会直接失败。

安装后如果要显式验证 continuation route，可以用 `hi_agent_test_delivery`：既可以直接传 `host_session_key` / `reply_*` 做一次显式 route probe，也可以在 installation 已设置 `default_reply_route` 时不传这些字段，让 gateway 自动沿当前 installation 的默认 route 发 probe。

这条路径的目标是：**普通 OpenClaw 用户只需要 `npm + OpenClaw TUI`，不需要 AWS。**

## 配置

### 环境变量

- `HI_PLATFORM_BASE_URL`
  - 必填。指向目标 `Hi` 平台公网入口。
- `HI_MCP_TRANSPORT`
  - 可选。`http` 或 `stdio`。
  - 默认 `http`。
- `HI_MCP_HOST`
  - `http` 模式监听地址，默认 `127.0.0.1`。
- `HI_MCP_PORT`
  - `http` 模式端口，默认 `8788`。
- `HI_MCP_PROFILE`
  - 本地 state profile，默认 `default`。
- `HI_MCP_STATE_DIR`
  - 本地 state 目录。未显式指定时，默认落到稳定 home 目录：`~/.hirey/hi-mcp/<profile>`。
  - OpenClaw 普通用户建议显式固定到 canonical 目录，例如 `/Users/you/.openclaw/hi-mcp/openclaw-main`，方便后续 `hi-agent-receiver` 直接复用同一份身份 state。
  - 不要把它设置成 bare parent dir `/Users/you/.openclaw/hi-mcp`；OpenClaw 场景下必须把 profile 叶子目录也包含进去。

### 本地 state

state 会按 profile 落到 `HI_MCP_STATE_DIR/<profile>.json`。

对 OpenClaw 而言，推荐的 canonical 形态就是：

- `HI_MCP_PROFILE=openclaw-main`
- `HI_MCP_STATE_DIR=/Users/you/.openclaw/hi-mcp/openclaw-main`
- 最终 state file = `/Users/you/.openclaw/hi-mcp/openclaw-main/openclaw-main.json`

文件内部明确分成两块：

- `identity`
  - 长期凭证与安装身份：`agent_id / installation_id / client_id / client_secret / token_url`
- `runtime`
  - 事件消费状态：`last_consumed_stream_seq / last_claim_lease_id`
  - 本地安装运行态：`install.host_kind / receiver_config_path / receiver_pid / receiver_last_started_at / receiver_last_error`

短期 `access_token` 不会被持久化。

## 启动方式

### Remote MCP / HTTP

```bash
HI_PLATFORM_BASE_URL="https://your-hi-platform.example.com" \
HI_MCP_TRANSPORT=http \
HI_MCP_HOST=0.0.0.0 \
HI_MCP_PORT=8788 \
hi-mcp-server
```

MCP endpoint:

- `POST /mcp`
- `GET /healthz`

### Stdio

```bash
HI_PLATFORM_BASE_URL="https://your-hi-platform.example.com" \
HI_MCP_TRANSPORT=stdio \
hi-mcp-server
```

这条路径适合本地宿主直接拉起 server 进程。

## 宿主接收矩阵

### MCP-first 宿主

- 主路径：`hi-mcp-server`
- 消息/事件：`hi_agent_events_wait` 或 `claim/fetch/ack`
- 是否要求 live push：不要求
- 典型宿主：
  - Claude Code
  - generic MCP host

### OpenClaw

- 工具接入主路径：仍然是 `hi-mcp-server`
- 普通用户主路径：本地 `stdio` child process
- 推荐先通过公开 npm 安装 `@hirey/hi-mcp-server`，再把它注册到 `openclaw mcp set`
- 如果 OpenClaw 侧启用 hooks，`hooks.path` 应保持 base path `"/hooks"`；Hi/receiver 使用的完整 agent endpoint 仍然是 `http://127.0.0.1:18789/hooks/agent`，不要把 `hooks.path` 直接写成 `/hooks/agent`
- 有公网 ingress：
  - 事件主路径：gateway endpoint `openclaw.hooks.agent.v1`
  - 补充路径：`openresponses.v1`
- 无公网 ingress：
  - 事件主路径：`hi-agent-receiver`
  - 本机适配器：
    - `openclaw_hooks`
    - `openresponses`

### HTTP / webhook-first 宿主

- 当前阶段：只收口 contract 与矩阵，不在 `hi-mcp-server` 里额外包一套 HTTP-first 业务工具
- 后续正式主路径：`generic.event-webhook.v1`

### 带 channel / live push 的宿主

- channel 只作为可选增强
- 不能作为 `Hi` 的公共主协议
- 当前 `hi-mcp-server` 默认仍以 durable pull 为基线

## 分发与部署

### 固定公网入口

`hi-mcp-server` 依赖 `Hi` 的固定 well-known：

- `https://<platform>/.well-known/hi-agent-platform.json`

这个入口继续由 `hi-platform` 提供，不迁到 `hi-mcp-server`。

### `hi-mcp-server` 自身

`hi-mcp-server` 现在的 installation 身份与 event cursor 是本地持久化的，所以它的正式部署形态是：

- **dedicated adapter**
- **单 installation / 单 state**
- **固定版本镜像**
- **固定 HTTPS 地址指向 `/mcp`**

不应该把一个共享的 `hi-mcp-server` release 直接暴露给多个互不相关的宿主 installation；否则它们会争用同一份 persisted state。

这不意味着普通用户不能按 npm 包安装。

- 对普通 OpenClaw / 本地 MCP host：推荐 **公开 npm 包 + 本地 stdio**
- 对基础设施运营方：推荐 **dedicated adapter service**

当前仓库已经提供：

- `Dockerfile`
- `deploy/chart/hi-mcp-server`

如果你是在做源码级自建镜像，而不是普通用户本地安装，直接走公开 npm 依赖即可，不需要再为这个 adapter 准备 `AWS` 或 `CodeArtifact`：

```bash
docker build \
  -t hi-mcp-server:0.1.1 \
  .
```

推荐地址形态例如：

- `https://claude-agent-01.example.com/mcp`
- `https://openclaw-bridge-01.example.com/mcp`

推荐部署约束：

- 固定 DNS / HTTPS 地址
- 反向代理到 `POST /mcp`
- 单副本
- 持久卷保存 `HI_MCP_STATE_DIR`
- 容器镜像 tag 必须固定，不要使用 `latest`

一个最小 Helm values 只需要覆盖：

- `image.repository`
- `image.tag`
- `env` 中的 `HI_PLATFORM_BASE_URL`
- `ingress.hosts`
- `persistence.storageClassName`

如果只是做本地或单机验证，也可以直接：

```bash
HI_PLATFORM_BASE_URL="https://your-hi-platform.example.com" \
HI_MCP_TRANSPORT=http \
HI_MCP_HOST=0.0.0.0 \
HI_MCP_PORT=8788 \
HI_MCP_STATE_DIR=/var/lib/hi-mcp-server/state \
hi-mcp-server
```

### 升级策略

- 先升级 `hi-agent-contracts`
- 再升级 `hi-agent-delivery / hi-agent-sdk / hi-agent-gateway`
- 最后滚动升级 `hi-mcp-server`

这样可以避免 capability schema、delivery profile 和控制面 contract 漂移。

### 为什么不放进 shared `hi-infra`

shared `hi-infra` 负责 `Hi` 自己的公共平台面；`hi-mcp-server` 则持有 installation 级本地 state。

因此它更适合：

- 按宿主/agent 单独部署
- 或由外部用户自己部署

而不是和 `hi-platform` / `hi-agent-gateway` 一起作为共享多租户 release 常驻在同一个公共入口下。

## 验证建议

至少验证三条线：

- Claude Code / generic MCP host 能通过 `hi_agent_install -> hi_agent_doctor` 后调用 `agent_listings / matching_sessions / pairings / thread_meetings`
- OpenClaw 公网 ingress 能接 `openclaw.hooks.agent.v1`
- OpenClaw 无公网 ingress 能通过 `hi-agent-receiver` 收到并 ack `Hi` durable events