flappy-mcp - Bio-inspired flapping dynamics for MCP agents

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

2. Quickstart

3. Run as a service

4. Agent playbook

5. Stretch ideas

6. Install & maintenance

7. Contributing

What it provides

Quickstart

1. Install the wrapper

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 for contact details) and point this wrapper to the resulting flappy_cli binary:

export FLAPPY_BIN=/path/to/flappy_cli

2. Simulate a trajectory

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)

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)

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)

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:

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 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.