tool-bridge 文档
tool-bridge 是 HTBP（HTTP ToolBridge Protocol） 的参考实现。它把 MCP Server、HTTP API、对象存储、本地机器和其他网关投影到一棵带权限、自描述的 HTTP 树上。
Agent 或客户端只需要一个 BaseURL 和一把限定了路径与动作的 Secret Key（SK），就能发现当前身份可见的能力、读取参数契约并发起调用。它不要求调用方安装专用 SDK，也不要求一定运行 MCP Client。
你可以用它做什么
Section titled “你可以用它做什么”| 目标 | tool-bridge 提供的能力 | 从哪里开始 |
|---|---|---|
| 统一接入工具 | 挂载 MCP、声明式 HTTP、内置集成与外部 Plugin | 使用内置集成或挂载 MCP Server |
| 管理上下文 | 以统一 Context 接口访问 R2、S3 或本地对象 | 挂载 Context 对象存储 |
| 接入内网机器 | 由本机主动建立 WebSocket，按白名单暴露 shell、文件或 SDK 工具 | 接入本地设备与服务 |
| 跨团队组合能力 | 把另一套 HTBP 服务挂成本地子树，同时隔离两侧身份 | 联邦另一棵 tool-bridge |
| 给现有 MCP Client 使用 | 通过 /<base>/~mcp 投影当前 SK 可见的工具 |
运行时 HTTP 契约速查 |
| 沉淀使用经验 | 在具体路径上提交 Feedback，让高分经验进入帮助和搜索 | 搜索、反馈与注解 |
如果你还没有运行中的网关，建议按下面的顺序完成第一个闭环：
- 用5 分钟本地启动运行 Node/Docker 网关；
- 阅读从
~help到调用，理解为什么客户端应先发现再调用； - 按权限、SK 与可见性签发第一把受限 SK；
- 选择一个真实来源，挂载内置集成、MCP Server或HTTP API；
- 分别用 Admin SK 和受限 SK 读取
~help，确认受限身份只能看到和调用被授权的子树。
成功的标志不是“容器已经启动”，而是你已经完成一次真实能力调用，并证明最小权限身份看不到无权路径。
选择部署方式
Section titled “选择部署方式”| 方式 | 状态与运行时 | 适合场景 | 主要取舍 |
|---|---|---|---|
| Node / Docker | SQLite、本地对象存储、Node WebSocket | 自托管、内网、快速验证 | 需要自己维护主机、TLS、卷与备份；状态强一致 |
| Cloudflare 一键模板 | KV、R2、Durable Objects、Static Assets | 最少步骤部署边缘网关 | 模板不含 D1 Search；需要理解 Workers KV 的最终一致窗口 |
| Cloudflare 源码部署 | KV、R2、D1、Durable Objects、Static Assets | 需要完整 gateway、Search 或定制源码 | 要维护源码 checkout 与 Cloudflare 资源配置 |
| 嵌入式 SDK | 由应用注入 StateStore、ObjectStore 与本地 Provider | 把 tool-bridge 嵌入现有 Node 22+ 应用 | 存储、部署与生命周期由宿主负责 |
不确定时先读选择你的使用路径。准备长期运行前，无论选择哪种宿主，都应完成生产上线检查清单。
核心心智模型
Section titled “核心心智模型”tool-bridge 同时解决四件事：
- 发现：节点级
~help列出当前身份可用的工具，工具级~help再披露完整参数； - 调用：HTTP、CLI、Dashboard 与 MCP 投影访问同一棵树；
- 治理：SK 按路径与动作授权，deny 优先，无权路径对调用者表现为不存在；
- 协作：Feedback 与注解附着在路径上，远端网关可以安全联邦为子树。
深入阅读：
文档与运行时如何分工
Section titled “文档与运行时如何分工”本站解释稳定的产品模型、操作方法、部署选项和安全边界，但不会复制某个实例动态生成的完整工具目录。
下面这些内容必须从目标实例读取：
| 动态事实 | 当前真源 |
|---|---|
| 当前 SK 能看见哪些路径 | GET /<path>/~tree 或 tb tree |
| 某个节点有哪些工具 | GET /<node>/~help；工具 Provider 在这里返回索引 |
| 单个工具的完整输入/输出 schema | GET /<node>/<tool>/~help，并请求 Accept: application/json |
| Search 或 Context 的可选 capability | GET /~describe 或 GET /<context>/~describe；未装配可选 capability 时可能返回 404 |
| 当前 catalog 的 provider 与 export | system/catalog 的运行时命令，或 tb integration catalog |
| 当前 CLI 参数与互斥关系 | tb <command> --help |
发生差异时，按以下顺序判断：
- 目标实例在当前身份下返回的
~tree、~help、~describe与 JSON Schema； - 对应版本的源代码与发布说明；
- 本站教程和示例。
CLI 的精确参数、默认值和互斥关系以你当前安装版本的 tb --help 与 tb <command> --help 为准。
先确认 /healthz 与带 SK 的 /~help 是两项不同检查：健康检查成功不代表认证数据面一定可用。然后进入故障排查与升级，按状态码、宿主和 Provider 收集脱敏证据。