simulator-simulate

Simulate a Simulator graph

The simulation engine runs inside this MCP server. It reads a layer (actors, links, account values), runs behaviour rules in model time for each scenario and returns metrics. It never writes to Simulator: the source layer is only read.

Format of models and scenarios: $CLAUDE_PLUGIN_ROOT/docs/simulation/model-format.md — read it before writing a model. Worked examples: $CLAUDE_PLUGIN_ROOT/docs/simulation/examples/.

1. Pick the graph — always ask

If a tool answers "not authenticated", call login and repeat the call.

• If the UI context has activeLayer, offer it first; otherwise help the user find a layer (getLayerActorsPaginated, layerStats) and confirm which one.
• Look at what is there before modelling: simulationSnapshot(layerId, period?) writes <layerId>.sim.yaml with every actor, link and account value the simulation will see.
• Account values that accumulate over time (bills, turnover) need period (e.g. 30d): values become the turnover of the last period. Check for accounts that are breakdowns of the same total (by service, region, operation): summing them counts one bill many times.

2. Write the model with the user

Ask only what changes the result: which actors behave and how, what the scenarios change, the horizon, what to measure. Show the rules in plain words before running, and label assumptions (durations, probabilities, growth rates) as assumptions.

A model is YAML (spec §5): value_types, refs, params, horizon, initial_events, behaviors.<actor type>.<event>: [actions], metrics, goals, optional helper actors (people or resources that are not on the graph). Actor types are form titles.

Rules of thumb:

• Money and other quantities that only move between actors: conserved: true and transfer. Things that only grow (hours worked, missed sales): not conserved, add.
• Capacity (people, machines, slots): an integer conserved account on a resource actor plus enqueue / release.
• Processes drawn as graphs: steps are actors, transitions are links; an application walks with pick(where(actor(self.at).children(), …)) (see examples/process_flow).
• Never write a key named on: (YAML reads it as true); use actor:.