HTTP TOOLBRIDGE PROTOCOL

让 Agent 通过一棵树，发现并调用所有工具。

tool-bridge 把工具、上下文、设备与远端服务投影成受权限约束、运行时自描述的 HTTP 树。调用方只需要一个 BaseURL 和一把 scoped Secret Key。

5 分钟快速开始 →理解产品模型 ↗

/toolbridge.example

tools/3 nodes visible

github/issues.createcall · JSON Schema

ctx/briefs/read · search

2 paths omittedoutside current scope

runtime helpGET /tools/github/issues.create/~help

tools/github/issues.create

Create an issue in a visible repository.

title: string · required
body: string
labels: string[]

projected toHTTPCLIMCP

011 BaseURL

整个能力面的统一入口

02Identity-scoped

每个调用者只看见被授权的树

03HTTP · CLI · MCP

同一节点语义，投影到多个入口

01 / SEE IT WORK

一次连接，完成发现、理解与调用。

不先下载静态工具清单。调用者从运行中的实例读取当前身份真正可见的树、文档和 schema，再沿同一路径发起调用。

agent@tool-bridgescoped session

$tb tree --depth 2

/
├── tools/
│   ├── github/
│   └── linear/
├── ctx/
│   └── briefs/
└── system/
    └── status

scope applied 不可见路径不会进入结果。

$tb help tools/github/issues.create --json

# tools/github/issues.create

Create an issue in a visible repository.

title *string

bodystring

labelsstring[]

runtime truth Markdown、Help DSL 与 JSON 来自同一实例。

$tb call system/status --tool get

caller→policy: call→system/status

{
  "status": "ok",
  "host": "cloudflare"
}

200 · allowed 本地 SK 不会被透传给上游。

02 / ONE MENTAL MODEL

路径不只是地址，也是组织、发现与授权边界。

不同 provider 保留自己的实现方式，对调用者却呈现为同一棵树。节点描述能力，路径建立上下文，scope 决定可见性。

BASE URLtoolbridge.example

+ scoped SK

↗

tools/

MCP · HTTP · Plugin

≡

ctx/

R2 · S3 · Skillhub

⌁

device/

Local tools · Files

∞

teams/

Federated remotes

PROJECT

HHTTPdirect / envelope

CCLItb commands

DDashboardsame API

MMCP/~mcp

DISCOVER~help、~tree与可选的 ~describe、~search都经过身份裁剪。

CALL 直接调用或 {tool, arguments} 信封共享同一权限判断。

FEDERATE remote 子树使用自己的凭证，不转发本地调用者 SK。

03 / BUILT INTO THE TREE

不是另一层 API 包装，而是一套完整能力模型。

文档、权限、密钥、搜索和联邦都有清晰 ownership。它们共同工作，但不会把状态和凭证混进同一个注册表。

RUNTIME TRUTH

契约来自正在运行的实例。

~help 根据路径和身份生成 Markdown、Help DSL 或 JSON；公共文档解释模型，不冒充实例状态。

理解运行时发现 →

MarkdownHelp JSON

# tools/github

Available tools
  create  Create an issue
  list    List visible issues

SCOPED ACCESS

不可见，就像不存在。

read、write、call、register、admin 按路径授权；deny 永远优先。

阅读权限模型 →

PROVIDERS

一个协议，多种能力来源。

查看集成目录 →

FEDERATION

把另一棵树挂进来，不交出本地身份。

理解联邦边界 →

VISIBLE SEARCH

只搜索当前身份有权看见的结果。

搜索与协作 →

IN-CONTEXT FEEDBACK

把使用经验留在它真正发生的路径。

“创建前先检查同名 issue。” +12

了解反馈投影 →

04 / SECURITY IS STRUCTURAL

权限和密钥不是附加层，而是树模型的一部分。

每次发现与调用都带着身份进入同一条路径。配置可以被管理，密钥值留在 SecretStore；上游和 remote 使用自己的引用身份。

阅读安全边界 →

PATHACTIONRULERESULT

tools/github/issuescall allow200

tools/github/adminread deny404

device/macbookregister no scope404

Denied paths do not reveal whether the node exists.

Deny wins

allow 与 deny 同时匹配时，deny 永远优先。

Secrets by reference

节点保存 authRef，不回显真实凭证。

Isolated outbound identity

调用者 SK 不会被透传给 provider 或 remote。

05 / RUN IT YOUR WAY

同一应用语义，适配不同运行边界。

Cloudflare、Node 和 Embedded SDK 共享 app/core 契约；每个宿主只负责自己的存储、连接与部署方式。

EDGE NATIVE

把控制面放到离调用者更近的位置。

使用 KV、R2、D1 与 Durable Objects 装配同一个应用语义。向导创建资源、注入密钥并完成首次验证。

适合: 全球入口、Serverless 运维、设备长连接
状态: KV · R2 · D1 · Durable Objects

Cloudflare CLI 部署指南 →

terminal

$ tb init cloudflare --repo .

provision resources
configure secrets
deploy & verify

SELF HOSTED

在自己的网络与存储边界里运行。

Node 宿主装配 SQLite、文件对象存储与 WebSocket；Docker 提供最短的可复现运行路径。

适合: 内网工具、固定基础设施、完整数据控制
状态: SQLite · Files · WebSocket

Node / Docker 部署指南 →

terminal

$ docker compose up -d

persist TB_DATA_DIR
preserve WebSocket upgrade
keep Admin SK private

HOST INJECTED

把工具树嵌入你已经拥有的应用。

由宿主注入 StateStore、ObjectStore、SecretStore 与本地 provider，同时复用完整协议语义。

适合: 产品内嵌、定制 provider、已有身份系统
边界: 存储与运行时适配器由宿主拥有

Embedded SDK 指南 →

TypeScript

import { createToolBridge }
  from '@tool-bridge/sdk'

inject stores
mount providers
expose your own transport

06 / DOCUMENTATION

按你的下一步进入文档。

从第一次运行到生产安全边界，每条路径都给出模型、命令、验收和下一步。

浏览全部 24 篇文档 →

开始使用

从本地运行到第一次发现和调用。

理解系统

掌握工具树、运行时发现和安全边界。

连接与部署

接入已有 provider，并把实例带到生产。

READY TO CONNECT?

从第一个可见节点开始。

本地启动一个实例，读取它的树，然后完成第一次受控调用。

打开快速开始 →查看 GitHub ↗