MCP Helpers

The gekko.gk_mcp add-on module provides a sidecar helper layer for working with GEKKO models directly from Python code. It does not modify the base GEKKO implementation. Instead, it operates on a live GEKKO() object or creates a new one when needed.

Core usage follows this pattern:

from gekko import GEKKO
from gekko import gk_mcp

m = GEKKO(remote=False)
helper = gk_mcp.ModelMCP(m)

dof = helper.get_degrees_of_freedom()
options = helper.get_options()
tuning = helper.suggest_tuning_changes(goal="faster solve")

The helper can also create a model:

from gekko import gk_mcp

m = gk_mcp.create_model(remote=False, name="my_model")

Available Functions

  • create_model: create a new GEKKO() object.

  • attach_model / ModelMCP: wrap an existing GEKKO() object with direct helper methods.

  • materialize_model: write .apm, .csv, .info, and measurements.dbs files for the current model state.

  • bundle_model: copy the current model artifacts into .mcp/runs/<run_id> for later inspection.

  • get_degrees_of_freedom: return structural counts and a solver-reported or estimated degrees-of-freedom summary.

  • get_options: parse measurements.dbs, .info, and options.json into grouped tuning data.

  • summarize_results: summarize results.json when it is available.

  • diagnose_model: inspect current artifacts plus optional stdout and stderr text to classify failures.

  • suggest_tuning_changes: return rule-based tuning suggestions from the current model artifacts.

  • check_python_syntax: catch Python parser errors before running a model script.

  • scaffold_model_script: generate starter scripts for steady-state, dynamic optimization, MHE, and MPC use cases.

  • run_python_script: execute a Python model script and bundle its artifacts.

Building a New Model

You can build directly with GEKKO() and then inspect the current model:

from gekko import GEKKO, gk_mcp

m = GEKKO(remote=False)
x = m.Var(value=1)
y = m.Var(value=2)
m.Equations([x + y == 5, x - y == 1])

helper = gk_mcp.ModelMCP(m)
print(helper.materialize())
print(helper.get_degrees_of_freedom())

If you want a script template first:

from gekko import gk_mcp
from pathlib import Path

workspace = Path(".")
template = gk_mcp.scaffold_model_script(workspace, problem_type="steady_state", model_name="demo")
syntax = gk_mcp.check_python_syntax(source=template["source"])

Syntax errors are reported with the line, column, and offending text so an LLM can repair the script before execution.

Diagnosing Solve Failures

When a solve fails, pass the current model and any captured solver output:

from gekko import gk_mcp

helper = gk_mcp.ModelMCP(m)
diagnosis = helper.diagnose(stdout_text=solver_stdout, stderr_text=solver_stderr)
print(diagnosis)

The diagnosis looks for:

  • Python syntax and runtime exceptions

  • APMonitor @error blocks

  • infeasibility messages

  • time limits and convergence issues

  • negative or suspicious degrees of freedom

The return value includes supporting file paths so the LLM can inspect the compiled model and tuning files alongside the failure summary.

Tuning to Improve Performance

Use the helper on the current model after materialization or solve:

from gekko import gk_mcp

helper = gk_mcp.ModelMCP(m)
options = helper.get_options()
results = helper.summarize_results()
tuning = helper.suggest_tuning_changes(goal="faster solve with smoother MV movement")

Typical suggestions include:

  • reducing NODES for smaller solves

  • enabling SCALING

  • increasing MV.DCOST to smooth controller action

  • setting a finite MV.DMAX

  • decreasing CV.TAU for tighter tracking

  • increasing FSTATUS or WMEAS for estimation workflows

Optional Run Bundles

If you want a persistent copy of the current model artifacts, create a bundle:

bundle = helper.bundle(stdout_text=solver_stdout, stderr_text=solver_stderr)

Bundles are stored under:

.mcp/runs/<run_id>/

This is useful when an LLM needs to inspect a model repeatedly after the original temporary GEKKO run directory changes.