cloudburrow (Open Agents Inc)

云洞

_隧道是原始的——Cloudflare+MCP_

Cloudbureau在桌面“网桥”和启用MCP的客户端（例如移动应用程序或其他代理）之间实现安全的、每台设备的Cloudflare隧道连接。它侧重于单命令配对流，稳定 wss:// Cloudflare Worker上公开了端点和可选的MCP工具，用于可观察性和远程控制，无需与任何特定客户端耦合。

简单地说，以下是您现在可以做的事情：

• 将您的本地应用程序变成可公开访问的安全应用程序 wss:// URL。
• 让MCP服务器创建一个隧道，告诉你公共链接，检查它是否已连接，并在完成后撤销它。
• 从任何兼容MCP的客户端使用这些工具，而无需在聊天中暴露连接器令牌。

为什么重要

• 代理本机、设备到设备原语

- 如果网桥可以在没有每个设备的集中式帐户的情况下运行，隧道将成为代理形成按需设备到设备链接的可重用构建块。 MCP充当控制平面（创建/状态/撤销），而隧道是数据平面(wss://…/ws).

• 无每台设备的注册流程

- 运行桌面应用程序的人不需要创建隧道提供商帐户或共享凭据。一个Cloudflare帐户（您的）通过Worker为幕后的一切提供支持。

• 在Cloudflare的全球边缘运行

- 在您的区域上使用Cloudflare Tunnels+DNS，以获得稳定的一流主机名。没有不透明的URL，没有跨网络的NAT技巧。

• 通过MCP进行远程控制

- 直接从任何支持MCP的客户端（代理、应用程序、脚本）创建、检查和撤销隧道，而不会泄露秘密。令牌永远不会离开服务器。

• 命名隧道，而不是“快速”或瞬态链接

- 您可以获得可预测的主机名，并可以强制执行策略和清理，而不是临时的临时URL。

• 专为自动化而设计

- 可编写脚本 bun 以及JSON-RPC；易于嵌入工作流、CI或代理运行时。

我们正在建造什么

• 通过命名的Cloudflare隧道（无快速隧道）进行安全设备配对。
• 每台设备的一级主机名，如 wss://tunnel-.openagents.com/ws 为了桥。
• 适用于任何客户端的单命令用户体验：可选自动安装 cloudflared，向代理请求凭据，运行连接器，并打印配对QR/深度链接。
• 桌面网桥上的WebSocket令牌门控(/ws)以强制执行经过身份验证的连接。
• 托管在同一Worker上的可选MCP工具，用于管理聊天流中的隧道生命周期，而不会暴露连接器机密。

组件（普通语言）

• 工人（经纪人+MCP）

- 住在Cloudflare。控制平面可以创建命名隧道，告诉您公共主机名，检查状态并撤销它。 - 暴露两个接口：REST端点（用于桌面获取连接器令牌并运行 cloudflared)以及MCP工具（用于代理/应用程序在不查看机密的情况下驱动生命周期）。 - 保护您的Cloudflare API代币的安全；令牌永远不会出现在MCP响应中。

• 桥接器（桌面）

- 在您的机器上运行。它向Worker的REST API请求隧道令牌和主机名，然后启动 cloudflared 因此隧道指向您的本地应用程序（例如。， http://127.0.0.1:8787). - 结果是一个稳定的公共URL wss:///ws 这将转发到您的本地服务。 - 可以在 /ws 端点，因此只有授权的客户端才能连接。

• 客户端（代理/应用程序）

- 任何能说话的MCP。它要求Worker（通过MCP）创建隧道，显示/使用已宣布的 wss://…/ws 链接，检查状态，完成后撤销。 - 它从不处理隧道令牌；桌面网桥通过Worker的REST处理该问题。

当前状态

• 在线经纪人： https://cloudburrow-broker.openagents.com （绑定到Worker的自定义域）。
• 工作端点：

- POST /tunnels → 回报 { tunnelId, hostname, token } - GET /tunnels/:id/status - DELETE /tunnels/:id

• MCP端点 /mcp 使用工具启用： tunnel.create_named, tunnel.status, tunnel.revoke, tunnel.announce_link.
• 新生成的主机名的DNS传播通常在~5-10秒内完成。
• 可用的桌面助手： bun run tunnel 创建+运行连接器并打印公共文件 wss://…/ws URL。

