io.github.bayesian-energy/convexity-mcp

The signed-in Convexity account: which cloud features the organisation has enabled (cloud solve, solvers, data APIs, playbook signing, MCP access) and which Modelverse models it may open. Call it before promising a cloud feature, or to explain a refusal.

Whether the Convexity desktop app is running, its version, the model it currently has loaded, and whether its solve backend is up. Cheap; call it before choosing between the app (free, live) and the cloud.

Cancel a queued or running cloud solve. Billing stops once the machine is released.

Download a SOLVED cloud job into a new file beside the source model (<model>_solved.db, never overwriting the original) and make it the active model, so the results tools read from it. Pass save_path to choose the destination.

Solver output of a cloud solve (structured log lines, newest page first via page_token). Use it to explain a FAILED or INFEASIBLE job or to report progress; keep page_size small.

List the cloud machine sizes available for cloud_solve_submit with their vCPUs, memory, parallel-scenario capacity and hourly price in GBP (the charged rate). Call this before submitting so you can tell the user what a solve will cost; never guess prices.

Status of a cloud solve: phase, timings, per-scenario progress and any error. Without job_uuid, lists the cloud solves submitted from this machine (newest first) so you can find the id.

Solve the open model in the Convexity cloud (paid per hour of machine time; needs a signed-in account with cloud solve enabled). Quote cloud_solve_machines first; pass wait: true to block until it finishes, then cloud_solve_fetch_result brings the solved model back beside the original.

Compare two or more scenarios on one metric, by technology, in a single call — use this for any "compare scenario A vs B" request instead of reading each scenario separately and subtracting by hand. Returns an aligned per-technology table of values for each scenario plus signed deltas against the baseline (the FIRST scenario, usually the Base Scenario). Read-only; only over solved scenarios.

Create many components in one call: each item names its type (bus, generator, load, link, storage_unit, carrier) and its fields; any other key is set as a static attribute. Buses need latitude and longitude; generators, loads and storage units take their bus's position unless given one. Carriers, then buses, then the rest are created in order, so references resolve; a line is a link with p_nom. PROCESS is read-only here.

Create a brand-new blank Convexity model at an absolute .db path (must not already exist) and make it the active model. Sets the time axis (naive-UTC timestamps) and seeds the default carrier set. Use this when the user wants to build a model from scratch — no need to ask them to create a file in the app first.

Create a new scenario in the network. Use this to set up ensembles or sensitivity analyses. The returned scenario_id is what every other tool's scenario_id takes (solve, results, attributes, timeseries); the base case is scenario_id omitted or "base". After creating a scenario, use set_component_attribute with scenario_id to override attribute values. ENSEMBLE CONVENTION: To create an ensemble, use '/' in the name: 'ensemble_name/member_name'. For example, to create a 'climate' ensemble with 3 members, call create_scenario three times with names 'climate/dry', 'climate/wet', 'climate/normal'. The app automatically groups scenarios sharing the same prefix into an ensemble.

Get a compact summary of a timeseries attribute (length, min/max/mean, p05/p50/p95, zero_count, first/last 5 values, variation hint). Use for load profiles (p_set), generation (p), capacity factors (p_max_pu), marginal prices, state of charge, etc. Pass full=true ONLY when you need the raw array (e.g. to plot or inspect a specific hour) — otherwise the summary is enough to reason about shape.

Get a summary of the current model. When aggregate:true (or auto-selected for large models), returns counts by type/carrier and capacity totals without a per-row dump. When aggregate:false, returns full component rows with every set static attribute (p_min_pu, efficiencies, cyclic flags — the ones that change dispatch). Use this before EDITING a model — it replaces multiple list_components/get_attribute calls. For analysis or results, orient with assess_model and pull aggregates with get_statistic instead.

Report which model .db file this server is currently operating on, and whether it is writable or read-only (and why). Call this first when the user names a file, to check it matches.

