OASiS

Open-source Agent for Simulation across multiple FEM Solvers — an open-source multi-physics and multi-code framework for verified computer simulations.

OASiS is a Model Context Protocol (MCP) server that connects AI coding agents to eight independent finite element codes (FEniCSx, deal.II, 4C Multiphysics, NGSolve, scikit-fem, Kratos Multiphysics, DUNE-fem, FEBio). Any MCP-compatible AI tool (Claude Code, Cursor, Windsurf, GitHub Copilot) can operate solvers, couple them across codes, develop new solver capabilities, and verify simulation correctness — all through one protocol.

Key Numbers

Quick Start

1. Clone and install

git clone https://github.com/Hereon-InstituteMS/OASiS.git && cd OASiS
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

2. Install solver backends (pick what you need)

# pip-installable (any combination)
pip install ngsolve scikit-fem dune-fem
pip install KratosMultiphysics KratosStructuralMechanicsApplication

# FEniCSx (requires conda)
conda create -n fenics -c conda-forge fenics-dolfinx
# or: pip install fenics-dolfinx (if available for your platform)

# deal.II (system package)
sudo apt install libdeal.ii-dev   # Ubuntu/Debian

# 4C Multiphysics (build from source — see 4C documentation)

# FEBio (binary download)
# https://febio.org/downloads/  — set FEBIO_BINARY env var or place in PATH

3. Connect to your AI tool

The MCP server runs as a stdio process. Each AI tool has its own way to register it.

Claude Code (recommended — supports sub-agent spawning for critic workflow):

# From the project root:
claude mcp add oasis \
  .venv/bin/python -- -m server \
  -e PYTHONPATH=src \
  -e PYVISTA_OFF_SCREEN=true

Or manually create .claude/settings.json in the project directory:

{
  "mcpServers": {
    "oasis": {
      "type": "stdio",
      "command": ".venv/bin/python",
      "args": ["-m", "server"],
      "cwd": "src",
      "env": {
        "PYTHONPATH": "src",
        "PYVISTA_OFF_SCREEN": "true"
      }
    }
  }
}

Cursor:

Go to Settings > MCP Servers > Add Server, then enter:

• Name: oasis
• Command: /path/to/OASiS/.venv/bin/python
• Args: -m server
• Working directory: /path/to/OASiS/src
• Environment: PYTHONPATH=src, PYVISTA_OFF_SCREEN=true

Windsurf:

Add to your Windsurf MCP configuration (Settings > MCP):

{
  "oasis": {
    "command": "/path/to/OASiS/.venv/bin/python",
    "args": ["-m", "server"],
    "cwd": "/path/to/OASiS/src",
    "env": { "PYTHONPATH": "src", "PYVISTA_OFF_SCREEN": "true" }
  }
}

OpenAI Codex / any MCP client:

The server speaks standard MCP over stdio. Point your client at:

command: .venv/bin/python -m server
cwd: src/
env: PYTHONPATH=src

4. Verify

source .venv/bin/activate
cd src && python -m server  # should start without errors (Ctrl+C to stop)

# Run tests
cd .. && pytest tests/ -v

5. Optional: configure solver source access

To enable developer mode (source browsing, modification, rebuild), add solver paths to your MCP environment. See .claude/settings.json.example for the template.

Environment Variables

Solver backends are auto-detected from pip/conda installations. For compiled solvers or source-level development access, set these in your MCP settings:

When a *_ROOT variable is set, the agent can browse, modify, and rebuild the solver source code (developer mode).

Architecture

User --> AI Agent (any MCP client) --> MCP Protocol --> OASiS
                                                          |
   +-------------+---------+------+--------+--------+--------+--------+-------+
   |             |         |      |        |        |        |        |       |
FEniCSx     deal.II      4C   NGSolve   skfem   Kratos    DUNE    FEBio
(Python)     (C++)    (YAML) (Python) (Python) (JSON)   (Python)  (XML)

Three Modes of Operation

1. Operate: Run Simulations

The agent generates solver-specific input, runs the simulation, and validates results.

2. Couple: Multi-Solver Workflows

Domain decomposition, field transfer, and multi-physics coupling across different FEM codes.

3. Develop: Extend Solver Capabilities

When a solver lacks a needed feature, the agent can read source code, implement the missing piece, rebuild, and test.

MCP Tools

The Cross-Backend Differentiator

OASiS ships 26 cross-backend collation topics with 45+ pitfalls that describe gotchas at the delta between two or more solvers — content that has no equivalent in any individual solver's docs:

• units, element node ordering, linear-elastic semantics, Dirichlet BC enforcement
• restart/checkpoint compatibility, MPI launch idioms, element-type naming
• time-integration defaults, solver-tolerance defaults, contact formulation defaults
• output-format conventions, integration-order defaults, boundary-tag semantics
• plasticity return-mapping, turbulence model defaults, material orientation
• frequency-unit conventions, mesh-quality thresholds, stress-measure conventions
• periodic-BC implementation, damping-convention defaults, timestamp output
• initial-condition interpolation, frame-of-reference BC
• linear-solver defaults (direct vs iterative dispatch, GMRES restart, tolerance scaling)
• nonlinear convergence criteria (relative vs absolute, energy-norm, line-search, failure-signal paths)

Reach via knowledge(topic='cross_backend') or filter by physics: knowledge(topic='cross_backend', physics='units').

Tested Benchmarks

These benchmarks have been run as end-to-end stress tests with a fresh AI agent. Each prompt was given verbatim to the agent with no additional guidance.

Single-Solver Benchmarks (9/9 pass)

Cross-Solver Validation (2/2 pass)

Multi-Solver Coupling (4/4 pass)

Advanced (7/7 pass)

Solver Selection & Agent Intelligence (1/1 pass)

Contributing

We welcome contributions that improve the general-purpose capabilities of OASiS. The key principle:

Every improvement must benefit ALL simulations, not be fine-tuned for specific examples.

How to contribute

1. Report agent behavior — Run any of the benchmark prompts (or your own) with your AI tool and solver setup. Report:

   • Which AI tool you used (Claude Code, Cursor, Windsurf, etc.)
   • The exact prompt you gave
   • What worked and what didn't
   • The agent's retrospective (ask the debrief questions below)

2. Improve solver knowledge — Add pitfalls, element catalogs, or API documentation that would help any agent set up simulations correctly. Focus on things the agent had to discover by trial-and-error.

3. Add solver backends — Implement the SolverBackend interface for a new FEM code.

4. Expand coupling — Add script generators for new solver pairs in src/tools/coupling.py.

What NOT to contribute

• Benchmark-specific parameter databases (the agent should research these per-problem)
• Model-specific templates (e.g., "Turek-Hron FSI2 template") — these are fine-tuning
• Hardcoded paths or machine-specific configurations

Debrief questions (ask after every stress test)

- "What went wrong and what workarounds did you have to use?"
- "Which MCP tools were useful and which were missing or unhelpful?"
- "What information did you have to look up online that should have been available through the MCP?"
- "What parameters did you struggle with and why?"
- "If you had to do this again, what would you do differently?"

Feed the answers back as general-purpose improvements to the MCP knowledge and tools.

AI Tool Compatibility

The MCP server works with any MCP-compatible AI tool. Agent instructions are provided in multiple formats:

License

MIT

Citation

If you use OASiS in your research, please cite:

@article{oasis2026,
  title={OASiS: an open-source multi-physics and multi-code framework for verified computer simulations},
  author={Hermann, Alexander and Shojaei, Arman and Scheider, Ingo and Cyron, Christian},
  year={2026},
}