@hirey/hi-mcp-server 0.1.1

package/README.md

@@ -0,0 +1,285 @@
+# 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_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`
+- `meeting_chain`
+- `meeting_confirmation`
+
+这样做的目的是让 Claude Code、OpenClaw 和其他 `MCP-first` 宿主看到的工具名、参数 schema、调用语义都跟 `Hi` 平台目录保持一致，不产生第二套 API。
+
+## 普通用户安装
+
+普通用户的正式安装路径不应该依赖 `AWS`、`CodeArtifact`、私有 registry，或者一套专门给内部同事写的 Docker/Helm 操作。
+
+面向 OpenClaw / 本地 MCP host 的官方安装方式应是：
+
+```bash
+npm install -g @hirey/hi-mcp-server@0.1.1
+```
+
+安装后，普通用户推荐把它作为 **本地 stdio MCP server** 挂到宿主里，而不是先自己部署一个公网 `/mcp` 服务。
+
+对 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"
+  }
+}
+```
+
+普通用户首次接入后的典型顺序：
+
+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`
+
+这条路径的目标是：**普通 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 目录，默认 `./.hi-agent-state`。
+  - OpenClaw 普通用户建议显式固定到稳定目录，例如 `/Users/you/.openclaw/hi`，方便后续 `hi-agent-receiver` 直接复用同一份身份 state。
+
+### 本地 state
+
+state 会按 profile 落到 `HI_MCP_STATE_DIR/<profile>.json`。
+
+文件内部明确分成两块：
+
+- `identity`
+  - 长期凭证与安装身份：`agent_id / installation_id / client_id / client_secret / token_url`
+- `runtime`
+  - 事件消费状态：`last_consumed_stream_seq / last_claim_lease_id`
+
+短期 `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`
+- 有公网 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 常驻在同一个公共入口下。
+
+## 验证建议
+
+phase 1 至少验证三条线：
+
+- Claude Code / generic MCP host 能通过 `hi_agent_register -> hi_agent_activate` 后调用 `agent_listings / matching_sessions / pairings / meeting_chain`
+- OpenClaw 公网 ingress 能接 `openclaw.hooks.agent.v1`
+- OpenClaw 无公网 ingress 能通过 `hi-agent-receiver` 收到并 ack `Hi` durable events

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":""}

package/dist/server.js

