# radio-free-ai

A local MCP server for ham radio, built around [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) so tools can render interactive UI in the host.

Right now it's a map: grayline, Maidenhead grids, and points the model can add and remove while the map is on screen.

## Installing in Claude

This repo is a Claude plugin marketplace. The plugin includes the Radio Free AI server and skills for using the map on the air. Claude starts the server on your computer when it needs it.

You need [Node.js](https://nodejs.org) 20 or later installed and on your PATH. An installer that removes this requirement is coming.

1. Add the marketplace `guyroyse/radio-free-ai` in Claude.
2. Install the `radio-free-ai` plugin.
3. Ask Claude to show you the radio map.

In Claude Code, steps 1 and 2 are one command:

```
/plugin install radio-free-ai --marketplace guyroyse/radio-free-ai
```

The plugin lives in [`plugins/radio-free-ai`](plugins/radio-free-ai):

- `.claude-plugin/plugin.json` starts the bundled server over stdio
- `server/` holds the built server and map view, committed because plugins install straight from git
- `skills/radio-map` teaches Claude how to drive the map tools
- `skills/maidenhead-and-grayline` covers grid locators, grid chasing, and grayline propagation

## Running

```sh
npm install
npm run build        # builds the view and the stdio server into plugins/radio-free-ai/server, then typechecks
npm start            # runs the bundled server on stdio
npm run start:http   # runs the server over HTTP on http://127.0.0.1:3737/mcp
```

Run `npm run build` and commit `plugins/radio-free-ai/server` whenever the source changes, or the plugin ships stale code.

The HTTP server is for sharing one server between several clients or machines, and is where the stdio server will eventually relay to. `RADIO_FREE_AI_HOST` and `RADIO_FREE_AI_PORT` override its bind address. It binds to loopback by default; the Host and Origin checks in `src/server/http.ts` will need loosening before it can serve the LAN.

Opening `plugins/radio-free-ai/server/map.html` directly in a browser shows the view with demo data.

## Tools

| Tool | Who | What |
| --- | --- | --- |
| `show_map` | model | Renders the map; can set options and add points/grids in one call |
| `add_to_map` | model | Upserts points (by id) and highlighted grids |
| `remove_from_map` | model | Removes by point id, grid, or group; no arguments clears everything |
| `set_map_options` | model, app | Projection, grayline, grid overlay, paths, home QTH |
| `get_map_state` | app | Polled by the view so it picks up changes from later tool calls |
| `maidenhead` | model | Grid ↔ lat/lon, plus distance and heading from home |

Locations are either a Maidenhead grid (`FN31`, `FN31pr`) or `{ lat, lon }`.

## Privacy

The Radio Free AI server runs on your own computer and talks only to the Claude app that started it. The map is drawn from data bundled with the app, so showing it sends nothing over the network. Your callsign, grid, and anything you put on the map stay in the server's memory on your machine and are gone when it stops. Claude sees what its tools send back, as with any MCP server.

## Layout

- `src/server` — the stdio and HTTP entry points, tool registration, and the `MapStore` that holds map state
- `src/view` — the MCP App, bundled to one self-contained HTML file because hosts sandbox it with no external origins
- `src/shared` — Maidenhead and great-circle math used by both