Abaqus Codex MCP

A secure local STDIO MCP server that lets OpenAI Codex automate Abaqus FEM workflows: create model scripts, submit jobs, monitor solver logs, and extract ODB results.

This project is a Codex-focused derivative of MOBAI547800/abaqus-mcp-server. See UPSTREAM.md for provenance and the maintained differences.

中文安装说明：docs/CODEX_SETUP.zh-CN.md

What makes this the Codex edition

• Codex-ready config.toml example and Windows installer.

• Server-level MCP instructions that teach Codex the safe Abaqus workflow.

• Read/write/destructive MCP annotations for Codex tool approval policies.

• Content-bound SHA-256 approval for user script execution.

• Stable job IDs with separate background submission and synchronous solve tools.

• Static ODB worker plus JSON payloads; selectors never enter generated source.

• Reproducible protocol tests, including the parser fixtures missing upstream.

• Windows CI across Python 3.10 and 3.14 with coverage and package gates.

• Both ABAQUS_COMMAND and ABAQUS_MCP_ABAQUS_COMMAND are supported.

• Parameterized true-cylinder, mirrored dual-belt polishing model construction.

• Resumable 30 N / 20 N contact-force calibration with independent final reruns.

• Rigid-equivalent two-stage quality simulation with roundness, straightness, Ra, and efficiency outputs.

• Abaqus-specific project artifacts are excluded from the reusable server distribution.

The legacy 0.4.0 engineering baseline has real Abaqus 2025 evidence for the independent 30 N and 20 N target-force reruns, but it does not yet pass every physical quality gate: pretension (G3) and pressure-area force closure (G7) remain blockers. The calibration tool reports QUALITY_GATES_FAILED instead of a false success until those checks pass. Final INP generation and Standard solves are verified; the current CAE import path exceeded its bounded 1800 s timeout and is not claimed as a successful artifact.

Related MCP server: COMSOL MCP Server

Requirements

• Windows 10 or 11

• Python 3.10+

• OpenAI Codex CLI, ChatGPT desktop app, or Codex IDE extension

• Abaqus (tested against an Abaqus 2025-style command layout)

Abaqus and its license are not bundled.

Quick start on Windows

git clone https://github.com/MOBAI547800/abaqus-codex-mcp.git
Set-Location abaqus-codex-mcp

powershell -ExecutionPolicy Bypass -File .\scripts\install-codex.ps1 `
  -AbaqusCommand "D:\SIMULIA\Commands\abaqus.bat" `
  -Workspace "D:\AbaqusCodexWorkspace"

Restart the ChatGPT desktop app or Codex extension after registration, then ask:

Check the Abaqus environment and validate the workspace. Do not submit a job.

The installer creates .venv, installs the package, creates the workspace, and registers the server with codex mcp add. If the Codex executable is unavailable, it still completes the local install and prints the manual configuration path.

Manual Codex configuration

Codex stores MCP configuration in ~/.codex/config.toml. Replace the paths:

[mcp_servers.abaqus]
command = "D:\\path\\to\\abaqus-codex-mcp\\.venv\\Scripts\\python.exe"
args = ["-m", "abaqus_mcp_server.cli", "serve"]
cwd = "D:\\path\\to\\abaqus-codex-mcp"
startup_timeout_sec = 30
tool_timeout_sec = 7200
default_tools_approval_mode = "writes"
enabled = true

[mcp_servers.abaqus.env]
ABAQUS_COMMAND = "D:\\SIMULIA\\Commands\\abaqus.bat"
ABAQUS_MCP_WORKSPACE_DIR = "D:\\AbaqusCodexWorkspace"
ABAQUS_MCP_MAX_CPUS = "4"
ABAQUS_MCP_SCRIPT_TIMEOUT = "300"
ABAQUS_MCP_JOB_TIMEOUT = "3600"
ABAQUS_MCP_ALLOW_HIGH_RISK_SCRIPTS = "false"
ABAQUS_MCP_SCRIPT_MAX_BYTES = "2000000"
ABAQUS_MCP_KEEP_TEMP_ARTIFACTS = "false"
ABAQUS_MCP_BACKGROUND_STARTUP_TIMEOUT = "30"
ABAQUS_MCP_LOG_LEVEL = "WARNING"

The desktop app, Codex CLI, and IDE extension share this configuration on the same Codex host.

Tools

All user-controlled paths are constrained to ABAQUS_MCP_WORKSPACE_DIR. clean_job never deletes .odb, .inp, or .cae.

The polishing tools implement macro-scale continuous-belt contact only. Default belt material, friction, pretension, compliance, and target-force values are marked UNCALIBRATED_ENGINEERING_BASELINE. They are not a material-removal, thermal, roughness, or DOE model. Only a real licensed Abaqus independent final job that passes every G0-G7 gate is reported as calibrated.

See polishing model documentation and contact-force calibration documentation. For the recommended 0.5.0 pipeline, see rigid polishing quality model, quality metrics, and workspace cleanup.

submit_job uses Abaqus background mode and returns promptly. run_job uses interactive mode and reports completed only when the Abaqus status file has the success marker. Prefer job_id for job_status, read_job_logs, and clean_job; duplicate job names are never silently resolved.

Background submission persists a pending registry record before Abaqus is started. Startup observation reports the configured probe limit and the first explicit launcher/.lck/.sta observation; failed starts remain queryable by the same job_id.

ODB extraction uses the package's fixed odb_worker.py and a JSON payload in a unique .mcp_tmp session. Field components and invariants are distinct, instance filters use getSubset(region=...), HistoryOutput is read as (time, value) pairs, and CSV files are published atomically. Existing CSV files are not replaced unless allow_overwrite=true is explicit.

Configuration

Development and verification

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest tests -v
.\.venv\Scripts\python.exe -m pytest tests --cov=abaqus_mcp_server --cov-report=term-missing --cov-fail-under=80

The default suite does not require Abaqus. A real local verification can be run after installation through the safe check_environment tool.

GitHub Actions runs the mocked test suite on Windows with Python 3.10 and 3.14, enforces at least 80% package coverage, builds both distribution formats, and smoke-installs the wheel. A licensed Abaqus solve remains a local verification because GitHub-hosted runners do not include Abaqus or its license.

Security model

• No arbitrary shell command tool.

• Subprocess calls use explicit argument arrays and never shell=True.

• Paths are resolved and checked against the configured workspace.

• Output is truncated before returning it to the model.

• Execution and deletion require both Codex approval policy and server-side confirmation where applicable.

• Solver success is reported only from actual Abaqus output/status files.

• run_script first returns the file size, SHA-256, and AST risk findings. The confirmed call must provide the same hash; obvious high-risk imports/calls are blocked by default.

• AST screening resolves imported aliases such as import os as x and from pathlib import Path as P; destructive Path.unlink()/Path.rmdir() calls are treated as high risk.

These controls are not an operating-system sandbox. A Python script that is allowed to run can use the permissions of the server process, including access outside the configured workspace. For true isolation use a low-privilege Windows account, virtual machine, or dedicated compute node. AST screening is a preflight control and cannot detect every malicious program.

License

MIT. The original upstream copyright and license are preserved in LICENSE.