@hirey-ai/mcp-server

v0.1.24

Published

9 days ago

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

0High
0Medium
0Low

liyongzhi

hirey-ai-mcp-server

hirey-ai-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. 业务工具

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

hirey-ai-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-ai/mcp-server 挂成 本地 stdio MCP server，而不是先自己部署一个公网 /mcp 服务。

npm install -g @hirey-ai/mcp-server

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

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

{
  "command": "hirey-ai-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 布局。

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

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

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

对 OpenClaw 的普通用户本地 vendor 安装，不要显式传 receiver_command="hirey-ai-agent-receiver" 或 receiver_command_argv=["hirey-ai-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，方便后续 hirey-ai-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

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 \
hirey-ai-mcp-server

MCP endpoint:

POST /mcp
GET /healthz

Stdio

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

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

宿主接收矩阵

MCP-first 宿主

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

OpenClaw

工具接入主路径：仍然是 hirey-ai-mcp-server
普通用户主路径：本地 stdio child process
推荐先通过公开 npm 安装 @hirey-ai/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：
- 事件主路径：hirey-ai-agent-receiver
- 本机适配器：
  - openclaw_hooks
  - openresponses

HTTP / webhook-first 宿主

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

带 channel / live push 的宿主

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

分发与部署

固定公网入口

hirey-ai-mcp-server 依赖 Hi 的固定 well-known：

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

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