Wholesale electricity prices from the loaded solve: a load-weighted system price, a per-bus breakdown in the model's currency per MWh, and a separate scarcity line for any bus that shed load. Use it for any price question, per scenario; pass price_type "marginal" for the LP shadow price. Read-only; needs a solved scenario.

Get the results from the most recent optimization solve that has been loaded into the current model. Returns status, objective value, solve time, and network statistics. Pass scenario_id to get results for a specific scenario; omit for the base case. Returns a "not solved" message when no solve has been loaded (the model has not been solved, or the solve result has not been loaded from the Jobs panel yet).

Get overall summary statistics for the current model from the loaded solve results: power/transmission/energy capacity, dispatch, emissions, capital/operational/total cost — each broken down by carrier — plus unmet load and LOLH per bus. This is the whole-horizon total; for a per-year breakdown use get_yearly_results. Pass scenario_id for a specific scenario; omit for the base case. Optionally filter to one bus. Read-only.

Get the validation rule for a specific component type and attribute, including data type, default value, and valid range.

A complete walkthrough for a common task, as text: three_bus_network (Build a small gas + wind + load network on a one-week hourly axis, then solve it locally and show the dispatch in the Convexity app.); load_demand_from_csv (Load a half-hourly regional demand file onto the matching loads of an existing model, aligned to its hourly axis.); solve_and_plot (Solve a model locally through the Convexity app, then set the Results Viewer up with a dispatch chart and a price chart and show it.); describe_model (A read-only summary of a model: component counts, capacity by carrier, whether timeseries data is loaded.); parameter_sweep (Create one scenario per value of a single attribute, solve them all locally, and compare system cost across the sweep.); unit_commitment (Turn a thermal generator into a unit-commitment unit with a minimum up time, using the attribute rules to find the right names.); compare_scenario (Create a scenario that changes one thing, solve the base case and the scenario locally, and report how system cost and prices moved.); compare_on_canvas (Solve a scenario against the base case and show both in the Analytics dashboard at once, grouped by scenario — not one at a time.); write_playbook (Write a small playbook for the open model, save it into the model, run it locally through the Convexity app, and report its outputs.); publish_playbook (Publish a playbook stored in a model as a page anyone with the link can run, with a daily run cap. Needs an API key.); run_playbook_cloud (Sign a playbook source file and run it in the cloud against a model on the smallest machine, then report its outputs. Paid; needs an API key.). The same content as the MCP prompts, for clients that do not surface prompts.

Every solve job this machine knows about: the desktop app's queue (when the app is running) and the cloud jobs submitted from here, newest first, with live status. One view instead of desktop_app_jobs plus cloud_solve_status.

The tools beyond the default set, by area: build (single-component edits, timeseries operations, data files, constraints, comments), analyse (statistics, carrier breakdowns, reliability, ensembles, sweeps, diagnostics), app (import/export through the desktop app), data (renewables, demand, costs, outlook). Returns their names and purposes — call any of them by name afterwards, whether or not your client refreshes its tool list.

List all scenarios defined in the network, including their run status and descriptions. By default the 'Actual' scenario is excluded. Set include_actual=true when the user asks about actuals data or wants to compare actuals against other scenarios.

The attribute vocabulary. With no filter: an index — per component type, the attribute groups and attribute names (cheap; start here). Pass component_type for that type's rules (data type, unit, default, required, input vs result, timeseries allowed), optionally narrowed by group_name. Use get_validation_rule for one attribute in full.

Open a model in the Convexity desktop app and bring the app to the front — starting the app if it is not running. Defaults to the active model. Once the app has the model open, edits made here appear in it live and solve_via_desktop_app can run it locally. With no tab connected this opens the web app in the computer's DEFAULT browser, already paired.

Switch to a different Convexity model: absolute path to a .db file on disk. All subsequent tools operate on it. Edits are written in place — suggest the user works on a copy of any model they care about. Resets the active scenario to the base case.

