@hirey/hi-mcp-server 0.1.2 → 0.1.4

package/README.md

@@ -27,6 +27,9 @@
 这些工具都以 `hi_agent_*` 命名，保持和 gateway 控制面同一语义边界：
 
 - `hi_agent_status`
+- `hi_agent_install`
+- `hi_agent_doctor`
+- `hi_agent_reset`
 - `hi_agent_register`
 - `hi_agent_connect`
 - `hi_agent_activate`
@@ -51,8 +54,7 @@
 - `agent_listings`
 - `matching_sessions`
 - `pairings`
-- `meeting_chain`
-- `meeting_confirmation`
+- `thread_meetings`
 
 这样做的目的是让 Claude Code、OpenClaw 和其他 `MCP-first` 宿主看到的工具名、参数 schema、调用语义都跟 `Hi` 平台目录保持一致，不产生第二套 API。
 
@@ -60,19 +62,15 @@
 
 普通用户的正式安装路径不应该依赖 `AWS`、`CodeArtifact`、私有 registry，或者一套专门给内部同事写的 Docker/Helm 操作。
 
-面向 OpenClaw / 本地 MCP host 的官方安装方式应是固定版本的公开 tarball：
+这里的 `Hi` 指 `Hirey Hi Agent Platform`，不是 `Hi.Events`。
 
-```bash
-npm install -g "https://registry.npmjs.org/@hirey/hi-mcp-server/-/hi-mcp-server-0.1.2.tgz"
-```
-
-如果你的 npm 客户端已经能正确读到 `@hirey` scope 元数据，也可以直接按包名安装：
+普通本地宿主的推荐方式是把 `@hirey/hi-mcp-server` 挂成 **本地 stdio MCP server**，而不是先自己部署一个公网 `/mcp` 服务。
 
 ```bash
-npm install -g @hirey/hi-mcp-server@0.1.2
+npm install -g @hirey/hi-mcp-server
 ```
 
-安装后，普通用户推荐把它作为 **本地 stdio MCP server** 挂到宿主里，而不是先自己部署一个公网 `/mcp` 服务。
+如果你是在自动化脚本、镜像、或可复现安装链里使用它，应该固定具体版本，不要依赖隐式最新版本。
 
 对 OpenClaw，推荐的 MCP 配置形态是：
 
@@ -83,7 +81,7 @@ npm install -g @hirey/hi-mcp-server@0.1.2
     "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"
+    "HI_MCP_STATE_DIR": "/Users/you/.openclaw/hi-mcp/openclaw-main"
   }
 }
 ```
@@ -91,9 +89,13 @@ npm install -g @hirey/hi-mcp-server@0.1.2
 普通用户首次接入后的典型顺序：
 
 1. 用宿主把 `hi-mcp-server` 作为 `stdio` MCP server 挂上
-2. 在宿主对话里执行 `hi_agent_register -> hi_agent_connect -> hi_agent_activate`
-3. 让 `hi-mcp-server` 把 installation 长期身份持久化到固定 `HI_MCP_STATE_DIR`
-4. 如果宿主需要主动事件回流，再安装 `hi-agent-receiver`
+2. 优先执行 `hi_agent_install`，而不是让用户手工走 `register -> connect -> activate`
+3. `hi_agent_install` 会自动完成 register / activate、delivery capability 声明、默认订阅，以及在 OpenClaw 场景下的 receiver 配置
+4. `agent_id` 可以省略；省略时由 gateway 正式生成 canonical `ag_...`，不需要用户手写
+5. 完成后执行 `hi_agent_doctor`
+6. 如果要 clean reinstall，先执行 `hi_agent_reset`
+
+如果宿主不能直接执行裸命令 `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 用户只需要 `npm + OpenClaw TUI`，不需要 AWS。**
 
@@ -113,8 +115,8 @@ npm install -g @hirey/hi-mcp-server@0.1.2
 - `HI_MCP_PROFILE`
   - 本地 state profile，默认 `default`。
 - `HI_MCP_STATE_DIR`
-  - 本地 state 目录，默认 `./.hi-agent-state`。
-  - OpenClaw 普通用户建议显式固定到稳定目录，例如 `/Users/you/.openclaw/hi`，方便后续 `hi-agent-receiver` 直接复用同一份身份 state。
+  - 本地 state 目录。未显式指定时，默认落到稳定 home 目录：`~/.hirey/hi-mcp/<profile>`。
+  - OpenClaw 普通用户建议显式固定到 canonical 目录，例如 `/Users/you/.openclaw/hi-mcp/openclaw-main`，方便后续 `hi-agent-receiver` 直接复用同一份身份 state。
 
 ### 本地 state
 
@@ -126,6 +128,7 @@ state 会按 profile 落到 `HI_MCP_STATE_DIR/<profile>.json`。
   - 长期凭证与安装身份：`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` 不会被持久化。
 
@@ -284,8 +287,8 @@ shared `hi-infra` 负责 `Hi` 自己的公共平台面；`hi-mcp-server` 则持
 
 ## 验证建议
 
-phase 1 至少验证三条线：
+至少验证三条线：
 
-- Claude Code / generic MCP host 能通过 `hi_agent_register -> hi_agent_activate` 后调用 `agent_listings / matching_sessions / pairings / meeting_chain`
+- 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

package/dist/server.d.ts

@@ -1,2 +1,3 @@
+#!/usr/bin/env node
 export {};
 //# sourceMappingURL=server.d.ts.map