pterasim-mcp - UVLM + surrogate aerodynamics for MCP agents

TL;DR: Expose PteraSoftware's analytical/UVLM solvers through MCP so agents can request aerodynamic coefficients with provenance metadata.

What it provides

Scenario	Value
Surrogate aerodynamics	Evaluate lightweight rigid-vortex-lattice models without a GUI, returning aerodynamic coefficients as structured data.
High-fidelity UVLM	When PteraSoftware is installed, the service switches to its UVLM solver and records provenance metadata.
Controller integration	Provide consistent outputs that downstream MCP tools (e.g., `ctrltest-mcp` ) can ingest for control and evidence pipelines.

Quickstart

1. Install

uv pip install "git+https://github.com/Three-Little-Birds/pterasim-mcp.git"

2. Run an analytic solve

from pterasim_mcp import PterasimInput, simulate_pterasim request = PterasimInput( span_m=0.8, mean_chord_m=0.12, stroke_frequency_hz=12.0, stroke_amplitude_rad=0.55, cruise_velocity_m_s=6.0, air_density_kg_m3=1.225, cl_alpha_per_rad=6.2, cd0=0.03, planform_area_m2=0.18, ) response = simulate_pterasim(request) print(response.metadata["solver"]) # "analytic" or "pterasoftware_uvlm" print(response.thrust_N, response.lift_N, response.torque_Nm) Typical metadata payload: ```json { "solver": "pterasoftware_uvlm", "thrust_delta_pct_vs_analytic": -4.1, "lift_delta_pct_vs_analytic": -2.7 }

If a Python 3.13 environment with `PteraSoftware` (≥3.2) is available, the wrapper will prefer UVLM and note the solver in the metadata. Install it inside a dedicated environment: ```bash uv python install 3.13 uv venv .venv-pterasim --python 3.13 source .venv-pterasim/bin/activate pip install pterasoftware==3.2.0 uv pip install "git+https://github.com/Three-Little-Birds/pterasim-mcp.git"

If the UVLM solve fails for any reason (missing binaries, convergence issues, or the current PteraSoftware regression that removes geometry.airfoil), the wrapper logs a warning and falls back to the analytic surrogate—you will see solver: "analytic" in the metadata and no delta fields. UVLM runs with thousands of timesteps can take minutes; batch analytic sweeps first and promote only promising cases to the high-fidelity environment. Analytic-only mode works on Python 3.11 without PteraSoftware. Until the UVLM API stabilizes upstream, treat the analytic path as the supported/default mode.

Run as a service

CLI (STDIO / Streamable HTTP)

uvx pterasim-mcp # runs the MCP over stdio # or python -m pterasim_mcp python -m pterasim_mcp --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp

Use python -m pterasim_mcp --describe to emit metadata without starting the server.

FastAPI (REST)

uv run uvicorn pterasim_mcp.fastapi_app:create_app --factory --port 8003

python-sdk tool (STDIO / MCP)

from mcp.server.fastmcp import FastMCP from pterasim_mcp.tool import build_tool mcp = FastMCP("pterasim-mcp", "Wing UVLM & surrogate solver") build_tool(mcp) if __name__ == "__main__": mcp.run()

ToolHive smoke test

uvx --with 'mcp==1.20.0' python scripts/integration/run_pterasim.py # ToolHive 2025+ defaults to Streamable HTTP; match that transport when registering # the workload manually so IDE clients avoid the SSE 502 bug.

Agent playbook

Scenario sweeps - vary span, frequency, or flapping amplitude and log derivatives for control studies.
Solver comparison - leverage metadata to benchmark surrogate vs UVLM deltas and store the comparisons for regression dashboards.
Design flows - combine with openvsp-mcp to generate geometry + aerodynamics pipelines.

Stretch ideas

Generate JSONL experiment logs that feed directly into ctrltest-mcp or reinforcement-learning agents.
Use the metadata to route results into Grafana dashboards for solver provenance.
Auto-promote surrogate runs to UVLM once a high-fidelity environment is detected.

Accessibility & upkeep

Tests simulate solver responses; run uv run pytest before pushing.
Keep .venv-pterasim aligned with the PteraSoftware version you report in metadata.

Contributing

uv pip install --system -e .[dev]
Run uv run ruff check . and uv run pytest
Include sample metadata/CSV artefacts in PRs so reviewers can confirm provenance handling.

MIT license - see LICENSE.