Render a map of the model as an inline image: buses at their coordinates, lines and links between them, and generators (triangles), loads (squares) and storage (diamonds) ringed around their bus. Use it to show the user the network — especially right after edits, to confirm what changed and where. Optionally pass component names to highlight.

Search the Convexity product documentation for how features work. Use when the user asks how to do something in Convexity or how a concept works.

Set static attributes on multiple components in one call. Pass a list of updates, each with component_name, attribute_name, and value. Much more efficient than calling set_component_attribute repeatedly. Example: set annual_failure_frequency on 30 generators in one call.

Set a static attribute value for a component, looked up by name. Pass scenario_id to set the value only for a specific scenario (leaving the base case unchanged).

Configure the analytics dashboard from the app’s built-in chart templates. Sets up which charts appear in the Analytics tab, with auto-generated layout. Call this after building a model to give the user a pre-configured analytics view. REPLACES the whole dashboard — to append one custom chart, use create_chart instead. TO COMPARE SCENARIOS SIDE BY SIDE: give a chart `scenarios` (names or ids, "base" for the base case) and it becomes one pinned chart per scenario; pass group_by "scenario" to arrange the canvas by scenario. A chart with no scenario follows the active-scenario cursor instead, so it re-renders in place when the scenario changes and never shows two at once. Valid template ids — timeseries: dispatch, curtailment, available-capacity, availability, lmp, lcp, link-flows, transformer-flows · summary: generation, system-cost, power-capacity, transmission-capacity, storage-capacity, emissions, curtailment-summary, unmet-load · reliability: unmet-load-timeseries, lol-duration-curve, lolh-distribution, load-duration-curve · map: network.

Set several timeseries in one call without shipping every value: each series gives values (full array), OR constant (one number for every period), OR pattern (a short array tiled along the time axis — 24 values on an hourly model is a daily profile, 168 a weekly one; add scale for its peak), OR scale_of (copy another component's series and multiply/offset it). Use load_timeseries_from_file for data that lives in a file.

Point the Convexity app's file explorer at a folder (default: the open model's folder) so the user sees the model file. open_in_app does this on its own; use this to show another folder or to refresh the listing.

Switch the Convexity app to a view: 'map', 'table', 'analytics' (results), 'jobs', 'text' or 'settings'. To focus specific components on the map or filter the table, use show_on_map / show_in_table.

Switch the user to the table view for a component type — the whole table when only component_type is given, or filtered by component IDs, names (exact) or carrier names (e.g. 'show all oil generators'). Needs the Convexity desktop app running (open_in_app starts it).

Navigate the user's map view to show specific components. Supports three modes: 1. By component IDs/names: flies to and selects the specific components. 2. By carrier names: hides all other carriers on the map and zooms to fit the matching components. Use this when the user asks to see a category like 'solar farms', 'wind turbines', 'gas plants' etc. 3. Both: filters by carrier AND selects specific components. Use after creating components or when the user asks to see something on the map. Needs the Convexity desktop app running (open_in_app starts it).

Solve the open model through the running Convexity app: on DESKTOP this queues one job per scenario in the app’s Job Queue exactly as the Run button does — free, on this computer, results written into the model file in place, so the results tools read them once desktop_app_jobs reports it completed. ON WEB THERE IS NO LOCAL SOLVER: the tab submits a CLOUD solve instead, which is BILLED to the account (machine_size, default xs) and loads its result back into the tab. Say so before solving on web if the user has not already asked for a cloud run. Do not edit the model while its solve is running. Returns at once; solves take minutes.

Set the active scenario for all subsequent tool calls. Pass a scenario id from list_scenarios, or null to work on the base case.

Block until solve jobs finish, reporting progress on the way, then return each one's outcome (failed local jobs include their log tail). Pass job_ids (desktop app queue, from solve_via_desktop_app) and/or job_uuids (cloud, from cloud_solve_submit); with neither it waits for every unfinished job in the app's queue.