acm-mcp

# ACM MCP Server An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that automates **Aspen Custom Modeler (ACM)** via COM. Designed for use with Claude Code to open `.acmf` files, run simulations, and read/write variable values programmatically. ## Features - **15 MCP tools** for full ACM automation: session management, steady-state and dynamic simulation, variable access, and task control - **Session-based** — manage multiple ACM instances - **COM automation** via `comtypes` (not `win32com`, which has known VARIANT issues with ACM) - **Comprehensive docs** — includes condensed ACM V15 Help (2,227 pages distilled to 10 markdown files) ## Requirements - **Windows** (COM automation is Windows-only) - **Python 3.10+** - **Aspen Custom Modeler V15** installed - **Claude Code** (or any MCP-compatible client) ## Installation ```bash pip install "mcp[cli]>=1.0.0" "comtypes>=1.4.0" ``` ## Setup with Claude Code Add this to your project's `.mcp.json`: ```json { "mcpServers": { "acm": { "command": "python", "args": ["<path-to>/acm-mcp/server.py"] } } } ``` Restart Claude Code after first setup to pick up the server. ## Tools ### Session Tools | Tool | Description | |---|---| | `open_acm` | Open an `.acmf` file and create a session | | `connect_acm` | Connect to an already-running ACM instance | | `close_acm` | Close a session and quit ACM | | `list_acm_sessions` | List all active sessions | ### Simulation Tools | Tool | Description | |---|---| | `run_steady_state` | Run steady-state simulation | | `run_dynamic` | Run dynamic simulation to a specified end time | | `get_simulation_status` | Get current status, DOF, convergence info | | `reset_simulation` | Reset to initial conditions | ### Variable Tools | Tool | Description | |---|---| | `get_variable` | Get a variable by dot-notation path (e.g. `B1.Tank.h`) | | `set_variable` | Set a variable's value | | `get_variables_bulk` | Get multiple variables at once | | `find_variables` | Find variables matching a wildcard pattern | ### Task Tools | Tool | Description | |---|---| | `create_task` | Create a task on the flowsheet | | `activate_task` | Activate a task for dynamic simulation | | `deactivate_task` | Deactivate a task | ## Quick Start ``` 1. open_acm("path/to/model.acmf") 2. run_steady_state("model") 3. get_variable("model", "B1.Tank.h") → "B1.Tank.h = 40.0 [cm] (Free)" ``` ### Dynamic step change procedure To observe transient dynamics after a step change: 1. `run_steady_state` at initial conditions 2. `run_dynamic` to a small time (e.g. 0.001) — locks state variables at old SS 3. `set_variable` to apply the step change 4. `run_dynamic` to successive times, reading variables at each point > **Important:** Do NOT `set_variable` before the first `run_dynamic` — ACM re-initializes state variables at the new conditions, producing an instant jump to new SS with no visible transient. ## Documentation Detailed documentation is in `docs/`: - [`overview.md`](docs/overview.md) — Architecture and design decisions - [`tools.md`](docs/tools.md) — Full tool reference with parameters and examples - [`com-api.md`](docs/com-api.md) — ACM COM API notes and gotchas - [`Error_Logbook.txt`](docs/Error_Logbook.txt) — Known ACM errors and fixes - [`acm_help/`](docs/acm_help/) — Condensed ACM V15 Help system (10 files covering modeling language, solver options, library reference, examples, etc.) ## Architecture ``` server.py # FastMCP entry point, 15 tool registrations acm_manager.py # COM lifecycle: subprocess launch, GetActiveObject, sessions tools/ session_tools.py # open, connect, close, list simulation_tools.py # run steady/dynamic, status, reset variable_tools.py # get, set, bulk get, find task_tools.py # create, activate, deactivate docs/ # Documentation and ACM Help reference ``` ## License MIT