Metadata-Version: 2.4
Name: mcbirdcage
Version: 2026.2.18
Summary: MCP server for Winegard satellite dish control via serial
Project-URL: Repository, https://git.supported.systems/warehack.ing/birdcage
Project-URL: Documentation, https://birdcage.warehack.ing
Author-email: Ryan Malloy <ryan@supported.systems>
License-Expression: MIT
Keywords: amateur-radio,antenna,mcp,satellite,winegard
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Communications :: Ham Radio
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.0
Requires-Dist: winegard-birdcage
Description-Content-Type: text/markdown

# mcbirdcage

[MCP](https://modelcontextprotocol.io/) server for controlling Winegard satellite dishes through conversational tools. Built on [FastMCP](https://gofastmcp.com/), exposes 36 tools for dish positioning, signal analysis, firmware inspection, and satellite pass planning.

## Install

```bash
# Add to Claude Code
claude mcp add mcbirdcage -- uvx mcbirdcage

# Or run standalone
uvx mcbirdcage
```

## Demo Mode

No dish required. Set `BIRDCAGE_DEMO=1` to get simulated responses for all tools:

```bash
BIRDCAGE_DEMO=1 uvx mcbirdcage
```

## Tools

36 tools across six groups:

| Group | Count | Examples |
|-------|-------|---------|
| Connection | 3 | `connect`, `disconnect`, `status` |
| Movement | 9 | `get_position`, `move_to`, `home_motor`, `stow` |
| Signal | 8 | `get_rssi`, `enable_lna`, `az_sweep`, `get_lock_status` |
| System | 11 | `nvs_dump`, `get_firmware_id`, `set_pid_gains`, `get_a3981_diag` |
| Satellite | 4 | `search_satellites`, `get_passes`, `get_visible_targets` |
| Console | 1 | `send_raw_command` (direct firmware access) |

Plus 5 resources (hardware specs, NVS reference, firmware docs) and 3 prompts.

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `BIRDCAGE_DEMO` | `0` | Enable demo mode (no hardware) |
| `BIRDCAGE_PORT` | `/dev/ttyUSB0` | Serial port path |
| `BIRDCAGE_FIRMWARE` | `hal205` | Firmware variant (`hal000`, `hal205`, `g2`) |
| `BIRDCAGE_CRAFT_URL` | -- | Craft API URL for live satellite TLEs |

## Documentation

Full tool reference and hardware setup: **[birdcage.warehack.ing](https://birdcage.warehack.ing)**

## Credits

- **Gabe Emerson (KL1FI / [saveitforparts](https://github.com/saveitforparts))** -- original Winegard rotor scripts
- **Chris Davidson ([cdavidson0522](https://github.com/cdavidson0522))** -- Carryout G2 sky scan and rotator control

## License

MIT
