Content
# Aspen-MCP: schema-constrained tool-calling for Aspen Plus
An [MCP](https://modelcontextprotocol.io) server that exposes **typed, schema-constrained tools** for
driving [Aspen Plus](https://www.aspentech.com/) via COM automation — so a language model can
interrogate, specify, build, run, and optimize process flowsheets **without writing raw `win32com`
code**. Ships with a declarative blank→simulatable **flowsheet builder** and an **evaluation harness**
that benchmarks schema-constrained tool-calling against raw code-generation.
> Research code accompanying our study on driving chemical-process simulators with local open-weight
> LLMs. See [`evaluation/E6_failure_taxonomy.md`](evaluation/E6_failure_taxonomy.md) for the failure
> analysis behind the headline result (schema-constrained tools convert *interface* errors into either
> success or a much smaller class of *reasoning* errors).
## Why
The Aspen COM tree isn't learnable from pre-training, so an LLM asked to write `win32com` code
overwhelmingly hallucinates variable paths (`Tree.FindNode(...)` returns `None`). A typed tool layer
removes that entire failure mode: the model calls `get_stream_data`, `set_block_conditions`,
`build_flowsheet_from_spec`, … and the schema does the rest.
## What's inside
| Path | What it is |
|------|-----------|
| `src/aspen_mcp_server.py` | The MCP server — 42 typed tools over the Aspen COM API (identical tool surface on both stdio and HTTP transports) |
| `src/flowsheet_builder.py`, `src/flowsheet_spec.py`, `src/flowsheet_normalize.py`, `src/flowsheet_bkp.py` | Declarative spec → simulatable `.bkp` builder |
| `src/com_funnel.py` | Serializes all COM calls onto one owning thread (multi-agent safety) |
| `src/eo_bridge.py`, `src/tea_bridge.py` | Equation-oriented optimization + techno-economic analysis bridges (orchestration only — they drive external AspenEO/TEA framework packages that are **not included**; see `requirements.txt`) |
| `src/Configurations/`, `src/Extract/`, `src/aspen_simulator.py`, `src/utils.py` | Supporting COM/config layer |
| `evaluation/` | Benchmark harness: code-gen vs tool-calling, autonomous synthesis, routing, and the SPEC_OPT ablation (+ curated result logs in `results/`) |
| `demos/` | Standalone builder demos + `showcase.py`, an end-to-end showcase (prompt → built & converged cyclohexane process → stream table) |
| `tests/` | Integration tests (COM funnel, MCP build, priority tool suites) |
| `docs/TOOLS.md` | Reference for every MCP tool |
| `Aspen_Flowsheet/` | A blank template (`Template file.bkp`) + example processes |
> Run all commands **from the repo root** — data paths (`Aspen_Flowsheet/`, `results/`) resolve
> relative to it. Demos, tests, and the evaluation package locate `src/` automatically.
## Requirements
- **Windows** with **Aspen Plus** installed (COM automation; developed on Aspen Plus V14).
- **Python 3.10+**
- An **OpenAI-compatible LLM endpoint** (local vLLM, etc.) for the tool-calling / eval paths.
```bash
pip install -r requirements.txt
```
> ⚠️ **Reproducibility:** Aspen Plus is proprietary, so the live simulation paths cannot be reproduced
> without an Aspen license + Windows. The curated logs in `results/*.jsonl` let you inspect and replot
> the paper's numbers without running Aspen.
## Verify your install (no Aspen needed)
Three self-test suites run without Aspen Plus or an LLM endpoint — each should end with an
`ALL ... TESTS PASSED` line:
```bash
python src/flowsheet_normalize.py # spec normalizer: aliases, SPEC_OPT inference, name sanitization
python tests/test_com_funnel.py # COM funnel: single-owner-thread serialization, reentrancy, errors
python -m evaluation.test_sandbox_mock # code-gen sandbox + failure taxonomy on a mocked Aspen
```
Together they exercise the spec-normalization layer, the concurrency machinery, and the evaluation
harness's scoring path — so a green run means the repo is wired correctly before you bring Aspen or
a model endpoint into the loop.
## Quickstart
**1. Run the MCP server** (see the top of `src/aspen_mcp_server.py` for stdio vs. HTTP options) and
point your MCP client (Claude Desktop, OpenClaw, …) at it. For the HTTP transport, set an optional
bearer token via `ASPEN_MCP_TOKEN` (see `.env.example`):
```bash
python src/aspen_mcp_server.py --transport http --host 127.0.0.1 --port 8765
```
**2. Try the builder** (no LLM needed):
```bash
python demos/demo_build_flowsheet.py # spec -> blank -> simulatable flowsheet
python demos/demo_build_reaction_spec.py # a stoichiometric-reactor flowsheet
```
**3. Run the evaluation harness** against your LLM endpoint:
```bash
export ASPEN_EVAL_LLM_BASE_URL=http://localhost:8000/v1 # your OpenAI-compatible endpoint
python -m evaluation.check_env # sanity-check connectivity
python -m evaluation.run_2x2 --help # code-gen vs tool-calling, per model
```
See [`evaluation/README.md`](evaluation/README.md) for the full harness.
**4. Autonomous synthesis showcase** — a local model designs, builds, and runs a process from one brief:
```bash
python demos/showcase.py # the model builds a cyclohexane reactor->flash process and runs it to convergence
```
## Results & reproducibility
The harness produces the paper's findings; the curated logs in `results/` let you inspect them without
an Aspen license:
- **Schema-constrained tools ≫ code-generation.** Hallucinated COM variable paths dominate code-gen
failures; the typed-tool layer converts them into success or a much smaller class of *reasoning*
errors. Failure taxonomy: [`evaluation/E6_failure_taxonomy.md`](evaluation/E6_failure_taxonomy.md);
definitive log: `results/e3_final_v2.jsonl` (+ the run-history repetitions `results/e3_2x2*.jsonl`,
`results/e3_rep4_steps16.jsonl`), code-gen: `results/e0_codegen_k*.jsonl`.
- **Autonomous conceptual synthesis** — build a *converged* flowsheet from a one-line brief (verified by
reopening the persisted artifact). Harness: `evaluation/run_synthesis_bench.py`; log:
`results/synthesis_bench3.jsonl`.
- **SPEC_OPT ablation** — a measured intervention: one toggle isolates a single normalizer fix to test
whether it moves the small model. Pre-registration + method + result in
[`evaluation/SPEC_OPT_ABLATION.md`](evaluation/SPEC_OPT_ABLATION.md); logs: `results/syn_specopt_*.jsonl`.
Reproduce: `python -m evaluation.run_specopt_ablation && python -m evaluation.print_specopt_ablation`.
- **Heterogeneous routing** — a static read→small / write→large policy retains most of the large model's
successes at lower token and wall-clock cost. `evaluation/run_routing.py`.
- **Techno-economic analysis** — `run_tea` auto-maps arbitrary block names onto the costing nomenclature
and computes CAPEX / OPEX / annualized profit on any converged flowsheet. Validation:
[`results/tea_validation.md`](results/tea_validation.md).
## Citing
- **This repository / the MCP tool-calling study** — see [`CITATION.cff`](CITATION.cff) (GitHub's
"Cite this repository" button), or cite the preprint:
> Son, Y. W., Kim, C., Pak, J. H., Kim, D. W., Lee, K., & Lee, J. M. (2026). Autonomous flowsheet
> synthesis, simulation, and analysis with a locally deployed language model agent: An open-standard
> interface to Aspen Plus. *ChemRxiv*. https://doi.org/10.26434/chemrxiv.15006587/v1
```bibtex
@article{Son_Kim_Pak_Kim_Lee_Lee_2026,
title={Autonomous Flowsheet Synthesis, Simulation, and Analysis with a Locally Deployed Language Model Agent: An Open-Standard Interface to Aspen Plus},
DOI={10.26434/chemrxiv.15006587/v1},
author={Son, Yeong Woo and Kim, Chan and Pak, Ji Hun and Kim, Dong Woo and Lee, Kyoungmin and Lee, Jong Min},
year={2026}
}
- **The Aspen Plus COM automation layer** (`src/utils.py`, `src/Configurations/`, `src/Extract/`,
`src/aspen_simulator.py` — i.e., if you use the win32com framework underneath the tools), please cite:
> Son, Y. W., Kim, C., Pak, J. H., Lee, H., & Lee, J. M. (2026). Automated generative process
> synthesis via transformer-based dual-loop simulation and optimization. *AIChE Journal*, e70489.
> https://doi.org/10.1002/aic.70489
```bibtex
@article{son2026automated,
author = {Son, Yeong Woo and Kim, Chan and Pak, Ji Hun and Lee, Hain and Lee, Jong Min},
title = {Automated generative process synthesis via transformer-based dual-loop simulation and optimization},
journal = {AIChE Journal},
year = {2026},
pages = {e70489},
doi = {10.1002/aic.70489}
}
```
- **The TEA methodology** (the costing framework `src/tea_bridge.py` orchestrates) — the manuscript is
currently under review; its citation will be added here upon publication. Until then, please cite
the framework paper above and this repository.
## License
[MIT](LICENSE).
