Skip to content

Commit f2364fc

Browse files
KI7MTclaude
andcommitted
Update wspr-mcp docs for v0.2.0 — 8 tools, good neighbour policy
- wspr.md: full 8-tool reference with all parameters - wspr.md: Good Neighbour Policy section (rate limit, circuit breaker, caching) - index.md: wspr-mcp 5 -> 8 tools, adif-mcp 7 -> 8 tools - servers/index.md: wspr-mcp tool count, rate limit table updated - llms.txt: updated wspr-mcp description and tool count Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent ad4980f commit f2364fc

4 files changed

Lines changed: 102 additions & 30 deletions

File tree

docs/index.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Ask your AI assistant to look up a callsign, check your LoTW confirmations, find
1212

1313
| Package | Tools | What It Does |
1414
|---------|:-----:|--------------|
15-
| [adif-mcp](servers/adif-mcp.md) | 7 | ADIF 3.1.6 spec engine, validation, persona management, keyring credentials |
15+
| [adif-mcp](servers/adif-mcp.md) | 8 | ADIF 3.1.6 spec engine, validation, persona management, keyring credentials |
1616

1717
### Logbook Services (Authenticated)
1818

@@ -31,7 +31,7 @@ Ask your AI assistant to look up a callsign, check your LoTW confirmations, find
3131
| [sota-mcp](servers/sota.md) | 5 | Spots, alerts, summit info, nearby search |
3232
| [iota-mcp](servers/iota.md) | 6 | Group lookup, island search, DXCC mapping, nearby |
3333
| [solar-mcp](servers/solar.md) | 6 | SFI, Kp, solar wind, X-ray, band outlook |
34-
| [wspr-mcp](servers/wspr.md) | 5 | Beacon spots, band activity, propagation |
34+
| [wspr-mcp](servers/wspr.md) | 8 | Beacon spots, band activity, top beacons/spotters, propagation, SNR trends |
3535

3636
---
3737

