Ottosim — Simulation MCP Server

Give an AI assistant first-order engineering physics on a real CAD model. This local stdio MCP server carries a STEP file through explicit meshing in Gmsh to a typed study in Elmer — steady and transient thermal, linear static structural, modal, DC conduction, and laminar flow — and returns revisioned results, with no cloud service and no prepared solver input.

Every engineering input is explicit: the materials, boundaries, and mesh are stated, never inferred, and each study, mesh, and result is revision-bound so a number can always be traced back to what produced it.

Qualified against analytic references. Gmsh 4.15.2 and Elmer (devel, most recently released as 26.2.1) complete production-SIF qualifications for every advertised physics — steady and transient thermal, static structural, modal frequency, DC potential, and steady and transient laminar flow — each against an analytic reference with mesh (or timestep) refinement.

Runs on Node 26 / TypeScript 7 against MCP SDK 2.4.0, with a Python Gmsh worker over a one-request/one-response JSON-file protocol (protocol: 1).

Install and launch

Distribution targets match Geometry MCP: Windows x64, macOS ARM64 (Apple Silicon), and Linux x64. Intel macOS, Linux ARM64, and Windows ARM64 are outside the target matrix. CI runs unit/artifact/process checks on these three targets, builds the pinned serial Elmer solver on each target, caches the native install, runs the analytic integration and qualification suites, then packs and smoke-tests the published tarball. This validates native execution; a standalone runtime package is not yet published.

The repository owns its artifact schema in contracts/. Builds bundle that schema and the Python worker; Gmsh and Elmer runtimes are installed separately.

From this directory:

nix develop
just setup
just build
export SIMULATION_INPUT_ROOTS='["/absolute/path/to/models"]'
export SIMULATION_WORKSPACE=/absolute/path/to/run-workspace
just start

.envrc already contains use flake; direnv allow is an alternative to nix develop. .env.example documents variables; .env is not auto-loaded. just setup installs npm dependencies without lifecycle scripts. The flake pins nixpkgs (and thus Gmsh) by commit, and pins upstream Elmer by commit. Elmer's transitive inputs use its checked-in lock.

Nix provisions the solver toolchain only on x86_64-linux. packages.<system>.toolchain provisions Node, Gmsh, the Python wrapper and headless upstream Elmer built serially without MPI, OpenMP, ElmerIce or Lua. The analytic thermal benchmark passes with that serial solver. The dev shell also provisions Python, Ruff and Nix tooling; TypeScript language server/formatter/linter/test deps are project-local npm dependencies. Gmsh's Python module lives under its Nix package's lib, supplied through PYTHONPATH. Elmer is an external package, not compiled by npm.

Non-Nix deployments must provide compatible Gmsh Python bindings and native library plus ElmerGrid and ElmerSolver with HeatSolve, FluxSolver, SaveData and ResultOutputSolve modules. Executables are operator configuration:

Generic host configuration example (environment may instead be inherited from the Nix shell):

{
  "command": "node",
  "args": ["/absolute/path/to/simulation/dist/src/index.js"],
  "env": {
    "SIMULATION_INPUT_ROOTS": "[\"/absolute/path/to/models\"]",
    "SIMULATION_WORKSPACE": "/absolute/path/to/run-workspace",
    "SIMULATION_PYTHON": "/absolute/path/to/provisioned/simulation-python",
    "SIMULATION_ELMERGRID": "/absolute/path/to/ElmerGrid",
    "SIMULATION_ELMERSOLVER": "/absolute/path/to/ElmerSolver"
  }
}

Related MCP server: COMSOL MCP

Study tools

The public workflow is get_capabilities → inspect_model → query_model → validate_study → prepare_study → run_study → inspect_job → query_results. list_jobs recovers recent jobs after context loss and cancel_job stops an active preparation or solver process.

inspect_job accepts waitMs (up to 60 s) and then waits in-process for a terminal state instead of returning immediately, so prepare_study → inspect_job(waitMs) → run_study → inspect_job(waitMs) → query_results is normally five calls rather than dozens of polls. The state is returned whether or not the window expires. A cancelled or timed-out client request stops the mesh or the solve: ctx.signal is forwarded to the job's abort path and the record ends cancelled. Preparation and solver execution return job IDs immediately. Jobs survive client disconnects, not server shutdown. Interrupted jobs are recorded and are not resumed.

