openmdao-mcp
# openmdao-mcp
`openmdao-mcp` is a domain-agnostic Model Context Protocol server for
[OpenMDAO](https://openmdao.org/) 3.45. It builds `om.Problem` instances from
declarative, validated specifications (components, nested groups, coupling
solvers, design variables, drivers) instead of hard-coded model topologies,
and it has no dependency on any discipline-specific analysis code.
It targets conceptual-design MDAO of the kind used in rotorcraft sizing:
coupled feedback loops converged by `NonlinearBlockGS` or Newton, black-box
command-line solvers, Latin-hypercube seed generation, finite-difference noise
diagnostics, and multi-start SLSQP. Development happens on Windows; production
runs on headless Rocky Linux 9.8.
[`REFACTOR_PLAN.md`](REFACTOR_PLAN.md) records the design, the full schema
catalogue, and the implementation history.
## Quickstart
Requires Python 3.12+. Dependencies go into a local `.venv` with `pip`.
Windows:
```powershell
python -m venv .venv
.\.venv\Scripts\pip.exe install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest
```
Linux:
```bash
python3.12 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest
```
Run the end-to-end example (Sellar problem: coupled loop, scaled SLSQP, active constraints):
```bash
PYTHONPATH=src python examples/client/sellar_mdao_workflow.py
```
## Running the server
Local use over stdio (the default transport):
```bash
openmdao-mcp --transport stdio
```
Remote use over streamable HTTP:
```bash
openmdao-mcp --transport streamable-http --host 127.0.0.1 --port 8765 --allowed-commands /opt/solvers/bin/rotor_perf
```
| Option | Meaning |
|--------|---------|
| `--transport {stdio,streamable-http}` | Default `stdio`. |
| `--host`, `--port`, `--path` | HTTP only. `--host` defaults to `127.0.0.1`. |
| `--workdir DIR` | Problem specs, recordings and external-code runs. Default `$OPENMDAO_MCP_WORKDIR`, else `~/.openmdao_mcp`. |
| `--allowed-commands LIST` | Comma-separated executable paths or names that `external_code` components may run, or `*`. Without it, stdio allows any command and streamable-http disables `external_code`. |
| `--log-level LEVEL` | Logs always go to stderr. |
The server has no built-in authentication. Keep `--host 127.0.0.1` and put a
reverse proxy that authenticates clients in front of it.
## Tools
All 21 tools validate their arguments with Pydantic v2 and answer with a JSON
object. Failures come back in-band as `{"error": {"type", "message", "details"}}`;
a failed evaluation (`om.AnalysisError`) is reported as `success: false`, never
as an unhandled exception.
| Group | Tools |
|-------|-------|
| Health | `ping` |
| Problems | `create_problem`, `update_problem`, `load_problem`, `list_problems`, `get_problem_spec`, `close_problem` |
| Variables | `list_variables`, `set_inputs`, `get_outputs` |
| Solvers and drivers | `configure_solvers`, `configure_optimization` |
| Runs | `run_model`, `run_driver`, `run_doe`, `run_multistart` |
| Derivatives | `configure_approx_totals`, `compute_totals`, `check_totals_sweep` |
| Observability | `query_cases`, `export_n2` |
A typical session:
1. `create_problem` with a `ProblemSpec`: independent variables, `exec_comp`
equations (checked against an AST whitelist), `external_code` black boxes
(template in, run in an isolated `eval_<uuid>` directory, JSONPath/regex
out), `metamodel` surrogates, and nested groups with their own solvers.
2. `run_model` to converge the coupled loop at the baseline.
3. `configure_optimization`: design variables (gradient-based optimizers
require `ref`/`ref0` or `scaler`), objective, constraints, driver.
4. `check_totals_sweep` before SLSQP: finite-difference totals at several
steps expose black-box noise and recommend a step for
`configure_approx_totals`.
5. `run_doe` (LHS via `scipy.stats.qmc`, full factorial via
`itertools.product`, both fed to `ListGenerator`), `run_driver`, or
`run_multistart` (LHS, keep the best feasible seeds, normalized SLSQP from
each, optionally in `spawn` worker processes).
6. `query_cases` on the `SqliteRecorder` file of the run: best feasible
design, convergence history, active constraints, sensitivity ranking.
7. `export_n2` writes a standalone N2 diagram without opening a browser.
## Design notes
- **stdout isolation.** Under stdio, stdout is the JSON-RPC channel. Every
OpenMDAO call runs inside `diagnostics.isolated_stdout()`, which diverts
Python-level output to a buffer (returned as `captured_output`) under one
process-wide lock. External codes write to log files in their run
directory, and multi-start workers redirect their descriptors to
`workers.log`.
- **Responsive event loop.** Every tool that touches OpenMDAO is `async` and
runs in a worker thread (`anyio.to_thread.run_sync`), so a long
optimization never blocks other requests.
- **Persistence.** Each problem lives in `<workdir>/<problem_id>/` with its
`problem_spec.json` (UTF-8, LF). A restarted server, or a spawn worker,
rebuilds the problem from that file. Every driver run writes its own
recording under `recordings/`.
- **No `pydoe`.** OpenMDAO's LHS and full-factorial generators and
`SimpleGADriver` need `pydoe`, which this package does not install;
`configure_optimization` with `simple_ga` returns a structured error that
points to COBYLA or Nelder-Mead.
- **OpenMDAO 3.45.2 quirks handled.** `DOEDriver` records every case as
successful; a small subclass restores the per-case failure flag. Derivatives
recorded by `ScipyOptimizeDriver` belong to the previous iterate, so
`sensitivity_ranking` evaluates them at the recorded point instead.
## Deployment on Rocky Linux 9.8
```bash
sudo deploy/rocky9_setup.sh --enable
```
The script installs `python3.12` from AppStream, creates an unprivileged
`openmdao` account, builds `/opt/openmdao-mcp/.venv`, installs this checkout,
checks `openmdao-mcp --help` and a headless import, and installs
[`deploy/openmdao-mcp.service`](deploy/openmdao-mcp.service), which runs
`--transport streamable-http --host 127.0.0.1 --port 8765` with
`MPLBACKEND=Agg`. Run `deploy/rocky9_setup.sh --help` for the options.
## Layout
| Module | Role |
|--------|------|
| `openmdao_mcp.server` | FastMCP factory, the 21 tool registrations, CLI |
| `openmdao_mcp.session` | Thread-safe problem registry with on-disk `problem_spec.json` |
| `openmdao_mcp.components` | Builds components and nested groups from specs; external-command policy |
| `openmdao_mcp.solvers` | Nonlinear/linear solvers and line searches |
| `openmdao_mcp.drivers` | Problem definition, drivers, DOE sampling, run tools, multi-start |
| `openmdao_mcp.diagnostics` | stdout isolation, approx/compute/check totals, case queries, N2 |
| `openmdao_mcp.schemas` | Pydantic v2 models for every spec, request and response |
| `openmdao_mcp.errors` | Structured error envelope |
## Quality checks
```bash
python -m ruff check .
python -m ruff format --check .
python -m mypy --strict src
python -m pytest
```
`tests/test_rotorcraft_mdao_benchmark.py` is the end-to-end acceptance test:
a gross-weight / required-power / mission-fuel loop around a noisy black-box
CLI, checked through the step sweep, normalized multi-start SLSQP, active
constraint identification and N2 export.
## Contributing
Contribution guidelines live in [`CONTRIBUTING.md`](CONTRIBUTING.md).
## License
MIT. See [`LICENSE`](LICENSE).
TDQS
Scored across 21 tools
Most tools map to distinct lifecycle stages, and the descriptions clearly separate problem creation, update, loading, and execution. There is minor conceptual overlap between related execution tools such as run_driver, run_doe, and run_multistart, and between list_variables and get_outputs, but their intended uses are still recoverable.
Tool names consistently use lowercase snake_case with an action verb first: get_, create_, update_, load_, list_, configure_, run_, compute_, check_, query_, and export_. The lone single-verb tool, ping, is a standard health-check name and does not meaningfully break the pattern.
At 21 tools the surface is somewhat heavy, but the OpenMDAO workflow legitimately spans problem management, configuration, execution, derivative analysis, case querying, and visualization. Each tool appears to correspond to a meaningful operation rather than duplicating another, though the specialized run and check tools push the count above the typical range.
The tool set covers the full lifecycle: create/update/load/list/close problems, retrieve specs, inspect variables, set inputs, configure solvers/optimization/approximations, run models/drivers/DOE/multistart, compute and verify totals, query recordings, export N2 diagrams, and health-check the server. Deletion is handled through close_problem with delete_files, so there are no obvious dead ends.