Metadata-Version: 2.4
Name: pterasim-mcp
Version: 0.1.0
Summary: Pterasim MCP helper with analytic fallback
Author: Pterasim MCP Maintainers
License: MIT License
Copyright (c) 2025, Three Little Birds
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Project-URL: Homepage, https://github.com/Three-Little-Birds/pterasim-mcp
Project-URL: Repository, https://github.com/Three-Little-Birds/pterasim-mcp
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.20
Requires-Dist: fastapi<1.0,>=0.121
Requires-Dist: pydantic>=2.11
Provides-Extra: dev
Requires-Dist: pytest>=8.4; extra == "dev"
Requires-Dist: ruff>=0.14; extra == "dev"
Requires-Dist: httpx>=0.28; extra == "dev"
Dynamic: license-file
# 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).