get_capabilities reports the available physics and the study shape (required and optional fields, notes, and a worked example); the machine-readable simulation://help resource carries the full study schema — per-physics material and boundary fields with units, regimes, observation quantities with time/mode selectors, enums, and a parseable example. Both are generated from one catalog so discovery cannot drift from the accepted study schema.

steady-thermal, transient-thermal, static-structural, modal, dc-conduction, and laminar-flow are implemented and benchmarked. Other physics reported by get_capabilities remain unavailable, not implied by the fact that Elmer has upstream solvers for them.

Transient studies require explicit density and heat capacity per solid, one uniform initial temperature, a positive timestep, and a step count capped at 10,000. Fixed-temperature, insulated and inward-heat-flux boundaries are supported; time-varying conditions and per-region initial temperatures are not. Transient scalar and VTU results are validated at every step. An observation may select a positive timestep-aligned time in seconds; without time, it observes the final step. Acceptance thresholds remain in the quantity's units (for example, K), not seconds.

Static structural studies require an explicit isotropic Young's modulus and Poisson ratio for every solid, and an explicit fixed-displacement, prescribed-displacement, uniform-traction, or free condition for every surface. The supported model is static, linear-elastic, and small-strain; displacement and stress summaries are unweighted nodal samples, not volume averages.

Modal studies require explicit density in addition to elastic properties, fixed-displacement/free surface assignments, and request 1–20 modes. The first modal implementation reports eigenfrequencies only; it does not expose mode shapes, damping, prestress, or harmonic response. Modal observations select a mode number and use Hz.

DC conduction studies require explicit positive isotropic electrical conductivity per solid, explicit prescribed-potential or insulated conditions on every surface, and at least two distinct prescribed potentials per disconnected conductive component. Results report the nodal potential field; current, Joule heating, magnetic effects, and transient/capacitive behavior are not modeled.

Laminar-flow studies model incompressible Newtonian fluids with explicitly assigned constant density and dynamic viscosity. Every fluid surface must be explicitly assigned either a prescribed pressure or a no-slip wall; each disconnected fluid region needs at least two distinct prescribed pressures. Steady and transient runs are supported; transient runs use first-order BDF, constant timestep, and an explicit quiescent initial velocity. The solver is Elmer's monolithic FlowSolve module; qualification covers pressure-driven square-duct flow and transient startup against the analytic rectangular-duct solution, inlet/outlet flux conservation, and mesh/timestep refinement. Flux and section averages are not exposed; reported velocity and pressure values are nodal extrema. Elmer's segregated IncompressibleNS module is installed but not qualified. Turbulence, compressibility, moving walls, nonzero initial velocity, and thermal/electric coupling are not modeled.

Selections use dimension-qualified inspection entity IDs (for example 3:1 for a volume or 2:7 for a surface), have unique names and cannot mix solids and surfaces. Every inspected entity must be assigned exactly once. Each solid selection needs one material; every surface selection defaults to insulated in thermal studies unless explicitly overridden. Structural, modal, and DC studies require explicit conditions on every surface. A thermal default is a declared engineering assumption, not an inferred boundary condition. The solver uses SI units, but study quantities may be supplied in compatible engineering units (for example mm, in, psi, ksi, lbf, degC) and are converted at the API boundary. Mesh sizes default to metres and accept mm, cm, in or ft through mesh.units. Results are SI by default; an optional displayUnits block (for example { "length": "in", "pressure": "ksi" }) returns observations in the engineer's units. Linear tetrahedra are still the only supported element type.

Material entries may carry an optional reference with the designation, source name/revision, and basis returned by a reference tool such as Standards. The study preserves this caller-supplied context alongside the explicit numeric properties; Simulation does not fetch or verify the source. A typical value remains distinct from a qualified design allowable.

Example steady thermal study after inspecting the STEP file:

