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}]

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.