NetLogo MCP

Unload the currently loaded model and reset the workspace. Useful when you want to discard pending state (mid-run agents, set parameters, pending plots) and start fresh, or before opening a new model file from disk to make sure cached compilation state isn't carried forward. Note: this does NOT shut down the JVM or NetLogo workspace — only the model. The next `open_model` / `create_model` call will reuse the same JVM (no 30-60s warmup).

Execute a NetLogo command (e.g. 'setup', 'go', 'create-turtles 10').

Create a new NetLogo model from code and load it.

Download and safely extract a COMSES model archive. Standalone "fetch but don't open" tool. Most AI flows should use `open_comses_model` instead — it subsumes this tool and also loads NetLogo models into the workspace. Safety guarantees: - `version="latest"` is resolved to a concrete version BEFORE any cache path is computed. Cache dirs are named by the resolved version. - HEAD request screens oversize archives before streaming. - Stream enforces the byte cap mid-download; overruns abort and delete the partial file. - Zip members are validated against path traversal before extraction. - Uncompressed total is checked against 2 × cap to reject zip bombs. - Extract happens in a temp directory; only a successful extract is moved atomically into the cache. A `.comses_complete` marker is written on success; future calls only trust cached dirs with the marker.

Export the current NetLogo view as a PNG image. Returns the image so Claude can see the model visualization.

Export the full world state to a CSV file. Saves all turtle, patch, and link data. Useful for checkpointing a simulation or analyzing the complete state offline. Returns the path to the exported CSV file.

Return a sample of agents with selected variables as a markdown table. Filling the gap between ``get_world_state`` (aggregates only) and hand-crafted ``report`` calls. Picks N random agents from the named breed (or all turtles when ``breed`` is None) and reports the requested per-agent attributes.

Get detailed metadata for a specific CoMSES model.

Get patch data as a 2D grid (useful for heatmaps / spatial analysis).

Get the current world state: tick count, agent counts, world dimensions. Returns JSON with ticks, turtle/patch/link counts, and world bounds.

List BehaviorSpace experiments saved inside a NetLogo model file. Reads the `<experiments>` section of a `.nlogox` (or `.nlogo`) without starting a JVM, so it's instant. By default it inspects the model the AI most recently loaded; pass `model_path` to inspect a specific file. Returns JSON: `{"model_path": ..., "experiments": [<spec>...]}` where each spec includes `name`, `repetitions`, `time_limit`, `setup_commands`, `go_commands`, `metrics`, `variables` (with `expanded_size` per variable), and `total_runs`. An empty list means the file has no saved experiments — you can still pass an inline spec to `run_experiment`.

List all .nlogo model files in the configured models directory. Returns a JSON array of {name, path, size_kb} objects.

Download (or reuse cache), then open a COMSES model ready to use. This is the **single entry point** most AI flows should call. Behavior: - Resolves `"latest"` to a concrete version BEFORE any cache path is computed. The returned `resolved_version` is what every follow-up `read_comses_files` call MUST pass — never re-pass `"latest"` in the same flow, or you risk inspecting a different cache slot than the model you just loaded. - If the cache for `(identifier, resolved_version)` is already complete (has `.comses_complete`), skips download. - Otherwise, downloads + extracts safely (same logic as `download_comses_model`). - If the model is NetLogo, picks one `.nlogo` / `.nlogox` per Section 4.4 rules (exactly one → use it; else prefer `code/`; else prefer `.nlogox`; else lex-largest relative path — a deterministic tie-breaker, NOT semver-aware). - If NetLogo, loads it into the workspace. - If not NetLogo, returns structured info for manual follow-up. Returns JSON with: - `status`: "loaded_netlogo", "not_runnable_in_netlogo", or "no_netlogo_file". - `resolved_version`: concrete version string (never "latest"). - `identifier`, `title`, `language`, `license`, `cached`. - `extracted_path`: absolute path to cached model directory. - `all_netlogo_files`: list of every NetLogo file found. - `loaded_netlogo_file`: the one selected (if any). - `code_files`: source files by extension. - `odd_doc`: ODD / README path, if any. - `message`: short text for the AI to show the user.

Open an existing .nlogo model file.

