COMSOL MCP Verifier

Verification-first simulation workflows for coding agents.

COMSOL MCP Verifier connects engineering intent to bounded COMSOL runs and inspectable evidence. A Python service validates candidates against a design contract, checks execution policy, drives a fixed MATLAB LiveLink adapter, and returns deterministic verifier feedback with provenance and artifact paths.

A model that solves can still have the wrong excitation, evaluate the wrong dataset, or reuse an old solution. Giving an agent the raw solver API does not resolve those problems. This project makes the contract, observed model facts, result bindings, and verification evidence explicit. Physical validity still depends on the model and its package-owned checks.

A successful MCP call is not necessarily a successful solver run, a correctly configured simulation, a fresh solution, or a physically validated result. Each claim needs its own evidence.

This is the canonical repository for future development of the generic core. The internal Python package remains em_design_mcp for compatibility.

flowchart LR
    A[Engineering request / agent] --> B[Bounded design contract]
    B --> C[Candidate validation and execution policy]
    C --> D[Model inspection and declared preflight]
    D --> E[COMSOL through fixed LiveLink adapter]
    E --> F[Bound measurements and package verifier]
    F --> G[Compact feedback and evidence artifacts]
    G --> A
    P[Input fingerprints] -. checked across the run .-> G

The generic core lives here. Production models, builders, physical assumptions, parameter ranges, objectives, calibration data, parsers, and verifiers live in external design packages. Adding a model normally requires no core changes.

Engineering capabilities

There is no MCP tool for arbitrary MATLAB, Java, Python, shell, or COMSOL commands. Packages are nevertheless trusted executable inputs: their Python plugins run locally and their bindings control model operations. This is not a sandbox for untrusted packages or a multi-tenant service.

Related MCP server: COMSOL MCP Server

Try it without COMSOL

Use Python 3.10+ and a source checkout with an editable installation. Keep the checkout in place: the current runtime locates MATLAB adapters and fingerprints relative to it. Standalone wheel installation is not supported yet.

git clone https://github.com/yushi-zhou/comsol-mcp-verifier.git
cd comsol-mcp-verifier
python -m venv .venv

Activate the environment with source .venv/bin/activate on POSIX, or .\.venv\Scripts\Activate.ps1 in PowerShell, then:

python -m pip install -e ".[test]"
python -m pytest -q

The default tests use synthetic fixtures, not commercial solver software. To run one complete mock evaluation, select the included fixture package:

# POSIX, from the checkout root
export EM_DESIGN_PACKAGE_ROOTS="$PWD/tests/fixtures/designs"
export EM_DESIGN_MCP_RUNS_DIR="$PWD/runs/mock-demo"

# PowerShell, from the checkout root
$env:EM_DESIGN_PACKAGE_ROOTS = (Resolve-Path tests/fixtures/designs).Path
$env:EM_DESIGN_MCP_RUNS_DIR = Join-Path (Get-Location).Path "runs/mock-demo"

Then, in either shell:

python -m em_design_mcp.cli run-json --input tests/fixtures/mock-request.json --output runs/mock-demo/response.json --pretty

Expect schema_version: "em_design_mcp_cli_v1", ok: true, and result.status: "evaluated". Inspect result.overall_pass separately from the CLI envelope. The synthetic verifier exercises plumbing; its scores are not EM predictions or benchmark results. Generated evidence stays under runs/.

Use from an MCP client

Launch the STDIO server with the installed environment's Python:

python -m em_design_mcp.server

Configure your client to use that interpreter and the checkout as its working directory. A generic client configuration is:

{
  "mcpServers": {
    "comsol": {
      "command": "/absolute/path/to/comsol-mcp-verifier/.venv/bin/python",
      "args": ["-m", "em_design_mcp.server"],
      "env": {"EM_DESIGN_PACKAGE_ROOTS": "/absolute/path/to/design-packages"}
    }
  }
}

On Windows, use the checkout's .venv/Scripts/python.exe. These are placeholders, not required directory names. The optional EM simulation skill describes the same workflow for coding agents.

Discover and inspect once; pass the returned provenance ID to start_run. If the job is still running, use get_run with its revision and a server-side wait (maximum 55 seconds per call). Full arrays require include_result=true; normal responses provide bounded summaries and local artifact paths. With fixture profiles, explicitly select backend="mock".

The synchronous JSON CLI remains available for harnesses and keeps the em_design_mcp_cli_v1 envelope.

Connect real models

COMSOL version compatibility: COMSOL MCP Verifier targets COMSOL Multiphysics 6.0 and later. The core workflow was developed on COMSOL 6.0 and end-to-end smoke-tested on COMSOL Multiphysics 6.4 Build 429 with MATLAB R2026a. Version-specific installation paths and model-authoring APIs may differ between releases.

MCP workflow smoke-tested on COMSOL 6.4. This does not establish a complete compatibility matrix across physics modules or COMSOL APIs. See the smoke-test evidence and scope.

Real execution and inspection require MATLAB, COMSOL Multiphysics with LiveLink for MATLAB, the model's required modules/licenses, a running COMSOL server, and a trusted external package. None of those commercial assets are distributed here.

Copy .env.example to .env, configure runtime paths, and register package roots. See installation and LiveLink setup and the design package guide. Package discovery defaults to the sibling directory ../em_design_modals; EM_DESIGN_PACKAGE_ROOTS overrides it.

Evidence and limits

The test guide distinguishes Python tests, mocked adapter tests, MATLAB source checks, and reported real solver evidence. Public CI runs only the COMSOL-free suite and mock example. This source release includes no real COMSOL model or solver example package; reproducible physics regressions belong to external design packages.

• Preflight checks declared expectations. It does not establish Maxwell-equation correctness, convergence, suitable boundary conditions, or valid normalization.

• Saved model identity does not establish solution freshness. Execution receipts cover only the named measurement solutions explicitly recomputed by a run; arbitrary saved solutions and legacy table-only outputs remain unverified.

• Candidate validation supports a documented schema subset. Cost gates use declared sweep counts, not predictions of memory or solve time.

• Jobs are local subprocesses with retained files, not checkpoint/restart or scheduling infrastructure. Cancellation cannot guarantee interruption of work already running on a separately hosted COMSOL server.

• Source installation and trusted local use are the supported deployment model. Version support is a workflow target, not universal COMSOL API/module coverage.

Read architecture and trust boundaries and model observation, preflight, and freshness for the precise guarantees and limitations.

Development and publication

See contributing for scope, checks, and review expectations, and the publication checklist for release prerequisites.

This repository's source code and documentation are licensed under the MIT License, copyright 2026 yushi-zhou. This grant does not cover COMSOL Multiphysics, MATLAB, other third-party software, external MPH files, private design packages, or third-party datasets. Those have their own terms. This project is not affiliated with COMSOL or MathWorks.