OpenVSP MCP Server

# openvsp-mcp - Parametric geometry for MCP workflows <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/openvsp-mcp/actions/workflows/ci.yml"><img src="https://github.com/Three-Little-Birds/openvsp-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**: Automate [OpenVSP](https://openvsp.org/) geometry edits and VSPAero runs so agents can generate meshes, scripts, and aerodynamic coefficients without manual GUI steps. ## 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 | |----------|-------| | OpenVSP scripting | Automate [OpenVSP](https://openvsp.org/) commands (set parameters, duplicate geometries, export meshes) without opening the GUI. | | VSPAero batch runs | Launch [VSPAero](https://vspu.larc.nasa.gov/) cases and capture generated metrics/CSV files for downstream optimisation. | | MCP transport | Publish the same functionality over STDIO or HTTP via the Model Context Protocol so ToolHive or other clients can drive geometry studies remotely. | ## Quickstart ### 1. Install the package ```bash uv pip install "git+https://github.com/Three-Little-Birds/openvsp-mcp.git" ``` Install the official binaries from the [OpenVSP download page](https://openvsp.org/download.php) (this wrapper was tested with OpenVSP/VSPAero 3.46.0 on macOS). Verify they are in your `PATH`: ```bash export OPENVSP_BIN=/Applications/OpenVSP/vsp export VSPAERO_BIN=/Applications/OpenVSP/vspaero ``` > **Tip (macOS/Linux):** if you prefer to avoid GUI installers, build the repo's ToolHive image and run the examples inside Docker: > ```bash > docker build -t openvsp-mcp-toolhive -f infra/docker/openvsp_toolhive/Dockerfile . > docker run --rm --entrypoint /usr/local/bin/vsp openvsp-mcp-toolhive --version > ``` > Mount your geometry directory and set `OPENVSP_BIN=/usr/local/bin/vsp` when executing the Python snippets in-container. ### 2. Run a scripted geometry edit ```python from importlib import resources import shutil import tempfile from pathlib import Path from openvsp_mcp import OpenVSPRequest, VSPCommand, execute_openvsp with resources.as_file(resources.files("openvsp_mcp.data") / "rect_wing.vsp3") as bundled: with tempfile.TemporaryDirectory(prefix="openvsp_mcp_") as tmpdir: geometry_path = Path(tmpdir) / "rect_wing.vsp3" shutil.copy(bundled, geometry_path) request = OpenVSPRequest( geometry_file=str(geometry_path), set_commands=[ VSPCommand(command='string geom_id = FindGeom("RectWing", 0)'), VSPCommand(command='string span_id = GetParm( geom_id, "TotalSpan", "WingGeom" )'), VSPCommand(command='SetParmVal( span_id, 12.0 )'), VSPCommand(command='Update()'), ], run_vspaero=False, case_name="rectwing_span12", ) response = execute_openvsp(request) print("Script used:", response.script_path) print("ADB path:", response.result_path) # None unless run_vspaero=True ``` `OpenVSPResponse` contains: - `script_path` – absolute path to the generated `.vspscript` you can archive for repeatability. - `result_path` – VSPAero `.adb` file (string) when `run_vspaero=True`, otherwise `None`. Meshes, CSVs, and other artefacts are emitted by OpenVSP next to your original `.vsp3`. Need a starter geometry? The package ships with `openvsp_mcp.data/rect_wing.vsp3`, generated from a single OpenVSP wing primitive. The snippet above uses OpenVSP script helpers (`FindGeom` + `GetParm`) so it works out of the box. For your own models, open the geometry in the GUI, note the component name returned by `FindGeom`, and update the commands accordingly. ## Run as a service ### CLI (STDIO / Streamable HTTP) ```bash uvx openvsp-mcp # runs the MCP over stdio # or python -m openvsp_mcp python -m openvsp_mcp --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp ``` Registered tools: - `openvsp.inspect` – describe a geometry without modifying it. - `openvsp.modify` – apply scripted parameter edits (no VSPAero). - `openvsp.run_vspaero` – run edits followed by VSPAero. Use `python -m openvsp_mcp --describe` to list the tools at runtime. ### FastAPI (REST) ```bash uv run uvicorn openvsp_mcp.fastapi_app:create_app --factory --port 8002 ``` Endpoints: - `POST /vsp/inspect` → `OpenVSPInspectResponse` - `POST /vsp/modify` → run edits only - `POST /vsp/run` → run edits + VSPAero All operations return structured JSON; explore them via the interactive docs at `http://127.0.0.1:8002/docs`. ### python-sdk tool (STDIO / MCP) ```python from mcp.server.fastmcp import FastMCP from openvsp_mcp.tool import build_tool mcp = FastMCP("openvsp-mcp", "OpenVSP automation") build_tool(mcp) if __name__ == "__main__": mcp.run() ``` Then launch with `uv run mcp dev examples/openvsp_tool.py` and connect your agent. ### ToolHive smoke test Requires exported binaries and a geometry file reachable inside the container: ```bash export OPENVSP_BIN=/path/to/vsp export VSPAERO_BIN=/path/to/vspaero # optional export OPENVSP_GEOMETRY=/path/to/model.vsp3 uvx --with 'mcp==1.20.0' python scripts/integration/run_openvsp.py # ToolHive 2025+ defaults to Streamable HTTP; select the same transport when registering # the workload manually to avoid the legacy SSE 502 proxy issue. ``` ## Agent playbook - **Geometry studies** - script sweep operations (span, twist, control surface deflections) and archive each variant. - **Aerodynamic coefficients** - hand VSPAero results to `ctrltest-mcp` or custom controllers. - **Mesh exports** - agents can request STL/OBJ assets for CFD or manufacturing pipelines. ## Stretch ideas 1. Pair with `foam-agent-mcp-core` to auto-generate mesh-ready cases. 2. Use deck.gl to visualise planform edits by surfacing geometry metadata in the response. 3. Schedule nightly configuration sweeps (span x sweep x incidence) and store the results for design-of-experiments studies. ## Accessibility & upkeep - Run `uv run pytest` before committing; tests mock VSPAero calls so they finish quickly. - Keep OpenVSP/VSPAero versions consistent across developers to avoid geometry mismatches. ## Contributing 1. `uv pip install --system -e .[dev]` 2. Run `uv run ruff check .` and `uv run pytest` 3. Submit PRs with sample scripts or geometry diffs so reviewers can validate quickly. MIT license - see [LICENSE](LICENSE). - OpenVSP ships under NASA’s license; VSPAero usage must comply with the terms that accompany your download. Commercial redistribution generally requires a separate agreement—check the [official FAQ](https://openvsp.org/#license) before packaging binaries into your MCP workloads.