Skip to main content
Glama
Three-Little-Birds

Flappy MCP Server

by Three-Little-Birds
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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

Related MCP server: OpenVSP MCP Server

What it provides

Scenario

Value

Flappy CLI automation

Drive the Purdue BioRobotics Flappy simulator 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

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.

Available Tools

1 tool
flappy.simulateC

Run the Flappy dynamics simulator for a mission profile. Provide wing morphology, control schedule, and duration. Returns pose histories, energy metrics, and solver provenance. Example: {"scenario_id":"demo","duration_s":8.0}

ParametersJSON Schema
NameRequiredDescriptionDefault
requestYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
sourceYes
scenarioNo
trajectoryYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It mentions what the tool returns (pose histories, energy metrics, solver provenance) but doesn't disclose behavioral traits like computational cost, error conditions, or whether it's read-only or mutating. The example is helpful but insufficient for full transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded with the core purpose. The second sentence details inputs and outputs, and the third provides an example. Each sentence adds value, though the example could be more integrated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (dynamics simulator with 1 parameter but nested schema), no annotations, and an output schema (which handles return values), the description is moderately complete. It covers purpose, inputs, and outputs, but lacks usage context and detailed parameter semantics, leaving gaps for effective tool invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It lists required inputs (wing morphology, control schedule, duration) and provides an example, but doesn't explain parameter meanings, formats, or constraints beyond the schema. The example clarifies the structure but leaves semantics vague.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Run the Flappy dynamics simulator for a mission profile.' It specifies the action (run simulator), target (Flappy dynamics simulator), and context (mission profile). However, with no sibling tools, differentiation isn't needed, so it doesn't reach the highest score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It mentions an example but doesn't explain prerequisites, constraints, or typical use cases. With no sibling tools, this is less critical, but still lacks context for effective tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3/5.0
Disambiguation5/5

With only one tool, there is no possibility of ambiguity or overlap between tools. The single tool 'flappy.simulate' has a clearly defined and distinct purpose for running a Flappy dynamics simulator.

Naming Consistency5/5

Since there is only one tool, naming consistency is inherently perfect. The tool name 'flappy.simulate' follows a clear verb_noun pattern with no deviations or mixing of conventions.

Tool Count2/5

A single tool is too few for the apparent scope of a Flappy dynamics simulator server, which typically involves complex mission profiles, morphology, and control schedules. This minimal toolset feels thin and likely incomplete for the domain.

Completeness2/5

The tool surface is severely incomplete for a dynamics simulator domain. There are obvious gaps such as tools for configuring scenarios, retrieving past simulations, managing mission profiles, or analyzing results, which will cause agent failures in typical workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Three-Little-Birds/flappy-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server