{
  "schemaVersion": "1",
  "name": "Bar conduction",
  "objective": "Estimate the steady temperature and heat flux",
  "model": {
    "source": {
      "revision": "sha256:<64 lowercase hex digits>",
      "uri": "file:///.../source.step",
      "format": "step",
      "units": "mm"
    },
    "inspection": {
      "revision": "sha256:<64 lowercase hex digits>",
      "uri": "file:///.../inspection.json",
      "format": "json"
    }
  },
  "selections": [
    { "name": "bar", "entities": ["3:1"] },
    { "name": "hot_end", "entities": ["2:2"] },
    { "name": "cold_end", "entities": ["2:3"] },
    { "name": "other_faces", "entities": ["2:4", "2:5", "2:6", "2:7"] }
  ],
  "mesh": { "minSize": 0.003, "maxSize": 0.006, "elementOrder": 1 },
  "physics": {
    "kind": "steady-thermal",
    "defaultBoundary": "insulated",
    "materials": [
      {
        "selection": "bar",
        "conductivity": { "value": 10, "units": "W/(m.K)" }
      }
    ],
    "sources": [],
    "boundaries": [
      {
        "selection": "hot_end",
        "kind": "temperature",
        "temperature": { "value": 400, "units": "K" }
      },
      {
        "selection": "cold_end",
        "kind": "temperature",
        "temperature": { "value": 300, "units": "K" }
      }
    ]
  },
  "observations": [{ "id": "max_temperature", "quantity": "temperature_max" }],
  "acceptanceCriteria": [
    {
      "observationId": "max_temperature",
      "operator": "<",
      "threshold": { "value": 410, "units": "K" }
    }
  ],
  "assumptions": []
}

The example entity tags are illustrative; use tags from query_model and confirm each selection against the actual part. prepare_study returns a jobId; poll inspect_job until it succeeds, then pass its prepared artifact to run_study, which returns another jobId. query_results reports solver evidence separately from observation values and criterion outcomes; a failed criterion is an engineering result, not a solver error. Its response is bounded by default — observation values without duplicate backing summaries, de-duplicated field descriptors, and one page of artifact refs (limit/cursor, artifactCount). Summaries are returned when requested with include:["summaries"], or as a fallback when no observations were declared. Pass time to select one frame or observations to filter. Scalar means are nodal, not volume averages or integrated heat rates. Arbitrary SIF, procedures, expressions, scripts and solver commands are never study inputs.

