Metadata-Version: 2.4
Name: mcbebop
Version: 2026.10.2
Summary: MCP server for the Parrot Bebop 2 drone: telemetry, camera, files, and every ARSDK command
Keywords: mcp,drone,parrot,bebop,arsdk,fastmcp
Author: Ryan Malloy
Author-email: Ryan Malloy <ryan@supported.systems>
License-Expression: MIT AND BSD-3-Clause
License-File: LICENSE
License-File: LICENSE-arsdk-xml
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Dist: fastmcp>=4.0.10,<5
Requires-Dist: pydantic-settings>=2.7
Requires-Dist: zeroconf>=0.147
Requires-Dist: pillow>=11.0
Requires-Python: >=3.12
Project-URL: Homepage, https://bebop-2.warehack.ing
Project-URL: Repository, https://git.supported.systems/warehack.ing/mcbebop
Project-URL: Issues, https://git.supported.systems/warehack.ing/mcbebop/issues
Description-Content-Type: text/markdown

# mcbebop

An MCP server for the Parrot Bebop 2, so an agent can talk to the drone without
anyone writing code for each question.

Parrot abandoned the Bebop line, but the aircraft is still a capable, cheap
platform and its protocol is fully described by Parrot's own XML, which this
package vendors. Every one of the **264 commands** is reachable; nothing is
hand-wrapped.

> **Status: in development.** Not flight-tested. See the safety section.

## What it talks to

| Interface | Notes |
|---|---|
| ARSDK3 over UDP | commands and telemetry; this package implements the protocol directly |
| ARStream2 | live H.264 video. The Bebop 2 serves no RTSP, despite what older libraries assume |
| FTP | media, flight plans, blackbox logs |
| Telnet | read-only shell, only after the drone's debug mode is enabled |

## Safety

Commands are classified by consequence. Observing and configuring are open;
anything that can spin a motor or change the flight envelope refuses until
`arm()` is called with a reason, and re-locks on a timer and on disconnect.
`Landing` and `Emergency` are deliberately never locked, because refusing to
land an airborne aircraft is the more dangerous answer.

`connect(target="sim")` runs everything against a protocol-accurate simulator,
which is where anything involving motion should be rehearsed.

## The simulator streams video

The simulator can push RTP/H.264 exactly as the aircraft does, so a viewer's
whole video path can be developed and measured without a drone. It answers the
handshake with `arstream2_server_stream_port: 5004`, sends nothing until
`ardrone3.MediaStreaming.VideoEnable` arrives with 1, then streams from its own
5004 to whatever `arstream2_client_stream_port` the client named, and stops on a
0, on a link loss, or at shutdown.

```bash
python -m mcbebop.sim --video clip.h264                 # steady 30 fps
python -m mcbebop.sim --video clip.h264 --start-offset random --seed 7
python -m mcbebop.sim --video flight.rtpcap             # a real capture, replayed
```

`MCBEBOP_SIM_VIDEO_SOURCE=clip.h264` does the same for `connect(target="sim")`.

Two kinds of source, and they are **different instruments**:

| Source | Pacing | Use it for |
|---|---|---|
| `.h264` Annex-B elementary stream | packetised here, steady frame rate | does the decoder work, does the renderer work |
| `.rtpcap` capture off the aircraft | the recorded inter-packet gaps, packet for packet | latency and jitter, bursts, loss behaviour |

Make the first from any video, at the resolution the aircraft streams:

```bash
ffmpeg -i anything.mp4 -t 10 -vf scale=856:480 -r 30 \
  -c:v libx264 -preset ultrafast -pix_fmt yuv420p -g 30 -f h264 clip.h264
```

`-f h264` already writes Annex-B, so no bitstream filter is wanted;
`h264_mp4toannexb` converts the other direction and ffmpeg rejects it here.

Make the second from a real drone. Start the recorder first, because RTP is
connectionless and anything sent before the bind is gone, then enable video
from a session that holds the ARSDK link:

```bash
python -m mcbebop.media.capture flight.rtpcap --seconds 30   # binds 55004
```

`--start-offset random` is worth knowing about. It begins mid-GOP, which is
what a viewer switched on while the drone is already flying is handed, and
`--seed` makes a failure repeatable. Parameter sets repeat about once a second
on the packetised path, which is what lets a late joiner recover at all.

## Install

```bash
uvx mcbebop
claude mcp add mcbebop -- uvx mcbebop
```

## Licence

This package is MIT (`LICENSE`), and it vendors one third-party component:
`src/mcbebop/arsdk-xml/` is Parrot SA's own protocol definition, BSD-3-Clause
(`LICENSE-arsdk-xml`). It ships in both the sdist and the wheel because nothing
here can decode a single command without it. What that snapshot is and how it
differs from upstream is recorded in `arsdk-xml/PROVENANCE.md`.

So the distribution as a whole is `MIT AND BSD-3-Clause`.
