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

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

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

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