# Abaqus Codex MCP

[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-stdio-orange)](https://modelcontextprotocol.io/)
[![CI](https://github.com/MOBAI547800/abaqus-codex-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/MOBAI547800/abaqus-codex-mcp/actions/workflows/ci.yml)

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`](https://github.com/MOBAI547800/abaqus-mcp-server).
See [UPSTREAM.md](UPSTREAM.md) for provenance and the maintained differences.

中文安装说明：[docs/CODEX_SETUP.zh-CN.md](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.

## 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

```powershell
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:

```toml
[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` |
| `build_dual_belt_polishing_model` | Builds a dual-belt CAE/INP project through a fixed worker | `confirmed=true` + config SHA-256 |
| `calibrate_contact_force` | Runs real adaptive force calibration and G0-G7 checks | `confirmed=true` + config SHA-256 |
| `simulate_polishing_quality` | Runs the rigid-equivalent rough/fine quality pipeline and outputs four metrics | `confirmed=true` + input-bundle SHA-256 |

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](docs/POLISHING_MODEL.zh-CN.md) and
[contact-force calibration documentation](docs/CONTACT_FORCE_CALIBRATION.zh-CN.md).
For the recommended 0.5.0 pipeline, see
[rigid polishing quality model](docs/RIGID_POLISHING_QUALITY_MODEL.zh-CN.md),
[quality metrics](docs/QUALITY_METRICS.zh-CN.md), and
[workspace cleanup](docs/WORKSPACE_CLEANUP.zh-CN.md).

`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

```powershell
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](LICENSE).