# shack-mcp

**Give Claude a ham radio.** An [MCP](https://modelcontextprotocol.io) server that lets an LLM operate an amateur radio shack: query live APRS traffic, predict satellite passes, schedule SDR captures, and monitor FT8/WSPR band activity.

> Status: under construction. Done: M1 (storage core), M2 (zero-hardware replay demo), M3 (live APRS: rtl_fm → direwolf → KISS TCP, plus `shack fixtures import` for your old packet dumps), M4 (Celestrak TLEs, pass prediction, Doppler — `predict_passes` over MCP), M5 (capture scheduling + cooperative hardware arbitration: priority leases, preemption hand-off, command queue), M6 (band-rotating FT8/WSPR monitor: slot-aligned WAV slicing, jt9/wsprd decoders, park/resume, `get_band_activity`). Next: M7 prompts + polish.

## Why

Thousands of MCP servers exist for databases and SaaS tools. Approximately zero exist for RF. This one turns a $30 RTL-SDR and a rooftop antenna into a set of tools Claude can reason with:

> *"Who's been heard on 2m in the last hour? When's the next ISS pass over 30°, and which antenna should I grab? Is 20m open to Japan?"*

## Design

```
[RTL-SDR / HackRF]                     [Claude Code / Claude Desktop]
      │                                          │ stdio
 collector daemons (systemd)              MCP server (stateless)
      │ decoded frames/spots                    │ reads tables,
      ▼                                         ▼ enqueues commands
 ┌───────────── SQLite + WAL (shack.db) ─────────────┐
 └────────────────────────────────────────────────────┘
```

- **Collector daemons own the radios** and write decodes to SQLite. The MCP server is a stateless query-and-command layer. No LLM calls anywhere in this repo — the model lives on the client side of the protocol.
- **Replay mode is first-class**: recorded fixtures let you run the entire demo (and CI) with no hardware, no antenna, and no license.
- **One radio, many suitors**: an RTL-SDR tunes one place at a time. Priority leases with cooperative preemption arbitrate between ambient APRS listening and scheduled satellite captures.

## Quick start (no hardware needed)

```bash
git clone <repo> && cd shack-mcp
python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
cp .env.example .env
.venv/bin/shack db init
.venv/bin/shack demo        # replays recorded APRS traffic and serves MCP
```

Then attach a client — see `docs/` for Claude Code (`claude mcp add`) and Claude Desktop config.

## Learning in public

This repo doubles as a teaching project. Each milestone has a lesson in `docs/lessons/` and **challenge tests**: run `pytest -m challenge`, open the matching stub in `challenges/`, and implement until green. The reference implementations live in `src/`, so the app always works even while you're mid-challenge.

## Roadmap

POCSAG, ADS-B, Meteor LRPT decode chains — the collector/decoder Protocol seams are designed for community contributions. See CONTRIBUTING (coming with M7).

## License

MIT