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.
• Abaqus-specific project artifacts are excluded from the reusable server distribution.

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

Tool	Effect	Confirmation
check_environment	Read-only environment check	No
validate_workspace	Creates workspace folders	Codex write approval
generate_script	Writes an Abaqus Python script	Codex write approval
run_script	Executes a reviewed Abaqus Python script	confirmed=true + SHA-256
submit_job	Starts a background solve and returns job_id	confirmed=true
run_job	Runs a synchronous solve and waits	confirmed=true
job_status	Reads .sta and .lck status	No
read_job_logs	Reads solver logs	No
extract_odb_summary	Runs Abaqus Python for ODB metadata	Codex write approval
extract_field_output	Writes field output CSV	Codex write approval
extract_history_output	Writes history output CSV	Codex write approval
clean_job	Deletes regenerable intermediates	confirmed=true

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

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

Variable	Default	Description
ABAQUS_COMMAND	auto-detect	Abaqus launcher path
ABAQUS_MCP_ABAQUS_COMMAND	auto-detect	Prefixed alias; takes precedence
ABAQUS_MCP_WORKSPACE_DIR	./abaqus_work	Sandboxed workspace
ABAQUS_MCP_MAX_CPUS	4	Maximum CPUs per job
ABAQUS_MCP_SCRIPT_TIMEOUT	300	Script timeout in seconds
ABAQUS_MCP_JOB_TIMEOUT	3600	Job timeout in seconds
ABAQUS_MCP_MAX_OUTPUT_CHARS	20000	Per-tool output limit
ABAQUS_MCP_ALLOW_OVERWRITE	false	Allow tool file overwrite
ABAQUS_MCP_ALLOW_HIGH_RISK_SCRIPTS	false	Permit reviewed high-risk scripts
ABAQUS_MCP_SCRIPT_MAX_BYTES	2000000	Maximum user script size
ABAQUS_MCP_KEEP_TEMP_ARTIFACTS	false	Retain internal temp sessions for diagnosis
ABAQUS_MCP_BACKGROUND_STARTUP_TIMEOUT	30	Background launcher probe limit
ABAQUS_MCP_LOG_LEVEL	WARNING	Server stderr log level

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

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 75% 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.