# ampl-mcp

An MCP server exposing AMPL optimisation modelling to coding agents, plus a
matching Claude plugin.

## Requirements

- An AMPL licence UUID (free community licences: https://ampl.com/ce) - optional, see below
- `uv` / `uvx`

## Install as a Claude Code plugin

This repository is its own plugin marketplace, so both steps take the repo URL:

    /plugin marketplace add worc4021/ampl-mcp
    /plugin install ampl@ampl-mcp

The plugin runs the server straight from its own checkout
(`uv run --directory ${CLAUDE_PLUGIN_ROOT} ampl-mcp`), so nothing needs to be
published to PyPI and no `UV_INDEX` has to be set - the AMPL package index is
declared in `pyproject.toml`.

Set your licence UUID first if you have one - it is optional, see "Licensing":

    setx AMPLKEY_UUID "your-uuid-here"     # Windows, then open a new terminal
    export AMPLKEY_UUID=your-uuid-here     # POSIX

## Run the server directly

From a checkout, without installing the plugin:

    uv run ampl-mcp

The package is not on PyPI, so `uvx ampl-mcp` will not resolve it. Use
`uvx --from . ampl-mcp` from a checkout if you want the uvx form.

## Licensing

Without `AMPLKEY_UUID` the server still runs, on the wheel's shipped
size-limited demo licence - small models solve correctly; a model past the
demo's size limit fails with an error that reads like a modelling problem.
Call the `ampl_version` tool to see which tier is active before assuming a
failure is a modelling bug.

With `AMPLKEY_UUID` set, activation happens lazily on the first session and
is persisted to a durable directory so it survives across runs:
`%LOCALAPPDATA%/ampl-mcp/licence` on Windows,
`~/.local/share/ampl-mcp/licence` on POSIX (override with
`AMPL_MCP_LICENCE_DIR`).

## Development

    UV_INDEX=https://pypi.ampl.com uv run pytest

Tests marked `licence` are skipped when no AMPL engine can be constructed
(see `tests/conftest.py`) - `AMPLKEY_UUID` is not required, because the AMPL
wheel ships a size-limited demo licence that is enough to build an engine.
Set `AMPL_MCP_REQUIRE_ENGINE=1` in CI to turn that skip into a hard failure.

## Security note

The server blocks AMPL's `shell` and `cd` statements (in `ampl_eval`,
`ampl_sweep`'s `collect` expressions, and in files loaded by
`ampl_read_files`) to prevent *accidental* shell/cd use. This is an
accident-preventer, not a sandbox: it is not a guarantee that shell execution
is impossible. Set `AMPL_MCP_ALLOW_SHELL=1` if you need those statements.

Two things it deliberately does **not** stop:

- **Loading a file runs that file's contents unchecked.** `include`,
  `commands`, `model`, `data` and `load` are permitted on purpose - by
  project ruling, whoever approves the call owns what the loaded file does.
  The guard sees only the text handed to the server, so a `shell` inside a
  loaded file (or inside anything it loads in turn) will run. `ampl_eval`,
  `ampl_read_files` and `ampl_display` return a `warnings` list when they
  see such a statement; they do not refuse it.
- **AMPL expression text is not confined to the working directory.** The
  path guard applies to this server's own path *arguments*. AMPL's own
  output redirection - `ampl_display("1 > 'C:/anywhere/file.txt'")` - writes
  outside the session workdir, and an `include` with an absolute path reads
  from outside it.

## Configuration

| Variable | Purpose |
|---|---|
| `AMPLKEY_UUID` | AMPL licence UUID. Read from the environment only. |
| `UV_INDEX` | Must include `https://pypi.ampl.com`. |
| `AMPL_MCP_LICENCE_DIR` | Override the durable licence directory. |
| `AMPL_MCP_ALLOW_SHELL` | Set to `1` to permit AMPL's `shell` and `cd`. |