envimcp — drive ENVI 5.2 from an AI agent over MCP

English | 简体中文

envimcp exposes the 58 ENVITask operators of a local ENVI 5.2 / IDL 8.4 installation to any MCP client (DeepSeek Harness, Codex, ZCode, Claude Desktop, …) as eight tools and five resources, with no ENVI GUI and no Python bridge.

MCP client (agent)
   │  stdio  or  streamable HTTP
   ▼
envimcp MCP server  (Python 3.12, mcp 2.3.0)
   ├─ TaskCatalog   reads D:\ENVI52\resource\templates\tasks\*.task   (58 operators)
   ├─ ScriptGen     emits literal-property IDL source per job
   └─ JobRunner     spawns  idl.exe -e "@<job>\run_job.pro"  (1 job at a time)
   ▼
IDL 8.4 process → ENVI(/HEADLESS) → ENVITask → status.json

Why not envipyengine

The obvious approach for "Python drives ENVI" does not work on this machine, for two independent reasons:

1. IDL 8.4 ships no IDL-Python bridge. There is no omniidl, no *.pyd and no Python DLL anywhere under D:\IDL84; D:\IDL84\lib\bridges contains only Java and COM bridges. NV5's own documentation: "IDL versions prior to 8.5 do not support Python bridge functionality."

2. Stronger: envipyengine does not use the bridge at all. It spawns taskengine.exe and exchanges JSON on stdin/stdout, and that executable first appears in IDL 8.5.2 / ENVI 5.3 (idltask.html version history: 8.5.2 | Introduced). IDL 8.5 alone is still not enough.

So this project takes the route that is supported: ENVI 5.2's documented ENVI(/HEADLESS), driven through idl.exe -e. The price is that ENVI task parameters can only be set as compile-time literal keywords, so Python generates IDL source instead of making calls. See IDL_NOTES.md for the 24 traps that shaped the generator.

Related MCP server: Task Tracker MCP

Install

Everything below assumes a local ENVI 5.2 / IDL 8.4 install and one checkout of this repository. <repo> stands for the absolute path of that checkout — it may contain spaces, which is why every command below quotes it. The project has only been verified on the machine that produced it. Create the environment first — the .venv directory is not part of the source tree:

# 1. create/reuse .venv, install the package, print a health report
pwsh -File '<repo>\tools\setup_env.ps1'
#    ...or, if the interpreter is not at the default path:
pwsh -File '<repo>\tools\setup_env.ps1' -Python D:\python312\python.exe

Then, from the repository root:

$root = '<repo>'
& "$root\.venv\Scripts\python.exe" -m envimcp.cli --config "$root\config\envimcp.toml" doctor

setup_env.ps1 needs D:\python312\python.exe (bare python does not resolve in this shell) and reaches packages through the Tsinghua mirror, because pypi.org is unreachable from this network. It finishes by running doctor, which prints a JSON health report and exits non-zero if anything is missing.

Configure

config/envimcp.toml is the only configuration file. Every key can be overridden by an ENVIMCP_* environment variable.

envi_idl.exe and idlde.exe are byte-identical Eclipse Workbench GUI launchers (MD5 E786D30B00ACE364B26657F98D79F03A) and are the wrong binary.

Command line

$py  = '<repo>\.venv\Scripts\python.exe'
$cfg = '<repo>\config\envimcp.toml'

