# BailingHub MCP Server

## 0.8.0：完整工具输入与知识按需读取

提交完整页面内容时不再受适配器的小参数限制；只读取相关业务指导，并把模型默认预算与服务上限分开。配套 Core 0.10.0 / SDK 0.8.0 / DSH 0.8.0。原授权、审批和原操作恢复保持；任务自动续跑由宿主实现。

[本次变化](docs/RELEASE_NOTES_v0.8.0.md) · [升级指南](docs/UPGRADE_v0.8.0.md)

[English](README.md) | 简体中文

让兼容 MCP 的本地或桌面智能体，通过自然语言查询和操作已经接入
[BailingHub](https://www.bailinghub.com/) 的商城、SaaS、CRM、ERP 或其他业务后台。

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

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

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

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

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

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

[看具体变化和升级步骤](docs/RELEASE_NOTES_v0.5.0.md#简体中文)


## 0.4.0 引入的对话归档

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

0.4.0 引入了对话同步接口。SDK 本身不会自动记录聊天；账号选择和会话界面由
[DSH 插件等原生客户端](https://github.com/bailinghub/bailinghub-dsh-plugin)负责。
独立 MCP Server 的工具入口保持兼容。

## 谁该升级，如何开始

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

升级此 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 路径初始只暴露 7 个小型元工具，用于启动本轮、搜索能力及参考知识、按需读取知识、
受治理调用/恢复以及同步可见结果。BailingHub 每轮最多返回 12 个 active tools，
新集合会替换旧集合，不会在上下文中无限累加。

启动和搜索结果会透出 `description_truncated`、`usage_guidance_available`，提示短描述
是否省略了内容、是否有补充指导。开始本轮后，可向 `search_business_capabilities` 显式传入
`{"tool_name":"已载入的原始工具名","include_usage_guidance":true}`，只读取该工具的有界详情。
详情绑定当前运行、授权和能力修订，只是参考资料，不会调用业务工具；应保留返回的截断和大小信息。
旧客户端不支持详情时明确返回兼容性错误，普通搜索维持原有行为。

宿主开发者应使用[宿主无关的 Agent Client SDK 指南](docs/AGENT_CLIENT_SDK.zh-CN.md)。

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

## 认证模式

- **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 字段。

## 安全边界

```text
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 中这样配置：

```json
{
  "mcpServers": {
    "bailinghub": {
      "command": "npx",
      "args": ["-y", "bailinghub-mcp-server@0.8.0"],
      "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 完成授权：

```bash
npm install --global bailinghub-mcp-server@0.8.0

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 接入路径](https://www.bailinghub.com/integrations#mcp)作为统一起点。
首次接入成功应同时满足：

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

请通过 [BailingHub 独立验证表单](https://github.com/bailinghub/bailinghub/issues/new?template=independent_validation.yml)
提交 PASS、部分通过或失败结果，并选择 MCP 路径。不得提交 Token、模型密钥、个人信息或
生产业务数据。

## 项目边界

依赖方向是单向的：

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

进一步阅读：

- [项目边界](docs/PROJECT_BOUNDARIES.md)
- [威胁模型](docs/THREAT_MODEL.md)
- [兼容性契约](docs/COMPATIBILITY.md)
- [Agent Client SDK](docs/AGENT_CLIENT_SDK.zh-CN.md)
- [隐私说明](PRIVACY.md)
- [安全策略](SECURITY.md)

## 开发

```bash
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.8.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、配置或业务系统直接接口。