flappy-mcp

License: MIT Python

Reusable Model Context Protocol (MCP) toolkit for the Flappy avian dynamics simulator. The package exposes typed request models, CLI execution helpers, and python-sdk integration so any project can trigger Flappy simulations or rely on a deterministic sinusoidal fallback without inheriting Orthodrone-specific schema.

Features

Writes Flappy configuration JSON, invokes flappy_cli, and returns parsed trajectories.
Includes a deterministic analytic fallback (sinusoidal stroke) when the binary is absent.
FastAPI app factory and python-sdk helper for rapid MCP integration.
Fully typed, MIT-licensed, and covered by tests.

Installation

pip install "git+https://github.com/yevheniikravchuk/flappy-mcp.git"

FastAPI usage

from flappy_mcp.fastapi_app import create_app app = create_app()

Run locally:

uv run uvicorn flappy_mcp.fastapi_app:create_app --factory --host 127.0.0.1 --port 8004

python-sdk usage

from mcp.server.fastmcp import FastMCP from flappy_mcp.tool import build_tool app = FastMCP("flappy-mcp", "Flappy dynamics simulator") build_tool(app) if __name__ == "__main__": app.run()

Example STDIO request

{ "tool": "flappy-mcp.run", "arguments": { "scenario": { "simulation": {"duration_s": 2.0, "timestep_s": 0.02}, "control": {"stroke_amplitude_rad": 0.3, "stroke_frequency_hz": 4.0} } } }

Environment variables

FLAPPY_BIN (default flappy_cli) — set to the compiled Flappy executable.

Local development

uv pip install --system -e .[dev] uv run ruff check . uv run pytest

License

MIT — see LICENSE.

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Enables running avian flight dynamics simulations through the Flappy simulator. Provides typed configuration models and deterministic fallback calculations for bird flight analysis.

Flappy MCP Server