radiochron-mcp

# radiochron-mcp

**[radiochron.com](https://radiochron.com)** · the chronicle of your radio.

A [Model Context Protocol](https://modelcontextprotocol.io) server that gives an
AI assistant local Wi-Fi diagnostics over stdio: connection-history **verdicts**
(reconnect loops, an AP failing key exchange, a credential mismatch), findings
instead of data dumps, live signal sampling, and native WLAN collectors.

Built on the [`radiochron`](https://github.com/sergii-ziborov/radiochron) library. Pure
Rust, **no MCP SDK**, three third-party dependencies, and **no build
toolchain beyond a stock [`rustup`](https://rustup.rs)**. The optional chronicle
writes only its rotating local JSONL file; saved passwords are never read and
nothing leaves the machine.

The engine, Node library, desktop app and website live independently in
[`radiochron`](https://github.com/sergii-ziborov/radiochron),
[`radiochron-js`](https://github.com/sergii-ziborov/radiochron-js),
[`radiochron-electron`](https://github.com/sergii-ziborov/radiochron-electron), and
[`radiochron-site`](https://github.com/sergii-ziborov/radiochron-site).
This repository depends directly on the Rust core. It is not distributed by
`radiochron-js`, and RadioChron Desktop does not depend on this server.

## Install

The crate is `radiochron-mcp`; the binary it installs is named `radiochron`,
because a `radiochron-mcp.exe` in a client config reads as internal plumbing.

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

The separate `radiochron-mcp` npm package carries revision-checked native binaries
for Windows x64, Linux x64/ARM64, Intel Mac, and Apple Silicon. It is assembled
and published from this repository; `radiochron-js` is an independent Node
library and does not contain this server.

```sh
claude mcp add radiochron -- npx -y radiochron-mcp
```

Releases are deliberately published from a maintainer console. Download all five
native artifacts from one green CI run, point the five
`RADIOCHRON_MCP_BINARY_*` variables at the matching binaries, then run
`npm pack`, `npm publish <archive> --access public`, and verify the package from
the public registry. Only after that, authenticate the official
`mcp-publisher`, publish `server.json`, verify the Registry entry, and push the
matching `v<package-version>` tag. No npm credential is stored in GitHub.

## Register with an MCP client

For Claude Code, point it at the installed binary:

```sh
claude mcp add radiochron -- radiochron
```

Or add it to any MCP client config directly:

```json
{
  "mcpServers": {
    "radiochron": { "command": "radiochron" }
  }
}
```

No arguments are required. `RADIOCHRON_CHRONICLE_PATH` optionally overrides
the platform-local chronicle path (`%LOCALAPPDATA%\RadioChron` on Windows,
`~/Library/Application Support/RadioChron` on macOS, or the XDG state directory
on Linux). The transport is
newline-delimited JSON-RPC 2.0 over stdio.

## Tools

Ten portable tools with machine-readable input/output schemas, structured
results and truthful MCP safety annotations. Windows exposes an eleventh tool,
`wifi_history`, backed by WLAN AutoConfig.

| Tool | Arguments | Returns |
|---|---|---|
| `wifi_status` | — | Every WLAN interface and, for the associated one: SSID, BSSID, PHY type (`ht`/`vht`/`he`/`eht`), signal quality, estimated RSSI in dBm, rx/tx rates |
| `wifi_networks` | `refresh_scan?: boolean`<br>`detail?: "summary" \| "full"` | Nearby BSS plus cache age, scan completion, per-interface errors, WPA2/WPA3/OWE, cipher, PMF, width and load fields |
| `wifi_analyze` | `refresh_scan?: boolean` | **Findings, not records.** Co-channel contention, crowded-channel association, weak signal, band-steering and roam candidates, insecure security, hidden SSIDs, scan-quality problems |
| `wifi_history` (Windows) | `within_seconds?: number`<br>`max_events?: number`<br>`include_events?: boolean` | **Why it dropped earlier.** Reads the WLAN AutoConfig event log and returns a verdict: reconnect loops, an AP repeatedly failing key exchange, a suspected credential mismatch |
| `wifi_sample` | `interface_guid?: string`<br>`duration_seconds?: 1..120`<br>`interval_ms?: 250..60000` | Cancelable sampling with progress; collector errors remain distinct from disconnects |
| `wifi_scan` | — | Triggers a standard native scan and reports per-interface completion/failure |
| `connectivity_diagnose` | DNS/TCP/Internet endpoints plus optional portal, TLS and quality targets | Separates radio, authentication, DHCP/static IP, gateway, DNS, TCP, captive portal, TLS, packet loss/jitter and Internet. TLS certificate validation lives in the agent transport; MCP reports that stage as unknown. |
| `chronicle_start` | `interval_seconds?: 1..300`<br>`signal_threshold_db?: 1..50` | Starts the local rotating change-only recorder |
| `chronicle_stop` | — | Stops and flushes the recorder |
| `chronicle_status` | — | Recorder state, path and latest error |
| `chronicle_recent` | `max_entries?: 1..1000` | Recent entries from active and rotated files |

**Prefer `wifi_analyze`.** On a real 43-BSS environment it answers in ~800 bytes
where the full BSS list costs ~41 KB — because it returns the conclusion, not
the evidence. Every finding carries a `caveat` field stating why it might be
wrong; that is part of the payload on purpose, since a bare severity invites
over-trust and several of these signals are genuinely weaker than they look.

Two behaviours worth knowing about `wifi_networks`: the driver cache can be
empty, so a first empty read is retried once behind a real scan (the `refresh`
object says what completed) rather than reported as "no networks"; and `summary`
is the default — ask for `full` (raw IEs, rates, capability bits) only when you
need those fields.

## Deliberately not exposed

The parent project grew collectors that are unsafe to hand to an autonomous
model. They are **not** part of this server's tool surface, and calling them
returns `-32601 unknown tool`:

- **plaintext saved Wi-Fi keys** — a model must not be able to read and leak credentials
- **adapter MAC change / adapter restart / computer rename** — privileged, disruptive, can drop the operator off the network
- **active LAN sweeps** — emit probe traffic, trip IDS on managed segments
- **external AI-review shell-out** — arbitrary process execution and off-box data flow

## Why no SDK

The official `rmcp` crate would add `tokio`, `schemars`, and a mandatory
`chrono` whose `clock` feature depends on `windows-link`/`raw-dylib` —
reintroducing the exact build requirement this project exists to avoid. The
stdio transport is a few hundred lines over `serde_json` instead, so the server
builds on nothing but `rustup`.

## Platform

The MCP binary runs on Windows, Linux and macOS. It uses WLAN API on Windows,
nl80211 on Linux, and CoreWLAN on Apple systems, including Apple Silicon.
Windows alone exposes WLAN AutoConfig event history; all other tools remain
available on macOS and Linux.

## Safety and privacy

SSIDs, BSSIDs, MAC addresses and event logs are sensitive. This server is
local-first, has no telemetry, and transmits nothing off the machine. Only run
scans against networks you own or are authorized to test. It is not a packet
sniffer, a geolocation system, or offensive Wi-Fi tooling.

## License

Licensed under the [MIT License](LICENSE-MIT). The underlying `radiochron`
Rust core remains separately dual-licensed under MIT or Apache-2.0.