& $py -m envimcp.cli --config $cfg doctor            # is this machine usable?
& $py -m envimcp.cli --config $cfg smoke             # end-to-end NDVI regression
& $py -m envimcp.cli --config $cfg tasks spectral    # search the operator catalog
& $py -m envimcp.cli --config $cfg schema SpectralIndex
& $py -m envimcp.cli --config $cfg inspect D:\ENVI52\data\qb_boulder_msi
& $py -m envimcp.cli --config $cfg run SpectralIndex `
      --input INPUT_RASTER=D:\ENVI52\data\qb_boulder_msi --input INDEX=NDVI --output '#ndvi.dat'
& $py -m envimcp.cli --config $cfg export D:\ENVI52\data\qb_boulder_msi '#msi.tif'
& $py -m envimcp.cli --config $cfg serve --transport stdio
& $py -m envimcp.cli --config $cfg serve --transport http --port 8765

smoke asserts the NDVI statistics against the measured golden baseline within 1e-6 and prints the deltas:

MCP client setup

stdio (DeepSeek Harness, Codex, ZCode):

{
  "mcpServers": {
    "envi": {
      "command": "<repo>\\.venv\\Scripts\\python.exe",
      "args": [
        "-m", "envimcp.cli",
        "--config", "<repo>\\config\\envimcp.toml",
        "serve", "--transport", "stdio"
      ]
    }
  }
}

streamable HTTP (long-lived server, multiple clients):

& $py -m envimcp.cli --config $cfg serve --transport http --port 8765

The endpoint is http://127.0.0.1:8765/mcp.

DeepSeek Harness does not use a JSON blob: it registers servers by patching its profile composition. The exact entry, the configuration keys it accepts, and a dependency-free handshake probe for verifying any client are in DSH_MCP_SETUP.md.

Tools

Every tool that starts work returns a job_id even when it also waits, because ENVI is single-licensed: a second request either queues or is rejected according to limits.on_busy.

Resources

Output URI tokens

A bare filename (name.dat) is rejected — an unconstrained path is an unconstrained write. .dat is appended when the name has no known extension.

ENVI 5.2 caveat: the *name token is not an ENVI feature. ENVI treats the URI literally, so envimcp gives the task a throwaway temporary file (e.GetTemporaryFilename()) and carries only the runtime raster handle to the next step. The observable contract is what matters: no intermediate file is delivered, and the next step sees the in-memory raster.

Typical agent flow

1. envi_list_tasks("vegetation") — find candidate operators.

2. envi_get_task_schema("SpectralIndex") — read required parameters and, for INDEX, the 64 accepted names. Note NDVI is not one of them; envimcp resolves the acronym, but the long name is Normalized Difference Vegetation Index.

3. envi_run_task(task="SpectralIndex", inputs={...}, output="#ndvi.dat").

4. Read steps[0].stats and steps[0].raster from the result.

For multi-step chains use envi_create_task_workflow with *NAME wiring:

{
  "steps": [
    {"task": "SpectralIndex",
     "inputs": {"INPUT_RASTER": "D:/ENVI52/data/qb_boulder_msi", "INDEX": "NDVI"},
     "outputs": {"OUTPUT_RASTER": "*NDVI"}},
    {"task": "LinearPercentStretchRaster",
     "inputs": {"INPUT_RASTER": "*NDVI", "PERCENT": 2.0},
     "outputs": {"OUTPUT_RASTER": "!stretched.dat"}}
  ]
}

Security model

• envi_run_idl is off by default. When on it executes arbitrary IDL with the full privileges of the ENVI session.

• Absolute output paths must resolve inside outputs_dir, jobs_dir or an explicitly pinned output root unless allow_outputs_outside_root is set.

• The #/!/* tokens accept only bare file names, so a token cannot escape its directory (#../../evil is rejected, not silently relocated).

• MCP resources use ResourceSecurity(reject_path_traversal=True, reject_absolute_paths=True, reject_null_bytes=True) — the mcp 2.x default.

• Every job is confined to jobs/<id>/; its status.json is the verdict.

Testing

cd '<repo>'
& .\.venv\Scripts\python.exe -m pytest tests -q -m "not slow"   # 52 fast tests, ~1.5 s
& .\.venv\Scripts\python.exe -m pytest tests -q -m slow         # 4 acceptance tests, ~20 s

The slow tests really launch idl.exe and re-assert the golden NDVI baseline (AC1), the virtual-raster workflow (AC6), the inspect path and a real GeoTIFF.

Troubleshooting

Deterministic detail for each of these lives in IDL_NOTES.md.