BailingHub MCP Server

0.6.0：长任务、附件与原调用恢复

连续查询、编辑和核对时保留正确目标；上传获准图片后复用URL，重开后核对原调用，任务额度不因换轮重置。配套 Core 0.8.0 / SDK 0.6.0 / DSH 0.6.0；任务启用和跨轮复用需宿主按契约接入。

本次变化 · 升级指南

English | 简体中文

让兼容 MCP 的本地或桌面智能体，通过自然语言查询和操作已经接入 BailingHub 的商城、SaaS、CRM、ERP 或其他业务后台。

具体能做什么，取决于业务系统主动声明的能力，以及管理员为当前连接放行的路由。例如：

• 找出库存低于 10 件的商品，并生成补货建议；
• 修改员工或客户资料；
• 发起订单退款，并在路由要求时等待人工审批。

智能体不会拿到管理员凭据或业务系统凭据。BailingHub 保留路由边界、审批状态、执行记录 和审计轨迹，最终能否执行仍由业务系统按照当前登录身份和自身规则决定。

0.5.0 带来什么：一个会话连接商城与库存

例如，用户说：“先查保温杯库存，有货再把商城对应商品改为 59 元并上架。”SDK 为宿主提供同一中枢下不同系统的原目标校验、首次工具搜索前的系统说明，以及业务后端提供的授权名称。相关业务能力和商品映射需已准备，原审批继续生效。

这些增量配套 Core 0.8.0 + SDK 0.6.0 及兼容宿主，范围限同一中枢、同一管理审计域。宿主负责显式选择和持久化会话范围；独立 MCP Server 不会自动新增多系统选择界面。

看具体变化和升级步骤

0.4.0 引入的对话归档

支持归档的 Agent 客户端可以把“用户提出了什么、助手如何回复、最后执行了哪些业务动作” 连成一条可查看的记录。例如，在一段对话里比较两家已经分别授权的门店，管理员既能看到 整段可见对话，也能追溯每家门店各自的执行记录。推荐配合 BailingHub Core 0.7.0， 以及负责记录和同步对话的客户端使用；归档接口最低需要 Core 0.6.0。

0.4.0 引入了对话同步接口。SDK 本身不会自动记录聊天；账号选择和会话界面由 DSH 插件等原生客户端负责。 独立 MCP Server 的工具入口保持兼容。

谁该升级，如何开始

| 你的使用方式 | 下一步 | | --- | --- | | 在 MCP 应用里连接一条固定业务路由 | 按下方安装说明使用 0.5.0。原 Client Token 和 Agent Session 用法继续兼容。 | | 使用 DSH 等原生 Agent 客户端 | 按客户端配套版本升级，并按其指南选择会话可用账号。单独安装这个 MCP 命令不会增加多账号会话界面。 | | 开发自己的 Agent 客户端 | 安装 [email protected]，完整新能力配合 Core 0.7.0，再按 SDK 指南接入。 |

升级此 SDK 不需要修改业务 API 声明。原有读写、审批和调用恢复规则继续生效。 对话补传沿用原事件 ID，不会重新执行业务动作；聚合归档仅供当前部署有权限的管理员读取， 不上传隐藏推理。

它是一个独立、轻量的生态适配器，不内嵌 BailingHub，不授予业务权限，也不替代 业务系统的最终授权。它同时保留原有 Client Token 模式，并新增 Agent Session 模式：用户通过系统浏览器授权当前本地智能体。

暴露的工具

| 工具 | 用途 | | --- | --- | | submit_governed_job | 把不可信任务文本提交到管理员固定的 BailingHub route | | get_governed_job | 查询当前 Client 所拥有任务的公开状态 | | wait_for_governed_job | 最多等待 60 秒，不会重新提交业务操作 |

Agent Session MCP 路径初始只暴露 5 个小型元工具，用于启动本轮、搜索能力、 受治理调用/恢复以及同步可见结果。BailingHub 每轮最多返回 12 个 active tools， 新集合会替换旧集合，不会在上下文中无限累加。

宿主开发者应使用宿主无关的 Agent Client SDK 指南。

BailingHub 地址、凭据和 route 都是本地进程配置，不能由模型作为 MCP 工具参数提供。 SDK 宿主可以公开同一系统内固定的可用授权引用，供模型按次选择；宿主将引用解析为创建时捕获的 连接，并继续掌握连接管理。参见授权引用接入指南。

认证模式

