云洞

Name: 云洞
Author: OpenAgentsInc

作者：OpenAgentsInc2 星标更新：2025-10-29

安装使用来源：spider==github.com

项目介绍

Cloudburrow

作为基础的隧道 — Cloudflare + MCP

Cloudburrow 允许在桌面“桥接器”和启用 MCP 的客户端（例如移动应用或其他代理）之间建立安全的、基于设备的 Cloudflare 隧道连接。它专注于一键配对流程、稳定的 wss:// 端点以及在 Cloudflare Worker 上暴露的可选 MCP 工具，用于监控和远程控制——与任何特定客户端无耦合。

用简单的话来说，你现在可以做到以下几点：

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

为什么这很重要

代理原生、设备到设备的基础
- 如果桥梁可以在没有每个设备集中账户的情况下运行，隧道将成为代理形成按需设备到设备链接的可重用构建块。 MCP 作为控制平面（创建/状态/撤销），而隧道是数据平面（wss://…/ws）。
没有每个设备的注册流程
- 运行桌面应用程序的人不需要创建隧道提供商账户或分享凭证。一个 Cloudflare 账户（你的）通过 Worker 在幕后处理一切。
在 Cloudflare 的全球边缘运行
- 使用 Cloudflare 隧道 + DNS 在你的区域上稳定、一流的主机名。没有不透明的 URL，没有跨网络失效的 NAT 技巧。
通过 MCP 进行远程控制
- 直接从任何 MCP 能力的客户端（代理、应用、脚本）创建、检查和撤销隧道，而不暴露秘密。令牌永远不会离开服务器。
命名隧道，而不是“快速”或瞬时链接
- 你可以获得可预测的主机名并执行策略和清理，而不是临时的瞬时 URL。
设计用于自动化
- 可以使用 bun 和 JSON-RPC 脚本；易于嵌入工作流、CI 或代理运行时。

我们正在构建什么

通过命名的 Cloudflare 隧道进行安全设备配对（没有快速隧道）。
每个设备的一级主机名，如 wss://tunnel-<rand>.openagents.com/ws 用于桥梁。
任何客户端的一键用户体验：可选自动安装 cloudflared，从经纪人请求凭证，运行连接器，并打印配对二维码/深度链接。
桌面桥梁上的 WebSocket 令牌门控（/ws），以强制认证连接。
在同一个 Worker 上托管可选的 MCP 工具，以便从聊天流管理隧道生命周期，而不暴露连接器秘密。

组件（简单语言）

Worker（经纪人 + MCP）
- 存在于 Cloudflare。它是可以创建命名隧道、告知公共主机名、检查状态和撤销的控制平面。
- 暴露两个接口：REST 端点（供桌面获取连接器令牌并运行 cloudflared）和 MCP 工具（供代理/应用驱动生命周期而不查看秘密）。
- 保护你的 Cloudflare API 令牌；令牌永远不会出现在 MCP 响应中。
桥梁（桌面）
- 在你的机器上运行。它向 Worker 的 REST API 请求隧道令牌和主机名，然后启动 cloudflared 使隧道指向你的本地应用程序（例如 http://127.0.0.1:8787）。
- 结果是一个稳定的公共 URL wss://<hostname>/ws，该 URL 转发到你的本地服务。
- 可以为 /ws 端点添加身份验证，以便只有授权客户端连接。
客户端（代理/应用）
- 任何能够与 MCP 通信的东西。它通过 MCP 向 Worker 请求创建隧道，显示/使用宣布的 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://<hostname>/ws “链接”只是客户端用来通过该隧道连接到你的应用程序的 URL。
- 你使用 create/status/revoke 来管理管道，并使用 announce_link 打印你要共享或拨打的确切 URL。
tunnel.announce_link
- 输入：{ hostname: string }
- 返回：wss://<hostname>/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 <hostname> 解析到 Cloudflare 边缘 IP（例如 104.18.14.36，1104.18.15.36）通常在约 5-10 秒内完成。
连接器注册（HTTP/2）
- 启动连接器：cloudflared tunnel --no-autoupdate run --protocol http2 --proxy-keepalive-connections 1 --token "<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://<HOSTNAME>/ 返回来自你的本地服务的 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));" <HOSTNAME>
- 预期：OPEN 然后 MSG echo:ping。

快速入门（Bun）

安装依赖项：
```
bun install
```
本地运行（占位符）：
```
bun run index.ts
```

此仓库目前搭建了项目和文档。经纪人、客户端集成和 MCP 端点将逐步增加，首先使用 Bun 工具。

MCP 工具测试脚本

使用包含的脚本来测试运行在 Cloudflare Worker 上的 MCP 服务器。

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

使用 Bun 运行：

# 列出工具并宣布一个链接（无变更）
bun scripts/test-mcp.ts --url https://cloudburrow-broker.openagents.com/mcp \
  --hostname cloudburrow-broker.openagents.com

# 完整生命周期：创建 → 状态 → 撤销（通过 Worker 触发 Cloudflare API 调用）
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://<hostname>/ws 链接。
tunnel.create_named：成功生成了一个命名隧道和 DNS 主机名；连接器令牌未由 MCP 返回（设计如此）。
tunnel.status：创建后立即返回 connected=false（直到连接器附加之前预期如此），lastSeen 缺失或 n/a。
tunnel.revoke：成功撤销创建的隧道并尽力清理 DNS。

注意事项：

测试脚本使用 JSON-RPC 2.0 过 HTTP 并设置 MCP-Protocol-Version 头为服务器支持的版本。
--create 和 --revoke 通过 Worker 触发真实的 Cloudflare API 调用；确保 Worker 配置了 CF_API_TOKEN, CF_ACCOUNT_ID, 和 CF_ZONE_ID。
你可以传递 --tunnelId <id> 来检查现有隧道的状态而不创建新的隧道。

Cloudflare Worker（经纪人）

部署/开发命令（通过 Bun 的 Wrangler）：
- 开发：bun run dev:worker
- 部署：bun run deploy:worker
Worker 上所需的秘密：
- CF_API_TOKEN — 对帐户/区域具有隧道 + DNS 写权限的 API 令牌
- CF_ACCOUNT_ID — Cloudflare 账户 ID
- CF_ZONE_ID — 你的域的区域 ID（例如 openagents.com）
- 可选 BROKER_KEY — 如果设置，则经纪人端点需要 Authorization: Bearer <BROKER_KEY>
设置秘密的一行命令（无需传递 --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 → Worker。

使用示例

创建一个隧道（返回令牌 + 主机名）：
- 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 "<TOKEN>" --url http://127.0.0.1:8787
探测公共主机：
- curl -i https://<HOSTNAME>/

故障排除

在受限网络上看到 QUIC/UDP 警告是正常的。我们强制使用 HTTP/2；查找“Registered tunnel connection … 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 流程和经纪人边缘情况的自动化测试。