Show the run plan for a BehaviorSpace experiment WITHOUT executing it. Use this before `run_experiment` to verify the parameter combinations, total runs, and rough time estimate. Two modes: - **By name:** pass `experiment_name` (must match a saved experiment in the model file). The other args are ignored. - **Inline:** omit `experiment_name` and pass `metrics` + (optionally) `variables`, `repetitions`, `time_limit`, `setup_commands`, `go_commands`, `stop_condition`. Returns JSON with the resolved spec, `total_runs`, and a coarse `estimated_seconds_lower_bound` derived from `time_limit × total_runs` assuming roughly 1k ticks/s per run (real models are usually slower).

Return text contents of source and documentation files from a downloaded COMSES model. The model MUST already be downloaded by `open_comses_model` or `download_comses_model`. If the cache is absent, this tool returns an error telling the AI to call one of those first. The AI should pass the `resolved_version` it captured from `open_comses_model` — not the literal string `"latest"` — or it risks inspecting a different cache slot than the model it just loaded. When `version="latest"` is passed, this tool calls the COMSES API to resolve it (so it works standalone) and surfaces the concrete version in the `resolved_version` field of the response. Behavior: - Files are UTF-8 decoded with `errors="replace"` so binary junk never aborts the call. Every file that matches `extensions` is returned as a string (may contain replacement characters for non-text bytes). - Files are included in priority order: ODD docs → NetLogo source → other code → other .md/.txt → everything else matching extensions. - Total body is capped at `max_total_bytes` (default 50 KB — sized to fit in a single conversational-LLM tool response). When the cap is hit mid-file, that file is truncated at a line boundary; subsequent files are listed in `omitted_files` with reason `byte_cap_reached`. For larger pulls, pass a higher value explicitly. - Files matching no `extensions` filter are listed in `omitted_files` with reason `extension_not_in_filter`.

Evaluate a NetLogo reporter expression and return its value.

Run a BehaviorSpace experiment headlessly and return summarized results. Two ways to specify the experiment: - **By name** — pass `experiment_name` matching a saved experiment in the loaded model (.nlogox `<experiments>` section). All other experiment-shape args are ignored. - **Inline** — omit `experiment_name`. Required: `metrics`. Optional: `variables` (list of `{"name", "values"}` or `{"name", "first", "step", "last"}`), `repetitions`, `time_limit`, `setup_commands`, `go_commands`, `stop_condition`. Variable shapes (Cartesian product of all expanded values is run for each repetition):: [{"name": "density", "values": [50, 60, 70]}, {"name": "growth-rate", "first": 0.1, "step": 0.05, "last": 0.3}] Long-run controls: - `max_total_runs` — refuse to start if `total_runs` exceeds this. - `timeout_seconds` — kill the launcher after this many seconds. Partial results in the table CSV are preserved. - `threads` — parallel runs (0 = let NetLogo decide; default ~75% of CPUs). The launcher runs in a SEPARATE JVM, so the GUI workspace this server is hosting is unaffected. Run before calling this only matters insofar as the model file must be saved on disk (it is, after open_model / create_model / open_comses_model). Returns JSON with: `output_csv`, `runs`, `metrics_summary`, `per_combination`, `duration_seconds`, `command`, `timed_out`. The full per-tick data is in `output_csv` for offline analysis.

Run the simulation for N ticks and collect reporter data each tick.

Save NetLogo model code to a .nlogox file in the models directory. This saves the model so you can open it in the NetLogo desktop app for live visualization with GUI, sliders, and real-time animation.

Search the CoMSES Net computational model library.

Return a snapshot of the running NetLogo MCP server's configuration. Useful as a no-cost health check for the AI / user — returns the server version, configured paths, GUI mode, currently-loaded model, and whether a NetLogo headless launcher is reachable for BehaviorSpace runs. No JVM round-trip; this is a pure config / filesystem inspection so it works even before the workspace is fully initialized.

Set a NetLogo global variable / slider / switch value.

Update the currently loaded model's code in place and reload it. Prefer this over create_model when iterating on an existing model: the same .nlogox file is rewritten and reloaded, so the NetLogo window stays on one model and the models directory doesn't grow a new file per iteration.

Run the simulation SLOWLY so a human can watch it in the GUI window. Unlike run_simulation (full speed, returns data), this steps `go` once per tick with a pause between steps — use it for demos and teaching when the user wants to see the dynamics unfold live. In headless mode it works but there's nothing to watch; prefer run_simulation there.