RETICOLO MCP — RCWA Solver via MATLAB Engine API

English | 中文

MCP server for the RETICOLO V10 rigorous coupled-wave analysis (RCWA) solver. Wraps MATLAB R2025b via the Engine API.

Quick start

# 1. Create conda env
conda create --name reticolo-mcp python=3.11 -y
conda activate reticolo-mcp

# 2. Install dependencies
pip install mcp numpy pydantic

# 3. Install MATLAB Engine API (one-time)
cd "D:\Program Files\MATLAB\R2025b\extern\engines\python"
pip install .

# 4. Install this package
pip install .

# 5. Set RETICOLO path and run
$env:RETICOLO_MCP_DIR = "D:\RETICOLO V10\V10_2025\reticolo_allege_v10"
python -m reticolo_mcp.server

opencode / Codex MCP config

{
  "reticolo": {
    "type": "local",
    "command": ["D:\\condaenvs\\reticolo-mcp\\python.exe", "-m", "reticolo_mcp.server"],
    "cwd": "D:\\reticolo_runtime",
    "environment": { "RETICOLO_MCP_DIR": "D:\\RETICOLO V10\\V10_2025\\reticolo_allege_v10" },
    "enabled": true,
    "timeout": 120000
  }
}

Use an ASCII-only cwd outside the checkout. A source-tree cwd can shadow the non-editable installation and makes the deployment receipt report source_tree.

Related MCP server: axiomatic-mcp

Tools

Use reticolo_capabilities as the live maturity and deployment receipt. Historical real-engine results below remain fixture evidence; they do not promote every current tool revision to verified status.

Synchronous sweep, convergence, and field export are disabled by default. Development-only access requires RETICOLO_MCP_ENABLE_EXPERIMENTAL=1 followed by an MCP host restart; the flag does not promote these tools to verified status.

Field artifacts, when experimental access is enabled, may only be written under RETICOLO_ARTIFACT_DIR (default: <runtime>/artifacts).

One-point incidence uses signed theta_deg and degree-valued azimuth_deg. RETICOLO receives ro=n_superstrate*sin(theta); nonzero angle requires a positive real uniform incident medium. Durable jobs currently remain normal-incidence only.

Durable job_submit requires an explicit resource policy. A warning decision must be resubmitted with the returned decision_hash; a refusal never launches a worker. Scientific acceptance policy is also caller-owned: point solves, sweeps, durable jobs, and convergence require passivity_tolerance; convergence additionally requires center, absorption, FWHM, and branch-match tolerances. Field export requires slice_tol, while field pairing requires a bounded coordinate_tolerance_um. These values enter artifacts or durable identity instead of server defaults.

Verification

After a non-editable install, verify the actual stdio transport from an ASCII directory outside the checkout. Supply identities from the reviewed build receipt:

python scripts\verify_installed_transport.py `
  --python "D:\condaenvs\reticolo-mcp\python.exe" `
  --cwd "D:\reticolo_runtime" `
  --reticolo-dir "D:\RETICOLO V10\V10_2025\reticolo_allege_v10" `
  --expected-version "<version>" `
  --expected-tool-count <count> `
  --expected-build-id "<build-sha256>" `
  --expected-schema-id "<schema-sha256>" `
  --output "D:\reticolo_runtime\installed_stdio_receipt.json"

The gate performs MCP initialization, tool discovery, and a capability call in a fresh child process. It fails if the installed identity/profile differs, MATLAB is imported during discovery, or the MATLAB PID set changes. Use --experimental only for a separately declared restart-bound profile check, then restart without it.

Archived convergence data can be audited without MATLAB by using scripts\audit_external_evidence.py. The audit first binds the manifest, script, point CSV, and summary CSV by SHA-256 and exact configuration identity. With the required --balance-tolerance, it checks derived R/T/A consistency. With --convergence-group-column plus center, absorption, FWHM, numeric-consistency, and maximum order-gap policy arguments, it then reconstructs each peak, two-sided half-prominence FWHM, Q, and adjacent-order center/A/width gate from raw rows. Provenance can pass while scientific acceptance returns exit code 2; such a receipt is a bounded residual, not an execution failure or capability promotion.

Known limitations

• Convergence: the MCP convergence path remains experimental and disabled by default. Archived Xu evidence passes an independent three-metric reconstruction, while the archived Sun summary lacks the width contract. Neither external result promotes MCP execution maturity.

• Field export: the old imag(apod) failure came from passing ef to RETICOLO's one-argument retchamp apodization helper. The corrected bounded res3 path has verified uniform-TE artifacts with embedded source/config/point/request identities. A solver-free recovery paired two real artifacts at a caller-selected 1e-12 um coordinate tolerance; the measured maximum delta was 5.55e-17 um. TM, resonant-mode classification, visual mode claims, and publication claims remain unaccepted.

⚠ Disk safety

RETICOLO's internal retio system spills large matrices to retXXXX/ scratch directories during high-order scans. This server defaults to memory mode (vmax=inf, no disk spill). MATLAB temp files are redirected to D:\matlab_temp.

Startup applies:

• retio([], inf*1i) — disable scratch writes

• TMP/TEMP/TMPDIR → D:\matlab_temp

• Working directory → D:\reticolo_scratch

• Lease with COMSOL MCP collision detection

Configuration

The server requires an external RETICOLO V10 installation. The bundled reticolo_v10/ directory in the repository is for development only and is not included in the PyPI wheel (CC-BY 4.0 — separate from the MIT wrapper).

$env:RETICOLO_MCP_DIR = "D:\RETICOLO V10\V10_2025\reticolo_allege_v10"
python -m reticolo_mcp.server --reticolo-dir "D:\RETICOLO V10\V10_2025\reticolo_allege_v10"

Architecture

reticolo-mcp/
├── src/reticolo_mcp/
│   ├── server.py        # FastMCP server, all tools
│   ├── engine.py        # MATLAB Engine lifecycle + solve
│   ├── lease.py         # Atomic solver lease (named mutex)
│   ├── sweep.py         # Resumable sweep + peak analysis
│   ├── jobs.py          # Durable job store (spec/state/events)
│   ├── worker.py        # Detached worker process
│   ├── convergence.py   # Progressive harmonic convergence
│   ├── evidence_audit.py # Solver-free archived evidence and claim reconstruction
│   ├── field_export.py  # bounded res3 field export
│   ├── schema.py        # Pydantic models for materials/geometry
│   ├── config_hash.py   # Canonical SHA-256 config identity
│   └── config.py        # Paths, limits, env vars
├── reticolo_v10/        # Bundled RETICOLO V10 (CC-BY 4.0, dev only)
├── tests/               # Unit + integration tests
├── pyproject.toml
├── LICENSE              # MIT (wrapper code)
├── NOTICE               # CC-BY 4.0 attribution
└── README.md

License

• MCP wrapper code (all Python files): MIT License.

• Bundled RETICOLO V10 (reticolo_v10/): CC-BY 4.0, © Jean Paul Hugonin & Philippe Lalanne. DOI: 10.5281/zenodo.14631951.

See LICENSE and NOTICE for details.