Ampl mcp
How to drive the ampl MCP server - start a session, declare or load an AMPL model, set data, solve, read duals and diagnose infeasibility, and run parametric sweeps. Use whenever working with AMPL, optimisation models, .mod/.dat/.run files, LP/MIP/NLP formulations, or this server's tools.From its SKILL.md
npx -y skills add worc4021/ampl-mcp --skill ampl-mcpAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
10.4 KB, as published. Nobody here has run it
Driving the AMPL MCP server
This server exposes sixteen tools: ampl_version, ampl_init_session,
ampl_list_sessions, ampl_use_session, ampl_restart_session,
ampl_close_session, ampl_eval, ampl_read_files, ampl_list_entities,
ampl_set_data, ampl_get_data, ampl_display, ampl_option, ampl_solve,
ampl_sweep, ampl_diagnose.
Session model
The server starts no AMPL engine when it connects. Call
ampl_init_session before any other tool. If a tool reports "no AMPL session
is running", that is what it means.
workdir defaults to a temporary directory. Pass a real path to work against
project files. Every path argument to a tool (ampl_read_files's
model/data/run) is resolved inside it and escapes are refused - but
that is not a sandbox, and two things reach outside it:
- AMPL expression text is not path-guarded.
ampl_display("1 > 'C:/somewhere/else.txt'")uses AMPL's own output redirection and writes outside the workdir, reportingok: true. include(and friends) with an absolute path reads a file from anywhere. See "Guard" below.
Treat the workdir as where work is meant to happen, not as a boundary that holds.
Use ampl_restart_session to discard model state and start clean. It is also
the recovery path if the engine becomes unresponsive.
Check every result's ok, not just the absence of an exception
No tool raises out of the MCP layer - a problem comes back as a normal
result with "ok": false and an error_class/message. Several tools
(ampl_eval, ampl_get_data, ampl_solve, ampl_sweep, ampl_read_files)
can report a structured failure this way for a single statement or run while
the rest of the call still "succeeds" in the sense of not throwing. Always
check the top-level ok; never infer success from the call merely returning.
Separately from ok, a result may carry a top-level warnings list of
strings. That means the call succeeded and did something the user should
know about - today, that it loaded a file whose contents were executed
without being guard-checked. Relay it; do not silently drop it.
Check the licence when anything is strange
ampl_version reports the licence tier. A demo licence solves small models
correctly and fails only when the model exceeds its size limit, with an
error that reads like a modelling problem. If a model that should work does
not, call ampl_version before debugging the formulation.
AMPL syntax that catches people out
- A set literal needs braces. Both
set S = {1,2,3};andset S := {1,2,3};work in model mode. What fails is omitting the braces, e.g.set S := 1 2 3;- that is a syntax error. - Declare before you use.
param c{S};requiresSto exist already. subject to(ors.t.) introduces a constraint; a bare expression is not one.- Indexed variables carry their bounds in the declaration:
var x{S} >= 0, <= 4;
The workflow
- Start -
ampl_init_session(workdir=...). - Build or load -
ampl_eval([...])for new models,ampl_read_filesfor existing.mod/.dat/.run. - Check what exists -
ampl_list_entities. Do this rather than guessing at names; it is cheap and prevents redeclaring or misspelling entities. - Data -
ampl_set_data(name, values)assigns a parameter from JSON rather than hand-writing.datsyntax. It handles parameters only - a set is declared or assigned viaampl_eval(e.g.set S = {1,2,3};), not throughampl_set_data. - Solve -
ampl_solve(). Check the returnedokandsolve_result, not just absence of error -okis only true whensolve_resultis exactly"solved", no error/warning was captured, and at least one objective was declared. - Read results -
ampl_get_data(name)for values,ampl_get_data(name, suffix="dual")for shadow prices,suffix="rc"for reduced costs,suffix="slack"for constraint slack,suffix="lb"/"ub"for bounds. At most one suffix per call. - Study -
ampl_sweep(param, values, collect=[...])for what-if analysis. Prefer one sweep call over a loop of solves; AMPL re-presolves only what changed, so it is far cheaper than round-trippingampl_solveyourself.
ampl_sweep in detail
ampl_sweep(param, values, collect=[...], objective=..., solver=...)sets a scalar parameter to each value in turn, re-solves, and collects the objective (plus any extracollectexpressions) per run.- Pass
objective=to pick which declared objective is activated and optimized for every run in the sweep - the same wayampl_solve's ownobjective=works. Omit it and AMPL uses whichever objective it reports first, which on a model with more than one declared objective may not be the one you want. - Trap: the sweep leaves the parameter set to the last value it swept
to. It does not restore whatever value the parameter had before the
call. A following plain
ampl_solve()on the same session solves against that last swept value, not the model's original state - re-set the parameter yourself (e.g. viaampl_set_data) afterwards if you need the original value back.
Reading errors
ampl_eval returns a record per statement with ok and messages. A
statement can fail without raising. Always check ok; do not assume
success because no error was thrown. Each message carries a class:
| class | meaning | what to do |
|---|---|---|
syntax_error | the AMPL statement itself is malformed | fix the statement and retry |
semantic_error | an undeclared, misspelled, or wrongly-dimensioned name | call ampl_list_entities to see what actually exists |
infeasible / unbounded | the solve completed but found no/no bounded optimum | call ampl_diagnose |
solver_missing | the named solver isn't installed/invokable | choose an installed solver; ampl_version lists what's available |
licence_error | the demo licence's size limit (or another licence problem) was hit | call ampl_version, report the tier to the user; do not keep debugging the model |
guard_refused | a shell/cd-style statement was blocked | tell the user rather than working around it; see "Guard" below |
argument_error | your own tool call's arguments were malformed (wrong shape, empty list, unknown kind, an entity name that isn't a bare identifier, an option name AMPL doesn't have, ...) | fix the arguments you passed - this is not an AMPL-side problem, and restarting the session will not help |
session_error | a session-lifecycle problem, and only that: no session running, unknown session name, session already closed | call ampl_init_session or ampl_restart_session |
unknown | none of the above patterns matched the message text | read message yourself; there is no further structured hint |
Infeasibility playbook
ampl_diagnose- readsolve_messageandviolated_constraints.- Drop suspect constraints one at a time with
ampl_eval(["drop cname;"])and re-solve to isolate the conflict. - Restore with
restore cname;. - Check bounds: an infeasibility is often a variable bound, not a constraint.
Guard: accidental shell/cd use is blocked, not sandboxed
AMPL's shell and cd statements are refused inside ampl_eval, inside
collect expressions passed to ampl_sweep, and inside files loaded by
ampl_read_files (file contents are guard-checked the same way).
AMPL_MCP_ALLOW_SHELL=1 is the documented escape hatch if you genuinely need
them. This is an accident-preventer, not a sandbox - treat it as blocking
accidental shell/cd use, not as a security guarantee.
One known false positive: a data or model file whose tokens happen to be
spelled cd or shell (e.g. a set member literally named cd) is refused
with a clear message even though nothing shell-related was intended. If you
hit this, it's a naming collision, not a real problem - rename the token or
use the escape hatch.
Loading a file executes its contents unchecked - by design
include, commands, model, data and load are not blocked, and
will not be. The guard only ever sees the text you hand this server, so:
- AMPL executes a loaded file's contents without guard-checking them. A
shellorcdinside that file - or inside anything it loads in turn - will run. ampl_read_filesguard-checks the file you name. That check does not extend to files that file pulls in.loadis worse still: it loads a native shared library, whose machine code cannot be checked at all.- An absolute path in an
includereads a file from outside the workdir.
This is a deliberate project decision: the human who approves the call owns what the loaded file does. Your job is not to work around it, and not to refuse it - it is to surface it.
ampl_eval, ampl_read_files and ampl_display return a top-level
warnings list (a plain list of strings) whenever they see such a
statement. ok stays true - a warning is not a failure. When
warnings is present, tell the user what is being loaded and from where,
especially if the path or the file did not come from them.
The solver name (ampl_solve(solver=...), ampl_option("solver", ...)) must
be a bare identifier such as highs or cplex - a path is refused
regardless of AMPL_MCP_ALLOW_SHELL. The same goes for every entity-name
argument (ampl_get_data(name), ampl_set_data(name), ampl_sweep(param)):
these are interpolated into AMPL statements, so they must be bare
identifiers and anything else is an argument_error.
ampl_option: a name AMPL doesn't have is an error, not a no-op
AMPL creates an option on first assignment, so a typo silently makes a new,
inert option. This server refuses that: ampl_option("solvre", "cbc") is an
argument_error, not a success that leaves the solve on HiGHS. Reading an
option AMPL doesn't have is an argument_error too. The exception is the
<solver>_options convention (highs_options, gurobi_options, ...),
which by design does not exist until you create it.
Solvers
highs (default) for LP/MIP. The coin module supplies cbc for MIP,
ipopt for smooth NLP, bonmin for MINLP and couenne for global MINLP.
Pass solver= to ampl_solve, or set it once with ampl_option.