# 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.