README.md•4.96 kB
# flappy-mcp - Bio-inspired flapping dynamics for MCP agents
<p align="center">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
<a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.10%2B-3776AB.svg" alt="Python 3.10 or newer"></a>
<a href="https://github.com/Three-Little-Birds/flappy-mcp/actions/workflows/ci.yml"><img src="https://github.com/Three-Little-Birds/flappy-mcp/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
<img src="https://img.shields.io/badge/MCP-tooling-blueviolet.svg" alt="MCP tooling badge">
</p>
> **TL;DR**: Control the Purdue BioRobotics "Flappy" simulator through MCP so agents can explore flapping-wing dynamics and log trajectories without headless GUIs.
## Table of contents
1. [What it provides](#what-it-provides)
2. [Quickstart](#quickstart)
3. [Run as a service](#run-as-a-service)
4. [Agent playbook](#agent-playbook)
5. [Stretch ideas](#stretch-ideas)
6. [Install & maintenance](#install--maintenance)
7. [Contributing](#contributing)
## What it provides
| Scenario | Value |
|----------|-------|
| Flappy CLI automation | Drive the Purdue BioRobotics [Flappy simulator](https://engineering.purdue.edu/SMARTLab/research/flappingflight) from Python or MCP without bespoke shell scripts. |
| Trajectory logging | Collect pose, velocity, and energy histories as JSON for reinforcement learning or system-identification studies. |
| MCP transport | Expose the CLI via STDIO/HTTP so ToolHive and other clients can batch missions or plug results into `ctrltest-mcp`.
## Quickstart
### 1. Install the wrapper
```bash
uv pip install "git+https://github.com/Three-Little-Birds/flappy-mcp.git"
```
Build the CLI from the Purdue SMARTLab Flappy sources (partners receive access on request—see the [research page](https://engineering.purdue.edu/SMARTLab/research/flappingflight) for contact details) and point this wrapper to the resulting `flappy_cli` binary:
```bash
export FLAPPY_BIN=/path/to/flappy_cli
```
### 2. Simulate a trajectory
```python
from flappy_mcp import FlappyRequest, execute_flappy
request = FlappyRequest(
scenario=None,
fallback={"duration_s": 5.0, "timestep_s": 0.01},
)
response = execute_flappy(request)
print("Trajectory points:", len(response.trajectory))
print("Source:", response.source) # "generated" or path to CLI JSON
print("First sample:", response.trajectory[0].model_dump())
```
## Run as a service
### CLI (STDIO transport)
```bash
uvx flappy-mcp # runs the MCP over stdio
# or python -m flappy_mcp
```
Use `python -m flappy_mcp --describe` to inspect metadata without starting the server.
### FastAPI (REST)
```bash
uv run uvicorn flappy_mcp.fastapi_app:create_app --factory --port 8004
```
Invoke via the auto-generated docs at `http://127.0.0.1:8004/docs`.
### python-sdk tool (STDIO / MCP)
```python
from mcp.server.fastmcp import FastMCP
from flappy_mcp.tool import build_tool
mcp = FastMCP("flappy-mcp", "Flapping dynamics simulator")
build_tool(mcp)
if __name__ == "__main__":
mcp.run()
```
Launch with `uv run mcp dev examples/flappy_tool.py` and wire in your agent.
### ToolHive smoke test
Requires the Flappy CLI executable:
```bash
export FLAPPY_BIN=/path/to/flappy_cli
uvx --with 'mcp==1.20.0' python scripts/integration/run_flappy.py
```
## Agent playbook
- **Policy tuning** - sweep control inputs and feed trajectories into reinforcement-learning pipelines.
- **Sensor synthesis** - generate inertial traces for testing perception/estimation stacks.
- **Energy studies** - derive energy usage from the returned stroke kinematics or augment the scenario before launching the CLI.
## Stretch ideas
1. Couple with `diffsph` gradients to evaluate loads alongside motion.
2. Feed trajectories into `ctrltest-mcp` for closed-loop evaluation.
3. Build deck.gl overlays of position data for mission rehearsal.
## Install & maintenance
- **Runtime install:** follow the [Quickstart](#quickstart) `uv pip install "git+https://github.com/Three-Little-Birds/flappy-mcp.git"` step on machines that need the MCP wrapper.
- **Validate dependencies:** set `FLAPPY_BIN` to the compiled `flappy_cli` path, run `$FLAPPY_BIN --help`, and confirm the simulator launches without interactive prompts.
- **Runtime expectations:** CLI runs block until completion and may take several minutes for long scenarios; the built-in sinusoidal fallback returns instantly. All trajectories are returned as lists of `{t, angle}` samples in SI units so downstream controllers can replay them verbatim.
- **Keep fixtures in sync:** document any generated trajectories or fixture updates so downstream services can replay them reliably.
## Contributing
1. `uv pip install --system -e .[dev]`
2. Run `uv run ruff check .` and `uv run pytest`
3. Submit sample trajectories or metrics with your PR so reviewers can validate quickly.
MIT license - see [LICENSE](LICENSE).