iOS Web Bluetooth (WebBLE)

@beacio/mcp

MCP 服务，教会编码 Agent（Claude、Cursor、Copilot，……）如何借助 beacio 发布 iOS Safari Web Bluetooth。

提供 11 个工具（7 个面向用户，4 个面向开发者），全部可离线使用，并且都会引用 https://beacio.com/docs-md/* 中的规范文档。

安装

通过 npx 运行，无需安装：

npx -y @beacio/mcp

或者将其添加到 MCP 客户端配置中（示例：Claude Desktop，~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "beacio": {
      "command": "npx",
      "args": ["-y", "@beacio/mcp"],
      "env": { "MCP_CLIENT": "claude-desktop" }
    }
  }
}

beacio 脚手架 CLI

此包还随 MCP 服务提供非作用域的 beacio CLI（原为独立的 @beacio/cli）。它可以在 Web 项目中搭建并验证 beacio 集成：

npx beacio init       # auto-detect framework and add the detection snippet
npx beacio migrate    # brownfield: patch an existing Web Bluetooth app for iOS Safari
npx beacio check      # verify beacio integration (add --brownfield for an existing app)

beacio migrate 应用与 beacio_patch_existing_app MCP 工具生成的相同三项修改（由同一个转换器生成）。

工具

面向用户的工具

Agent 在默认（用户）模式下可使用这些工具，将 SDK 发布到应用中。

工具	用途
beacio_install_plan	规范的安装步骤 + 可运行代码片段，适用于 html | react | vue | svelte | angular | next × npm | pnpm | yarn | bun | cdn。
beacio_patch_existing_app	旧项目改造：生成具体的 FileEdits，为现有 Web Bluetooth 应用添加 iOS Safari 支持——在首次读取 navigator.bluetooth 前将引导代码加入 <head>，为 iOS 的 requestDevice 分支添加 optionalServices，并将“使用 Bluefy / Web BLE 浏览器”提示替换为安装/启用选项。
beacio_verify_integration	可由 Agent 运行的检查清单（shell 命令 + 通过标准），用于确认 polyfill 已安装、已引导、可构建且类型可解析——另有适用于已编写应用的 brownfield 模式。
beacio_example	可直接粘贴的 BLE 配置文件代码：heart-rate、battery、cgm、lock、beacon、peripheral-chat。
beacio_detect_ios_support	检测 navigator.bluetooth + window.beacioIOS 的运行时代码片段，并注明所有注意事项。
beacio_premium_guide	iOS 专属高级功能之一：backgroundSync、notifications、liveActivity、beacons、peripheral、whiteLabel。
beacio_troubleshoot	诊断检查清单 + 常见问题修复方法，适用于 extension-not-detected、device-disconnects、gatt-operation-failed、notifications-not-firing。
beacio_spec_citation	针对指定方法（例如 navigator.bluetooth.requestDevice）提供 W3C Web Bluetooth 规范 URL、摘要和注意事项。

面向开发者的工具

通过 --developer 模式提供，适用于在 beacio monorepo 内工作的 Agent。

工具	用途
beacio_dev_best_practices	阅读项目的 AGENTS.md 最佳实践指南，可按主题章节筛选。
beacio_dev_search_docs	按关键字搜索 beacio 文档索引；返回按相关性排序的结果及 beacio.com URL。
beacio_dev_list_structure	构建 monorepo 目录结构的树状视图（可选根路径、深度 1-4，支持 gitignore）。
beacio_dev_find_examples	搜索精选的关键源文件索引；返回按相关性排序的匹配项，包含文件路径、行号和类别。

每个响应都是 JSON，并包含指向 https://beacio.com/docs-md/ 的 source_url，供 Agent 引用权威文档。

归因令牌

beacio_install_plan 会返回一个格式如下的 attribution_token：

beacio_YYYYMM_mcp_<8..16 chars a–z0–9>

示例：beacio_202604_mcp_3p9xq2k8m4r

beacio 信标端点接受此令牌，以便追踪源自此 MCP 服务的安装。请原样向用户提供此令牌——不要修改、截断或重新生成。

遥测

每次工具调用都会向 https://mcp-telemetry.beacio.com/mcp-telemetry 发送一条精简事件（默认启用遥测）：

{
  "tool": "beacio_install_plan",
  "client_name": "claude-desktop",
  "client_version": "1.2.3",
  "success": true,
  "duration_ms": 42,
  "attribution_token": "beacio_202604_mcp_3p9xq2k8m4r"
}

不会发送设备数据、BLE 载荷或任何用户输入。即发即弃，超时时间为 1 秒。

**选择退出：**遥测默认开启；将 BEACIO_MCP_TELEMETRY 设为 0、false、off 或 no（不区分大小写），或设置跨工具通用的 DO_NOT_TRACK=1，即可禁用遥测。

**标识你的客户端：**设置 MCP_CLIENT（例如 claude-desktop、cursor、copilot-cli）。默认值为空字符串。也可选择设置 MCP_CLIENT_VERSION（默认值为空字符串）。

链接

• 主页：https://beacio.com/mcp
• 文档（机器可读）：https://beacio.com/docs-md/
• 源码：https://github.com/wklm/beacio-sdk/tree/main/packages/mcp
• 问题反馈：https://github.com/wklm/beacio-sdk/issues
• 应该安装哪个 beacio 软件包？packages/AGENTS.md

许可证

MIT © wklm