Tool failures use MCP isError. Domain failures from the service return a JSON { code, message } object (with revisioned diagnostic log refs where available); invalid tool arguments are rejected by the MCP layer before the handler runs and are returned as plain text. The domain error codes are a closed, documented set (listed under enums.error_codes in simulation://help): invalid_input, invalid_study, invalid_physics, invalid_selection, invalid_job_kind, unsupported_condition, unsupported_physics, unsupported_format, stale_artifact, path_policy, file_not_found, too_large, bad_mesh, bad_groups, malformed_results, solver_failed, worker_failed, conversion_failed, process_failed, spawn_error, output_limit, persistence_failed, cancelled, timeout, interrupted, worker_protocol, and internal_error. Failed solves return inspectable run metadata rather than disguising partial outputs as successful results.

Server diagnostics are written as newline-delimited JSON to stderr (stdout is the MCP channel). Set MCP_LOG_LEVEL (debug|info|warn|error, default info), MCP_LOG_FORMAT=human for a compact form, and MCP_TRACE_ID to correlate events; secret-like fields are redacted.

Boundaries, security and retention

• This is a trusted-local tool, not a filesystem sandbox. Input roots are canonicalized and used to catch accidental path mistakes; the server assumes the local user and files are trusted. Do not expose it to untrusted clients.

• Artifact revisions are SHA-256 digests of the exact bytes read or produced. Reusing a ref after its file changes fails explicitly, but concurrent edits during an operation are not defended against.

• Processes use configured executables and argument arrays, no shell. The local process environment is inherited for runtime compatibility, with deterministic locale/thread settings applied; child tools therefore also inherit local env vars.

• Per-process wall timeout, serial execution and 8 MiB combined captured-output bound are enforced. There is no portable memory, mesh-size, input-size or workspace-disk quota; provision OS quotas/cgroups if deployment needs them.

• V1 supports separate solid regions and exterior BC groups. Internal/orphan native boundaries fail; no contact resistance, automatic fragmentation, repairs, nonconformal coupling, radiation, plasticity, or geometric nonlinearity. Transient thermal supports only the explicit constant-property/ time-step model above; structural support is isotropic, linear small-strain; modal support is undamped and unloaded.

• Selectors are tied to exact source revision, Gmsh version and gmsh-occ-import-v1. No Geometry SubjectRef-to-Gmsh topology equivalence is claimed. Imported names are hints, never engineering intent.

• No automatic deletion. Shut down the server, then explicitly archive/remove UUID operation directories when refs are no longer needed. just clean removes only compiled code. Interrupted records are not resumed. After an ungraceful termination inspect/reap any orphaned solver processes before restarting against that workspace. Graceful shutdown cancels owned runs.

• Hosted deployments need an external isolation boundary (e.g. a container or VM with explicit input mounts and resource limits); application path checks are not a substitute. These outputs are numerical evidence, not engineering certification.

Implementation choices

• The Gmsh Python API owns STEP import, topology inventory, and mesh generation. It communicates with TypeScript through a bounded JSON-file worker protocol; no generated .geo script is required.

• Typed inputs generate deterministic SIF. PyElmer and model-authored SIF are unnecessary for supported workflows.

• ASCII MSH 2.2 transfers explicit physical groups to ElmerGrid; converted group membership and connectivity are verified instead of trusting labels alone.

• Upstream Elmer and Gmsh are external tools provisioned by Nix, not downloaded by npm at server startup. Non-Nix deployments can configure executable paths.

• Scalar summaries and VTU inventory are intentionally limited to the supported solver output. Geometry IDs are not cross-kernel mesh selectors.

Artifact references

Every reference identifies one exact byte stream with revision: "sha256:<64 lowercase hex digits>" and a format. A URI is an optional locator; operations requiring bytes need an accessible local file: URI. Supported format identifiers are step, gmsh-msh, elmer-mesh, vtu, elmer-sif, text, and json. Derived artifacts receive their own digests. An Elmer mesh directory is not a single artifact: its metadata references individual native files.

Limits

• Linear tetrahedra only; studies are small-strain and use the physics kinds listed above. Every engineering input is explicit — materials, boundaries, and idealisations are never inferred.

• Results are numerical evidence, not engineering certification; a failed acceptance criterion is an engineering result, not a solver error.

• A job survives a client disconnect but not a server shutdown, and interrupted jobs are recorded rather than resumed.

Development

Requires Node.js 26+ and just. A Nix flake and .envrc provide the toolchain; run direnv allow after changing either.

Server logs go to stderr as newline-delimited pino JSON. MCP_LOG_LEVEL (debug|info|warn|error), MCP_LOG_FORMAT=human, and MCP_TRACE_ID tune them; secret-like fields are redacted.

The lightweight checks shell includes Node and Ruff without building the Gmsh/Elmer solver toolchain:

# Run from this repository.
nix develop .#checks --accept-flake-config --command just setup
nix develop .#checks --accept-flake-config --command just check
nix develop --accept-flake-config --command just test-integration
nix develop --accept-flake-config --command just check
nix develop --accept-flake-config --command just build

just test-integration runs the opt-in direct-service Gmsh/Elmer benchmark. It is server-owned integration coverage; public stdio acceptance runs separately against the built server artifact.

In a source checkout, tests/fixtures/README.md documents analytic bar dimensions, generation, and temperature/heat-flux tolerances. Unit checks do not require a solver runtime. Native integration checks additionally cover malformed inputs, solver failures, timeout/cancellation, restart persistence, and stale outputs. Tests use the operating system's temporary directory; SIMULATION_TEST_TMP can select another temporary root.

Licensing and upstream source references are recorded in third-party notices.

Packaging

npm pack builds first and includes compiled runtime code, the local artifact schema, Python worker, README, and third-party notices. Tests, source maps, and Python caches are excluded. Install the tarball to check simulation-mcp-server with a compatible MCP client. The server serves both protocol eras: the 2025-11-25 handshake that stock MCP hosts negotiate, and 2026-07-28 through server/discover. Native tools still require separate installation.

just check includes solver-independent stdio protocol tests for modern discovery, workflow resources, tool errors, and both protocol eras.

License

MIT. Third-party toolchain terms are in THIRD_PARTY_NOTICES.md.