@@ -0,0 +1,838 @@
+import { createServer } from 'node:http';
+import process from 'node:process';
+import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { normalizeAgentEndpointList, normalizeAgentInstallationDeliveryDeclaration, normalizeAgentSubscriptionList, normalizeText, } from '@hirey/hi-agent-contracts';
+import { createHiAgentClients, exchangeHiAgentClientCredentialsToken, HiAgentGatewayClient, HiAgentPlatformClient, } from '@hirey/hi-agent-sdk';
+import { readState, updateState, } from './state.js';
+const CAPABILITY_CACHE_TTL_MS = 30_000;
+const config = {
+    host: normalizeText(process.env.HI_MCP_HOST) || '127.0.0.1',
+    port: Number(process.env.HI_MCP_PORT || 8788),
+    profile: normalizeText(process.env.HI_MCP_PROFILE) || 'default',
+    stateDir: normalizeText(process.env.HI_MCP_STATE_DIR) || `${process.cwd()}/.hi-agent-state`,
+    platformBaseUrl: normalizeText(process.env.HI_PLATFORM_BASE_URL),
+    transport: normalizeText(process.env.HI_MCP_TRANSPORT).toLowerCase() === 'stdio' ? 'stdio' : 'http',
+};
+let capabilityCache = null;
+function assertConfig() {
+    if (!config.platformBaseUrl) {
+        throw new Error('missing_hi_platform_base_url');
+    }
+    if (!Number.isFinite(config.port) || config.port <= 0) {
+        throw new Error('invalid_hi_mcp_port');
+    }
+}
+function jsonText(value) {
+    return JSON.stringify(value, null, 2);
+}
+function ok(structuredContent, text) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: text || jsonText(structuredContent),
+            },
+        ],
+        structuredContent,
+    };
+}
+function fail(message, detail) {
+    const payload = detail == null
+        ? { ok: false, error: message }
+        : { ok: false, error: message, detail };
+    return {
+        isError: true,
+        content: [
+            {
+                type: 'text',
+                text: jsonText(payload),
+            },
+        ],
+        structuredContent: payload,
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function controlTools() {
+    // control tools 只映射 gateway/onboarding/runtime 管理面，不伪装成第二套业务 API。
+    return [
+        {
+            name: 'hi_agent_status',
+            description: '读取当前本地持久化的 Hi agent 身份、installation 与事件 cursor；可选做一次远端 me/installation 刷新。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    include_remote: { type: 'boolean', description: 'true 时额外请求 gateway me/installation 做一次实时校验。' },
+                },
+            },
+        },
+        {
+            name: 'hi_agent_register',
+            description: '按 Hi 官方 register -> token -> activate 主线创建一个新的 external agent installation，并把长期凭证持久化到本地 state。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    agent_id: { type: 'string' },
+                    display_name: { type: 'string' },
+                    agent_kind: { type: 'string' },
+                    capabilities: { type: 'object' },
+                    metadata: { type: 'object' },
+                    delivery_capabilities: { type: 'object' },
+                    replace_existing_state: { type: 'boolean', description: 'true 时允许覆盖当前 profile 已持久化的 installation state。' },
+                },
+                required: ['display_name'],
+            },
+        },
+        {
+            name: 'hi_agent_connect',
+            description: '把当前 installation 绑定到一个已存在的 Hi agent；要求本地 profile 已经持久化了 installation 的 client_credentials。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    agent_id: { type: 'string' },
+                    metadata: { type: 'object' },
+                    delivery_capabilities: { type: 'object' },
+                },
+                required: ['agent_id'],
+            },
+        },
+        {
+            name: 'hi_agent_activate',
+            description: '对当前 installation 执行 activate，让它进入正式可用状态。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    agent_id: { type: 'string' },
+                },
+            },
+        },
+        {
+            name: 'hi_agent_installation_get',
+            description: '读取当前 installation 的正式 persisted state，包括 delivery_capabilities。',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
+        {
+            name: 'hi_agent_installation_update',
+            description: '更新当前 installation 的 metadata / delivery_capabilities；不会额外包装成新的业务协议。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    metadata: { type: 'object' },
+                    delivery_capabilities: { type: 'object' },
+                },
+            },
+        },
+        {
+            name: 'hi_agent_endpoints_list',
+            description: '列出当前 agent 的 delivery endpoints。',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
+        {
+            name: 'hi_agent_endpoints_upsert',
+            description: '写入当前 agent 的 delivery endpoints，用于公网 webhook / openclaw hooks / openresponses 等正式交付面。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    endpoints: {
+                        type: 'array',
+                        items: { type: 'object' },
+                    },
+                },
+                required: ['endpoints'],
+            },
+        },
+        {
+            name: 'hi_agent_subscriptions_list',
+            description: '列出当前 agent 的 event subscriptions。',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
+        {
+            name: 'hi_agent_subscriptions_upsert',
+            description: '写入当前 agent 的 event subscriptions。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    subscriptions: {
+                        type: 'array',
+                        items: { type: 'object' },
+                    },
+                },
+                required: ['subscriptions'],
+            },
+        },
+        {
+            name: 'hi_agent_test_delivery',
+            description: '对当前 agent 的 endpoints 触发一次 test-delivery。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    topic: { type: 'string' },
+                    text: { type: 'string' },
+                    payload: { type: 'object' },
+                    profile: { type: 'string' },
+                },
+            },
+        },
+        {
+            name: 'hi_agent_events_claim',
+            description: '按 persisted cursor 或显式 after_seq claim 一批 durable events。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    after_seq: { type: 'number' },
+                    limit: { type: 'number' },
+                    claim_lease_id: { type: 'string' },
+                    use_persisted_cursor: { type: 'boolean', description: '默认 true；未显式传 after_seq 时从本地 runtime cursor 继续。' },
+                },
+            },
+        },
+        {
+            name: 'hi_agent_event_fetch',
+            description: '按 event_id 拉取单条 event 的完整 payload。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    event_id: { type: 'string' },
+                },
+                required: ['event_id'],
+            },
+        },
+        {
+            name: 'hi_agent_events_ack',
+            description: '提交一批 event ack，并在 consumed 时推进本地 persisted cursor。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    acks: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                event_id: { type: 'string' },
+                                status: { type: 'string' },
+                                last_error: { type: 'string' },
+                                result: { type: 'object' },
+                                retry_after_ms: { type: 'number' },
+                            },
+                            required: ['event_id', 'status'],
+                        },
+                    },
+                },
+                required: ['acks'],
+            },
+        },
+        {
+            name: 'hi_agent_events_wait',
+            description: '用 claim/poll 等待下一批 durable events，适合没有 live push 的 MCP-first 宿主。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    after_seq: { type: 'number' },
+                    limit: { type: 'number' },
+                    timeout_ms: { type: 'number' },
+                    poll_interval_ms: { type: 'number' },
+                    use_persisted_cursor: { type: 'boolean' },
+                },
+            },
+        },
+    ];
+}
+function isPlainObject(input) {
+    return !!input && typeof input === 'object' && !Array.isArray(input);
+}
+function normalizeRecord(input) {
+    return isPlainObject(input) ? input : {};
+}
+async function loadWellKnown() {
+    const platform = new HiAgentPlatformClient({ baseUrl: config.platformBaseUrl });
+    return await platform.wellKnown();
+}
+async function loadCapabilities() {
+    if (capabilityCache && Date.now() - capabilityCache.fetchedAt < CAPABILITY_CACHE_TTL_MS) {
+        return capabilityCache.items;
+    }
+    const platform = new HiAgentPlatformClient({ baseUrl: config.platformBaseUrl });
+    const out = await platform.listCapabilities();
+    const items = Array.isArray(out.capabilities) ? out.capabilities : [];
+    capabilityCache = {
+        fetchedAt: Date.now(),
+        items,
+    };
+    return items;
+}
+async function createBootstrapClients() {
+    const wellKnown = await loadWellKnown();
+    const platform = new HiAgentPlatformClient({ baseUrl: config.platformBaseUrl });
+    const gateway = new HiAgentGatewayClient({
+        baseUrl: wellKnown.platform.registry_base_url,
+        token: '',
+    });
+    return {
+        wellKnown,
+        platform,
+        gateway,
+    };
+}
+async function loadPersistedState() {
+    return await readState({
+        stateDir: config.stateDir,
+        profile: config.profile,
+    });
+}
+async function persistState(updater) {
+    return await updateState({
+        stateDir: config.stateDir,
+        profile: config.profile,
+        updater,
+    });
+}
+async function createAuthorizedClients() {
+    const state = await loadPersistedState();
+    if (!state.identity)
+        throw new Error('missing_agent_identity');
+    const token = await exchangeHiAgentClientCredentialsToken({
+        tokenUrl: state.identity.token_url,
+        clientId: state.identity.client_id,
+        clientSecret: state.identity.client_secret,
+    });
+    const clients = await createHiAgentClients({
+        platformBaseUrl: state.platform?.platform_base_url || config.platformBaseUrl,
+        token: token.access_token,
+    });
+    return {
+        state,
+        accessToken: token.access_token,
+        ...clients,
+    };
+}
+async function handleRegister(args) {
+    const current = await loadPersistedState();
+    if (current.identity && args.replace_existing_state !== true) {
+        return fail('agent_state_already_exists', {
+            profile: config.profile,
+            agent_id: current.identity.agent_id,
+            installation_id: current.identity.installation_id,
+        });
+    }
+    const { wellKnown, gateway } = await createBootstrapClients();
+    const agentId = normalizeText(args.agent_id);
+    if (!agentId) {
+        return fail('missing_agent_id');
+    }
+    const request = {
+        agent_id: agentId,
+        display_name: normalizeText(args.display_name),
+        agent_kind: normalizeText(args.agent_kind) || undefined,
+        capabilities: args.capabilities,
+        metadata: isPlainObject(args.metadata) ? args.metadata : null,
+        delivery_capabilities: normalizeAgentInstallationDeliveryDeclaration(args.delivery_capabilities),
+        status: normalizeText(args.status) || undefined,
+    };
+    const registered = await gateway.register(request);
+    await persistState(() => ({
+        profile: config.profile,
+        platform: {
+            platform_base_url: config.platformBaseUrl,
+            registry_base_url: wellKnown.platform.registry_base_url,
+            fetched_at: new Date().toISOString(),
+        },
+        identity: {
+            agent_id: registered.agent.agent_id,
+            installation_id: registered.installation.installation_id,
+            display_name: registered.agent.display_name,
+            agent_kind: registered.agent.agent_kind,
+            client_id: registered.auth.client_id,
+            client_secret: registered.auth.client_secret,
+            installation_subject: registered.auth.installation_subject,
+            issuer: registered.auth.issuer,
+            audience: registered.auth.audience,
+            token_url: registered.auth.token_url,
+            jwks_url: registered.auth.jwks_url,
+            activated_at: registered.installation.activated_at,
+            delivery_capabilities: registered.installation.delivery_capabilities,
+        },
+        runtime: {
+            last_consumed_stream_seq: 0,
+            last_claim_lease_id: null,
+            updated_at: new Date().toISOString(),
+        },
+    }));
+    return ok({
+        ok: true,
+        agent: registered.agent,
+        installation: registered.installation,
+        next: registered.next,
+        contract: registered.contract,
+        persisted_profile: config.profile,
+    });
+}
+async function handleConnect(args) {
+    const { gateway } = await createAuthorizedClients();
+    const connected = await gateway.connect({
+        agent_id: normalizeText(args.agent_id),
+        metadata: isPlainObject(args.metadata) ? args.metadata : null,
+        delivery_capabilities: normalizeAgentInstallationDeliveryDeclaration(args.delivery_capabilities),
+    });
+    await persistState((current) => ({
+        ...current,
+        identity: current.identity
+            ? {
+                ...current.identity,
+                agent_id: connected.agent.agent_id,
+                display_name: connected.agent.display_name,
+                agent_kind: connected.agent.agent_kind,
+                installation_id: connected.installation.installation_id,
+                activated_at: connected.installation.activated_at,
+                delivery_capabilities: connected.installation.delivery_capabilities,
+            }
+            : current.identity,
+        runtime: {
+            ...current.runtime,
+            updated_at: new Date().toISOString(),
+        },
+    }));
+    return ok({
+        ok: true,
+        agent: connected.agent,
+        installation: connected.installation,
+        contract: connected.contract,
+    });
+}
+async function handleActivate(args) {
+    const { gateway } = await createAuthorizedClients();
+    const activated = await gateway.activate({
+        agent_id: normalizeText(args.agent_id) || undefined,
+    });
+    await persistState((current) => ({
+        ...current,
+        identity: current.identity
+            ? {
+                ...current.identity,
+                agent_id: activated.agent.agent_id,
+                display_name: activated.agent.display_name,
+                agent_kind: activated.agent.agent_kind,
+                activated_at: activated.installation.activated_at,
+                delivery_capabilities: activated.installation.delivery_capabilities,
+            }
+            : current.identity,
+        runtime: {
+            ...current.runtime,
+            updated_at: new Date().toISOString(),
+        },
+    }));
+    return ok({
+        ok: true,
+        agent: activated.agent,
+        installation: activated.installation,
+        contract: activated.contract,
+    });
+}
+async function handleStatus(args) {
+    const state = await loadPersistedState();
+    if (args.include_remote !== true || !state.identity) {
+        return ok({
+            ok: true,
+            profile: config.profile,
+            state,
+        });
+    }
+    const { gateway } = await createAuthorizedClients();
+    const me = await gateway.me();
+    const installation = await gateway.getInstallation();
+    return ok({
+        ok: true,
+        profile: config.profile,
+        state,
+        remote: {
+            me,
+            installation,
+        },
+    });
+}
+async function handleInstallationGet() {
+    const { gateway } = await createAuthorizedClients();
+    const installation = await gateway.getInstallation();
+    return ok(installation);
+}
+async function handleInstallationUpdate(args) {
+    const { gateway } = await createAuthorizedClients();
+    const updated = await gateway.updateInstallation({
+        ...(Object.prototype.hasOwnProperty.call(args, 'metadata')
+            ? { metadata: isPlainObject(args.metadata) ? args.metadata : null }
+            : {}),
+        ...(Object.prototype.hasOwnProperty.call(args, 'delivery_capabilities')
+            ? { delivery_capabilities: normalizeAgentInstallationDeliveryDeclaration(args.delivery_capabilities) }
+            : {}),
+    });
+    await persistState((current) => ({
+        ...current,
+        identity: current.identity
+            ? {
+                ...current.identity,
+                delivery_capabilities: updated.installation.delivery_capabilities,
+            }
+            : current.identity,
+        runtime: {
+            ...current.runtime,
+            updated_at: new Date().toISOString(),
+        },
+    }));
+    return ok({
+        ok: true,
+        ...updated,
+    });
+}
+async function handleEndpointsList() {
+    const { gateway } = await createAuthorizedClients();
+    const out = await gateway.listEndpoints();
+    return ok(out);
+}
+async function handleEndpointsUpsert(args) {
+    const { gateway } = await createAuthorizedClients();
+    const endpoints = normalizeAgentEndpointList(args.endpoints);
+    const out = await gateway.upsertEndpoints({ endpoints });
+    return ok({
+        ok: true,
+        ...out,
+    });
+}
+async function handleSubscriptionsList() {
+    const { gateway } = await createAuthorizedClients();
+    const out = await gateway.listSubscriptions();
+    return ok(out);
+}
+async function handleSubscriptionsUpsert(args) {
+    const { gateway } = await createAuthorizedClients();
+    const subscriptions = normalizeAgentSubscriptionList(args.subscriptions);
+    const out = await gateway.upsertSubscriptions({ subscriptions });
+    return ok({
+        ok: true,
+        ...out,
+    });
+}
+async function handleTestDelivery(args) {
+    const { gateway } = await createAuthorizedClients();
+    const topic = normalizeText(args.topic);
+    const profile = normalizeText(args.profile);
+    const out = await gateway.testDelivery({
+        topic: topic ? topic : undefined,
+        text: normalizeText(args.text) || undefined,
+        payload: isPlainObject(args.payload) ? args.payload : undefined,
+        profile: profile ? profile : undefined,
+    });
+    return ok(out);
+}
+function resolveAfterSeq(args, state) {
+    if (typeof args.after_seq === 'number' && Number.isFinite(args.after_seq)) {
+        return Math.max(0, Math.floor(args.after_seq));
+    }
+    if (args.use_persisted_cursor === false)
+        return 0;
+    return Math.max(0, Math.floor(state.runtime.last_consumed_stream_seq || 0));
+}
+async function handleEventsClaim(args) {
+    const { gateway, state } = await createAuthorizedClients();
+    const request = {
+        after_seq: resolveAfterSeq(args, state),
+        limit: typeof args.limit === 'number' ? Math.max(1, Math.floor(args.limit)) : undefined,
+        claim_lease_id: normalizeText(args.claim_lease_id) || state.runtime.last_claim_lease_id || undefined,
+    };
+    const claimed = await gateway.claimEvents(request);
+    await persistState((current) => ({
+        ...current,
+        runtime: {
+            ...current.runtime,
+            last_claim_lease_id: claimed.claim_lease_id,
+            updated_at: new Date().toISOString(),
+        },
+    }));
+    return ok({
+        after_seq: request.after_seq ?? 0,
+        ...claimed,
+    });
+}
+async function handleEventFetch(args) {
+    const { gateway } = await createAuthorizedClients();
+    const out = await gateway.fetchEvent(normalizeText(args.event_id));
+    return ok(out);
+}
+async function handleEventsAck(args) {
+    const { gateway, state } = await createAuthorizedClients();
+    const body = {
+        acks: Array.isArray(args.acks)
+            ? args.acks.map((entry) => {
+                const row = normalizeRecord(entry);
+                return {
+                    event_id: normalizeText(row.event_id),
+                    status: normalizeText(row.status),
+                    last_error: normalizeText(row.last_error) || undefined,
+                    result: isPlainObject(row.result) ? row.result : undefined,
+                    retry_after_ms: typeof row.retry_after_ms === 'number' ? Math.floor(row.retry_after_ms) : undefined,
+                };
+            })
+            : [],
+    };
+    const acked = await gateway.ackEvents(body);
+    const ackStatusById = new Map(body.acks.map((entry) => [entry.event_id, entry.status]));
+    const nextCursor = acked.items.reduce((max, item) => {
+        return ackStatusById.get(item.event_id) === 'consumed'
+            ? Math.max(max, Number(item.stream_seq || 0))
+            : max;
+    }, Number(state.runtime.last_consumed_stream_seq || 0));
+    await persistState((current) => ({
+        ...current,
+        runtime: {
+            ...current.runtime,
+            last_consumed_stream_seq: nextCursor,
+            updated_at: new Date().toISOString(),
+        },
+    }));
+    return ok({
+        next_consumed_cursor: nextCursor,
+        ...acked,
+    });
+}
+async function handleEventsWait(args) {
+    const timeoutMs = typeof args.timeout_ms === 'number' ? Math.max(0, Math.floor(args.timeout_ms)) : 30_000;
+    const pollIntervalMs = typeof args.poll_interval_ms === 'number' ? Math.max(250, Math.floor(args.poll_interval_ms)) : 1_500;
+    const startedAt = Date.now();
+    while (Date.now() - startedAt <= timeoutMs) {
+        const claimed = await handleEventsClaim(args);
+        const structured = claimed.structuredContent;
+        if (isPlainObject(structured) && Array.isArray(structured.items) && structured.items.length > 0) {
+            return claimed;
+        }
+        if (Date.now() - startedAt >= timeoutMs)
+            break;
+        await sleep(pollIntervalMs);
+    }
+    return ok({
+        ok: true,
+        items: [],
+        timeout_ms: timeoutMs,
+        waited_ms: Date.now() - startedAt,
+    });
+}
+async function handleCapabilityTool(name, args) {
+    const { platform } = await createAuthorizedClients();
+    const capabilities = await loadCapabilities();
+    const capability = capabilities.find((item) => item.tool_name === name);
+    if (!capability)
+        return fail('unknown_hi_capability_tool', { name });
+    const out = await platform.callCapability(capability.capability_id, args);
+    return ok({
+        ok: true,
+        capability_id: capability.capability_id,
+        tool_name: capability.tool_name,
+        result: out.result,
+    }, jsonText(out));
+}
+async function handleControlTool(name, args) {
+    switch (name) {
+        case 'hi_agent_status':
+            return await handleStatus(args);
+        case 'hi_agent_register':
+            return await handleRegister(args);
+        case 'hi_agent_connect':
+            return await handleConnect(args);
+        case 'hi_agent_activate':
+            return await handleActivate(args);
+        case 'hi_agent_installation_get':
+            return await handleInstallationGet();
+        case 'hi_agent_installation_update':
+            return await handleInstallationUpdate(args);
+        case 'hi_agent_endpoints_list':
+            return await handleEndpointsList();
+        case 'hi_agent_endpoints_upsert':
+            return await handleEndpointsUpsert(args);
+        case 'hi_agent_subscriptions_list':
+            return await handleSubscriptionsList();
+        case 'hi_agent_subscriptions_upsert':
+            return await handleSubscriptionsUpsert(args);
+        case 'hi_agent_test_delivery':
+            return await handleTestDelivery(args);
+        case 'hi_agent_events_claim':
+            return await handleEventsClaim(args);
+        case 'hi_agent_event_fetch':
+            return await handleEventFetch(args);
+        case 'hi_agent_events_ack':
+            return await handleEventsAck(args);
+        case 'hi_agent_events_wait':
+            return await handleEventsWait(args);
+        default:
+            return fail('unknown_control_tool', { name });
+    }
+}
+async function listTools() {
+    const capabilities = await loadCapabilities();
+    return [
+        ...controlTools(),
+        ...capabilities.map((capability) => ({
+            name: capability.tool_name,
+            title: capability.title || capability.tool_name,
+            description: capability.description || capability.tool_name,
+            // 这里直接复用 Hi public capability schema，确保 MCP 宿主看到的参数语义与平台目录完全一致。
+            inputSchema: isPlainObject(capability.parameters)
+                ? capability.parameters
+                : { type: 'object', properties: {} },
+        })),
+    ];
+}
+function createMcpServer() {
+    const server = new Server({
+        name: 'hi-mcp-server',
+        version: '0.1.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+        instructions: 'Hi MCP adapter: control-plane tools stay in gateway, business tools mirror Hi public capabilities exactly.',
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: await listTools(),
+        };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const name = normalizeText(request.params.name);
+        const args = normalizeRecord(request.params.arguments);
+        try {
+            const controlToolNames = new Set(controlTools().map((tool) => tool.name));
+            return controlToolNames.has(name)
+                ? await handleControlTool(name, args)
+                : await handleCapabilityTool(name, args);
+        }
+        catch (error) {
+            return fail(normalizeText(error?.message) || 'tool_call_failed', isPlainObject(error?.detail) ? error.detail : { message: String(error?.message || error || 'unknown_error') });
+        }
+    });
+    return server;
+}
+async function runHttpServer() {
+    const app = createMcpExpressApp({ host: config.host });
+    app.get('/healthz', (_req, res) => {
+        res.json({
+            ok: true,
+            profile: config.profile,
+            transport: config.transport,
+        });
+    });
+    // readiness 必须确认上游 discovery 可达；否则 pod 虽然活着，但实际上没法服务真实 MCP 请求。
+    app.get('/readyz', async (_req, res) => {
+        try {
+            const wellKnown = await loadWellKnown();
+            res.json({
+                ok: true,
+                profile: config.profile,
+                transport: config.transport,
+                registry_base_url: wellKnown.platform.registry_base_url,
+            });
+        }
+        catch (error) {
+            res.status(503).json({
+                ok: false,
+                error: normalizeText(error?.message) || 'ready_check_failed',
+            });
+        }
+    });
+    app.post('/mcp', async (req, res) => {
+        const server = createMcpServer();
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+            res.on('close', () => {
+                void transport.close().catch(() => undefined);
+                void server.close().catch(() => undefined);
+            });
+        }
+        catch (error) {
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32603,
+                        message: normalizeText(error?.message) || 'internal_server_error',
+                    },
+                    id: null,
+                });
+            }
+        }
+    });
+    app.get('/mcp', (_req, res) => {
+        res.status(405).json({
+            jsonrpc: '2.0',
+            error: {
+                code: -32000,
+                message: 'Method not allowed.',
+            },
+            id: null,
+        });
+    });
+    app.delete('/mcp', (_req, res) => {
+        res.status(405).json({
+            jsonrpc: '2.0',
+            error: {
+                code: -32000,
+                message: 'Method not allowed.',
+            },
+            id: null,
+        });
+    });
+    const httpServer = createServer(app);
+    await new Promise((resolve) => {
+        httpServer.listen(config.port, config.host, () => resolve());
+    });
+    const shutdown = async () => {
+        await new Promise((resolve) => {
+            httpServer.close(() => resolve());
+        });
+        process.exit(0);
+    };
+    process.on('SIGINT', () => {
+        void shutdown();
+    });
+    process.on('SIGTERM', () => {
+        void shutdown();
+    });
+    console.log(`hi-mcp-server listening on http://${config.host}:${config.port}/mcp`);
+}
+async function runStdioServer() {
+    const server = createMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.on('SIGINT', () => {
+        void server.close().catch(() => undefined);
+    });
+    process.on('SIGTERM', () => {
+        void server.close().catch(() => undefined);
+    });
+}
+async function main() {
+    assertConfig();
+    if (config.transport === 'stdio') {
+        await runStdioServer();
+        return;
+    }
+    await runHttpServer();
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/state.d.ts

@@ -0,0 +1,51 @@
+export type HiAgentIdentityState = {
+    agent_id: string;
+    installation_id: string;
+    display_name: string;
+    agent_kind: string;
+    client_id: string;
+    client_secret: string;
+    installation_subject: string;
+    issuer: string;
+    audience: string;
+    token_url: string;
+    jwks_url: string;
+    activated_at: string | null;
+    delivery_capabilities: Record<string, unknown> | null;
+};
+export type HiAgentPlatformState = {
+    platform_base_url: string;
+    registry_base_url: string;
+    fetched_at: string;
+};
+export type HiAgentRuntimeState = {
+    last_consumed_stream_seq: number;
+    last_claim_lease_id: string | null;
+    updated_at: string | null;
+};
+export type HiAgentPersistedState = {
+    profile: string;
+    platform: HiAgentPlatformState | null;
+    identity: HiAgentIdentityState | null;
+    runtime: HiAgentRuntimeState;
+};
+export declare function buildDefaultState(profile: string): HiAgentPersistedState;
+export declare function resolveStateFile(args: {
+    stateDir: string;
+    profile: string;
+}): string;
+export declare function readState(args: {
+    stateDir: string;
+    profile: string;
+}): Promise<HiAgentPersistedState>;
+export declare function writeState(args: {
+    stateDir: string;
+    profile: string;
+    state: HiAgentPersistedState;
+}): Promise<void>;
+export declare function updateState(args: {
+    stateDir: string;
+    profile: string;
+    updater: (current: HiAgentPersistedState) => HiAgentPersistedState;
+}): Promise<HiAgentPersistedState>;
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACvD,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,wBAAwB,EAAE,MAAM,CAAC;IACjC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACtC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACtC,OAAO,EAAE,mBAAmB,CAAC;CAC9B,CAAC;AAQF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,CAOxE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,UAG3E;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAmBjC;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,qBAAqB,CAAC;CAC9B,iBAIA;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,qBAAqB,CAAC;CACpE,kCASA"}

package/dist/state.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const EMPTY_RUNTIME_STATE = {
+    last_consumed_stream_seq: 0,
+    last_claim_lease_id: null,
+    updated_at: null,
+};
+export function buildDefaultState(profile) {
+    return {
+        profile,
+        platform: null,
+        identity: null,
+        runtime: { ...EMPTY_RUNTIME_STATE },
+    };
+}
+export function resolveStateFile(args) {
+    // state 文件默认按 profile 分片，方便同一台机器上挂多个宿主 installation。
+    return path.join(args.stateDir, `${args.profile}.json`);
+}
+export async function readState(args) {
+    const filePath = resolveStateFile(args);
+    try {
+        const raw = await fs.readFile(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return {
+            profile: typeof parsed.profile === 'string' && parsed.profile.trim() ? parsed.profile : args.profile,
+            platform: parsed.platform ?? null,
+            identity: parsed.identity ?? null,
+            runtime: {
+                last_consumed_stream_seq: Number(parsed.runtime?.last_consumed_stream_seq || 0),
+                last_claim_lease_id: parsed.runtime?.last_claim_lease_id ?? null,
+                updated_at: parsed.runtime?.updated_at ?? null,
+            },
+        };
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return buildDefaultState(args.profile);
+        throw error;
+    }
+}
+export async function writeState(args) {
+    const filePath = resolveStateFile(args);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, `${JSON.stringify(args.state, null, 2)}\n`, 'utf8');
+}
+export async function updateState(args) {
+    const current = await readState(args);
+    const next = args.updater(current);
+    await writeState({
+        stateDir: args.stateDir,
+        profile: args.profile,
+        state: next,
+    });
+    return next;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@hirey/hi-mcp-server",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "main": "dist/server.js",
+  "types": "dist/server.d.ts",
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "bin": {
+    "hi-mcp-server": "dist/server.js"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "dev": "tsx watch src/server.ts",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "start": "node dist/server.js",
+    "test": "tsx --test src/**/*.test.ts",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@hirey/hi-agent-contracts": "^0.1.8",
+    "@hirey/hi-agent-sdk": "^0.1.4",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "express": "^5.2.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^20.19.37",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}