Skip to main content
Glama
README.md
# 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

A3.5/5.0

Scored across 21 tools

Disambiguation4/5

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.

Naming Consistency5/5

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.

Tool Count4/5

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.

Completeness5/5

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.

Maintenance

ActivityActive
ResponsivenessNo recent community issues