# ls-dyna-mcp

MCP server for LS-DYNA (Ansys 2026 R1, LS-DYNA 16.1). It works in two ways, separately or together:

- With Ansys Workbench / Mechanical: an AI client drives the LS-DYNA analysis through PyMechanical
  (analysis settings, loads, results, binout trackers, keyword snippets, deck export and a
  background solve).
- Standalone, without Workbench: it submits and monitors solver runs on your own keyword decks
  (`.k` files), as LS-Run does (SMP and MPP, queue, dependencies, restarts, `sw1` stop), and reads,
  audits and compares the files LS-DYNA writes. No Mechanical connection is needed.

Both modes share run monitoring (progress, ETA, energy-balance checks, termination read from the
solver's banner), readers for `glstat`, `binout`, `d3plot` and the ASCII histories, a deck audit and
comparison, and an optional keyword builder based on PyDYNA. Replies are redacted and file access is
limited to allowed folders; see [doc/security.md](doc/security.md).

## Tool surface

53 tools, grouped by purpose. One-line descriptions are in [doc/tools.md](doc/tools.md).

| Purpose | Needs Mechanical | Tools |
|---|---|---|
| Connection | yes | `connect_to_mechanical`, `disconnect_from_mechanical`, `list_lsdyna_analyses` |
| Discovery | yes | `inspect_object`, `get_analysis_settings`, `get_solution_information`, `list_binout_tracker_options`, `list_scoping_targets`, `list_addable_objects` |
| Discovery (user guide) | no | `search_lsdyna_help` |
| Model building | yes | `create_lsdyna_analysis`, `create_lsdyna_system_snippet`, `set_analysis_settings`, `add_load_or_condition`, `add_result`, `add_binout_tracker`, `add_keyword_commands`, `delete_object`, `set_dynain_output` |
| Keyword builder | only to add a card to the analysis | `describe_keyword`, `build_keyword` |
| Solve | yes | `write_solver_input`, `solve_analysis`, `get_solve_status`, `run_mechanical_script` |
| Standalone runs | no | `submit_lsdyna_job`, `list_lsdyna_jobs`, `get_lsdyna_job`, `stop_lsdyna_job`, `list_solver_versions` |
| Run monitoring and results | no | `list_solver_files`, `tail_solver_file`, `check_run_health`, `read_glstat`, `read_binout`, `scan_solver_messages`, `read_history_file`, `read_d3plot`, `read_implicit_progress`, `list_restart_files`, `send_sense_switch`, `check_restart_setup`, `prepare_dynain` |
| Decks and reference | no | `scan_keyword_file`, `describe_workbench_material`, `audit_deck`, `compare_decks` |
| Gates around a solve | `write_and_audit_deck` only | `write_and_audit_deck`, `get_run_progress`, `compare_early_results`, `presolve_check` |
| Experimental (off by default) | no | `run_lsprepost`, `summarize_d3plot` |

## Installation

For users:

```
pip install .                 # the server, with the ls-dyna-mcp console script
pip install ".[binout]"       # optional: read_binout and read_d3plot (lasso-python)
pip install ".[pydyna]"       # optional: describe_keyword and build_keyword (ansys-dyna-core)
```

For developers:

```
pip install -e ".[dev]"                  # core tests; tests that need lasso or PyDYNA are skipped
pip install -e ".[binout,pydyna,dev]"    # the full test suite, as CI runs it
```

`lasso-python` pins an older `psutil` than PyMechanical needs; see
[doc/getting-started.md](doc/getting-started.md) for the `--no-deps` workaround.

## Usage

Register the `ls-dyna-mcp` command with your MCP client (Claude Code, Claude Desktop or VS Code).
For the Mechanical-side tools, start Mechanical with a gRPC port first; the file readers and the
job runner work without it. Client configuration is in
[doc/getting-started.md](doc/getting-started.md) and a short walk-through is in
[examples/example_workflow.md](examples/example_workflow.md).

## Configuration

The most important environment variables (the full list is in
[doc/configuration.md](doc/configuration.md)):

| Variable | Effect |
|---|---|
| `LSDYNA_MCP_ROOTS` | Folders the file-side tools may use (default: the working directory) |
| `LSDYNA_MCP_MAX_JOBS` | Standalone jobs run at once (default 1) |
| `LSDYNA_MCP_MAX_NCPU` | Upper bound on `ncpu` (default 512) |
| `LSDYNA_MCP_WORKBENCH_ONLY` | `1` makes `submit_lsdyna_job` refuse, so runs are driven from Workbench only |
| `LSDYNA_MCP_ENABLE_SCRIPT` | `1` enables `run_mechanical_script` (arbitrary IronPython) |
| `LSDYNA_MCP_ENABLE_LSPREPOST` | `1` enables the experimental LS-PrePost tools |
| `LSDYNA_MCP_STATE_DIR` | Where the job table and the remembered Mechanical port are kept |
| `LSDYNA_MCP_REDACT` | `0` switches off redaction of host, user and licence details in replies |

## Safety

- File tools only touch allowed folders; network paths, links and alternate data streams are refused.
- Only Ansys-installed `lsdyna*.exe` solvers can run, with allow-listed arguments; scripts and LS-PrePost are off by default.
- Replies are redacted for computer, user and licence identifiers. Details: [doc/security.md](doc/security.md).

## Known limits

- Windows and Ansys 2026 R1 only.
- Workbench scripting cannot set the selection (drop-down) settings; use keyword snippets.
- A long Workbench solve through the MCP has not been tested; see [doc/known-limits.md](doc/known-limits.md) and [doc/workbench-notes.md](doc/workbench-notes.md).

## License

MIT, see [LICENSE](LICENSE). ANSYS and LS-DYNA are trademarks of their owners. This project is
independent and ships no vendor software.

## Resources

- [Documentation](doc/index.md) and [changelog](CHANGELOG.md)
- [Contributing](CONTRIBUTING.md), [security policy](SECURITY.md), [code of conduct](CODE_OF_CONDUCT.md)
- [PyMechanical](https://github.com/ansys/pymechanical), [PyDYNA](https://github.com/ansys/pydyna) and the
  [Model Context Protocol](https://modelcontextprotocol.io)