MCP工具

• 简明语言概述

- “隧道”是Cloudflare从公共主机名创建到本地计算机的安全管道（当您的 cloudflared 连接器运行）。 - 这 wss:///ws “链接”只是客户端用于通过该隧道连接到您的应用程序的URL。 - 您可以使用create/status/revoke来管理管道，并使用announce_link来打印您将共享或拨打的确切URL。

• tunnel.announce_link

- 输入： { hostname: string } - 退货： wss:///ws 作为供客户端显示或使用的结构化链接。 - 注：不创建隧道；这仅格式化主机的公共WebSocket URL。 - 原因：因此UI/代理可以显示或存储精确的URL，而无需猜测路径或协议。

• tunnel.create_named

- 输入： { deviceHint?: string } - 为唯一主机名创建命名的Cloudflare隧道和DNS CNAME（代理）。 - 退货： { tunnelId: string, hostname: string, createdAt: string } - 注：连接器 token MCP（按设计）从不返回。使用代理REST运行连接器。 - 原因：为设备/会话分配一个新的、唯一的公共管道+您控制的名称。

• tunnel.status

- 输入： { tunnelId: string } - 检查连接器当前是否已连接到隧道。 - 退货： { connected: boolean, lastSeen?: string } - 原因：告知您的本地连接器是否已联机；非常适合进行准备检查和健康检查。

• tunnel.revoke

- 输入： { tunnelId: string, hostname?: string } - 删除Cloudflare隧道，并尝试尽最大努力进行DNS清理，如果 hostname 提供。 - 退货： { ok: true } 关于成功。 - 原因：当你完成或轮换时，彻底关闭并删除公共曝光。

验证细节（我们测试的内容）

• 隧道薄荷+DNS

- curl -s -X POST https://cloudburrow-broker.openagents.com/tunnels -H 'content-type: application/json' -d '{}' | jq - 确认JSON格式 { tunnelId, hostname, token }. - dig +short 解析为Cloudflare边缘IP（例如。， 104.18.14.36, 104.18.15.36)通常在~5-10s内。

• 连接器注册（HTTP/2）

- 启动连接器： cloudflared tunnel --no-autoupdate run --protocol http2 --proxy-keepalive-connections 1 --token "" --url http://127.0.0.1:8787 - 查找日志： Registered tunnel connection ... protocol=http2 （边缘对齐）。瞬态QUIC/UDP警告正常。

• 公共HTTP可达性

- 在任何本地服务器上 127.0.0.1:8787 （例如。， bun -e "Bun.serve({port:8787, fetch(){return new Response('ok\n')}}); await new Promise(()=>{})"), - curl -i https:/// 从本地服务返回HTTP响应（2xx/4xx取决于路径）。

• WebSocket握手到 /ws

- 本地WS服务器： bun -e "Bun.serve({port:8787, fetch(r,s){ if(new URL(r.url).pathname==='\/ws') return s.upgrade(r); return new Response('ok');}, websocket:{ open(ws){ws.send('hello');}, message(ws,msg){ws.send('echo:'+msg)} } }); await new Promise(()=>{})" - 连接： bun -e "let u='wss://'+process.argv[2]+'/ws'; const ws=new WebSocket(u); ws.addEventListener('open',()=>{console.log('OPEN'); ws.send('ping')}); ws.addEventListener('message',ev=>{console.log('MSG '+ev.data); ws.close();}); ws.addEventListener('close',()=>process.exit(0));" - 预计： OPEN 然后 MSG echo:ping.

快速入门（Bun）

• 安装依赖项：

  bun install

• 在本地运行（占位符）：

  bun run index.ts

该仓库目前为项目和文档提供脚手架。代理、客户端集成和MCP端点将使用Bun-first工具逐步添加。

MCP工具测试脚本

使用附带的脚本来练习在Cloudflare Worker上运行的MCP服务器。

• 工作MCP URL: https://cloudburrow-broker.openagents.com/mcp
• 脚本： scripts/test-mcp.ts

与Bun一起跑步：

# List tools and announce a link (no mutations)
bun scripts/test-mcp.ts --url https://cloudburrow-broker.openagents.com/mcp \
  --hostname cloudburrow-broker.openagents.com

