GEMPACK MCP

An MCP server that exposes the local GEMPACK CGE toolchain (TABLO, GEMSIM, HAR utilities) as tools Claude can call: compile models, run simulations, read solution and HAR data files, and export to CSV/Excel.

中文速览：这是一个把本机 GEMPACK（TABLO/GEMSIM/HAR 工具链）封装成 MCP 工具的服务， 让 Claude 能直接帮你编译模型、跑模拟、读 SL4/HAR 结果、导出 CSV/Excel。 已注册到 Claude Code（user 作用域），工作区指向存放模型的文件夹（如 ./workspace），开箱即用。

---

Setup

Item	Value
GEMPACK binaries (GP_DIR)	C:\Program Files\GP (with dll64\ runtime)
GEMPACK version	12.1.004
Licence	a GEMSIM-only GEMPACK licence
Workspace (sandbox root)	a folder or drive that holds your GEMPACK models (.tab/.cmf/.har/.sl4)
Models	your own model folders under the workspace
Python	.venv\Scripts\python.exe (FastMCP 3.3)
Transport	stdio (registered with Claude Code); HTTP optional

Licence limitation that shaped the design: this licence does not permit TABLO to generate Fortran code. Only the interpretive GEMSIM engine is available — so compile always targets GEMSIM aux files and run_simulation uses the gemsim (or sagem) solver. TABLO-generated model EXEs are not built.

---

Tools

All file arguments are workspace-relative (or absolute inside the workspace) and confined to the sandbox root.

Tool	What it does
gempack_list_workspace(subdir=".")	List .tab/.cmf/.har/.sl4 files to discover what's available.
gempack_compile_tab(tab_file, sti_file=None, aux_name=None)	Compile .tab → GEMSIM .gss/.gst. Pass your own .sti for models needing condensation; otherwise a no-condensation GEMSIM stored-input is generated.
gempack_run_simulation(cmf_file, solver="gemsim")	Run a simulation from a .cmf → .sl4 solution, .upd data, summary .har. Aux files must already exist.
gempack_read_solution(sl4_file)	Convert .sl4 → <stem>_sol.har and list every solved variable (name → header code → size).
gempack_list_har_headers(har_file)	List headers in a HAR file (4-char code, dimensions, type) + a full .see dump.
gempack_read_har_header(har_file, header)	Extract one header to CSV (long format: index columns + Value).
gempack_convert(src_file, dst_file, headers=None)	Export HAR → CSV or HAR → XLS/XLSX (legacy .xls, one header per sheet).

Typical flow

1. gempack_list_workspace("examples/minimal") — see the files.
2. gempack_compile_tab("examples/minimal/minimal.tab") — build aux files.
3. gempack_run_simulation("examples/minimal/MINIMAL.CMF") — solve.
4. gempack_read_solution(<the .sl4 from step 3>) — list result variables.
5. gempack_read_har_header(<solution_har>, <header code>) — read values.

Note: some tools leave artifacts next to your model files by design — seehar writes <stem>-har.see, read_solution writes <stem>_sol.har, read_har_header writes _<stem>_<header>.csv. These are returned as paths so you can open them; delete them if you don't want them.

---

Install / register

To install and register:

# 1. dependencies
.venv\Scripts\python.exe -m pip install -r requirements.txt

# 2. register with Claude Code (user scope, stdio)
claude mcp add -s user gempack -e GEMPACK_WORKSPACE=./workspace -- `
  "<path-to-repo>\.venv\Scripts\python.exe" `
  "<path-to-repo>\server.py"

# 3. verify
claude mcp list        # -> gempack: ... ✓ Connected

To remove: claude mcp remove gempack -s user.

Use a forward slash (e.g. D:/models) for the workspace value — a trailing backslash gets escaped against the quote on Windows and breaks claude mcp add.

Changing the sandbox root

The server reads file paths only inside its allowed roots. Set:

• GEMPACK_WORKSPACE — primary root (relative paths resolve here).
• GEMPACK_EXTRA_ROOTS — extra read/write roots, ;-separated (e.g. add F:\).

Anything outside these roots is refused (verified: C:\Windows\win.ini is blocked).

---

Configuration (env vars)

See .env.example. Key defaults:

Var	Default	Meaning
GEMPACK_DIR	C:\Program Files\GP	GEMPACK install.
GEMPACK_WORKSPACE	<project>\workspace	Sandbox root (relative paths resolve here).
GEMPACK_EXTRA_ROOTS	(empty)	Extra allowed roots, ;-separated.
GEMPACK_SIM_TIMEOUT	1800	Simulation timeout (s).
GEMPACK_COMPILE_TIMEOUT	600	Compile timeout (s).
GEMPACK_TOOL_TIMEOUT	180	HAR/convert timeout (s).

A .env file in the project root is loaded automatically; the MCP client's env block and real environment variables override it.

---

HTTP transport (optional — for Claude on another machine)

Not needed for local use. If you want a remote Claude to reach this server:

$env:GEMPACK_TOKEN = "<a-long-random-secret>"   # required
.\run-http.bat          # serves http://127.0.0.1:8765/mcp

Clients must send Authorization: Bearer <token>. To accept connections from other machines, set GEMPACK_HTTP_HOST=0.0.0.0 and open the port in the firewall (see run-http.bat for the netsh command).

---

Tests

tests\test_e2e.py drives every operation against a pristine copy of the minimal example (in tests\minimal\) using the real GEMPACK engine:

$env:PYTHONPATH = (Get-Location)
.venv\Scripts\python.exe tests\test_e2e.py
# -> === required: 9/9 passed; info: 2/2 ok ===

---

Layout

gempack-mcp\
  server.py            FastMCP server: 7 tools + stdio/HTTP launch
  gempack_mcp\
    config.py          env-var config (paths, roots, timeouts, token)
    sandbox.py         path confinement to the allowed roots
    runner.py          non-interactive subprocess runner (EOF stdin, file snapshot)
    gp.py              the GEMPACK operations (verified CLI invocations)
  tests\test_e2e.py    end-to-end test against the minimal example
  run-stdio.bat        launch stdio manually
  run-http.bat         launch HTTP (needs GEMPACK_TOKEN)
  .env.example         documented configuration
  requirements.txt