RadioChron

radiochron-mcp

radiochron.com · 你的无线电编年史。

一个本地优先的 Model Context Protocol 服务 和命令行工具，用于诊断 Wi-Fi 事件并观测 Bluetooth Low Energy。 它将原生无线电数据采集与 radiochron Rust 核心相结合， 并返回类型化结论，而不是让助手解读原始操作系统输出。

这两个前端并非两套实现。radiochron analyze 和 wifi_analyze 工具运行的是同一个处理器，使用相同的限制和错误文本，因此无论你以何种方式调用，结论都不会改变。

首选 MCP 修订版本为 2025-11-25；请求 2025-06-18 的客户端会收到兼容的旧版工具结构。每个工具都有输入和 输出架构、结构化内容、安全注解、明确的执行语义；对于长时间运行的任务支持取消，并清晰区分 JSON-RPC 协议错误和工具执行错误，便于采取相应操作。

RadioChron 各仓库彼此独立：

• radiochron 是 Rust/IoT 核心。
• radiochron-js 是 Node/npm 库；它不包含 MCP。
• radiochron-mcp 是本项目的纯 Rust MCP 服务和命令行工具。
• radiochron-agent 是无人值守的持久化采集器/导出器，不依赖 MCP。
• radiochron-electron 是独立桌面应用，不依赖 MCP。

安装

npm 包附带经过验证的原生二进制文件，适用于 Windows x64、Linux x64/ARM64、Intel Mac 和 Apple 芯片：

claude mcp add radiochron -- npx -y radiochron-mcp

或者从源代码安装 Rust 二进制文件：

cargo install --git https://github.com/sergii-ziborov/radiochron-mcp

在 Debian/Ubuntu 上构建时，BlueZ 适配器需要 libdbus-1-dev 和 pkg-config。使用预构建 npm 包的用户无需安装 Rust 工具链。

向任意 stdio MCP 客户端注册已安装的二进制文件：

{
  "mcpServers": {
    "radiochron": {
      "command": "radiochron"
    }
  }
}

RADIOCHRON_CHRONICLE_PATH 可用于覆盖本地编年史路径： Windows 上为 %LOCALAPPDATA%\RadioChron，macOS 上为 ~/Library/Application Support/RadioChron，Linux 上为 XDG 状态目录。

命令行

同一个二进制文件也可用作 CLI。无需额外安装——npm 包可通过 npx radiochron status 运行，cargo install 则会将 radiochron 安装到 PATH 中。

radiochron status                  # association state of every adapter
radiochron scan                    # look again, then list what is there
radiochron analyze                 # findings about the environment
radiochron report                  # the full Markdown diagnostic report
radiochron incident --ble          # one composite answer for "the Wi-Fi is broken"
radiochron connectivity --dns example.com --tcp example.com:443
radiochron ble scan --duration 4000
radiochron chronicle recent --max 20
radiochron --help                  # every command and flag

在任意命令后添加 --json，即可获取原始工具结果，供脚本使用：

radiochron networks --json | jq '.networks[] | select(.rssi_dbm > -60) | .ssid'

radiochron tool <name> [--args '<json>'] 可调用目录中发布的任意工具，包括没有便捷名称的工具：

radiochron tool ble_evaluate --args '{"now_ms":1717000000000}'

遇到未知标志时会直接拒绝，而不是忽略。因此，拼错的 --durations 会明确报错，而不会悄悄使用默认值运行。

不带参数运行时仍会通过 stdio 提供 MCP 服务，与之前完全相同，因此所有现有客户端配置都能继续使用。若 stdin 是终端，表示有人输入了名称，此时会打印帮助信息；若 stdin 是管道，则表示客户端正在调用，程序会使用该协议。使用 radiochron mcp 可显式强制启动服务。

有两个命令仅限 CLI 使用，因为它们没有可供运行的会话： chronicle record 会在前台运行记录器，直到你将其停止；chronicle path 会打印日志的存放位置。

MCP 与 Node（radiochron-js）

它们共用一个 Rust 核心和一个事件分类器，但并非层层叠加。

界面	包	支持 MCP？	适用场景
MCP + CLI	radiochron-mcp	是（stdio）	助手、radiochron doctor、运维人员的 Shell
Node/npm	radiochron	否	应用、Electron、服务、CI 探测

桌面应用仅导入 radiochron（npm）。诊断时绝不能启动 MCP 服务——这会导致采集器重复运行，并使原因判断逻辑出现偏差。

相同结论，两种入口

# MCP / CLI — orchestrates collectors, then core::incident::classify
radiochron doctor --json

// Node — same classifier, in-process native bridge
import { getRadioChronCoreClient } from 'radiochron';

const rc = getRadioChronCoreClient();
const report = await rc.diagnose({ includeBle: false });
console.log(report.assessment, report.causes);

// Optional: portable transfer matching MCP incident exports
import { createIncidentBundle, readIncidentBundle } from 'radiochron';

const bytes = createIncidentBundle({
  report,
  producer: {
    surface: 'node',
    surface_version: '0.7.0',
    core_version: '0.6.0'
  }
});
// write bytes to a .rchron file, or round-trip:
const again = readIncidentBundle(bytes);

需要无线电证据的助手应调用 MCP 工具。已运行 Node 的应用应直接调用 radiochron，跳过 MCP 进程。

从一个工具开始

首先使用 diagnose_incident（CLI 别名：radiochron doctor）。该工具负责协调各采集器，并请求共享核心分类器给出一项事件结论。响应包含彼此独立的部分：