docs/llms.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
- [sota-mcp](https://qso-graph.io/servers/sota/): Summits on the Air — spots, alerts, summit info, nearby search, activator stats. 5 tools.
2020
- [solar-mcp](https://qso-graph.io/servers/solar/): NOAA SWPC — SFI, Kp, solar wind, X-ray flux, band outlook, alerts. 6 tools.
2121
- [iota-mcp](https://qso-graph.io/servers/iota/): Islands on the Air — group lookup, island search, DXCC mapping, nearby groups, programme stats. 6 tools.
22-
- [wspr-mcp](https://qso-graph.io/servers/wspr/): WSPR network — beacon spots, band activity, propagation paths, TX power. 5 tools.
22+
- [wspr-mcp](https://qso-graph.io/servers/wspr/): wspr.live ClickHouse — beacon spots, band activity, top beacons, top spotters, propagation, grid activity, longest paths, SNR trends. 8 tools.
2323

2424
## Documentation
2525

docs/servers/index.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ qso-graph provides 10 MCP packages covering amateur radio logging, confirmations
1010

1111
| Package | Tools | Service | Auth Pattern |
1212
|---------|:-----:|---------|-------------|
13-
| [adif-mcp](adif-mcp.md) | 7 | ADIF 3.1.6 spec | None (local) |
13+
| [adif-mcp](adif-mcp.md) | 8 | ADIF 3.1.6 spec | None (local) |
1414

1515
### Logbook Services
1616

@@ -29,7 +29,7 @@ qso-graph provides 10 MCP packages covering amateur radio logging, confirmations
2929
| [sota-mcp](sota.md) | 5 | Summits on the Air | None (public) |
3030
| [iota-mcp](iota.md) | 6 | Islands on the Air | None (public) |
3131
| [solar-mcp](solar.md) | 6 | NOAA SWPC | None (public) |
32-
| [wspr-mcp](wspr.md) | 5 | WSPR network | None (public) |
32+
| [wspr-mcp](wspr.md) | 8 | wspr.live (ClickHouse) | None (public) |
3333

3434
---
3535

@@ -94,4 +94,4 @@ Each server implements rate limiting appropriate for its service:
9494
| sota-mcp | 200ms |||
9595
| iota-mcp | 200ms |||
9696
| solar-mcp | 200ms |||
97-
| wspr-mcp | 200ms | | |
97+
| wspr-mcp | 3000ms | 20/min | Circuit breaker (60-300s) |

docs/servers/wspr.md

Lines changed: 96 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# wspr-mcp
22

3-
**WSPR beacon analytics — spots, band activity, top paths, and propagation analysis.**
3+
**WSPR beacon analytics — live spots, band activity, top beacons, propagation paths, SNR trends, and more.**
4+
5+
Data from [wspr.live](https://wspr.live/) (~2.7 billion spots, 2008-present).
46

57
```bash
68
pip install wspr-mcp
@@ -12,15 +14,18 @@ pip install wspr-mcp
1214

1315
## Tools
1416

15-
All 5 tools are **public** — no credentials needed.
17+
All 8 tools are **public** — no credentials needed.
1618

1719
| Tool | Description |
1820
|------|-------------|
19-
| `wspr_spots` | Recent WSPR spots |
20-
| `wspr_activity` | Activity summary for a callsign |
21-
| `wspr_band_activity` | Per-band activity overview |
22-
| `wspr_top_paths` | Longest/best paths in last 24 hours |
23-
| `wspr_propagation` | Band-by-band propagation between two grids |
21+
| `wspr_spots` | Recent WSPR spots with flexible filtering |
22+
| `wspr_band_activity` | Per-band activity — spots, stations, distances, SNR |
23+
| `wspr_top_beacons` | Top transmitters ranked by spot count or distance |
24+
| `wspr_top_spotters` | Top receivers ranked by spot count or distance |
25+
| `wspr_propagation` | Propagation between two locations (callsign or grid) |
26+
| `wspr_grid_activity` | All WSPR activity in/out of a Maidenhead grid square |
27+
| `wspr_longest_paths` | Longest distance paths in a time window |
28+
| `wspr_snr_trend` | Hourly SNR trend for a specific path over time |
2429

2530
---
2631

@@ -32,45 +37,112 @@ Get recent WSPR spots. Each spot is a 2-minute integration proving a propagation
3237

3338
| Parameter | Type | Required | Description |
3439
|-----------|------|:--------:|-------------|
35-
| `callsign` | str | No | Filter by TX or RX callsign |
36-
| `band` | str | No | Filter by band (e.g., "20m", "40m") |
40+
| `callsign` | str | No | Filter by TX or RX callsign (e.g., KI7MT) |
41+
| `band` | str | No | Filter by band (e.g., "20m", "40m", "10m") |
42+
| `hours` | int | No | Time window in hours. Default: 24, max: 72 |
3743
| `limit` | int | No | Maximum spots to return. Default: 50, max: 200 |
44+
| `grid` | str | No | Filter by grid square prefix (e.g., DN13). Matches TX or RX |
45+
| `min_snr` | int | No | Minimum SNR in dB (e.g., -20) |
46+
| `max_snr` | int | No | Maximum SNR in dB (e.g., -5) |
47+
| `min_distance` | int | No | Minimum path distance in km (e.g., 5000) |
48+
49+
### wspr_band_activity
50+
51+
Per-band WSPR activity summary. Shows spot counts, TX/RX station counts, average and max distance, and average SNR for each band.
52+
53+
| Parameter | Type | Required | Description |
54+
|-----------|------|:--------:|-------------|
55+
| `hours` | int | No | Time window in hours. Default: 1, max: 6 |
3856

39-
Returns list of spots with TX/RX callsigns, grids, SNR, distance, and band.
57+
### wspr_top_beacons
4058

41-
### wspr_activity
59+
Top WSPR transmitters ranked by spot count or maximum distance.
4260

43-
Get WSPR activity summary for a callsign. Shows TX/RX spot counts, active bands, unique reporters, maximum distance, and best SNR.
61+
| Parameter | Type | Required | Description |
62+
|-----------|------|:--------:|-------------|
63+
| `band` | str | No | Filter by band (e.g., "20m") |
64+
| `hours` | int | No | Time window in hours. Default: 24, max: 72 |
65+
| `sort_by` | str | No | Ranking: "spots" (default) or "distance" |
66+
| `limit` | int | No | Number of results. Default: 20, max: 50 |
67+
68+
### wspr_top_spotters
69+
70+
Top WSPR receivers ranked by spot count or maximum distance.
4471

4572
| Parameter | Type | Required | Description |
4673
|-----------|------|:--------:|-------------|
47-
| `callsign` | str | Yes | Callsign to look up (e.g., KI7MT, K9AN) |
74+
| `band` | str | No | Filter by band (e.g., "20m") |
75+
| `hours` | int | No | Time window in hours. Default: 24, max: 72 |
76+
| `sort_by` | str | No | Ranking: "spots" (default) or "distance" |
77+
| `limit` | int | No | Number of results. Default: 20, max: 50 |
4878

49-
### wspr_band_activity
79+
### wspr_propagation
80+
81+
Propagation between two locations. Accepts callsigns, grid squares, or a mix. Searches both directions automatically.
5082

51-
Get current per-band WSPR activity summary. Shows how many spots, TX stations, and RX stations are active on each band, with average path distance. No parameters.
83+
| Parameter | Type | Required | Description |
84+
|-----------|------|:--------:|-------------|
85+
| `tx` | str | Yes | First endpoint — callsign (e.g., KI7MT) or grid (e.g., DN13) |
86+
| `rx` | str | Yes | Second endpoint — callsign (e.g., G8JNJ) or grid (e.g., IO91) |
87+
| `band` | str | No | Filter to a specific band (e.g., "20m") |
88+
| `hours` | int | No | Time window in hours. Default: 24, max: 72 |
5289

53-
### wspr_top_paths
90+
Returns per-band propagation with spot counts, SNR stats, and UTC hours open.
5491

55-
Get the longest/best WSPR paths in the last 24 hours. Long paths prove the band is open.
92+
### wspr_grid_activity
93+
94+
All WSPR activity in or out of a Maidenhead grid square. Use 2-character (e.g., DN) for a wide area or 4-character (e.g., DN13) for a specific region.
5695

5796
| Parameter | Type | Required | Description |
5897
|-----------|------|:--------:|-------------|
98+
| `grid` | str | Yes | Maidenhead grid — 2 char (DN) or 4 char (DN13) |
5999
| `band` | str | No | Filter by band (e.g., "20m") |
60-
| `limit` | int | No | Maximum paths to return. Default: 20 |
100+
| `hours` | int | No | Time window in hours. Default: 24, max: 72 |
101+
| `limit` | int | No | Maximum recent spots to return. Default: 50, max: 200 |
61102

62-
Returns list of top paths with TX/RX callsigns, grids, band, SNR, and distance.
103+
Returns summary stats (totals, stations, bands) plus recent spot list.
63104

64-
### wspr_propagation
105+
### wspr_longest_paths
106+
107+
Longest WSPR paths in the given time window. Long paths prove the band is open.
65108

66-
Get WSPR-derived propagation between two grid squares. Shows which bands have been open between two locations in the last 24 hours, with spot counts, average SNR, best SNR, and hours of opening.
109+
| Parameter | Type | Required | Description |
110+
|-----------|------|:--------:|-------------|
111+
| `band` | str | No | Filter by band (e.g., "10m") |
112+
| `hours` | int | No | Time window in hours. Default: 24, max: 72 |
113+
| `limit` | int | No | Maximum paths to return. Default: 20, max: 50 |
114+
| `min_distance` | int | No | Minimum distance in km (e.g., 15000 for near-antipodal) |
115+
116+
### wspr_snr_trend
117+
118+
Hourly SNR trend for a specific path. Shows when a band opens/closes and how signal strength varies.
67119

68120
| Parameter | Type | Required | Description |
69121
|-----------|------|:--------:|-------------|
70-
| `tx_grid` | str | Yes | Transmitter grid square (e.g., DN13, FN31) |
71-
| `rx_grid` | str | Yes | Receiver grid square (e.g., JN48, IO91) |
122+
| `tx` | str | Yes | First endpoint — callsign (e.g., K9AN) or grid (e.g., EN50) |
123+
| `rx` | str | Yes | Second endpoint — callsign (e.g., G8JNJ) or grid (e.g., IO91) |
124+
| `band` | str | No | Filter to a specific band (e.g., "20m") |
125+
| `hours` | int | No | Time window in hours. Default: 24, max: 72 |
126+
127+
Returns hourly data points with spot counts, avg/best/worst SNR.
128+
129+
---
72130

73-
Returns per-band propagation data with spot counts, SNR stats, and open hours.
131+
## Good Neighbour Policy
132+
133+
wspr.live is a volunteer-run service. We are respectful with our query patterns:
134+
135+
| Measure | Detail |
136+
|---------|--------|
137+
| Rate limiting | 3 seconds between requests (20 req/min) |
138+
| Circuit breaker | Opens after 3 consecutive failures; exponential backoff up to 5 minutes |
139+
| Time-bounded queries | Every query filters by time (max 72 hours) |
140+
| Band filtering | Queries use band indexes when provided |
141+
| Column selection | Only needed columns per query, never `SELECT *` |
142+
| Result limits | All queries cap results (200 spots, 50 leaderboard entries) |
143+
| Response caching | 2-10 minute TTL per tool |
144+
| Request timeout | 20 seconds |
145+
| User-Agent | Every request identifies as `wspr-mcp/{version}` |
74146

75147
---
76148

0 commit comments

Comments
 (0)