README.md•5.43 kB
# pterasim-mcp - UVLM + surrogate aerodynamics 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/pterasim-mcp/actions/workflows/ci.yml"><img src="https://github.com/Three-Little-Birds/pterasim-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**: Expose PteraSoftware's analytical/UVLM solvers through MCP so agents can request aerodynamic coefficients with provenance metadata.
## 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. [Accessibility & upkeep](#accessibility--upkeep)
7. [Contributing](#contributing)
## 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](https://github.com/pterasoftware/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
```bash
uv pip install "git+https://github.com/Three-Little-Birds/pterasim-mcp.git"
```
### 2. Run an analytic solve
```python
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)
```bash
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)
```bash
uv run uvicorn pterasim_mcp.fastapi_app:create_app --factory --port 8003
```
### python-sdk tool (STDIO / MCP)
```python
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
```bash
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
1. Generate JSONL experiment logs that feed directly into `ctrltest-mcp` or reinforcement-learning agents.
2. Use the metadata to route results into Grafana dashboards for solver provenance.
3. 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
1. `uv pip install --system -e .[dev]`
2. Run `uv run ruff check .` and `uv run pytest`
3. Include sample metadata/CSV artefacts in PRs so reviewers can confirm provenance handling.
MIT license - see [LICENSE](LICENSE).