agentsclimarketplace

Ampl mcp

Skill worc4021/ampl-mcp/skills/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

Install
npx -y skills add worc4021/ampl-mcp --skill ampl-mcp

Assembled 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, reporting ok: 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}; and set 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}; requires S to exist already.
  • subject to (or s.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

  1. Start - ampl_init_session(workdir=...).
  2. Build or load - ampl_eval([...]) for new models, ampl_read_files for existing .mod/.dat/.run.
  3. Check what exists - ampl_list_entities. Do this rather than guessing at names; it is cheap and prevents redeclaring or misspelling entities.
  4. Data - ampl_set_data(name, values) assigns a parameter from JSON rather than hand-writing .dat syntax. It handles parameters only - a set is declared or assigned via ampl_eval (e.g. set S = {1,2,3};), not through ampl_set_data.
  5. Solve - ampl_solve(). Check the returned ok and solve_result, not just absence of error - ok is only true when solve_result is exactly "solved", no error/warning was captured, and at least one objective was declared.
  6. 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.
  7. 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-tripping ampl_solve yourself.

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 extra collect expressions) per run.
  • Pass objective= to pick which declared objective is activated and optimized for every run in the sweep - the same way ampl_solve's own objective= 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. via ampl_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:

classmeaningwhat to do
syntax_errorthe AMPL statement itself is malformedfix the statement and retry
semantic_erroran undeclared, misspelled, or wrongly-dimensioned namecall ampl_list_entities to see what actually exists
infeasible / unboundedthe solve completed but found no/no bounded optimumcall ampl_diagnose
solver_missingthe named solver isn't installed/invokablechoose an installed solver; ampl_version lists what's available
licence_errorthe demo licence's size limit (or another licence problem) was hitcall ampl_version, report the tier to the user; do not keep debugging the model
guard_refuseda shell/cd-style statement was blockedtell the user rather than working around it; see "Guard" below
argument_erroryour 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_errora session-lifecycle problem, and only that: no session running, unknown session name, session already closedcall ampl_init_session or ampl_restart_session
unknownnone of the above patterns matched the message textread message yourself; there is no further structured hint

Infeasibility playbook

  1. ampl_diagnose - read solve_message and violated_constraints.
  2. Drop suspect constraints one at a time with ampl_eval(["drop cname;"]) and re-solve to isolate the conflict.
  3. Restore with restore cname;.
  4. 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 shell or cd inside that file - or inside anything it loads in turn - will run.
  • ampl_read_files guard-checks the file you name. That check does not extend to files that file pulls in.
  • load is worse still: it loads a native shared library, whose machine code cannot be checked at all.
  • An absolute path in an include reads 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.

Keep looking

Skills are one crate of 608,475. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.