• 当前 Wi-Fi 接口及关联状态；
• RF／环境分析；
• 无线电 → 身份验证 → DHCP → 网关 → DNS → TCP → Internet 各阶段；
• 可用时的 Windows WLAN 事件历史记录；
• 最近仅记录变更的 chronicle 条目；
• 可选的原生 BLE 广告扫描、规范化身份、保留的历史记录，以及基于证据的发现。

某个采集器不可用，不会导致事件的其余部分被丢弃。每个部分都包含 ok、data 或可操作的 error，顶层 problems 列表简洁到足以让助手直接说明问题。除非调用方提供目标，否则绝不会联系目标。

工具列表

17 个工具可跨平台使用。Windows 还提供第 18 个工具 wifi_history，由 WLAN AutoConfig 提供支持。

工具	用途
diagnose_incident	在一份精简响应中协调 Wi-Fi、连接、历史记录、chronicle 和可选的原生 BLE 证据
wifi_status	所有 WLAN 接口的当前状态
wifi_networks	附近 BSS 记录，包含真实 dBm、安全性、带宽和负载；支持摘要或完整详情
wifi_analyze	信号、争用、漫游、安全性和扫描质量方面的发现
wifi_history（Windows）	重连循环、密钥交换失败和凭据不匹配证据
wifi_sample	可取消的 RSSI／速率／漫游采样，并提供进度
wifi_scan	原生 Wi-Fi 刷新，并报告每个接口的完成情况／失败情况
connectivity_diagnose	分别检查无线电、身份验证、IP 分配、网关、DNS、TCP、门户、TLS、质量和 Internet 各阶段
chronicle_start	启动本地循环写入、仅记录变更的 JSONL 记录器
chronicle_stop	停止记录器并刷新数据
chronicle_status	记录器状态、路径、计数器和最新错误
chronicle_recent	活动文件和轮换文件中的近期条目
ble_scan	扫描原生适配器但不连接，规范化广告数据，更新历史记录，并返回风险证据
ble_identify	识别调用方提供的广告数据并对其负载进行哈希处理
ble_tracker_reset	清除进程本地的 BLE 历史记录并应用检测器策略
ble_observe	添加外部采集的定时观测
ble_histories	首次／最近发现时间、重复情况、传感器、移动会话和 RSSI 摘要
ble_evaluate	针对预期身份，基于时间的消失情况发现

ble_scan 在 Windows 上使用 WinRT，在 Linux 上使用 BlueZ，在 macOS 上使用 CoreBluetooth。它只侦听在所请求扫描窗口内观测到的设备，不会建立 GATT 连接，并将数据馈送到与显式 ble_observe 调用相同的、经过隐私最小化处理的 RadioChron 跟踪器。iBeacon 和 Eddystone UID 数据可提供更可靠的协议身份；通用私有地址则是临时的。

在 macOS 11 及更高版本上，启动 MCP 进程的主机应用或终端必须拥有蓝牙权限。应用包需要 NSBluetoothAlwaysUsageDescription；通过终端启动的服务则需要在系统设置中为该终端启用蓝牙访问权限。Linux 需要正在运行的 BlueZ 服务，并需要访问系统 D-Bus。

MCP 行为

• 通过标准输入/输出传输以 UTF-8 编码、每行分隔的 JSON-RPC 2.0；标准输出仅包含 MCP 帧。
• 协商支持 2025-11-25 和 2025-06-18，并优先使用当前修订版。
• 当前工具定义声明 execution.taskSupport: "forbidden"，因为此本地标准输入/输出服务使用常规可取消请求，而非持久化实验性任务。
• 未知方法和格式错误的调用信封会使用 JSON-RPC 错误。
• 工具输入、无线电或平台故障会通过 isError: true 返回，以便模型修正参数或说明平台问题。
• 结构化结果也会序列化为文本内容，供较旧的客户端使用。
• 源文件受 300 行的架构限制；真实标准输入/输出一致性测试覆盖当前及旧版的生命周期、目录和错误行为。

工具和资源请求路径使用不依赖 Tokio 的 mcport 运行时及其 blazingly-json 值/编解码接口。RadioChron 仅在本地保留严格的初始化/通知生命周期。原生 BLE 收集由独立的 radiochron-native-ble crate 负责，它直接与 WinRT、BlueZ D-Bus 和 CoreBluetooth 通信，不使用 btleplug、Tokio 或 futures。可移植的 radiochron 核心仍独立于主机蓝牙 API。

安全与隐私

SSID、BSSID、蓝牙地址、广播载荷和事件日志可能包含敏感信息。此服务不进行遥测，也不会向机器外发送任何内容。事件记录仅写入轮换的本地 JSONL 文件。绝不会读取已保存的 Wi-Fi 密码。

RSSI 是信号证据，并不代表物理距离或方向。蓝牙私有地址可能会轮换，因此，克隆/复现声明需要协议身份或调用方提供的身份信息。原生 BLE 扫描绝不会连接外围设备。

MCP 接口有意排除明文 Wi-Fi 密钥、适配器 MAC 更改、适配器重启、计算机重命名、主动 LAN 扫描、任意 shell 执行和外部 AI 审核。

发布

发布版本由一次通过的跨平台 CI 运行构建。npm 压缩包必须包含与修订版匹配的二进制文件，以及全部五个目标平台的来源证明附属文件。不可变版本标签会通过受保护的仓库密钥发布 npm 包，随后通过 GitHub OIDC 将匹配的 server.json 发布到官方 MCP Registry。npm 凭证是受掩码保护、受标签门控的 NPM_TOKEN GitHub Actions 密钥；MCP Registry 不使用长期令牌。

许可证

根据 MIT License 授权。底层的 radiochron Rust 核心仍单独采用 MIT 或 Apache-2.0 双重许可。