# Full lifecycle: create → status → revoke (mutates Cloudflare via the Worker)
bun scripts/test-mcp.ts --url https://cloudburrow-broker.openagents.com/mcp \
  --hostname cloudburrow-broker.openagents.com --create --revoke

我们测试了什么以及它的表现如何：

• 初始化：使用MCP协议握手成功 2025-06-18.
• 工具/列表：报告的四种工具-- tunnel.announce_link, tunnel.create_named, tunnel.status, tunnel.revoke.
• tunnel.announce_link：返回了预期的结果 wss:///ws 链接。
• tunnel.create_named：已成功生成命名隧道和DNS主机名；MCP（按设计）不返回连接器令牌。
• tunnel.status：已返回 connected=false 创建后立即（预计在连接器连接之前） lastSeen 缺席或 n/a.
• tunnel.rinvoke：已成功撤销创建的隧道并尽最大努力清理DNS。

笔记：

• 测试脚本使用JSON‑RPC 2.0 over HTTP MCP-Protocol-Version 标头设置为服务器支持的版本。
• --create 和 --revoke 通过Worker触发真正的Cloudflare API调用；确保工人 CF_API_TOKEN, CF_ACCOUNT_ID，以及 CF_ZONE_ID 已配置。
• 你可以通过 --tunnelId 在不创建新隧道的情况下检查现有隧道的状态。

Cloudflare Worker（经纪人）

• 部署/dev命令（Wrangler通过Bun）：

- 开发人员： bun run dev:worker - 部署： bun run deploy:worker

• 工人所需的秘密：

- CF_API_TOKEN -API令牌，用于帐户/区域的隧道+DNS写入 - CF_ACCOUNT_ID --Cloudflare帐户id - CF_ZONE_ID --域的区域id（例如。， openagents.com) - 可选的 BROKER_KEY --如果已设置，则代理端点需要 Authorization: Bearer

• 设置秘密的单行程序（无需通过 --name):

- bun run cf:secret:api-token - bun run cf:secret:account-id - bun run cf:secret:zone-id - bun run cf:secret:broker-key

笔记：

• Worker配置位于 worker/wrangler.jsonc.脚本传递 --config worker/wrangler.jsonc 所以你不必这么做。
• 自定义域已绑定到 cloudburrow-broker.openagents.com → 工人。

使用示例

• 创建隧道（返回令牌+主机名）：

- curl -s -X POST https://cloudburrow-broker.openagents.com/tunnels -H 'content-type: application/json' -d '{}' | jq

• 在本地运行连接器（HTTP/2+最小保持活动）：

- env -u HTTP_PROXY -u HTTPS_PROXY -u http_proxy -u https_proxy -u ALL_PROXY -u all_proxy \ cloudflared tunnel --no-autoupdate run --protocol http2 --proxy-keepalive-connections 1 --token "" --url http://127.0.0.1:8787

• 探测公共主机：

- curl -i https:///

故障排除

• 在受限网络上预计会出现QUIC/UDP警告。我们强制使用HTTP/2；查找“已注册的隧道连接…protocol=http2”。
• 如果您看到“无法访问源服务…127.0.0.1:8787”，请确保您的本地服务正在监听，并且只有一个 cloudflared 正在运行。
• 如果DNS尚未传播主机名，请等待几秒钟，然后重试。

未来工作

今天什么有效

• Cloudflare Worker上的MCP服务器：初始化、列出工具和端到端调用工具。
• 通过Worker的隧道生命周期：创建、状态、撤销（Cloudflare API支持）。
• 运行连接器的本地帮助程序： bun run tunnel （要求 cloudflared 安装）。

计划中的增强功能

• 打包的库和CLI二进制文件，便于插入应用程序（以最少的设置嵌入代理/MCP客户端实用程序）。
• 具有令牌门控WebSocket端点和强化身份验证流的桌面网桥服务。
• TypeScript客户端SDK，用于编排隧道生命周期和解析MCP响应。
• 可观察性：结构化日志、度量、跟踪；改进了MCP输出的诊断。
• 重试/回退策略和DNS就绪检查；优雅的清理和恢复。
• 代理端点的安全强化（细粒度身份验证、签名切换、可选mTLS）。
• 其他MCP工具（列出/描述隧道、旋转主机名、发出健康摘要）。
• 通过以下方式进行自动化测试 bun test 涵盖MCP流和经纪商边缘案例。