• **Agent Session：**先执行一次 bailinghub-mcp-server login。CLI 使用随机回环端口和 PKCE，打开系统浏览器，并把已批准会话保存到各平台对应的安全凭据存储。MCP 工具改用 /agent-api/v1/*，并在本地安全轮换 refresh token。
• **Client Token（保持兼容）：**存在 BAILINGHUB_CLIENT_TOKEN 时，仍按原样调用 POST /run 和 GET /jobs/{job_id}。

两种模式都不允许模型提供凭据、route、行动主体或审批结论。Agent Session 只承载由 Hub/业务授权边界确认的身份，业务系统仍负责最终权限判断。

MCP Registry 的 server.json 只描述兼容的独立 stdio/Client Token 安装入口，因此该入口仍会 把 BAILINGHUB_CLIENT_TOKEN 标为必填。原生 DSH 插件不读取这份 Registry 配置；它把本包的 /sdk 子路径作为普通库依赖，并通过浏览器建立 Agent Session。不要根据 Registry 表单给 DSH 插件增加 Client Token 字段。

安全边界

MCP Host / 模型
    |
    | request_id + 不可信任务文本
    v
BailingHub MCP Server
    |
    | 固定 route + Client Token 或已授权 Agent Session
    v
BailingHub
    |
    | 受治理调度
    v
业务系统
    |
    +-- 解析可信主体并执行最终授权

首版有意不接受：

• 行动主体或身份声明；
• Client Token、管理员 Token、业务系统密钥；
• 审批结论或审批证据；
• 执行器身份；
• 任意 metadata 或 callback URL；
• 任意 route。

在兼容的 Client Token 模式中，每个 MCP Server 进程只绑定一个 route，并使用仅允许该 route 的专用 Client Token。不同 MCP 客户端需要不同边界时，应分别启动实例。

安装

前置条件：

• Node.js 20.15 或更高版本；
• 一套 MCP Host 可以访问的 BailingHub；
• 一个仅允许目标 route 的 BailingHub Client Token，或一个能被批准使用该 route 的 已注册公共 Agent 客户端。

旧版静态任务模式在 MCP Host 中这样配置：

{
  "mcpServers": {
    "bailinghub": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "BAILINGHUB_BASE_URL": "https://hub.example.com",
        "BAILINGHUB_CLIENT_TOKEN": "替换为仅允许指定-route-的-client-token",
        "BAILINGHUB_ROUTE": "order_assistant"
      }
    }
  }
}

Agent Session 登录

启动不携带 Client Token 的 MCP Host 前，先为已注册的公共 Agent 客户端和一条固定 route 完成授权：

npm install --global [email protected]

bailinghub-mcp-server login \
  --base-url https://hub.example.com \
  --client-app-id merchant-agent \
  --route order-assistant

bailinghub-mcp-server status
bailinghub-mcp-server logout

登录回调只监听 127.0.0.1 的随机端口，并同时校验 state 与 PKCE S256。access token 和 refresh token 不会出现在 CLI 输出中。macOS 使用 Keychain；Linux 与其他 POSIX 平台 目前只在显式设置 BAILINGHUB_ALLOW_FILE_CREDENTIAL_STORE=true 后才允许使用文件回退， 且文件必须属于当前用户并为 0600 权限。Windows 使用当前用户范围的 DPAPI 加密文件， 密文保存于该用户的 LocalAppData 目录；Windows PowerShell 或 DPAPI 不可用时失败关闭， 不会自动降级为明文。所有受支持平台仍可使用兼容的 Client Token 模式。

本机回环地址允许 HTTP。非回环 HTTP 默认拒绝；只有在 TLS 已由可信私有网络的其他边界 终止时，才可显式设置 BAILINGHUB_ALLOW_INSECURE_HTTP=true。

正确调用顺序

1. 为一项业务请求生成稳定的 request_id；
2. 使用该 ID 和任务文本调用 submit_governed_job；
3. 保存返回的 job_id；
4. 短时调用 wait_for_governed_job，或稍后调用 get_governed_job；
5. 重试同一业务请求时，复用完全相同的 request_id 和任务含义。

queued、running 和 dispatched 是非终态；done、error 和 rejected 是终态。

等待超时不等于任务失败，也不能因此重新提交一份替代任务。

首次成功与反馈

以官网 MCP 接入路径作为统一起点。 首次接入成功应同时满足：

1. MCP Host 只能通过管理员固定的 route 提交任务；
2. 同一个 job_id 到达终态；
3. BailingHub 保留审批与审计状态；
4. MCP Host 从未获得管理员凭据或业务系统凭据。

请通过 BailingHub 独立验证表单 提交 PASS、部分通过或失败结果，并选择 MCP 路径。不得提交 Token、模型密钥、个人信息或 生产业务数据。

项目边界

依赖方向是单向的：

bailinghub-mcp-server -> BailingHub 公共 Client API / Agent API
BailingHub 可以消费 ACC 声明
ACC 不依赖任何一个实现项目

进一步阅读：

• 项目边界
• 威胁模型
• 兼容性契约
• Agent Client SDK
• 隐私说明
• 安全策略

开发

npm install
npm run verify
npm pack --dry-run

Client Token 模式仅消费 bailing.client-api.v1 的 POST /run 与 GET /jobs/{job_id}。 Agent Session 模式另外消费增量的 Agent Auth v1 与 Agent API v1：

• POST /agent-auth/v1/authorizations
• POST /agent-auth/v1/token
• GET /agent-auth/v1/session
• POST /agent-auth/v1/revoke
• GET /agent-api/v1/workspaces
• GET /agent-api/v1/workspaces/{route}/bootstrap
• POST /agent-api/v1/workspaces/{route}/turns
• POST /agent-api/v1/workspaces/{route}/capabilities/search
• POST /agent-api/v1/tool-invocations
• POST /agent-api/v1/tool-invocations/{invocation_id}/resume
• POST /agent-api/v1/runs/{run_id}/complete

宿主 SDK 另外使用从 Core 0.6.0 开始提供的对话归档写入接口，跨系统模式、系统说明和授权名称配套 Core 0.7.0。 这些接口不作为 MCP 或模型工具开放：

• POST /agent-api/v1/conversation-audits
• POST /agent-api/v1/conversation-audits/{conversation_id}/confirm
• POST /agent-api/v1/conversation-audits/{conversation_id}/events

bailinghub-mcp-server/sdk 子路径暴露宿主无关的 Agent Client factory。它统一负责浏览器授权、 本机具名选择器、隔离凭据、Token 刷新和 Core DTO 映射。在相同 Hub/client/workspace 公开绑定下， 只有 Core 返回的可信 on_behalf_of 相同时才替换旧本机连接，不同业务身份仍可独立选择。业务授权 入口由 Core 解析，因此 DSH 等宿主既不填写业务 URL，也不保存凭据或拼装 BailingHub HTTP 路径。

本适配器仍不调用管理员、执行器、审批决策、Tool Proxy、配置或业务系统直接接口。